Initial commit of the diameter application.

The application provides an implementation of the Diameter protocol
as defined in RFC 3588.

18 files changed, 3557 insertions, 0 deletions

diff --git a/lib/diameter/doc/src/Makefile b/lib/diameter/doc/src/Makefile
new file mode 100644
index 0000000000..f2a91a88b7
--- /dev/null
+++ b/lib/diameter/doc/src/Makefile
@@ -0,0 +1,199 @@
+# 
+# %CopyrightBegin%
+#
+# Copyright Ericsson AB 2010-2011. All Rights Reserved.
+#
+# The contents of this file are subject to the Erlang Public License,
+# Version 1.1, (the "License"); you may not use this file except in
+# compliance with the License. You should have received a copy of the
+# Erlang Public License along with this software. If not, it can be
+# retrieved online at http://www.erlang.org/.
+#
+# Software distributed under the License is distributed on an "AS IS"
+# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+# the License for the specific language governing rights and limitations
+# under the License.
+#
+# %CopyrightEnd%
+
+ifneq ($(ERL_TOP),)
+include $(ERL_TOP)/make/target.mk
+include $(ERL_TOP)/make/$(TARGET)/otp.mk
+else
+include $(DIAMETER_TOP)/make/target.mk
+include $(DIAMETER_TOP)/make/$(TARGET)/rules.mk
+endif
+
+include ../../vsn.mk
+
+VSN = $(DIAMETER_VSN)
+
+RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN)
+
+# ----------------------------------------------------
+# Target Specs
+# ----------------------------------------------------
+include files.mk
+
+XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) \
+            $(XML_REF1_FILES) $(XML_REF3_FILES) $(XML_REF4_FILES) \
+            $(XML_PART_FILES) $(XML_CHAPTER_FILES) 
+
+INTERNAL_HTML_FILES = $(TECHNICAL_DESCR_FILES:%.xml=$(HTMLDIR)/%.html)
+
+HTML_APP_FILES   = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html)
+HTML_EXTRA_FILES = $(XML_EXTRA_FILES:%.xml=$(HTMLDIR)/%.html)
+HTML_PART_FILES  = $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html)
+
+HTML_FILES = $(HTML_APP_FILES) $(HTML_EXTRA_FILES) $(HTML_PART_FILES)
+
+INFO_FILE = ../../info
+
+HTML_REF_FILES = $(XML_REF1_FILES:%.xml=$(HTMLDIR)/%.html) \
+                 $(XML_REF3_FILES:%.xml=$(HTMLDIR)/%.html) \
+                 $(XML_REF4_FILES:%.xml=$(HTMLDIR)/%.html)
+
+HTML_CHAPTER_FILES = $(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html)
+
+EXTRA_FILES = \
+	$(DEFAULT_GIF_FILES)  \
+	$(DEFAULT_HTML_FILES) \
+	$(HTML_REF_FILES)    \
+	$(HTML_CHAPTER_FILES)
+
+MAN1_FILES = $(XML_REF1_FILES:%.xml=$(MAN1DIR)/%.1)
+MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3)
+MAN4_FILES = $(XML_REF4_FILES:%.xml=$(MAN4DIR)/%.4)
+
+HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
+
+TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf
+
+STANDARD_DIR = ../standard
+STANDARDS = 
+
+# ----------------------------------------------------
+# FLAGS 
+# ----------------------------------------------------
+
+XML_FLAGS += 
+DVIPS_FLAGS += 
+
+# ----------------------------------------------------
+# Targets
+# ----------------------------------------------------
+
+$(HTMLDIR)/%.gif: %.gif
+	$(INSTALL_DATA) $< $@
+
+docs: pdf html man
+
+ldocs: local_docs $(INDEX_TARGET)
+
+$(TOP_PDF_FILE): $(XML_FILES)
+
+pdf: $(TOP_PDF_FILE)
+
+html: gifs $(HTML_REF_MAN_FILE)
+
+clean clean_docs: clean_pdf clean_html clean_man
+	rm -f errs core *~
+
+clean_pdf:
+	rm -f $(PDFDIR)/*
+
+clean_man:
+	rm -f $(MAN1DIR)/* $(MAN3DIR)/* $(MAN4DIR)/*
+
+clean_html:
+	rm -rf $(HTMLDIR)/*
+
+gifs: $(GIF_FILES:%=$(HTMLDIR)/%)
+
+man: $(MAN1_FILES) $(MAN3_FILES) $(MAN4_FILES)
+
+$(INDEX_TARGET): $(INDEX_SRC) $(APP_FILE)
+	sed -e 's/%VSN%/$(VSN)/; \
+	        s/%ERLANG_SITE%/www\.erlang\.se\//; \
+	        s/%UP_ONE_LEVEL%/..\/..\/..\/doc\/index.html/; \
+	        s/%OFF_PRINT%/pdf\/diameter-$(VSN).pdf/' $< > $@
+
+depend debug opt: 
+
+info:
+	@echo "->Makefile<-"
+	@echo ""
+	@echo "DOCSUPPORT = $(DOCSUPPORT)"
+	@echo ""
+	@echo "INDEX_FILE   = $(INDEX_FILE)"
+	@echo "INDEX_SRC    = $(INDEX_SRC)"
+	@echo "INDEX_TARGET = $(INDEX_TARGET)"
+	@echo ""
+	@echo "XML_APPLICATION_FILES = $(XML_APPLICATION_FILES)"
+	@echo "XML_PART_FILES        = $(XML_PART_FILES)"
+	@echo "XML_REF1_FILES        = $(XML_REF1_FILES)"
+	@echo "XML_REF3_FILES        = $(XML_REF3_FILES)"
+	@echo "XML_REF4_FILES        = $(XML_REF4_FILES)"
+	@echo "XML_CHAPTER_FILES     = $(XML_CHAPTER_FILES)"
+	@echo ""
+	@echo "GIF_FILES             = $(GIF_FILES)"
+	@echo ""
+	@echo "TEX_FILES_USERS_GUIDE = $(TEX_FILES_USERS_GUIDE)"
+	@echo "TEX_FILES_REF_MAN     = $(TEX_FILES_REF_MAN)"
+	@echo "TEX_FILES_BOOK        = $(TEX_FILES_BOOK)"
+	@echo ""
+	@echo "MAN1_FILES            = $(MAN1_FILES)"
+	@echo "MAN3_FILES            = $(MAN3_FILES)"
+	@echo "MAN4_FILES            = $(MAN4_FILES)"
+	@echo ""
+	@echo "HTML_FILES            = $(HTML_FILES)"
+	@echo "TOP_HTML_FILES        = $(TOP_HTML_FILES)"
+	@echo ""
+	@echo "DEFAULT_HTML_FILES    = $(DEFAULT_HTML_FILES)"
+	@echo "DEFAULT_GIF_FILES     = $(DEFAULT_GIF_FILES)"
+	@echo ""
+	@echo ""
+
+
+# ----------------------------------------------------
+# Release Target
+# ---------------------------------------------------- 
+ifneq ($(ERL_TOP),)
+include $(ERL_TOP)/make/otp_release_targets.mk
+else
+include $(DIAMETER_TOP)/make/release_targets.mk
+endif
+
+release_docs_spec: $(LOCAL)docs
+	$(INSTALL_DIR) $(RELSYSDIR)/doc/pdf
+	$(INSTALL_DIR) $(RELSYSDIR)/doc/html
+	$(INSTALL_DIR) $(RELEASE_PATH)/man/man1
+	$(INSTALL_DIR) $(RELEASE_PATH)/man/man3
+	$(INSTALL_DIR) $(RELEASE_PATH)/man/man4
+	$(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf
+	$(INSTALL_DATA) $(HTMLDIR)/*.* $(RELSYSDIR)/doc/html
+	$(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR)
+	$(INSTALL_DATA) $(MAN1_FILES) $(RELEASE_PATH)/man/man1
+	$(INSTALL_DATA) $(MAN3_FILES) $(RELEASE_PATH)/man/man3
+	$(INSTALL_DATA) $(MAN4_FILES) $(RELEASE_PATH)/man/man4
+	[ -z "$(LOCAL)" ] || cp -r $(HTMLDIR)/js $(RELSYSDIR)/doc/html
+	echo $(LOCAL)
+
+release_spec:
+
+$(HTMLDIR)/diameter_app.html: diameter_app.xml
+$(HTMLDIR)/diameter_compile.html: diameter_compile.xml
+$(HTMLDIR)/diameter_debug.html: diameter_debug.xml
+$(HTMLDIR)/diameter_dict.html: diameter_dict.xml
+$(HTMLDIR)/diameter_intro.html: diameter_intro.xml
+$(HTMLDIR)/diameter_run.html: diameter_run.xml
+$(HTMLDIR)/diameter.html: diameter.xml
+$(HTMLDIR)/diameter_tcp.html: diameter_tcp.xml
+$(HTMLDIR)/diameter_transport.html: diameter_transport.xml
+$(HTMLDIR)/diameter_soc.html: diameter_soc.xml
+$(HTMLDIR)/diameter_sctp.html: diameter_sctp.xml
+
+.PHONY: clean clean_html clean_man clean_pdf \
+        depend debug opt info \
+        docs gifs html ldocs man pdf \
+        release_docs_spec release_spec
diff --git a/lib/diameter/doc/src/book.xml b/lib/diameter/doc/src/book.xml
new file mode 100644
index 0000000000..960296528b
--- /dev/null
+++ b/lib/diameter/doc/src/book.xml
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE book SYSTEM "book.dtd">
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<header titlestyle="normal">
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+<legalnotice>
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+
+</legalnotice>
+
+<title>Diameter</title>
+<prepared></prepared>
+<docno></docno>
+<date></date>
+<rev></rev>
+<file>book.xml</file>
+</header>
+
+<insidecover>
+</insidecover>
+
+<pagetext>Diameter</pagetext>
+
+<preamble>
+<contents level="2"></contents>
+</preamble>
+
+<parts lift="no">
+<xi:include href="user_man.xml"/>
+</parts>
+
+<applications>
+<xi:include href="ref_man.xml"/>
+</applications>
+
+<releasenotes>
+<xi:include href="notes.xml"/>
+</releasenotes>
+
+<index></index>
+
+</book>
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml
new file mode 100644
index 0000000000..9774183a2a
--- /dev/null
+++ b/lib/diameter/doc/src/diameter.xml
@@ -0,0 +1,1123 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+<header>
+
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+<legalnotice>
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+    
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+    
+</legalnotice>
+
+<title>diameter(3)</title>
+
+<prepared>Anders Svensson</prepared>
+<responsible></responsible>
+<docno></docno>
+<approved></approved>
+<checked></checked>
+<date></date>
+<rev>%VSN%</rev>
+<file>diameter.xml</file>
+
+</header>
+
+<!-- ===================================================================== -->
+<!-- ===================================================================== -->
+
+<module>diameter</module>
+<modulesummary>Main API of the diameter application.</modulesummary>
+
+<description>
+<p>
+This module provides the interface with which a user
+creates a service that sends and receives messages using the
+Diameter protocol as defined in RFC 3588.</p>
+
+<p>
+Basic usage consists of creating a representation of a
+locally implemented Diameter peer and its capabilities with <seealso
+marker="#start_service">start_service/2</seealso>, adding transport
+capability using <seealso
+marker="#add_transport">add_transport/2</seealso> and sending Diameter
+requests and receiving Diameter answers with <seealso
+marker="#call">call/4</seealso>.
+Incoming Diameter requests are communicated as callbacks to a
+<seealso
+marker="diameter_app">diameter_app(3)</seealso> callback modules as
+specified in the service configuration.</p>
+
+<p>
+Beware the difference between <em>diameter application</em> and
+<em>Diameter application</em>.
+The former refers to the Erlang application named diameter whose main
+api is defined here, the latter to an application of the Diameter
+protocol in the sense of RFC 3588.
+More generally, capitalized Diameter refers to the RFC
+and diameter to this implementation.</p>
+
+<p>
+The diameter application must be started before calling functions in
+this module.</p>
+
+</description>
+
+<!-- ===================================================================== -->
+<!-- ===================================================================== -->
+<section>
+<title>DATA TYPES</title>
+
+<taglist>
+
+<tag><c>Address()</c></tag>
+<tag><c>DiameterIdentity()</c></tag>
+<tag><c>Time()</c></tag>
+<tag><c>Unsigned32()</c></tag>
+<tag><c>UTF8String()</c></tag>
+<item>
+<p>
+Types corresponding to RFC 3588 AVP Data Formats.
+Defined in <seealso marker="diameter_dict">diameter_dict(4)</seealso>.</p>
+
+<marker id="application_alias"/>
+</item>
+
+<tag><c>application_alias() = term()</c></tag>
+<item>
+<p>
+A name identifying a Diameter application in
+service configuration passed to <seealso
+marker="#start_service">start_service/2</seealso> and passed to
+<seealso marker="#call">call/4</seealso> when sending requests
+belonging to the application.</p>
+
+<marker id="application_module"/>
+</item>
+
+<tag><c>application_module() = Mod | [Mod | ExtraArgs]</c></tag>
+<item>
+<code>
+Mod = atom()
+ExtraArgs = list()
+</code>
+
+<p>
+A module implementing the callback interface defined in <seealso
+marker="diameter_app">diameter_app(3)</seealso>, along with any
+extra arguments to be appended to those documented for the interface.
+Any extra arguments are appended to the documented list of arguments for
+each function.
+Note that additional arguments specific to an outgoing request be
+specified to <seealso marker="#call">call/4</seealso>, in which case
+the call-specific arguments are appended to any specified with the
+callback module.</p>
+
+<marker id="application_opt"/>
+</item>
+
+<tag><c>application_opt()</c></tag>
+<item>
+
+<p>
+Options defining a Diameter application as configured in an
+<c>application</c> option passed to
+<seealso marker="#start_service">start_service/2</seealso>.</p>
+
+<taglist>
+
+<tag><c>{alias, application_alias()}</c></tag>
+<item>
+<p>
+An unique identifier for the application in the scope of the
+service.
+Optional, defaults to the value of the <c>dictionary</c> option.</p>
+</item>
+
+<tag><c>{dictionary, atom()}</c></tag>
+<item>
+<p>
+The name of an encode/decode module for the Diameter
+messages defined by the application.
+These modules are generated from a specification file whose format is
+documented in <seealso
+marker="diameter_dict">diameter_dict(4)</seealso>.</p>
+</item>
+
+<tag><c>{module, application_module()}</c></tag>
+<item>
+<p>
+A callback module with which messages of the Diameter application are
+handled.
+See <seealso marker="diameter_app">diameter_app(3)</seealso> for
+information on the required interface and semantics.</p>
+</item>
+
+<tag><c>{state, term()}</c></tag>
+<item>
+<p>
+The initial callback state.
+Defaults to the value of the <c>alias</c> option if unspecified.
+The prevailing state is passed to certain
+<seealso marker="diameter_app">diameter_app(3)</seealso>
+callbacks, which can then return a new state.</p>
+</item>
+
+<tag><c>{call_mutates_state, true|false}</c></tag>
+<item>
+<p>
+Specifies whether or not the <seealso
+marker="diameter_app#pick_peer">pick_peer/4</seealso>
+application callback (following from a call to
+<seealso marker="#call">call/4</seealso>)
+can modifiy state,
+Defaults to <c>false</c> if unspecified.</p>
+
+<p>
+Note that <seealso
+marker="diameter_app#pick_peer">pick_peer</seealso> callbacks are
+serialized when these are allowed to modify state, which is a
+potential performance bottleneck.
+A simple Diameter client may suffer no ill effects from using mutable
+state but a server or agent that responds to incoming request but
+sending its own requests should probably avoid it.</p>
+</item>
+
+<tag><c>{answer_errors, callback|report|discard}</c></tag>
+<item>
+<p>
+Determines the manner in which incoming answer messages containing
+decode errors are handled.
+If <c>callback</c> then errors result in a <seealso
+marker="diameter_app#handle_answer">handle_answer/4</seealso>
+callback in the same fashion as for <seealso
+marker="diameter_app#handle_request">handle_request/3</seealso>, in the
+<c>errors</c> field of the <c>diameter_packet</c> record passed into
+the callback.
+If <c>report</c> then an answer containing errors is discarded
+without a callback and a warning report is written to the log.
+If <c>discard</c> then an answer containing errors is silently
+discarded without a callback.
+In both the <c>report</c> and <c>discard</c> cases the return value
+for the <seealso marker="#call">call/4</seealso> invocation in
+question is as if a callback had taken place and returned
+<c>{error, failure}</c>.</p>
+
+<p>
+Defaults to <c>report</c> if unspecified.</p>
+</item>
+
+</taglist>
+
+<marker id="call_opt"/>
+</item>
+
+<tag><c>call_opt()</c></tag>
+<item>
+
+<p>
+Options available to <seealso marker="#call">call/4</seealso> when
+sending an outgoing Diameter request.</p>
+
+<taglist>
+
+<tag><c>{extra, list()}</c></tag>
+<item>
+<p>
+Extra arguments to append to callbacks to the callback
+module in question.
+These are appended to any extra arguments configured with the callback
+itself.
+Multiple options append to the argument list.</p>
+</item>
+
+<tag><c>{filter, peer_filter()}</c></tag>
+<item>
+<p>
+A filter to apply to the list of available peers before passing them to
+the <seealso marker="diameter_app#pick_peer">pick_peer/4</seealso>
+callback for the application in question.
+Multiple options are equivalent a single <c>all</c> filter on the
+corresponding list of filters.
+Defaults to <c>none</c>.</p>
+</item>
+
+<tag><c>{timeout, Unsigned32()}</c></tag>
+<item>
+<p>
+The number of milliseconds after which the request should
+timeout.
+Defaults to 5000.</p>
+</item>
+
+<tag><c>detach</c></tag>
+<item>
+<p>
+Causes <seealso marker="#call">call/4</seealso> to return <c>ok</c> as
+soon as the request in
+question has been encoded instead of waiting for and returning
+the result from a subsequent
+<seealso marker="diameter_app#handle_answer">handle_answer/4</seealso>
+or <seealso
+marker="diameter_app#handle_error">handle_error/4</seealso>
+callback.</p>
+</item>
+
+</taglist>
+
+<marker id="capability"/>
+</item>
+
+<tag><c>capability()</c></tag>
+<item>
+
+<p>
+AVP values used in outgoing CER/CEA messages during capabilities exchange.
+Can be configured both on a service and a transport, the latter taking
+precedence over the former.</p>
+
+<taglist>
+
+<tag><c>{'Origin-Host', DiameterIdentity()}</c></tag>
+<item>
+<p>
+Value of the Origin-Host AVP in outgoing messages.</p>
+</item>
+
+<tag><c>{'Origin-Realm', DiameterIdentity()}</c></tag>
+<item>
+<p>
+Value of the Origin-Realm AVP in outgoing messages.</p>
+</item>
+
+<tag><c>{'Host-IP-Address', [Address()]}</c></tag>
+<item>
+<p>
+Values of Host-IP-Address AVPs.
+Optional.</p>
+
+<p>
+The list of addresses is available to the start function of a
+transport module, which either uses them as is or returns a new list
+(typically as configured as <c>transport_config()</c> on the
+transport module in question) in order for the correct list of
+addresses to be sent in capabilities exchange messages.</p>
+</item>
+
+<tag><c>{'Vendor-Id', Unsigned32()}</c></tag>
+<item>
+<p>
+Value of the Vendor-Id AVP sent in an outgoing capabilities
+exchange message.</p>
+</item>
+
+<tag><c>{'Product-Name', UTF8String()}</c></tag>
+<item>
+<p>
+Value of the Product-Name AVP sent in an outgoing capabilities
+exchange message.</p>
+</item>
+
+<tag><c>{'Origin-State-Id', Unsigned32()}</c></tag>
+<item>
+<p>
+Value of Origin-State-Id to be included in outgoing messages sent by
+diameter itself.
+In particular, the AVP will be included in CER/CEA and DWR/DWA messages.
+Optional.</p>
+
+<p>
+Setting a value of <c>0</c> (zero) is equivalent to not setting a
+value as documented in RFC 3588.
+The function <seealso
+marker="#origin_state_id">origin_state_id/0</seealso>
+can be used as to retrieve a value that is set when the diameter
+application is started.</p>
+</item>
+
+<tag><c>{'Supported-Vendor-Id', [Unsigned32()]}</c></tag>
+<item>
+<p>
+Values of Supported-Vendor-Id AVPs sent in an outgoing
+capabilities exchange message.
+Optional, defaults to the empty list.</p>
+</item>
+
+<tag><c>{'Auth-Application-Id', [Unsigned32()]}</c></tag>
+<item>
+<p>
+Values of Auth-Application-Id AVPs sent in an outgoing
+capabilities exchange message.
+Optional, defaults to the empty list.</p>
+</item>
+
+<tag><c>{'Acct-Application-Id', [Unsigned32()]}</c></tag>
+<item>
+<p>
+Values of Acct-Application-Id AVPs sent in an outgoing
+capabilities exchange message.
+Optional, defaults to the empty list.</p>
+</item>
+
+<tag><c>{'Vendor-Specific-Application-Id', [Grouped()]}</c></tag>
+<item>
+<p>
+Values of Vendor-Specific-Application-Id AVPs sent in
+an outgoing capabilities exchange message.
+Optional, defaults to the empty list.</p>
+</item>
+
+<tag><c>{'Firmware-Revision', Unsigned32()}</c></tag>
+<item>
+<p>
+Value of the Firmware-Revision AVP sent in an outgoing capabilities
+exchange message.
+Optional.</p>
+</item>
+
+</taglist>
+
+<p>
+Note that each tuple communicates one or more AVP values.
+It is an error to specify duplicate tuples.</p>
+
+<marker id="evaluable"/>
+</item>
+
+<tag><c>evaluable() = {M,F,A} | fun() | [evaluable() | A]</c></tag>
+<item>
+<p>
+An expression that can be evaluated as a function in the following
+sense.</p>
+
+<code>
+eval([{M,F,A} | T]) ->
+    apply(M, F, T ++ A);
+eval([F|A]) ->
+    apply(F, A);
+eval(F) ->
+    eval([F]).
+</code>
+
+<p>
+Evaluating an evaluable() <c>E</c> on an argument list <c>A</c>
+is meant in the sense of <c>eval([E|A])</c>.</p>
+
+<marker id="peer_filter"/>
+</item>
+
+<tag><c>peer_filter() = term()</c></tag>
+<item>
+<p>
+A filter passed to <seealso marker="#call">call/4</seealso>
+in order to select candidate peers for a 
+<seealso marker="diameter_app#pick_peer">pick_peer/4</seealso>
+callback.
+Has one of the following types.</p>
+
+<taglist>
+
+<tag><c>none</c></tag>
+<item>
+<p>
+Matches any peer.
+This is a convenience that provides a filter equivalent to no
+filter at all.</p>
+</item>
+
+<tag><c>host</c></tag>
+<item>
+<p>
+Matches only those peers whose <c>Origin-Host</c> has the same value
+as <c>Destination-Host</c> in the outgoing request in question,
+or any peer if the request does not contain
+a <c>Destination-Host</c> AVP.</p>
+</item>
+
+<tag><c>realm</c></tag>
+<item>
+<p>
+Matches only those peers whose <c>Origin-Realm</c> has the same value
+as <c>Destination-Realm</c> in the outgoing request in question,
+or any peer if the request does not contain
+a <c>Destination-Realm</c> AVP.</p>
+</item>
+
+<tag><c>{host, any|UTF8String()}</c></tag>
+<item>
+<p>
+Matches only those peers whose <c>Origin-Host</c> has the
+specified value, or all peers if the atom <c>any</c>.</p>
+</item>
+
+<tag><c>{realm, any|UTF8String()</c></tag>
+<item>
+<p>
+Matches only those peers whose <c>Origin-Realm</c> has the
+value, or all peers if the atom <c>any</c>.</p>
+</item>
+
+<tag><c>{eval, evaluable()}</c></tag>
+<item>
+<p>
+Matches only those peers for which the specified evaluable() evaluates
+to true on the peer's <c>diameter_caps</c> record.</p>
+</item>
+
+<tag><c>{neg, peer_filter()}</c></tag>
+<item>
+<p>
+Matches only those peers not matched by the specified filter.</p>
+</item>
+
+<tag><c>{all, [peer_filter()]}</c></tag>
+<item>
+<p>
+Matches only those peers matched by each filter of the specified list.</p>
+</item>
+
+<tag><c>{any, [peer_filter()]}</c></tag>
+<item>
+<p>
+Matches only those peers matched by at least one filter of the
+specified list.</p>
+</item>
+
+</taglist>
+
+<marker id="service_event"/>
+</item>
+
+<tag><c>service_event() = #diameter_event{}</c></tag>
+<item>
+<p>
+Event message sent to processes that have subscribed using <seealso
+marker="#subscribe">subscribe/1</seealso>.</p>
+
+<p>
+The <c>info</c> field of the event record can be one of the
+following.</p>
+
+<taglist>
+
+<tag><c>{up, Ref, Peer, Config, Pkt}</c></tag>
+<tag><c>{up, Ref, Peer, Config}</c></tag>
+<tag><c>{down, Ref, Peer, Config}</c></tag>
+<item>
+<code>
+Ref    = transport_ref()
+Peer   = diameter_app:peer()
+Config = {connect|listen, [transport_opt()]}
+Pkt    = #diameter_packet{}
+</code>
+
+<p>
+Reports that the RFC 3539 watchdog state machine has
+transitioned into (<c>up</c>) or out of (<c>down</c>) the open
+state.
+If a <c>diameter_packet</c> record is present in an <c>up</c> tuple
+then there has been an exchange of capabilities exchange messages and
+the record contains the received CER or CEA, otherwise the
+connection has reestablished without the loss or transport
+connectivity.</p>
+
+<p>
+Note that a single up/down event for a given peer corresponds to
+as many peer_up/down callbacks as there are Diameter
+applications shared by the peer, as determined during capablilities
+exchange.
+That is, the event communicates connectivity with the
+peer as a whole while the callbacks communicate connectivity with
+respect to individual Diameter applications.</p>
+</item>
+
+<tag><c>{reconnect, Ref, Opts}</c></tag>
+<item>
+<code>
+Ref  = transport_ref()
+Opts = [transport_opt()]
+</code>
+
+<p>
+A connecting transport is attempting to establish/reestablish a
+transport connection with a peer following <c>reconnect_timer</c> or
+<c>watchdog_timer</c> expiry.</p>
+</item>
+
+</taglist>
+
+<p>
+For forward compatibility, a subscriber should be prepared to receive
+<c>diameter_event.info</c> of forms other than those documented
+above.</p>
+
+<marker id="service_name"/>
+</item>
+
+<tag><c>service_name() = term()</c></tag>
+<item>
+<p>
+The name of a service as passed to <seealso
+marker="#start_service">start_service/2</seealso> and with which the
+service is identified.
+There can be at most one service with a given name on a given node.
+Note that <c>erlang:make_ref/0</c> can be used to generate a service name
+that is somewhat unique.</p>
+
+<marker id="service_opt"/>
+</item>
+
+<tag><c>service_opt()</c></tag>
+<item>
+<p>
+Options accepted by <seealso
+marker="#start_service">start_service/2</seealso>.
+Can be any <c>capability()</c> tuple as
+well as the following.</p>
+
+<taglist>
+
+<tag><c>{application, [application_opt()]}</c></tag>
+<item>
+<p>
+Defines a Diameter application supported by the service.</p>
+
+<p>
+A service must define one application for each Diameter application it
+intends to support.
+For an outgoing Diameter request, the application is specified by
+passing the desired application's <c>application_alias()</c> to
+<seealso marker="#call">call/4</seealso>, while for an
+incoming request the application identifier in the message
+header determines the application (and callback module), the
+application identifier being specified in the <seealso
+marker="diameter_dict">dictionary</seealso> file defining the
+application.</p>
+</item>
+
+</taglist>
+
+<marker id="transport_opt"/>
+</item>
+
+<tag><c>transport_opt()</c></tag>
+<item>
+<p>
+Options accepted by <seealso
+marker="#add_transport">add_transport/2</seealso>.</p>
+
+<taglist>
+<tag><c>{transport_module, atom()}</c></tag>
+<item>
+<p>
+A module implementing a transport process as defined in <seealso
+marker="diameter_transport">diameter_transport(3)</seealso>.
+Defaults to <c>diameter_tcp</c> if unspecified.</p>
+
+<p>
+The interface required of a transport module is documented in <seealso
+marker="diameter_transport">diameter_transport(3)</seealso>.</p>
+</item>
+
+<tag><c>{transport_config, term()}</c></tag>
+<item>
+<p>
+A term passed as the third argument to the <seealso
+marker="diameter_transport#start">start/3</seealso> function of
+the relevant <c>transport_module</c> in order to start a transport process.
+Defaults to the empty list if unspecified.</p>
+</item>
+
+<tag><c>{applications, [application_alias()]}</c></tag>
+<item>
+<p>
+The list of Diameter applications to which usage of the transport
+should be restricted.
+Defaults to all applications configured on the service
+in question.</p>
+</item>
+
+<tag><c>{capabilities, [capability()]}</c></tag>
+<item>
+<p>
+AVP's used to construct outgoing CER/CEA messages.
+Any AVP specified takes precedence over a corresponding value specified
+for the service in question.</p>
+</item>
+
+<tag><c>{watchdog_timer, TwInit}</c></tag>
+<item>
+<code>
+TwInit = Unsigned32()
+       | {M,F,A}
+</code>
+
+<p>
+The RFC 3539 watchdog timer.
+An integer value is interpreted as the RFC's TwInit in milliseconds,
+a jitter of &plusmn; 2 seconds being added at each rearming of the
+timer to compute the RFC's Tw.
+An MFA is expected to return the RFC's Tw directly, with jitter
+applied, allowing the jitter calculation to be performed by
+the callback.</p>
+
+<p>
+An integer value must be at least 6000 as required by RFC 3539.
+Defaults to 30000 if unspecified.</p>
+</item>
+
+<tag><c>{reconnect_timer, Tc}</c></tag>
+<item>
+<code>
+Tc = Unsigned32()
+</code>
+
+<p>
+For a connecting transport, the RFC 3588 Tc timer, in milliseconds.
+Note that this timer determines the frequency with which the transport
+will attempt to establish a connection with its peer only <em>before</em>
+an initial connection is established: once there is an initial
+connection it's watchdog_timer that determines the frequency of
+reconnection attempts, as required by RFC 3539.</p>
+
+<p>
+For a listening transport, the timer specifies the time after which a
+previously connected peer will be forgotten: a connection after this time is
+regarded as an initial connection rather than a reestablishment,
+causing the RFC 3539 state machine to pass to state OPEN rather than
+REOPEN.
+Note that these semantics are not goverened by the RFC and
+that a listening transport's reconnect_timer should be greater than its
+peers's Tc plus jitter.</p>
+
+<p>
+Defaults to 30000 for a connecting transport and 60000 for a listening
+transport.</p>
+</item>
+
+</taglist>
+
+<p>
+Unrecognized options are silently ignored but are returned unmodified
+by <seealso
+marker="#service_info_1">service_info/1,2</seealso> and can be referred to
+in predicate functions passed to <seealso
+marker="#remove_transport">remove_transport/2</seealso>.</p>
+
+</item>
+
+</taglist>
+
+</section>
+
+<marker id="add_transport"/>
+<funcs>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>add_transport(SvcName, {connect|listen, Options})
+        -> {ok, Ref} | {error, Reason}</name>
+<fsummary>Add transport capability to a service.</fsummary>
+<type>
+<v>SvcName = service_name()</v>
+<v>Options = [transport_opt()]</v>
+<v>Ref = ref()</v>
+<v>Reason = term()</v>
+</type>
+<desc>
+<p>
+Add transport capability to a service.
+The service will start a transport process(es) in order to establish a
+connection with the peer, either by connecting to the peer
+(<c>connect</c>) or by  accepting incoming connection requests
+(<c>listen</c>).
+A connecting transport establishes transport connections with at most
+one peer, an listening transport potentially with many.</p>
+
+<p>
+The diameter application takes responsibility for exchanging
+CER/CEA with the peer.
+Upon successful completion of capabilities exchange the service
+calls each relevant application module's <seealso
+marker="diameter_app#peer_up">peer_up/3</seealso> callback
+after which the caller can exchange Diameter messages with the peer over
+the transport.
+In addition to CER/CEA, the service takes responsibility for the
+handling of DWR/DWA and required by RFC 3539 as well as for DPR/DPA.</p>
+
+<p>
+The returned reference uniquely identifies the transport within the
+scope of the service.
+Not that the function returns before a transport connection has been
+established.</p>
+
+<p>
+It is not an error to add a transport to a service that has not yet
+been configured: a service can be started after configuring
+transports.</p>
+
+<marker id="call"/>
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>call(SvcName, App, Request, Options) -> Answer | {error, Reason}</name>
+<fsummary>Send a Diameter request message.</fsummary>
+<type>
+<v>SvcName = service_name()</v>
+<v>App = application_alias()</v>
+<v>Request = diameter_app:message()</v>
+<v>Answer = term()</v>
+<v>Options = [call_opt()]</v>
+</type>
+<desc>
+<p>
+Send a Diameter request message and possibly return the answer or error.</p>
+
+<p>
+<c>App</c> identifies the Diameter application in which the request is
+defined and callbacks to the corresponding callback module
+will follow as described below and in <seealso
+marker="diameter_app">diameter_app(3)</seealso>.
+The call returns either when an answer message is received from the
+peer or an error occurs, unless the <c>detach</c> option has been
+specified.
+If <c>detach</c> is not specified then the form of an <c>Answer</c> is
+as returned from a <seealso
+marker="diameter_app#handle_answer">handle_answer/4</seealso> or
+<seealso
+marker="diameter_app#handle_error">handle_error/4</seealso>
+callback.</p>
+
+<p>
+If there are no suitable peers, or if
+<seealso marker="diameter_app#pick_peer">pick_peer/4</seealso>
+rejects them by returning 'false', then <c>{error, no_connection}</c>
+is returned.
+If <seealso marker="diameter_app#pick_peer">pick_peer/4</seealso>
+selects a candidate peer then a request process is spawned for the
+outgoing request, in which there is a
+<seealso
+marker="diameter_app#prepare_request">prepare_request/3</seealso>
+callback, the message is encoded and sent.</p>
+
+<p>
+There are several error cases which may prevent an
+answer from being received and passed to a
+<seealso marker="diameter_app#handle_answer">handle_answer/4</seealso>
+callback:</p>
+
+<list>
+
+<item>
+<p>
+If the initial encode of the outgoing request
+fails, then the request process fails and <c>{error, encode}</c>
+is returned.</p>
+</item>
+
+<item>
+<p>
+If the request is successfully encoded and sent but
+the answer times out then a
+<seealso marker="diameter_app#handle_error">handle_error/4</seealso>
+callback takes place with <c>Reason = timeout</c>.</p>
+</item>
+
+<item>
+<p>
+If the request is successfully encoded and sent but the service in
+question is stopped before an answer is received then a
+<seealso marker="diameter_app#handle_error">handle_error/4</seealso>
+callback takes place <c>Reason = cancel</c>.</p>
+</item>
+
+<item>
+<p>
+If the transport connection with the peer goes down after the request
+has been sent but before an answer has been received then an attempt
+is made to resend the request to an alternate peer.
+If no such peer is available, or if the subsequent
+<seealso marker="diameter_app#pick_peer">pick_peer/4</seealso>
+callback rejects the candidates, then a
+<seealso marker="diameter_app#handle_error">handle_error/4</seealso>
+callback takes place with <c>Reason = failover</c>.
+If a peer is selected then a
+<seealso
+marker="diameter_app#prepare_retransmit">prepare_retransmit/3</seealso>
+callback takes place, after which the semantics are the same as
+following an initial
+<seealso marker="diameter_app#prepare_request">
+prepare_request/3</seealso>
+callback.</p>
+</item>
+
+<item>
+<p>
+If an encode error takes place during
+retransmission then the request process fails and
+<c>{error, failure}</c> is returned.</p>
+</item>
+
+<item>
+<p>
+If an application callback made in processing the request fails
+(pick_peer, prepare_request, prepare_retransmit,
+handle_answer or handle_error) then either
+<c>{error, encode}</c> or <c>{error, failure}</c>
+is returned depending on whether or not there has been an
+attempt to send the request over the transport.</p>
+</item>
+
+</list>
+
+<p>
+Note that <c>{error, encode}</c> is the only return value which
+guarantees that the request has not been sent over the transport.</p>
+
+<marker id="origin_state_id"/>
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>origin_state_id() -> Unsigned32()</name>
+<fsummary>Returns a reasonable Origin-State-Id.</fsummary>
+<desc>
+<p>
+Return a reasonable value for use as Origin-State-Id in
+outgoing messages.
+The value returned is the number of seconds since 19680120T031408Z
+(the first value that can be encoded as a Time())
+at the time the diameter application was started.</p>
+
+<marker id="remove_transport"/>
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>remove_transport(SvcName, Pred) -> ok</name>
+<fsummary>Remove previously added transports.</fsummary>
+<type>
+<v>SvcName = service_name()</v>
+<v>Pred = Fun | MFA | ref() | list() | true | false</v>
+<v></v>
+<v>Fun = fun((reference(), connect|listen, list()) -> boolean())</v>
+<v>&nbsp;&nbsp;&nbsp; | fun((reference(), list()) -> boolean())</v>
+<v>&nbsp;&nbsp;&nbsp; | fun((list()) -> boolean())</v>
+<v>MFA = {atom(), atom(), list()}</v>
+</type>
+<desc>
+<p>
+Remove previously added transports.</p>
+
+<p>
+<c>Pred</c> determines which transports to remove.
+An arity-3-valued <c>Pred</c> removes all transports for which
+<c>Pred(Ref, Type, Opts)</c> returns <c>true</c>, where <c>Type</c> and
+<c>Opts</c> are as passed to <seealso
+marker="#add_transport">add_transport/2</seealso> and <c>Ref</c> is
+as returned by the corresponding call.
+The remaining forms are equivalent to an arity-3 fun as follows.</p>
+
+<code>
+Pred = fun(reference(), list()):  fun(Ref, _, Opts) -> Pred(Ref, Opts) end
+Pred = fun(list()):               fun(_, _, Opts) -> Pred(Opts) end
+Pred = reference():               fun(Ref, _, _)  -> Pred == Ref end
+Pred = list():                    fun(_, _, Opts) -> [] == Pred -- Opts end
+Pred = true:                      fun(_, _, _) -> true end
+Pred = false:                     fun(_, _, _) -> false end
+Pred = {M,F,A}:  fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end
+</code>
+
+<p>
+Removing a transport causes all associated transport connections to
+be broken.
+A base application DPR message with
+Disconnect-Cause <c>DO_NOT_WANT_TO_TALK_TO_YOU</c> will be sent
+to each connected peer before disassociating the transport configuration
+from the service and terminating the transport upon reception of
+DPA or timeout.</p>
+
+<!-- TODO: document the timeout value, possibly make configurable. -->
+
+<marker id="service_info_1"/>
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>service_info(SvcName) -> Info</name>
+<fsummary>Return information about a started service.</fsummary>
+<type>
+<v>SvcName = service_name()</v>
+<v>Info = [{Item, Value}]</v>
+</type>
+<desc>
+<p>
+Return information about a started service.
+Equivalent to <c>service_info(SvcName, all)</c>.</p>
+
+<marker id="service_info_2"/>
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>service_info(SvcName, Item) -> Value</name>
+<fsummary>Return specific information about a started service.</fsummary>
+<type>
+<v>SvcName = service_name()</v>
+<v>Value = term()</v>
+</type>
+<desc>
+<p>
+Return specific information about a started service.</p>
+
+<marker id="services"/>
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>services() -> [SvcName]</name>
+<fsummary>Return the list of started services.</fsummary>
+<type>
+<v>SvcName = service_name()</v>
+</type>
+<desc>
+<p>
+Return the list of started services.</p>
+
+<marker id="session_id"/>
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>session_id(Ident) -> OctetString()</name>
+<fsummary>Return a value for a Session-Id AVP</fsummary>
+<type>
+<v>Ident = DiameterIdentity()</v>
+</type>
+<desc>
+<p>
+Return a value for a Session-Id AVP.
+The value has the form required by section 8.8 of RFC 3588.
+Ident should be the Origin-Host of the peer from which
+the message containing the returned value will be sent.</p>
+
+<marker id="start_service"/>
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+<func>
+<name>start_service(SvcName, Options) -> ok | {error, Reason}</name>
+<fsummary>Start a Diameter service</fsummary>
+<type>
+<v>SvcName = service_name()</v>
+<v>Options = [service_opt()]</v>
+<v>Reason  = term()</v>
+</type>
+<desc>
+<p>
+Start a diameter service.
+A service defines a locally-implemented Diameter peer, specifying the
+capabilities of the peer to be used during capabilities exchange and
+the Diameter applications that it supports.
+Transports are added to a service using <seealso
+marker="#add_transport">add_transport/2</seealso>.</p>
+
+<marker id="stop_service"/>
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+<func>
+<name>stop_service(SvcName) -> ok | {error, Reason}</name>
+<fsummary>Stops a Diameter service.</fsummary>
+<type>
+<v>SvcName = service_name()</v>
+<v>Reason = term()</v>
+</type>
+<desc>
+<p>
+Stop a diameter service.</p>
+
+<marker id="subscribe"/>
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>subscribe(SvcName) -> true</name>
+<fsummary>Subscribe to event messages from a service.</fsummary>
+<type>
+<v>SvcName = service_name()</v>
+</type>
+<desc>
+<p>
+Subscribe to <c>service_event()</c> messages from a service.</p>
+
+<p>
+It is not an error to subscribe to events from a service
+that does not yet exist.</p>
+
+<marker id="unsubscribe"/>
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>unsubscribe(SvcName) -> true</name>
+<fsummary></fsummary>
+<type>
+<v>SvcName = service_name()</v>
+</type>
+<desc>
+<p>
+Unsubscribe to event messages from a service.</p>
+
+</desc>
+</func>
+
+</funcs>
+
+<!-- ===================================================================== -->
+<!-- ===================================================================== -->
+<section>
+<title>SEE ALSO</title>
+
+<p>
+<seealso marker="diameter_app">diameter_app(3)</seealso>,
+<seealso marker="diameter_transport">diameter_transport(3)</seealso>,
+<seealso marker="diameter_dict">diameter_dict(4)</seealso></p>
+
+</section>
+
+</erlref>
diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml
new file mode 100644
index 0000000000..c2fecce768
--- /dev/null
+++ b/lib/diameter/doc/src/diameter_app.xml
@@ -0,0 +1,582 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+<header>
+
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+<legalnotice>
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+
+</legalnotice>
+
+<title>diameter_app(3)</title>
+<prepared>Anders Svensson</prepared>
+<responsible></responsible>
+<docno></docno>
+<approved></approved>
+<checked></checked>
+<date></date>
+<rev>%REV%</rev>
+<file>diameter_app.xml</file>
+
+</header>
+
+<module>diameter_app</module>
+<modulesummary>
+Callback module of a Diameter application.</modulesummary>
+
+<description>
+
+<p>
+A diameter service as started by <seealso
+marker="diameter#start_service">diameter:start_service/2</seealso>
+configures one of more Diameter applications, each of whose
+configuration specifies a callback that handles messages specific to
+its application.
+The messages and AVPs of the Diameter application are defined in a
+specification file whose format is documented in
+<seealso marker="diameter_dict">diameter_dict(4)</seealso>
+while the callback module is documented here.
+The callback module implements the Diameter application-specific
+functionality of a service.</p>
+
+<note>
+<p>
+The arities of the callback functions below assume no extra arguments.
+All functions will also be passed any extra arguments configured with
+the callback module itself when calling <seealso
+marker="diameter#start_service">diameter:start_service/2</seealso>
+and, except for peer_up, peer_down and handle_request, any extra
+arguments passed to <seealso
+marker="diameter#call">diameter:call/4</seealso>.</p>
+</note>
+
+<p>
+A callback module must export all of the functions documented below.
+The functions themselves are of three distinct flavours:</p>
+
+<list>
+<item>
+<p>
+<seealso marker="#peer_up">peer_up/3</seealso> and
+<seealso marker="#peer_down">peer_down/3</seealso> signal the attainment
+or loss of communicativity with a Diameter peer.</p>
+</item>
+
+<item>
+<p>
+<seealso marker="#pick_peer">pick_peer/4</seealso>,
+<seealso marker="#prepare_request">prepare_request/3</seealso>,
+<seealso marker="#prepare_retransmit">prepare_retransmit/3</seealso>,
+<seealso marker="#handle_answer">handle_answer/4</seealso>
+and <seealso marker="#handle_error">handle_error/4</seealso> are (or may
+be) called as a consequence of a call to <seealso 
+marker="diameter#call">diameter:call/4</seealso> to send an outgoing
+Diameter request message.</p>
+</item>
+
+<item>
+<p>
+<seealso marker="#handle_request">handle_request/3</seealso>
+is called in response to an incoming Diameter request message.</p>
+</item>
+
+</list>
+
+</description>
+
+<!-- ===================================================================== -->
+<!-- ===================================================================== -->
+
+<section>
+<title>DATA TYPES</title>
+
+<taglist>
+
+<tag><c>capabilities() = #diameter_caps{}</c></tag>
+<item>
+<p>
+A record containing the identities of
+the local and remote Diameter peers having an established transport
+connection, as well as the capabilities as
+determined by capabilities exchange.
+Each field of the record is a 2-tuple consisting of
+values for the (local) host and (remote) peer.
+Optional or possibly multiple values are encoded as lists of values,
+mandatory values as the bare value.</p>
+</item>
+
+<tag><c>message() = record() | list()</c></tag>
+<item>
+<p>
+The representation of a Diameter message as passed to
+<seealso marker="diameter#call">diameter:call/4</seealso>.
+The record representation is as outlined in
+<seealso
+marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>:
+a message as defined in a dictionary file is encoded as a record with
+one field for each component AVP.
+Equivalently, a message can also be encoded as a list whose head is
+the atom-valued message name (the record name minus any
+prefix in the dictionary file) and whose tail is a list of
+<c>{FieldName, FieldValue}</c> pairs.</p>
+
+<p>
+A third representation allows a message to be specified as a list
+whose head is a <c>diameter_header</c> record and whose tail is a list
+of <c>diameter_avp</c> records.
+This representation is used by diameter itself when relaying requests
+as directed by the return value of a
+<seealso marker="#handle_request">handle_request/3</seealso>
+callback.
+It differs from the other other two in that it bypasses the checks for
+messages that do not agree with their definitions in the dictionary in
+question: messages are sent exactly as specified.</p>
+
+</item>
+
+<tag><c>packet() = #diameter_packet{}</c></tag>
+<item>
+<p>
+A container for incoming and outgoing Diameters message that's passed
+through encode/decode and transport.
+Defined in diameter.hrl.
+Fields should not be altered except as documented.</p>
+</item>
+
+<tag><c>peer_ref() = term()</c></tag>
+<item>
+<p>
+A term identifying a transport connection with a Diameter peer.
+Should be treated opaquely.</p>
+</item>
+
+<tag><c>peer() = {peer_ref(), capabilities()}</c></tag>
+<item>
+<p>
+A tuple representing a Diameter peer connection.</p>
+</item>
+
+<tag><c>service_name() = term()</c></tag>
+<item>
+<p>
+The service supporting the Diameter application.
+Specified to <seealso
+marker="diameter#start_service">diameter:start_service/2</seealso>
+when starting the service.</p>
+</item>
+
+<tag><c>state() = term()</c></tag>
+<item>
+<p>
+The state maintained by the application callback functions
+<seealso marker="#peer_up">peer_up/3</seealso>,
+<seealso marker="#peer_down">peer_down/3</seealso> and (optionally)
+<seealso marker="#pick_peer">pick_peer/4</seealso>.
+The initial state is configured in the call to
+<seealso
+marker="diameter#start_service">diameter:start_service/2</seealso>
+that configures the application on a service.
+Callback functions returning a state are evaluated in a common
+service-specific process while
+those not returning state are evaluated in a request-specific
+process.</p>
+</item>
+
+</taglist>
+
+<marker id="peer_up"/>
+</section>
+
+<!-- ===================================================================== -->
+<!-- ===================================================================== -->
+
+<funcs>
+
+<func>
+<name>Mod:peer_up(SvcName, Peer, State) -> NewState</name>
+<fsummary>Invoked when a transport connection has been established</fsummary>
+<type>
+<v>SvcName = service_name()</v>
+<v>Peer    = peer()</v>
+<v>State   = NewState = state()</v>
+</type>
+<desc>
+<p>
+Invoked when a transport connection has been established
+and a successful capabilities exchange has indicated that the peer
+supports the Diameter application of the application on which
+the callback module in question has been configured.</p>
+
+<marker id="peer_down"/>
+</desc>
+</func>
+
+<func>
+<name>Mod:peer_down(SvcName, Peer, State) -> NewState</name>
+<fsummary>Invoked when a transport connection has been lost.</fsummary>
+<type>
+<v>SvcName = service_name()</v>
+<v>Peer    = peer()</v>
+<v>State   = NewState = state()</v>
+</type>
+<desc>
+<p>
+Invoked when a transport connection has been lost following a previous
+call to <seealso marker="peer_up">peer_up/3</seealso>.</p>
+
+<marker id="pick_peer"/>
+</desc>
+</func>
+
+<func>
+<name>Mod:pick_peer(Cands, Reserved, SvcName, State)
+      -> {ok, Peer} | {Peer, NewState} | false</name>
+<fsummary>Select a target peer for an outgoing request.</fsummary>
+<type>
+<v>Cands = [Peer]</v>
+<v>Peer = peer() | false</v>
+<v>SvcName = service_name()</v>
+<v>State = NewState = state()</v>
+</type>
+<desc>
+<p>
+Invoked as a consequence of a call to <seealso
+marker="diameter#call">diameter:call/4</seealso> to select a destination
+peer for an outgoing request, the return value indicating the selected peer.
+A new application state can also be returned but only if the Diameter
+application in question was
+configured with the option <c>call_mutates_state</c> set to
+<c>true</c>, as documented for <seealso
+marker="diameter#start_service">diameter:start_service/2</seealso>.</p>
+
+<p>
+The candidate peers list will only include those
+which are selected by any <c>filter</c> option specified in the call to
+<seealso marker="diameter#call">diameter:call/4</seealso>.</p>
+<!--
+The local candidates are those whose transport process is executing on
+the local Erlang node, the remote list those that are available on
+other nodes.</p> -->
+
+<p>
+The return values <c>false</c> and <c>{false, State}</c> are
+equivalent when callback state is mutable, as are
+<c>{ok, Peer}</c> and <c>{Peer, State}</c>.
+Returning a peer as <c>false</c> causes <c>{error, no_connection}</c>
+to be returned from <seealso marker="diameter#call">diameter:call/4</seealso>.
+Returning a peer() from an initial pick_peer/4 callback will result in a
+<seealso marker="#prepare_request">prepare_request/3</seealso> callback
+followed by either <seealso
+marker="#handle_answer">handle_answer/4</seealso>
+or <seealso marker="#handle_error">handle_error/4</seealso> depending
+on whether or not an answer message is received from the peer.
+If transport with the peer is lost before this then a new <seealso
+marker="#pick_peer">pick_peer/4</seealso> callback takes place to
+select an alternate peer.</p>
+
+<p>
+Note that there is no guarantee that a <seealso
+marker="#pick_peer">pick_peer/4</seealso> callback to select
+an alternate peer will be followed by any additional callbacks, only
+that the initial <seealso
+marker="#pick_peer">pick_peer/4</seealso> will be, since a
+retransmission to an alternate peer is abandoned if an answer is
+received from a previously selected peer.</p>
+
+<marker id="prepare_request"/>
+</desc>
+
+</func>
+
+<func>
+<name>Mod:prepare_request(Packet, SvcName, Peer) -> Action</name>
+<fsummary>Return a request for encoding and transport.</fsummary>
+<type>
+<v>Packet = packet()</v>
+<v>SvcName = service_name()</v>
+<v>Peer = peer()</v>
+<v>Action = {send, packet() | message()} | {discard, Reason} | discard</v>
+</type>
+<desc>
+<p>
+Invoked to return a request for encoding and transport.
+Allows the sender to access the selected peer's capabilities
+in order to set (for example) <c>Destination-Host</c> and/or
+<c>Destination-Realm</c> in the outgoing request, although the
+callback need not be limited to this usage.
+Many implementations may simply want to return <c>{send, Packet}</c></p>
+
+<p>
+A returned packet() should set the request to be encoded in its
+<c>msg</c> field and can set the <c>transport_data</c> field in order
+to pass information to the transport module.
+Extra arguments passed to <seealso
+marker="diameter#call">diameter:call/4</seealso> can be used to
+communicate transport data to the callback.</p>
+
+<p>
+Any returned packet() can set the <c>header</c> field to a
+<c>diameter_header</c> record in order to specify values that should
+be preserved in the outgoing request.
+A specified <c>message_length</c> is ignored.</p>
+
+<p>
+Returning <c>{discard, Reason}</c> causes the request to be aborted
+and the <seealso
+marker="diameter#call">diameter:call/4</seealso> for which the
+callback has taken place to return <c>{error, Reason}</c>.
+Returning <c>discard</c> is equivalent to returning <c>{discard,
+discarded}</c>.</p>
+
+<marker id="prepare_retransmit"/>
+</desc>
+</func>
+
+<func>
+<name>Mod:prepare_retransmit(Packet, SvcName, Peer) -> Result</name>
+<fsummary>Return a request for encoding and retransmission.</fsummary>
+<type>
+<v>Packet  = packet()</v>
+<v>SvcName = service_name()</v>
+<v>Peer    = peer()</v>
+<v>Result  = {send, packet() | message()} | {discard, Reason} | discard</v>
+</type>
+<desc>
+<p>
+Invoked to return a request for encoding and retransmission.
+Has the same role as <seealso
+marker="#prepare_request">prepare_request/3</seealso> in the case that
+a peer connection is lost an an alternate peer selected but the
+Packet passed to <c>prepare_retransmit/3</c> is as returned by
+<c>prepare_request/3</c>.</p>
+
+<p>
+Returning <c>{discard, Reason}</c> causes the request to be aborted
+and a <seealso
+marker="#handle_error">handle_error/4</seealso> callback to
+take place with <c>Reason</c> as initial argument.
+Returning <c>discard</c> is equivalent to returning <c>{discard,
+discarded}</c>.</p>
+
+<marker id="handle_answer"/>
+</desc>
+</func>
+
+<func>
+<name>Mod:handle_answer(Packet, Request, SvcName, Peer) -> Result</name>
+<fsummary>Receive an answer message from a peer.</fsummary>
+<type>
+<v>Packet  = packet()</v>
+<v>Request = message()</v>
+<v>SvcName = service_name()</v>
+<v>Peer    = peer()</v>
+<v>Result  = term()</v>
+</type>
+<desc>
+<p>
+Invoked when an answer message is received from a peer.
+The return value is returned from the call to <seealso
+marker="diameter#call">diameter:call/4</seealso> for which the
+callback takes place.</p>
+
+<p>
+The decoded answer record is in the <c>msg</c> field of <c>Packet</c>,
+the undecoded binary in the <c>packet</c> field.
+<c>Request</c> is the outgoing request message as was returned from
+<seealso marker="#prepare_request">prepare_request/3</seealso> or
+<seealso marker="#prepare_retransmit">prepare_retransmit/3</seealso>
+before the request was passed to the transport.</p>
+
+<p>
+For any given call to <seealso
+marker="diameter#call">diameter:call/4</seealso> there is at most one
+call to the handle_answer callback of the application in question: any
+duplicate answer (due to retransmission or otherwise) is discarded.
+Similarly, only one of <c>handle_answer/4</c> or <c>handle_error/4</c> is
+called for any given request.</p>
+
+<p>
+By default, an incoming answer message that cannot be successfully
+decoded causes the request process in question to fail, causing the
+relevant call to <seealso
+marker="diameter#call">diameter:call/4</seealso>
+to return <c>{error, failure}</c>.
+There is no <c>handle_error/4</c> callback in this case.
+Application configuration may change this behaviour as described for
+<seealso
+marker="diameter#start_service">diameter:start_service/2</seealso>.</p>
+
+<marker id="handle_error"/>
+</desc>
+</func>
+
+<func>
+<name>Mod:handle_error(Reason, Request, SvcName, Peer) -> Result</name>
+<fsummary>Return an error from a outgoing request.</fsummary>
+<type>
+<v>Reason  = timeout | failover | term()</v>
+<v>Request = message()</v>
+<v>SvcName = service_name()</v>
+<v>Peer    = peer()</v>
+<v>Result  = term()</v>
+</type>
+<desc>
+<p>
+Invoked when an error occurs before an answer message is received from
+a peer in response to an outgoing request.
+The return value is returned from the call to <seealso
+marker="diameter#call">diameter:call/4</seealso> for which the
+callback takes place.</p>
+
+<p>
+Reason <c>timeout</c> indicates that an answer message has not been
+received within the required time.
+Reason <c>failover</c> indicates
+that the transport connection to the peer to which the request has
+been sent has been lost but that not alternate node was available,
+possibly because a <seealso marker="#pick_peer">pick_peer/4</seealso>
+callback returned false.
+</p>
+
+<marker id="handle_request"/>
+</desc>
+</func>
+
+<func>
+<name>Mod:handle_request(Packet, SvcName, Peer) -> Action</name>
+<fsummary>Receive an incoming request.</fsummary>
+<type>
+<v>Packet  = packet()</v>
+<v>SvcName = term()</v>
+<v>Peer    = peer()</v>
+<v>Action  = Reply | NoReply | Relay | {eval, Action, ContF}</v>
+<v>Reply   = {reply, message()}
+           | {protocol_error, ResultCode}</v>
+<v>NoReply = discard</v>
+<v>Relay   = {relay, Opts}</v>
+<v>Opts    = list()</v>
+<v>ContF   = diameter:evaluable()</v>
+<v>ResultCode = 3000..3999</v>
+</type>
+<desc>
+<p>
+Invoked when a request message is received from a peer.</p>
+
+<p>
+The application in which the callback takes place (that is, the
+callback module as configured with <seealso
+marker="diameter#start_service">diameter:start_service/2</seealso>)
+is determined by the Application Identifier in the header of the
+incoming Diameter request message, the selected module being the one
+whose corresponding <seealso
+marker="diameter_dict#MESSAGE_RECORDS">dictionary</seealso> declares
+itself as defining the application in question, or the RFC 3588 relay
+application if the specific application is unsupported but the relay
+application has been advertised.</p>
+
+<p>
+The packet() in which the incoming request is communicated has the
+following signature.</p>
+
+<code>
+#diameter_packet{header = #diameter_header{},
+                 avps   = [#diameter_avp{}],
+                 msg    = record() | undefined,
+                 errors = [integer() | {integer(), #diameter_avp{}}],
+                 bin    = binary(),
+                 transport_data = term()}
+</code>
+
+<p>
+The <c>msg</c> field will be <c>undefined</c> only in case the request has
+been received in the relay application.
+Otherwise it contains the record representing the request as outlined
+in <seealso
+marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>.</p>
+
+<p>
+The <c>errors</c> field specifies any non-protocol errors that were
+encountered in decoding the request and can be returned in a
+<c>reply</c> tuple to have diameter set the Result-Code and Failed-AVP
+AVP's appropriately.
+The list is empty if the request has been received in the relay
+application.</p>
+
+<p>
+The <c>transport_data</c> field contains an arbitrary term passed into
+diameter from the transport module in question, or the atom
+<c>undefined</c> if the transport specified no data.
+The term is preserved in the packet() containing any answer message
+sent back to the transport process unless another value is explicitly
+specified.</p>
+
+<p>
+The semantics of each of the possible return values are as follows.
+(TODO: more.)</p>
+
+<taglist>
+
+<tag><c>{reply, Answer}</c></tag>
+<item>
+<p>
+Send the specified answer message to the peer.</p>
+</item>
+
+<tag><c>{relay, Opts}</c></tag>
+<item>
+<p>
+Relay a request to another peer.</p>
+</item>
+
+<tag><c>{protocol_error, ResultCode}</c></tag>
+<item>
+<p>
+Send an answer message to the peer containing the specified 3xxx
+protocol error.</p>
+
+<p>
+RFC 3588 mandates that only answers with a 3xxx series
+Result-Code (protocol errors) may set the E bit.
+Returning a non-3xxx value in a <c>{protocol_error, ResultCode}</c>
+tuple will cause the request process in question to fail.</p>
+</item>
+
+<tag><c>discard</c></tag>
+<item>
+<p>
+Discard the request.</p>
+</item>
+
+<tag><c>{eval, Action, ContF}</c></tag>
+<item>
+<p>
+Handle the request as if <c>Action</c> has been returned and then
+evaluate the evaluable() <c>ContF</c> in the request process.</p>
+</item>
+
+</taglist>
+
+<p>
+Note that diameter will respond to protocol errors in an incoming
+request without invoking the a <c>handle_request/3</c> callback.</p>
+
+</desc>
+</func>
+
+</funcs>
+
+</erlref>
diff --git a/lib/diameter/doc/src/diameter_compile.xml b/lib/diameter/doc/src/diameter_compile.xml
new file mode 100644
index 0000000000..72bac30709
--- /dev/null
+++ b/lib/diameter/doc/src/diameter_compile.xml
@@ -0,0 +1,124 @@
+<?xml version="1.0" encoding="iso-8859-1" ?>
+<!DOCTYPE comref SYSTEM "comref.dtd">
+
+<comref>
+<header>
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+<legalnotice>
+
+The program may be used and/or copied only with the written permission 
+from Ericsson AB, or in accordance with the terms and conditions 
+stipulated in the agreement/contract under which the program has been 
+supplied.
+
+</legalnotice>
+
+<title>diameterc(1)</title>
+
+<prepared></prepared>
+<docno></docno>
+<date></date>
+<rev></rev>
+<file>diameter_compile.xml</file>
+</header>
+
+<com>diameterc</com>
+<comsummary><![CDATA[diameterc [<options>] <file>]]></comsummary>
+
+<description>
+
+<p>
+The diameterc utility is used to transform diameter
+<seealso marker="diameter_dict">dictionary files</seealso>
+into Erlang source.
+The resulting source implements the interface diameter requires
+to encode and decode the dictionary's messages and AVP's.</p>
+
+</description>
+
+<section>
+<title>USAGE</title>
+
+<taglist>
+
+<tag><![CDATA[diameterc [<options>] <file>]]></tag>
+<item>
+<p>
+Transforms a single dictionary file. Valid options are as follows.</p>
+
+<!-- Leave -h/d/v undocumented, except for the usage message from the
+     utility itself. -->
+
+<taglist>
+<tag><![CDATA[-o <dir>]]></tag>
+<item>
+<p>
+Specifies the directory into which the generated source should be written.
+Defaults to the current working directory.</p>
+</item>
+
+<tag><![CDATA[-i <dir>]]></tag>
+<item>
+<p>
+Specifies a directory to add to the code path.
+Typically used to point at beam files corresponding to dictionaries
+included by the one being compiled (using the <c>@includes</c> directive):
+inclusion is a beam dependency, not an erl/hrl dependency.</p>
+
+<p>
+Multiple <c>-i</c> options can be specified.</p>
+</item>
+
+<tag><![CDATA[-E]]></tag>
+<item>
+<p>
+Supresses erl generation.</p>
+</item>
+
+<tag><![CDATA[-H]]></tag>
+<item>
+<p>
+Supresses hrl generation.</p>
+</item>
+
+</taglist>
+
+</item>
+</taglist>
+
+</section>
+
+<!-- ===================================================================== -->
+
+<section>
+<title>EXIT STATUS</title>
+
+<p>
+Returns 0 on success, non-zero on failure.</p>
+
+</section>
+
+<!-- ===================================================================== -->
+
+<section>
+<title>BUGS</title>
+
+<p>
+The identification of errors in the source file is poor.</p>
+
+</section>
+
+<!-- ===================================================================== -->
+
+<section>
+<title>SEE ALSO</title>
+
+<p>
+<seealso marker="diameter_dict">diameter_dict(4)</seealso></p>
+
+</section>
+
+</comref>
diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml
new file mode 100644
index 0000000000..5bc3cab9e4
--- /dev/null
+++ b/lib/diameter/doc/src/diameter_dict.xml
@@ -0,0 +1,601 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "fileref.dtd">
+
+<fileref>
+<header>
+
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+<legalnotice>
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+    
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+    
+</legalnotice>
+
+<title>diameter_dict(4)</title>
+<prepared>Anders Svensson</prepared>
+<responsible></responsible>
+<docno></docno>
+<approved></approved>
+<checked></checked>
+<date></date>
+<rev>%VSN%</rev>
+<file>diameter_dict.xml</file>
+</header>
+
+<!-- ===================================================================== -->
+
+<file>diameter_dict</file>
+<filesummary>Dictionary inteface of the diameter application.</filesummary>
+
+<description>
+<p>
+A diameter service as configured with <seealso
+marker="diameter#start_service">diameter:start_service/2</seealso>
+specifies one or more supported Diameter applications.
+Each Diameter application specifies a dictionary module that knows how
+to encode and decode its messages and AVP's.
+The dictionary module is in turn generated from a file that defines
+these messages and AVP's.
+The format of such a file is defined in
+<seealso marker="#FILE_FORMAT">FILE FORMAT</seealso> below.</p>
+
+<p>
+The codec generation also results in an hrl that defines records
+for the messages and grouped AVP's defined for the application, these
+records being what a user of the diameter application sends and
+receives.
+These records and the underlying Erlang data types corresponding to
+Diameter data formats are discussed in <seealso
+marker="#MESSAGE_RECORDS">MESSAGE RECORDS</seealso> and <seealso
+marker="#DATA_TYPES">DATA TYPES</seealso> respectively.</p>
+
+<!-- TODO: Need some reserved dictionary for agents that shouldn't -->
+<!--       know about specific applications. -->
+
+<p>
+The diameter application defines the base application of RFC 3588 in
+the file diameter_gen_base_rfc3588.dia, and
+this is the only application that diameter itself has any specific
+knowledge of.
+Other applications are callback modules configured for an application
+as far as diameter is concerned.</p>
+
+<p>
+A generated hrl also contains defines for the values of defined for
+AVPs of type Enumerated.</p>
+
+<p>
+See <seealso marker="diameter_compile">diameterc</seealso> for a
+utility that transforms dictionary files into codec modules needed
+at runtime.</p>
+
+<marker id="FILE_FORMAT"/>
+</description>
+
+<!-- ===================================================================== -->
+
+<section>
+<title>FILE FORMAT</title>
+
+<p>
+A specification file consists of distinct sections.
+Each section starts with a line consisting of a tag
+followed by zero or more arguments.
+Each section ends at the the start of the next section or end of file.
+Tags consist of an ampersand character followed by a keyword and are
+separated from their arguments by whitespace.
+Whitespace within a section separates individual tokens but its
+quantity is insignificant.</p>
+
+<p>
+The tags, their arguments and the contents of each corresponding
+section are as follows.
+Each section can occur only once unless otherwise specified.
+The order in which sections are specified is unimportant.</p>
+
+<taglist>
+
+<tag><c>@id Number</c></tag>
+<item>
+<p>
+Defines the integer Number as the Diameter Application Id of the
+application in question.
+The section has empty content.</p>
+
+<p>
+The Application Id is set in the Diameter Header of outgoing messages
+of the application, and the value in the header of an incoming message
+is used to identify the relevant dictionary module.</p>
+
+<p>
+Example:</p>
+
+<code>
+@id 16777231
+</code>
+
+</item>
+
+<tag><c>@name Mod</c></tag>
+<item>
+<p>
+Defines the name of the generated dictionary module.
+The section has empty content.
+Mod must match the regular expression '^[a-zA-Z0-9][-_a-zA-Z0-9]*$';
+that is, contains only alphanumerics, hyphens and underscores begin with an
+alphanumeric.</p>
+
+<p>
+A name is optional and defaults to the name of the dictionary file
+minus any extension.
+Note that a generated module must have a unique name an not colide
+with another module in the system.</p>
+
+<p>
+Example:</p>
+
+<code>
+@name etsi_e2
+</code>
+
+</item>
+
+<tag><c>@prefix Name</c></tag>
+<item>
+<p>
+Defines Name as the prefix to be added to record and constant names in
+the generated dictionary module and hrl.
+The section has empty content.
+Name must be of the same form as a @name.</p>
+
+<p>
+A prefix is optional but can
+be used to disambiguate record and constant names
+resulting from similarly named messages and AVP's in different
+Diameter applications.</p>
+
+<p>
+Example:</p>
+
+<code>
+@prefix etsi_e2_
+</code>
+
+</item>
+
+<tag><c>@vendor Number Name</c></tag>
+<item>
+<p>
+Defines the integer Number as the the default Vendor-ID of AVP's for
+which the V flag is set.
+Name documents the owner of the application
+but is otherwise unused.
+The section has empty content.</p>
+
+<p>
+Example:</p>
+
+<code>
+@vendor 13019 ETSI
+</code>
+
+</item>
+
+<tag><c>@avp_vendor_id Number</c></tag>
+<item>
+<p>
+Defines the integer Number as the Vendor-ID of the AVP's listed in the
+section content, overriding the <c>@vendor</c> default.
+The section content consists of AVP names.
+Can occur zero or more times (with different values of Number).</p>
+
+<p>
+Example:</p>
+
+<code>
+@avp_vendor_id 2937
+
+WWW-Auth
+Domain-Index
+Region-Set
+</code>
+
+</item>
+
+<tag><c>@inherits Mod</c></tag>
+<item>
+<p>
+Defines the name of a generated dictionary module containing AVP
+definitions referenced by the dictionary but not defined by it.
+The section content is empty.</p>
+
+<p>
+Can occur 0 or more times (with different values of Mod) but all
+dictionaries should typically inherit RFC3588 AVPs from
+diameter_gen_base_rfc3588.</p>
+
+<p>
+Example:</p>
+
+<code>
+@inherits diameter_gen_base_rfc3588
+</code>
+
+</item>
+
+<tag><c>@avp_types</c></tag>
+<item>
+<p>
+Defines the name, code, type and flags of individual AVPs.
+The section consists of definitions of the form</p>
+
+<p><c>Name Code Type Flags</c></p>
+
+<p>
+where Code is the integer AVP code, Flags is a string of V,
+M and P characters indicating the flags to be
+set on an outgoing AVP or a single - (minus) character if none are to
+be set.
+Type identifies either an AVP Data Format as defined in <seealso
+marker="DATA_TYPES">DATA TYPES</seealso> below or a
+type as defined by a <c>@custom_types</c> tag.</p>
+
+<p>
+Example:</p>
+
+<code>
+@avp_types
+
+Location-Information   350  Grouped     VM
+Requested-Information  353  Enumerated  V
+</code>
+
+<p>
+Note that the P flag has been deprecated by the Diameter Maintenance
+and Extensions Working Group of the IETF.</p>
+
+</item>
+
+<tag><c>@custom_types Mod</c></tag>
+<item>
+<p>
+Defines AVPs for which module Mod provides encode/decode.
+The section contents consists of type names.
+For each AVP Name defined with custom type Type, Mod should export the
+function Name/3 with arguments encode|decode, Type and Data,
+the latter being the term to be encoded/decoded.
+The function returns the encoded/decoded value.</p>
+
+<p>
+Can occur 0 or more times (with different values of Mod).</p>
+
+<p>
+Example:</p>
+
+<code>
+@custom_types rfc4005_types
+
+Framed-IP-Address
+</code>
+</item>
+
+<tag><c>@messages</c></tag>
+<item>
+<p>
+Defines the messages of the application.
+The section content consists of definitions of the form specified in
+section 3.2 of RFC 3588, "Command Code ABNF specification".</p>
+
+<!-- RFC 4740 RTR/RTA -->
+<code>
+@messages
+
+RTR ::= &lt; Diameter Header: 287, REQ, PXY >
+        &lt; Session-Id >
+        { Auth-Application-Id }
+        { Auth-Session-State }
+        { Origin-Host }
+        { Origin-Realm }
+        { Destination-Host }
+        { SIP-Deregistration-Reason }
+        [ Destination-Realm ]
+        [ User-Name ]
+      * [ SIP-AOR ]
+      * [ Proxy-Info ]
+      * [ Route-Record ]
+      * [ AVP ]
+
+RTA ::= &lt; Diameter Header: 287, PXY >
+        &lt; Session-Id >
+        { Auth-Application-Id }
+        { Result-Code }
+        { Auth-Session-State }
+        { Origin-Host }
+        { Origin-Realm }
+        [ Authorization-Lifetime ]
+        [ Auth-Grace-Period ]
+        [ Redirect-Host ]
+        [ Redirect-Host-Usage ]
+        [ Redirect-Max-Cache-Time ]
+      * [ Proxy-Info ]
+      * [ Route-Record ]
+      * [ AVP ]
+</code>
+
+</item>
+
+<tag><c>@grouped</c></tag>
+<item>
+<p>
+Defines the contents of the AVPs of the application having type
+Grouped.
+The section content consists of definitions of the form specified in
+section 4.4 of RFC 3588, "Grouped AVP Values".</p>
+
+<p>
+Example:</p>
+
+<code>
+@grouped
+
+SIP-Deregistration-Reason ::= &lt; AVP Header: 383 >
+                              { SIP-Reason-Code }
+                              [ SIP-Reason-Info ]
+                            * [ AVP ]
+</code>
+</item>
+
+<tag><c>@enum Name</c></tag>
+<item>
+<p>
+Defines values of AVP Name having type Enumerated.
+Section content consists of names and corresponding integer values.
+Integer values can be prefixed with 0x to be interpreted as
+hexidecimal.</p>
+
+<p>
+Can occur 0 or more times (with different values of Name).</p>
+
+<p>
+Example:</p>
+
+<code>
+@enum SIP-Reason-Code
+
+PERMANENT_TERMINATION    0
+NEW_SIP_SERVER_ASSIGNED  1
+SIP_SERVER_CHANGE        2
+REMOVE_SIP_SERVER        3
+</code>
+</item>
+
+</taglist>
+
+<p>
+Comments can be included in a dictionary file using semicolon:
+text from a semicolon to end of line is ignored.</p>
+
+<marker id="MESSAGE_RECORDS"/>
+</section>
+
+<!-- ===================================================================== -->
+
+<section>
+<title>MESSAGE RECORDS</title>
+
+<p>
+The hrl generated from a dictionary specification defines records for the
+messages and grouped AVPs defined in <c>@messages</c> and
+<c>@grouped</c> sections.
+For each message or grouped AVP definition, a record is defined whose
+name is the message or AVP name prefixed with any dictionary prefix
+defined with <c>@prefix</c> and whose fields are the names of the AVPs
+contained in the message or grouped AVP in the order specified in the
+definition in question.
+For example, the grouped AVP</p>
+
+<code>
+SIP-Deregistration-Reason ::= &lt; AVP Header: 383 >
+                              { SIP-Reason-Code }
+                              [ SIP-Reason-Info ]
+                            * [ AVP ]
+</code>
+
+<p>
+will result in the following record definition given an empty
+prefix.</p>
+
+<code>
+-record('SIP-Deregistration-Reason' {'SIP-Reason-Code',
+                                     'SIP-Reason-Info',
+                                     'AVP'}).
+</code>
+
+<p>
+The values encoded in the fields of generated records depends on the
+type and number of times the AVP can occur.
+In particular, an AVP which is specified as occurring exactly once is
+encoded as a value of the AVP's type while an AVP with any other
+specification is encoded as a list of values of the AVP's type.
+The AVP's type is as specified in the AVP definition, the RFC 3588
+types being described below.</p>
+
+<marker id="DATA_TYPES"/>
+</section>
+
+<!-- ===================================================================== -->
+
+<section>
+<title>DATA TYPES</title>
+
+<p>
+The data formats defined in sections 4.2 ("Basic AVP Data
+Formats") and 4.3 ("Derived AVP Data Formats") of RFC 3588 are encoded
+as values of the types defined here.
+Values are passed to <seealso
+marker="diameter#call">diameter:call/4</seealso>
+in a request record when sending a request, returned in a resulting
+answer record and passed to a diameter_app(3) <seealso
+marker="diameter_app#handle_request">handle_request</seealso>
+callback upon reception of an incoming request.</p>
+
+<p>
+<em>Basic AVP Data Formats</em></p>
+
+<marker id="OctetString"/>
+<marker id="Integer32"/>
+<marker id="Integer64"/>
+<marker id="Unsigned32"/>
+<marker id="Unsigned64"/>
+<marker id="Float32"/>
+<marker id="Float64"/>
+<marker id="Grouped"/>
+
+<code>
+OctetString() = [0..255]
+Integer32()   = -2147483647..2147483647
+Integer64()   = -9223372036854775807..9223372036854775807
+Unsigned32()  = 0..4294967295
+Unsigned64()  = 0..18446744073709551615
+Float32()     = '-infinity' | float() | infinity
+Float64()     = '-infinity' | float() | infinity
+Grouped()     = record()
+</code>
+
+<p>
+On encode, an OctetString() can be specified as an iolist(),
+excessively large floats (in absolute value) are equivalent to
+infinity or '-infinity' and excessively large integers result in
+encode failure.
+The records for grouped AVPs are as discussed in the previous
+section.</p>
+
+<p>
+<em>Derived AVP Data Formats</em></p>
+
+<marker id="Address"/>
+<code>
+Address() = OctetString()
+          | tuple()
+</code>
+
+<p>
+On encode, an OctetString() IPv4 address is parsed in the usual
+x.x.x.x format while an IPv6 address is parsed in any of the formats
+specified by section  2.2 of RFC 2373, "Text Representation of
+Addresses".
+An IPv4 tuple() has length 4 and contains values of type 0..255.
+An IPv6 tuple() has length 8 and contains values of type 0..65535.
+The tuple representation is used on decode.</p>
+
+<marker id="Time"/>
+<code>
+Time() = {date(), time()}
+
+where
+
+  date() = {Year, Month, Day}
+  time() = {Hour, Minute, Second}
+
+  Year   = integer()
+  Month  = 1..12
+  Day    = 1..31
+  Hour   = 0..23
+  Minute = 0..59
+  Second = 0..59
+</code>
+
+<p>
+Additionally, values that can be encoded are
+limited by way of their encoding as four octets as required by RFC
+3588 with the required extension from RFC 2030.
+In particular, only values between <c>{{1968,1,20},{3,14,8}}</c>
+and <c>{{2104,2,26},{9,42,23}}</c> (both inclusive) can be encoded.</p>
+
+<marker id="UTF8String"/>
+<code>
+UTF8String() = [integer()]
+</code>
+
+<p>
+List elements are the UTF-8 encodings of the individual characters
+in the string.
+Invalid codepoints will result in encode/decode failure.</p>
+
+<marker id="DiameterIdentity"/>
+<code>
+DiameterIdentity() = OctetString()
+</code>
+
+<p>
+A value must have length at least 1.</p>
+
+<marker id="DiameterURI"/>
+<code>
+DiameterURI() = OctetString()
+              | #diameter_URI{type = Type,
+                              fqdn = FQDN,
+                              port = Port,
+                              transport = Transport,
+                              protocol  = Protocol}
+
+where
+
+  Type = aaa | aaas
+  FQDN = OctetString()
+  Port = integer()
+  Transport = sctp | tcp
+  Protocol  = diameter | radius | 'tacacs+'
+</code>
+
+<p>
+On encode, fields port, transport and protocol default to 3868, sctp
+and diameter respectively.
+The grammar of an OctetString-valued DiameterURI() is as specified in
+section 4.3 of RFC 3588.
+The record representation is used on decode.</p>
+
+<marker id="Enumerated"/>
+<code>
+Enumerated() = Integer32()
+</code>
+
+<p>
+On encode, values can be specified using the macros defined in a
+dictionary's hrl file.</p>
+
+<marker id="IPFilterRule"/>
+<marker id="QoSFilterRule"/>
+<code>
+IPFilterRule()  = OctetString()
+QoSFilterRule() = OctetString()
+</code>
+
+<p>
+Values of these types are not parsed by diameter.</p>
+
+</section>
+
+<!-- ===================================================================== -->
+<!-- ===================================================================== -->
+
+<section>
+<title>SEE ALSO</title>
+
+<p>
+<seealso marker="diameter_util">diameterc(1)</seealso></p>
+
+</section>
+
+</fileref>
diff --git a/lib/diameter/doc/src/diameter_examples.xml b/lib/diameter/doc/src/diameter_examples.xml
new file mode 100644
index 0000000000..344b237866
--- /dev/null
+++ b/lib/diameter/doc/src/diameter_examples.xml
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+<header>
+
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+
+<legalnotice>
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+
+</legalnotice>
+
+<title>Examples</title>
+<prepared></prepared>
+<responsible></responsible>
+<docno></docno>
+<approved></approved>
+<checked></checked>
+<date></date>
+<rev></rev>
+<file>diameter_examples.xml</file>
+</header>
+
+<!-- ===================================================================== -->
+
+</chapter>
+
diff --git a/lib/diameter/doc/src/diameter_intro.xml b/lib/diameter/doc/src/diameter_intro.xml
new file mode 100644
index 0000000000..0009b2b77d
--- /dev/null
+++ b/lib/diameter/doc/src/diameter_intro.xml
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+<header>
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+
+<legalnotice>
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+    
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+    
+</legalnotice>
+
+<title>Introduction</title>
+<prepared></prepared>
+<responsible></responsible>
+<docno></docno>
+<approved></approved>
+<checked></checked>
+<date></date>
+<rev></rev>
+<file>diameter_intro.xml</file>
+</header>
+
+<p>
+The diameter application is an implementation of the Diameter protocol
+as defined by RFC 3588.
+It supports arbitrary Diameter applications by allowing a client to
+specify the commands and AVP's to be supported and has support for
+implementing all roles defined in the RFC: client, server and agent.
+</p>
+
+</chapter>
+
diff --git a/lib/diameter/doc/src/diameter_sctp.xml b/lib/diameter/doc/src/diameter_sctp.xml
new file mode 100644
index 0000000000..d0377f4b38
--- /dev/null
+++ b/lib/diameter/doc/src/diameter_sctp.xml
@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+<header>
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+<legalnotice>
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+
+</legalnotice>
+
+<title>diameter_sctp(3)</title>
+<prepared>Anders Svensson</prepared>
+<responsible></responsible>
+<docno></docno>
+<approved></approved>
+<checked></checked>
+<date></date>
+<rev></rev>
+<file>diameter_sctp.xml</file>
+</header>
+
+<module>diameter_sctp</module>
+<modulesummary>Diameter transport over SCTP.</modulesummary>
+
+<description>
+
+<p>
+This module implements diameter transport over SCTP using gen_sctp.
+It can be specified as the value of a transport_module option to
+<seealso
+marker="diameter#add_transport">diameter:add_transport/2</seealso>
+and implements the behaviour documented in
+<seealso marker="diameter_transport">diameter_transport(3)</seealso>.</p>
+
+<marker id="start"/>
+</description>
+
+<!-- ===================================================================== -->
+
+<funcs>
+
+<func>
+<name>start({Type, Ref}, Svc, [Opt])
+         -> {ok, Pid, [LAddr]} | {error, Reason}</name>
+<fsummary>Start a transport process.</fsummary>
+<type>
+<v>Type = connect | accept</v>
+<v>Ref = reference()</v>
+<v>Svc = #diameter_service{}</v>
+<v>Opt = {raddr, ip_address()} | {rport, integer()} | term()</v>
+<v>Pid = pid()</v>
+<v>LAddr = ip_address()</v>
+<v>Reason = term()</v>
+</type>
+<desc>
+
+<p>
+The start function required by <seealso
+marker="diameter_transport#start">diameter_transport(3)</seealso>.</p>
+
+<p>
+The only diameter_sctp-specific argument is the options list.
+Options <c>raddr</c> and <c>rport</c> specify the remote address
+and port for a connector and not valid for a listener.
+The former is required while latter defaults to 3868 if unspecified.
+More than one <c>raddr</c> option can be specified, in which case the
+connector in question attempts each in sequence until an association
+is established.
+Remaining options are any accepted by gen_sctp:open/1, with the exception
+of options <c>mode</c>, <c>binary</c>, <c>list</c>, <c>active</c>
+and <c>sctp_events</c>.
+Note that options <c>ip</c> and <c>port</c> specify the local address
+and port respectively.</p>
+
+<p>
+Multiple <c>ip</c> options can be specified for a multihomed peer.
+If none are specified then the values of Host-IP-Address
+on the service are used. (In particular, one of these must be specified.)
+Option <c>port</c> defaults to 3868 for a listener and 0 for a connector.</p>
+
+<p>
+diameter_sctp uses the <c>transport_data</c> field of
+the <c>diameter_packet</c> record to communicate the stream on which an
+inbound message has been received, or on which an outbound message
+should be sent: the value will be of the form <c>{stream, Id}</c>
+on an inbound message passed to a <seealso
+marker="diameter_app#handle_request">handle_request</seealso> or <seealso
+marker="diameter_app#handle_answer">handle_answer</seealso> callback.
+For an outbound message, either <c>undefined</c> (explicitly of
+by specifying the outbound message as a <c>binary()</c>) or a tuple
+should be set in the return value of <seealso
+marker="diameter_app#handle_request">handle_request</seealso>
+(typically by retaining the value passed into this function)
+or <seealso
+marker="diameter_app#prepare_request">prepare_request</seealso>.
+The value <c>undefined</c> uses a "next outbound stream" id and then
+increments this modulo the total number outbound streams. That
+is, successive values of <c>undefined</c> cycle through all outbound
+streams.</p>
+
+<!-- TODO: Some way of getting at the number of available outbound -->
+<!--       streams.                                                -->
+
+</desc>
+</func>
+
+</funcs>
+
+<!-- ===================================================================== -->
+<!-- ===================================================================== -->
+
+<section>
+<title>SEE ALSO</title>
+
+<p>
+<seealso marker="diameter_transport">diameter_transport(3)</seealso></p>
+
+</section>
+
+</erlref>
diff --git a/lib/diameter/doc/src/diameter_soc.xml b/lib/diameter/doc/src/diameter_soc.xml
new file mode 100644
index 0000000000..4f8581a904
--- /dev/null
+++ b/lib/diameter/doc/src/diameter_soc.xml
@@ -0,0 +1,110 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+
+<header>
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+
+<legalnotice>
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+
+</legalnotice>
+
+<title>Standards Compliance</title>
+<prepared></prepared>
+<responsible></responsible>
+<docno></docno>
+<approved></approved>
+<checked></checked>
+<date></date>
+<rev></rev>
+<file>diameter_soc.xml</file>
+
+</header>
+
+<p>
+Known points of questionable or non-compliance.</p>
+
+<!-- ===================================================================== -->
+
+<section>
+<title>RFC 3588</title>
+
+<list>
+
+<item>
+<p>
+The End-to-End Security framework (section 2.9) isn't implemented
+since it is largely unspecified.
+The document that was to describe it
+(reference [AAACMS]) was abandoned in an uncompleted state several
+years ago and the current draft RFC deprecates the framework,
+including the P Flag in the AVP header.</p>
+</item>
+
+<item>
+<p>
+There is no TLS support.
+It's unclear (aka uninvestigated) how TLS would impact
+diameter but IPsec can be used without it needing to know.</p>
+</item>
+
+<item>
+<p>
+There is no explicit support for peer discovery (section 5.2).
+It can possibly be implemented on top of diameter as is but this is
+probably something that diameter should do.
+The current draft deprecates portions of the original RFC's mechanisms
+however.</p>
+</item>
+
+<item>
+<p>
+The peer state machine's election process (section 5.6.4) isn't
+implemented as specified since it assumes knowledge of a
+peer's Origin-Host before sending it a CER. (The identity becoming known
+upon reception of CEA.)
+The possibility of configuring
+the peer's Origin-Host could be added, along with handling of the case
+that it sends something else, but for many applications this will
+just be unnecessary configuration of a value that it has no control over.</p>
+</item>
+<!-- Transport protocol plus address/port, which we do know when
+     sending and receiving CER, is enough to definitely identify
+     the peer. However, there's nothing stopping a peer from using
+     different identities on different transport protocols, even
+     if it's maybe a bit far-fetched. -->
+
+</list>
+
+</section>
+
+<!-- ===================================================================== -->
+
+<section>
+<title>RFC 3539</title>
+
+<p>
+RFC 3539 is more difficult to comply to since it discusses
+problems as much as it requires functionality but all the MUST's are
+covered, the watchdog state machine being the primary one.
+Of the optional functionality, load balancing is left to the
+diameter user (since it's the one deciding who to send to) and
+there is no Congestion Manager.</p>
+
+</section>
+
+</chapter>
diff --git a/lib/diameter/doc/src/diameter_tcp.xml b/lib/diameter/doc/src/diameter_tcp.xml
new file mode 100644
index 0000000000..5d6e07b1b8
--- /dev/null
+++ b/lib/diameter/doc/src/diameter_tcp.xml
@@ -0,0 +1,110 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+<header>
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+<legalnotice>
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+
+</legalnotice>
+
+<title>diameter_tcp(3)</title>
+<prepared>Anders Svensson</prepared>
+<responsible></responsible>
+<docno></docno>
+<approved></approved>
+<checked></checked>
+<date></date>
+<rev></rev>
+<file>diameter_tcp.xml</file>
+</header>
+
+<module>diameter_tcp</module>
+<modulesummary>Diameter transport over TCP.</modulesummary>
+
+<description>
+
+<p>
+This module implements diameter transport over TCP using gen_tcp.
+It can be specified as the value of a transport_module option to
+<seealso
+marker="diameter#add_transport">diameter:add_transport/2</seealso>
+and implements the behaviour documented in
+<seealso marker="diameter_transport">diameter_transport(3)</seealso>.</p>
+
+<marker id="start"/>
+</description>
+
+<!-- ===================================================================== -->
+
+<funcs>
+
+<func>
+<name>start({Type, Ref}, Svc, [Opt])
+         -> {ok, Pid, [LAddr]} | {error, Reason}</name>
+<fsummary>Start a transport process.</fsummary>
+<type>
+<v>Type = connect | accept</v>
+<v>Ref = reference()</v>
+<v>Svc = #diameter_service{}</v>
+<v>Opt = {raddr, ip_address()} | {rport, integer()} | term()</v>
+<v>Pid = pid()</v>
+<v>LAddr = ip_address()</v>
+<v>Reason = term()</v>
+</type>
+<desc>
+
+<p>
+The start function required by <seealso
+marker="diameter_transport#start">diameter_transport(3)</seealso>.</p>
+
+<p>
+The only diameter_tcp-specific argument is the options list.
+Options <c>raddr</c> and <c>rport</c> specify the remote address
+and port for a connector and not valid for a listener.
+Remaining options are any accepted by gen_tcp:connect/3 for
+a connector, or gen_tcp:listen/2 for a listener, with the exception
+of <c>binary</c>, <c>packet</c> and <c>active</c>.
+Also, option <c>port</c> can be specified for a listener to specify the
+local listening port, the default being the standardized 3868 if
+unspecified.
+Note that option <c>ip</c> specifies the local address.</p>
+
+<p>
+If the service specifies more than one Host-IP-Address and
+option <c>ip</c> is unspecified then then the
+first of the service's addresses is used as the local address.</p>
+
+<p>
+The returned local address list has length one.</p>
+
+</desc>
+</func>
+
+</funcs>
+
+<!-- ===================================================================== -->
+<!-- ===================================================================== -->
+
+<section>
+<title>SEE ALSO</title>
+
+<p>
+<seealso marker="diameter_transport">diameter_transport(3)</seealso></p>
+
+</section>
+
+</erlref>
diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml
new file mode 100644
index 0000000000..be1bb2c56e
--- /dev/null
+++ b/lib/diameter/doc/src/diameter_transport.xml
@@ -0,0 +1,203 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+<header>
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+<legalnotice>
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+
+</legalnotice>
+
+<title>diameter_transport(3)</title>
+<prepared>Anders Svensson</prepared>
+<responsible></responsible>
+<docno></docno>
+<approved></approved>
+<checked></checked>
+<date></date>
+<rev></rev>
+<file>diameter_transport.xml</file>
+</header>
+
+<module>diameter_transport</module>
+<modulesummary>Diameter transport behaviour.</modulesummary>
+
+<description>
+
+<p>
+A module specified as a <c>transport_module</c> to <seealso
+marker="diameter#add_transport">diameter:add_transport/2</seealso>
+must implement the interface documented here.
+The interface consists of a function with which
+diameter starts a transport process and a message interface with which
+the transport process communicates with the process that starts it (aka its
+parent).</p>
+
+<marker id="start"/>
+</description>
+
+<!-- ===================================================================== -->
+
+<funcs>
+
+<func>
+<name>Mod:start({Type, Ref}, Svc, Opts)
+         -> {ok, Pid} | {ok, Pid, LAddrs} | {error, Reason}</name>
+<fsummary>Start a transport process.</fsummary>
+<type>
+<v>Type = connect | accept</v>
+<v>Ref = reference()</v>
+<v>Svc = #diameter_service{}</v>
+<v>Opts = term()</v>
+<v>Pid = pid()</v>
+<v>LAddrs = [ip_address()]</v>
+<v>Reason = term()</v>
+</type>
+<desc>
+<p>
+Start a transport process.
+Called by diameter as a consequence of a call to <seealso
+marker="diameter#add_transport">diameter:add_transport/2</seealso> in
+order to establish or accept a transport connection respectively.
+A transport process maintains a connection with a single remote peer.</p>
+
+<p>
+The first argument indicates whether the transport process in question
+is being started for a connecting (<c>connect</c>) or listening
+(<c>accept</c>) transport.
+In the latter case, transport processes are started as required to
+accept connections from multiple peers.
+Ref is in each case the same value that was returned from the
+call to <seealso
+marker="diameter#add_transport">diameter:add_transport/2</seealso>
+that has lead to starting of a transport process.</p>
+
+<p>
+A transport process must implement the message interface documented below.
+It should retain the pid of its parent, monitor the parent and terminate if
+it dies.
+It should not link to the parent.
+It should exit if its transport connection with its peer is lost.</p>
+
+<p>
+Transport processes for a given service are started sequentially.</p>
+
+<p>
+The start function should use the 'Host-IP-Address' list on the service,
+namely <c>Svc#diameter_service.host_ip_address</c>, and/or
+<c>Opts</c> to select an appropriate list of local IP addresses,
+and should return this list if different from the service addresses.
+The returned list is used to populate 'Host-IP-Address' AVPs in outgoing
+capabilities exchange messages, the service addresses being used
+otherwise.</p>
+
+<marker id="MESSAGES"/>
+</desc>
+</func>
+
+</funcs>
+
+<!-- ===================================================================== -->
+
+<section>
+<title>MESSAGES</title>
+
+<p>
+All messages sent over the transport interface are of the
+form <c>{diameter, term()}</c>.</p>
+
+<p>
+A transport process can expect the following messages from
+diameter.</p>
+
+<taglist>
+
+<tag><c>{diameter, {send, Packet}}</c></tag>
+<item>
+<p>
+An outbound Diameter message.
+Packet can be either <c>binary()</c> (the message to be sent)
+or a <c>#diameter_packet{}</c> whose <c>transport_data</c> field
+containes a value other than undefined.</p>
+</item>
+
+<tag><c>{diameter, {close, Pid}}</c></tag>
+<item>
+<p>
+A request to close the transport connection.
+The transport process should terminate after closing the
+connection.
+Pid is the pid() of the parent process.</p>
+</item>
+
+</taglist>
+
+<p>
+A transport process should send the following messages
+to its parent.</p>
+
+<taglist>
+
+<tag><c>{diameter, {self(), connected}}</c></tag>
+<item>
+<p>
+Inform the parent that the transport process with Type = accept has
+established a connection with the peer.
+Not sent if the transport process has Type = connect.</p>
+</item>
+
+<tag><c>{diameter, {self(), connected, Remote}}</c></tag>
+<item>
+<p>
+Inform the parent that the transport process with Type = connect
+has established a connection with a peer.
+Not sent if the transport process has Type = accept.
+Remote is an arbitrary term that uniquely identifies the remote
+endpoint to which the transport has connected.</p>
+</item>
+
+<tag><c>{diameter, {recv, Packet}}</c></tag>
+<item>
+<p>
+An inbound Diameter message.
+Packet can be either <c>binary()</c> (the message to be sent)
+or <c>#diameter_packet{}</c>
+whose <c>packet</c> field contains a <c>binary()</c>.
+Any value (other than undefined) set in
+the <c>transport_data</c> field will be passed back with a
+corresponding answer message in the case that the inbound message is a
+request unless the sender sets another value.
+How the <c>transport_data</c> is used/interpreted is up to the
+transport module.</p>
+</item>
+
+</taglist>
+
+</section>
+
+<!-- ===================================================================== -->
+<!-- ===================================================================== -->
+
+<section>
+<title>SEE ALSO</title>
+
+<p>
+<seealso marker="diameter_tcp">diameter_tcp(3)</seealso>,
+<seealso marker="diameter_sctp">diameter_sctp(3)</seealso></p>
+
+</section>
+
+</erlref>
diff --git a/lib/diameter/doc/src/diameter_using.xml b/lib/diameter/doc/src/diameter_using.xml
new file mode 100644
index 0000000000..737a0a3941
--- /dev/null
+++ b/lib/diameter/doc/src/diameter_using.xml
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+
+<header>
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+
+<legalnotice>
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+    
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+    
+</legalnotice>
+
+<title>Using the stack</title>
+<prepared></prepared>
+<responsible></responsible>
+<docno></docno>
+<approved></approved>
+<checked></checked>
+<date></date>
+<rev></rev>
+<file>diameter_using.xml</file>
+
+</header>
+
+<!-- ===================================================================== -->
+
+</chapter>
diff --git a/lib/diameter/doc/src/files.mk b/lib/diameter/doc/src/files.mk
new file mode 100644
index 0000000000..23558e394f
--- /dev/null
+++ b/lib/diameter/doc/src/files.mk
@@ -0,0 +1,52 @@
+#-*-makefile-*-   ; force emacs to enter makefile-mode
+
+# %CopyrightBegin%
+#
+# Copyright Ericsson AB 2010. All Rights Reserved.
+#
+# The contents of this file are subject to the Erlang Public License,
+# Version 1.1, (the "License"); you may not use this file except in
+# compliance with the License. You should have received a copy of the
+# Erlang Public License along with this software. If not, it can be
+# retrieved online at http://www.erlang.org/.
+#
+# Software distributed under the License is distributed on an "AS IS"
+# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+# the License for the specific language governing rights and limitations
+# under the License.
+#
+# %CopyrightEnd%
+
+XML_APPLICATION_FILES = \
+	ref_man.xml
+
+XML_REF1_FILES = \
+	diameter_compile.xml
+
+XML_REF3_FILES = \
+	diameter.xml \
+	diameter_app.xml \
+	diameter_transport.xml \
+	diameter_tcp.xml \
+	diameter_sctp.xml
+
+XML_REF4_FILES = \
+	diameter_dict.xml
+
+XML_PART_FILES = \
+	user_man.xml
+
+XML_EXTRA_FILES = 
+
+XML_CHAPTER_FILES = \
+	diameter_intro.xml \
+	diameter_using.xml \
+	diameter_examples.xml \
+	diameter_soc.xml \
+	notes.xml
+
+BOOK_FILES = \
+	book.xml
+
+GIF_FILES = \
+	notes.gif
diff --git a/lib/diameter/doc/src/notes.gif b/lib/diameter/doc/src/notes.gif
new file mode 100644
index 0000000000..e000cca26a
--- /dev/null
+++ b/lib/diameter/doc/src/notes.gif
diff --git a/lib/diameter/doc/src/notes.xml b/lib/diameter/doc/src/notes.xml
new file mode 100644
index 0000000000..8fdb88749e
--- /dev/null
+++ b/lib/diameter/doc/src/notes.xml
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+
+<header>
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+<legalnotice>
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+
+</legalnotice>
+
+<title>Release Notes</title>
+<prepared></prepared>
+<docno></docno>
+<date></date>
+<rev></rev>
+<file>notes.xml</file>
+</header>
+
+<p>
+Releases are listed in reverse chronological order, most recent
+first.</p>
+
+<!-- ===================================================================== -->
+
+<section>
+<title>diameter 0.9</title>
+
+<p>
+First OTP release.</p>
+
+</section>
+
+</chapter>
diff --git a/lib/diameter/doc/src/ref_man.xml b/lib/diameter/doc/src/ref_man.xml
new file mode 100644
index 0000000000..137ce79094
--- /dev/null
+++ b/lib/diameter/doc/src/ref_man.xml
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE application SYSTEM "application.dtd">
+
+<application xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<header>
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+<legalnotice>
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+
+</legalnotice>
+
+<title>Diameter Reference Manual</title>
+<prepared></prepared>
+<docno></docno>
+<date></date>
+<rev></rev>
+<file>ref_man.xml</file>
+</header>
+
+<description>
+<p>
+The Diameter application is a framework for building
+applications on top of the Diameter protocol. </p>
+
+</description>
+
+<xi:include href="diameter.xml"/>
+<xi:include href="diameter_compile.xml"/>
+<xi:include href="diameter_app.xml"/>
+<xi:include href="diameter_dict.xml"/>
+<xi:include href="diameter_transport.xml"/>
+<xi:include href="diameter_tcp.xml"/>
+<xi:include href="diameter_sctp.xml"/>
+
+</application>
diff --git a/lib/diameter/doc/src/user_man.xml b/lib/diameter/doc/src/user_man.xml
new file mode 100644
index 0000000000..a6416c7e23
--- /dev/null
+++ b/lib/diameter/doc/src/user_man.xml
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<header>
+<copyright>
+<year>2011</year>
+<holder>Ericsson AB. All Rights Reserved.</holder>
+</copyright>
+<legalnotice>
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+
+</legalnotice>
+
+<title>Diameter Users Guide</title>
+<prepared></prepared>
+<docno></docno>
+<date></date>
+<rev></rev>
+<file>user_man.xml</file>
+</header>
+<description>
+
+<p>
+The diameter application is a framework for building
+applications on top of the Diameter protocol. </p>
+</description>
+
+<xi:include href="diameter_intro.xml"/>
+<xi:include href="diameter_using.xml"/>
+<xi:include href="diameter_examples.xml"/>
+<xi:include href="diameter_soc.xml"/>
+
+</part>