Add an "Asterisk Architecture Overview" section to the doxygen documentation.

This is a side project I've been poking at this week.  The intent is to discuss
Asterisk architecture in a top down fashion to help new developers understand how
Asterisk is put together.  There is a ton of stuff to write about, so this will
just continue to evolve over time.


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@226606 f38db490-d61c-443f-a65b-d21fe96a405b

contrib/asterisk-ng-doxygen

@@ -25,7 +25,7 @@ DOXYFILE_ENCODING      = UTF-8
 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded 
 # by quotes) that should identify the project.
 
-PROJECT_NAME           = "Asterisk - the Open Source PBX"
+PROJECT_NAME           = "Asterisk - The Open Source Telephony Project"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. 
 # This could be handy for archiving the generated documentation or 

include/asterisk/doxygen/architecture.h

@@ -0,0 +1,716 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2009, Digium, Inc.
+ *
+ * Russell Bryant <russell@digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+/*!
+ * \file
+ * \author Russell Bryant <russell@digium.com>
+ */
+
+/*!
+\page AsteriskArchitecture Asterisk Architecture Overview
+\author Russell Bryant <russell@digium.com>
+\AsteriskTrunkWarning
+
+<hr/>
+
+\section ArchTOC Table of Contents
+
+ -# \ref ArchIntro
+ -# \ref ArchLayout
+ -# \ref ArchInterfaces
+    -# \ref ArchInterfaceCodec
+    -# \ref ArchInterfaceFormat
+    -# \ref ArchInterfaceAPIs
+    -# \ref ArchInterfaceAMI
+    -# \ref ArchInterfaceChannelDrivers
+    -# \ref ArchInterfaceBridge
+    -# \ref ArchInterfaceCDR
+    -# \ref ArchInterfaceCEL
+    -# \ref ArchInterfaceDialplanApps
+    -# \ref ArchInterfaceDialplanFuncs
+    -# \ref ArchInterfaceRTP
+    -# \ref ArchInterfaceTiming
+ -# \ref ArchThreadingModel
+    -# \ref ArchChannelThreads
+    -# \ref ArchMonitorThreads
+    -# \ref ArchServiceThreads
+    -# \ref ArchOtherThreads
+ -# \ref ArchConcepts
+    -# \ref ArchConceptBridging
+ -# \ref ArchCodeFlows
+    -# \ref ArchCodeFlowPlayback
+    -# \ref ArchCodeFlowBridge 
+ -# \ref ArchDataStructures
+    -# \ref ArchAstobj2
+    -# \ref ArchLinkedLists
+    -# \ref ArchDLinkedLists
+    -# \ref ArchHeap
+ -# \ref ArchDebugging
+    -# \ref ArchThreadDebugging
+    -# \ref ArchMemoryDebugging
+
+<hr/>
+
+\section ArchIntro Introduction
+
+This section of the documentation includes an overview of the Asterisk architecture
+from a developer's point of view.  For detailed API discussion, see the documentation
+associated with public API header files.  This documentation assumes some knowledge
+of what Asterisk is and how to use it.
+
+The intent behind this documentation is to start looking at Asterisk from a high
+level and progressively dig deeper into the details.  It begins with talking about
+the different types of components that make up Asterisk and eventually will go
+through interactions between these components in different use cases.
+
+Throughout this documentation, many links are also provided as references to more
+detailed information on related APIs, as well as the related source code to what
+is being discussed.
+
+Feedback and contributions to this documentation are very welcome.  Please send your
+comments to the asterisk-dev mailing list on http://lists.digium.com/.
+
+Thank you, and enjoy Asterisk!
+
+
+\section ArchLayout Modular Architecture
+
+Asterisk is a highly modularized application.  There is a core application that
+is built from the source in the <code>main/</code> directory.  However, it is
+not very useful by itself.
+
+There are many modules that are loaded at runtime.  Asterisk modules have names that
+give an indication as to what functionality they provide, but the name is not special
+in any technical sense.  When Asterisk loads a module, the module registers the
+functionality that it provides with the Asterisk core.
+
+ -# Asterisk starts
+ -# Asterisk loads modules
+ -# Modules say "Hey Asterisk!  I am a module.  I can provide functionality X, Y,
+    and Z.  Let me know when you'd like to use my functionality!"
+
+
+\section ArchInterfaces Abstract Interface types
+
+There are many types of interfaces that modules can implement and register their
+implementations of with the Asterisk core.  Any module is allowed to register as
+many of these different interfaces as they would like.  Generally, related
+functionality is grouped into a single module.
+
+In this section, the types of interfaces are discussed.  Later, there will
+be discussions about how different components interact in various scenarios.
+
+\subsection ArchInterfaceCodec Codec Interpreter
+
+An implementation of the codec interpreter interface provides the ability to
+convert between two codecs.  Asterisk currently only has the ability to translate
+between audio codecs.
+
+These modules have no knowledge about phone calls or anything else about why
+they are being asked to convert audio.  They just get audio samples as input
+in their specified input format, and are expected to provide audio in the
+specified output format.
+
+It is possible to have multiple paths to get from codec A to codec B once many
+codec implementations are registered.  After modules have been loaded, Asterisk
+builds a translation table with measurements of the performance of each codec
+translator so that it can always find the best path to get from A to B.
+
+Codec modules typically live in the <code>codecs/</code> directory in the
+source tree.
+
+For a list of codec interpreter implementations, see \ref codecs.
+
+For additional information on the codec interpreter API, see the interface
+definition in <code>include/asterisk/translate.h</code>.
+
+For core implementation details related to the codec interpreter API, see
+<code>main/translate.c</code>.
+
+\subsection ArchInterfaceFormat File Format Handler
+
+An implementation of the file format handler interface provides Asterisk the
+ability to read and optionally write files.  File format handlers may provide
+access to audio, video, or image files.
+
+The interface for a file format handler is rather primitive.  A module simply
+tells the Asterisk core that it can handle files with a given %extension,
+for example, ".wav".  It also says that after reading the file, it will
+provide audio in the form of codec X.  If a file format handler provides the
+ability to write out files, it also must specify what codec the audio should
+be in before provided to the file format handler.
+
+File format modules typically live in the <code>formats/</code> directory in the
+source tree.
+
+For a list of file format handler implementations, see \ref formats.
+
+For additional information on the file format handler API, see the interface
+definition in <code>include/asterisk/file.h</code>.
+
+For core implementation details related to the file format API, see
+<code>main/file.c</code>.
+
+\subsection ArchInterfaceAPIs C API Providers
+
+There are some C APIs in Asterisk that are optional.  Core APIs are built into
+the main application and are always available.  Optional C APIs are provided
+by a module and are only available for use when the module is loaded.  Some of
+these API providers also contain their own interfaces that other modules can
+implement and register.
+
+Modules that provide a C API typically live in the <code>res/</code> directory
+in the source tree.
+
+Some examples of modules that provide C APIs (potentially among other things) are:
+ - res_musiconhold.c
+ - res_calendar.c
+   - provides a calendar technology interface.
+ - res_odbc.c
+ - res_ael_share.c
+ - res_crypto.c
+ - res_curl.c
+ - res_jabber.c
+ - res_monitor.c
+ - res_smdi.c
+ - res_speech.c
+   - provides a speech recognition engine interface.
+
+\subsection ArchInterfaceAMI Manager Interface (AMI) Actions
+
+The Asterisk manager interface is a socket interface for monitoring and control
+of Asterisk.  It is a core feature built in to the main application.  However,
+modules can register %actions that may be requested by clients.
+
+Modules that register manager %actions typically do so as auxiliary functionality
+to complement whatever main functionality it provides.  For example, a module that
+provides call conferencing services may have a manager action that will return the
+list of participants in a conference.
+
+\subsection ArchInterfaceCLI CLI Commands
+
+The Asterisk CLI is a feature implemented in the main application.  Modules may
+register additional CLI commands.
+
+\subsection ArchInterfaceChannelDrivers Channel Drivers
+
+The Asterisk channel driver interface is the most complex and most important
+interface available.  The Asterisk channel API provides the telephony protocol
+abstraction which allows all other Asterisk features to work independently of
+the telephony protocol in use.
+
+The specific interface that channel drivers implement is the ast_channel_tech
+interface.  A channel driver must implement functions that perform various
+call signaling tasks.  For example, they must implement a method for initiating
+a call and hanging up a call.  The ast_channel data structure is the abstract
+channel data structure.  Each ast_channel instance has an associated
+ast_channel_tech which identifies the channel type.  An ast_channel instance
+represents one leg of a call (a connection between Asterisk and an endpoint).
+
+Channel drivers typically live in the <code>channels/</code> directory in the
+source tree.
+
+For a list of channel driver implementations, see \ref channel_drivers.
+
+For additional information on the channel API, see
+<code>include/asterisk/channel.h</code>.
+
+For additional implementation details regarding the core ast_channel API, see
+<code>main/channel.c</code>.
+
+\subsection ArchInterfaceBridge Bridging Technologies
+
+Bridging is the operation which connects two or more channels together.  A simple
+two channel bridge is a normal A to B phone call, while a multi-party bridge would
+be something like a 3-way call or a full conference call.
+
+The bridging API allows modules to register bridging technologies.  An implementation
+of a bridging technology knows how to take two (or optionally more) channels and
+connect them together.  Exactly how this happens is up to the implementation.
+
+This interface is used such that the code that needs to pass audio between channels
+doesn't need to know how it is done.  Underneath, the conferencing may be done in
+the kernel (via DAHDI), via software methods inside of Asterisk, or could be done
+in hardware in the future if someone implemented a module to do so.
+
+At the time of this writing, the bridging API is still relatively new, so it is
+not used everywhere that bridging operations are performed.  The ConfBridge dialplan
+application is a new conferencing application which has been implemented on top of
+this bridging API.
+
+Bridging technology modules typically live in the <code>bridges/</code> directory
+in the source tree.
+
+For a list of bridge technology implementations, see \ref bridges.
+
+For additional information on the bridging API, see
+<code>include/asterisk/bridging.h</code> and
+<code>include/asterisk/bridging_technology.h</code>.
+
+For additional implementation details regarding the core bridging API, see
+<code>main/bridging.c</code>.
+
+\subsection ArchInterfaceCDR Call Detail Record (CDR) Handlers
+
+The Asterisk core implements functionality for keeping records of calls.  These
+records are built while calls are processed and live in data structures.  At the
+end of the call, these data structures are released.  Before the records are thrown
+away, they are passed in to all of the registered CDR handlers.  These handlers may
+write out the records to a file, post them to a database, etc.
+
+CDR modules typically live in the <code>cdr</code> directory in the source tree.
+
+For a list of CDR handlers, see \ref cdr_drivers.
+
+For additional information on the CDR API, see
+<code>include/asterisk/cdr.h</code>.
+
+For additional implementation details regarding CDR handling, see
+<code>main/cdr.c</code>.
+
+\subsection ArchInterfaceCEL Call Event Logging (CEL) Handlers
+
+The Asterisk core includes a generic event system that allows Asterisk components
+to report events that can be subscribed to by other parts of the system.  One of
+the things built on this event system is Call Event Logging (CEL).
+
+CEL is similar to CDR in that they are both for tracking call history.  While CDR
+records are typically have a one record to one call relationship, CEL events are
+many events to one call.  The CEL modules look very similar to CDR modules.
+
+CEL modules typically live in the <code>cel/</code> directory in the source tree.
+
+For a list of CEL handlers, see \ref cel_drivers.
+
+For additional information about the CEL API, see
+<code>include/asterisk/cel.h</code>.
+
+For additional implementation details for the CEL API, see <code>main/cel.c</code>.
+
+\subsection ArchInterfaceDialplanApps Dialplan Applications
+
+Dialplan applications implement features that interact with calls that can be
+executed from the Asterisk dialplan.  For example, in <code>extensions.conf</code>:
+
+<code>exten => 123,1,NoOp()</code>
+
+In this case, NoOp is the application.  Of course, NoOp doesn't actually do
+anything.
+
+These applications use a %number of APIs available in Asterisk to interact with
+the channel.  One of the most important tasks of an application is to continuously
+read audio from the channel, and also write audio back to the channel.  The details
+of how this is done is usually hidden behind an API call used to play a file or wait
+for digits to be pressed by a caller.
+
+In addition to interacting with the channel that originally executed the application,
+dialplan applications sometimes also create additional outbound channels.
+For example, the Dial() application creates an outbound channel and bridges it to the
+inbound channel.  Further discussion about the functionality of applications will be
+discussed in detailed use cases.
+
+Dialplan applications are typically found in the <code>apps/</code> directory in
+the source tree.
+
+For a list of dialplan applications, see \ref applications.
+
+For details on the API used to register an application with the Asterisk core, see
+<code>include/asterisk/pbx.h</code>.
+
+\subsection ArchInterfaceDialplanFuncs Dialplan Functions
+
+As the name suggests, dialplan functions, like dialplan applications, are primarily
+used from the Asterisk dialplan.  Functions are used mostly in the same way that
+variables are used in the dialplan.  They provide a read and/or write interface, with
+optional arguments.  While they behave similarly to variables, they storage and
+retrieval of a value is more complex than a simple variable with a text value.
+
+For example, the <code>CHANNEL()</code> dialplan function allows you to access
+data on the current channel.
+
+<code>exten => 123,1,NoOp(This channel has the name: ${CHANNEL(name)})</code>
+
+Dialplan functions are typically found in the <code>funcs/</code> directory in
+the source tree.
+
+For a list of dialplan function implementations, see \ref functions.
+
+For details on the API used to register a dialplan function with the Asterisk core,
+see <code>include/asterisk/pbx.h</code>.
+
+\subsection ArchInterfaceRTP RTP Engines
+
+The Asterisk core provides an API for handling RTP streams.  However, the actual
+handling of these streams is done by modules that implement the RTP engine interface.
+Implementations of an RTP engine typically live in the <code>res/</code> directory
+of the source tree, and have a <code>res_rtp_</code> prefix in their name.
+
+\subsection ArchInterfaceTiming Timing Interfaces
+
+The Asterisk core implements an API that can be used by components that need access
+to timing services.  For example, a timer is used to send parts of an audio file at
+proper intervals when playing back a %sound file to a caller.  The API relies on
+timing interface implementations to provide a source for reliable timing.
+
+Timing interface implementations are typically found in the <code>res/</code>
+subdirectory of the source tree.
+
+For a list of timing interface implementations, see \ref timing_interfaces.
+
+For additional information on the timing API, see <code>include/asterisk/timing.h</code>.
+
+For additional implementation details for the timing API, see <code>main/timing.c</code>.
+
+
+\section ArchThreadingModel Asterisk Threading Model
+
+Asterisk is a very heavily multi threaded application.  It uses the POSIX threads API
+to manage threads and related services such as locking.  Almost all of the Asterisk code
+that interacts with pthreads does so by going through a set of wrappers used for
+debugging and code reduction.
+
+Threads in Asterisk can be classified as one of the following types:
+
+ - Channel threads (sometimes referred to as PBX threads)
+ - Network Monitor threads
+ - Service connection threads
+ - Other threads
+
+\subsection ArchChannelThreads Channel Threads
+
+A channel is a fundamental concept in Asterisk.  Channels are either inbound
+or outbound.  An inbound channel is created when a call comes in to the Asterisk
+system.  These channels are the ones that execute the Asterisk dialplan.  A thread
+is created for every channel that executes the dialplan.  These threads are referred
+to as a channel thread.  They are sometimes also referred to as a PBX thread, since
+one of the primary tasks of the thread is to execute the Asterisk dialplan for an
+inbound call.
+
+A channel thread starts out by only being responsible for a single Asterisk channel.
+However, there are cases where a second channel may also live in a channel thread.
+When an inbound channel executes an application such as <code>Dial()</code>, an
+outbound channel is created and bridged to the inbound channel once it answers.
+
+Dialplan applications always execute in the context of a channel thread.  Dialplan
+functions \i almost always do, as well.  However, it is possible to read and write
+dialplan functions from an asynchronous interface such as the Asterisk CLI or the
+manager interface (AMI).  However, it is still always the channel thread that is
+the owner of the ast_channel data structure.
+
+\subsection ArchMonitorThreads Network Monitor Threads
+
+Network monitor threads exist in almost every major channel driver in Asterisk.
+They are responsible for monitoring whatever network they are connected to (whether
+that is an IP network, the PSTN, etc.) and monitor for incoming calls or other types
+of incoming %requests.  They handle the initial connection setup steps such as
+authentication and dialed %number validation.  Finally, once the call setup has been
+completed, the monitor threads will create an instance of an Asterisk channel
+(ast_channel), and start a channel thread to handle the call for the rest of its
+lifetime.
+
+\subsection ArchServiceThreads Service Connection Threads
+
+There are a %number of TCP based services that use threads, as well.  Some examples
+include SIP and the AMI.  In these cases, threads are used to handle each TCP
+connection.
+
+The Asterisk CLI also operates in a similar manner.  However, instead of TCP, the
+Asterisk CLI operates using connections to a UNIX %domain socket.
+
+\subsection ArchOtherThreads Other Threads
+
+There are other miscellaneous threads throughout the system that perform a specific task.
+For example, the event API (include/asterisk/event.h) uses a thread internally
+(main/event.c) to handle asychronous event dispatching.  The devicestate API
+(include/asterisk/devicestate.h) uses a thread internally (main/devicestate.c) 
+to asynchronously process device state changes.
+
+
+\section ArchConcepts Other Architecture Concepts
+
+This section covers some other important Asterisk architecture concepts.
+
+\subsection ArchConceptBridging Channel Bridging
+
+As previously mentioned when discussing the bridging technology interface
+(\ref ArchInterfaceBridge), bridging is the act of connecting one or more channel
+together so that they may pass audio between each other.  However, it was also
+mentioned that most of the code in Asterisk that does bridging today does not use
+this new bridging infrastructure.  So, this section discusses the legacy bridging
+functionality that is used by the <code>Dial()</code> and <code>Queue()</code>
+applications.
+
+When one of these applications decides it would like to bridge two channels together,
+it does so by executing the ast_channel_bridge() API call.  From there, there are
+two types of bridges that may occur.
+
+ -# <b>Generic Bridge:</b> A generic bridge (ast_generic_bridge()) is a bridging
+    method that works regardless of what channel technologies are in use.  It passes
+    all audio and signaling through the Asterisk abstract channel and frame interfaces
+    so that they can be communicated between channel drivers of any type.  While this
+    is the most flexible, it is also the least efficient bridging method due to the
+    levels of abstraction necessary.
+ -# <b>Native Bridge:</b> Channel drivers have the option of implementing their own
+    bridging functionality.  Specifically, this means to implement the bridge callback
+    in the ast_channel_tech structure.  If two channels of the same type are bridged,
+    a native bridge method is available, and Asterisk does not have a reason to force
+    the call to stay in the core of Asterisk, then the native bridge function will be
+    invoked.  This allows channel drivers to take advantage of the fact that the
+    channels are the same type to optimize bridge processing.  In the case of a DAHDI
+    channel, this may mean that the channels are bridged natively on hardware.  In the
+    case of SIP, this means that Asterisk can direct the audio to flow between the
+    endpoints and only require the signaling to continue to flow through Asterisk.
+
+
+\section ArchCodeFlows Code Flow Examples
+
+Now that there has been discussion about the various components that make up Asterisk,
+this section goes through examples to demonstrate how these components work together
+to provide useful functionality.
+
+\subsection ArchCodeFlowPlayback SIP Call to File Playback
+
+This example consists of a call that comes in to Asterisk via the SIP protocol.
+Asterisk accepts this call, plays back a %sound file to the caller, and then hangs up.
+
+Example dialplan:
+
+<code>exten => 5551212,1,Answer()</code><br/>
+<code>exten => 5551212,n,Playback(demo-congrats)</code><br/>
+<code>exten => 5551212,n,Hangup()</code><br/>
+
+ -# <b>Call Setup:</b> An incoming SIP INVITE begins this scenario.  It is received by
+    the SIP channel driver (chan_sip.c).  Specifically, the monitor thread in chan_sip
+    is responsible for handling this incoming request.  Further, the monitor thread
+    is responsible for completing any handshake necessary to complete the call setup
+    process.
+ -# <b>Accept Call:</b> Once the SIP channel driver has completed the call setup process,
+    it accepts the call and initiates the call handling process in Asterisk.  To do so,
+    it must allocate an instance of an abstract channel (ast_channel) using the
+    ast_channel_alloc() API call.  This instance of an ast_channel will be referred to
+    as a SIP channel.  The SIP channel driver will take care of SIP specific channel
+    initialization.  Once the channel has been created and initialized, a channel thread
+    is created to handle the call (ast_pbx_start()).
+ -# <b>Run the Dialplan:</b>: The main loop that runs in the channel thread is the code
+    responsible for looking for the proper extension and then executing it.  This loop
+    lives in ast_pbx_run() in main/pbx.c.
+ -# <b>Answer the Call:</b>: Once the dialplan is being executed, the first application
+    that is executed is <code>Answer()</code>.  This application is a built in
+    application that is defined in main/pbx.c.  The <code>Answer()</code> application
+    code simply executes the ast_answer() API call.  This API call operates on an
+    ast_channel.  It handles generic ast_channel hangup processing, as well as executes
+    the answer callback function defined in the associated ast_channel_tech for the
+    active channel.  In this case, the sip_answer() function in chan_sip.c will get
+    executed to handle the SIP specific operations required to answer a call.
+ -# <b>Play the File:</b> The next step of the dialplan says to play back a %sound file
+    to the caller.  The <code>Playback()</code> application will be executed.
+    The code for this application is in apps/app_playback.c.  The code in the application
+    is pretty simple.  It does argument handling and uses API calls to play back the
+    file, ast_streamfile(), ast_waitstream(), and ast_stopstream(), which set up file
+    playback, wait for the file to finish playing, and then free up resources.  Some
+    of the important operations of these API calls are described in steps here:
+    -# <b>Open a File:</b> The file format API is responsible for opening the %sound file.
+       It will start by looking for a file that is encoded in the same format that the
+       channel is expecting to receive audio in.  If that is not possible, it will find
+       another type of file that can be translated into the codec that the channel is
+       expecting.  Once a file is found, the appropriate file format interface is invoked
+       to handle reading the file and turning it into internal Asterisk audio frames.
+    -# <b>Set up Translation:</b> If the encoding of the audio data in the file does not
+       match what the channel is expecting, the file API will use the codec translation
+       API to set up a translation path.  The translate API will invoke the appropriate
+       codec translation interface(s) to get from the source to the destination format
+       in the most efficient way available.
+    -# <b>Feed Audio to the Caller:</b> The file API will invoke the timer API to know
+       how to send out audio frames from the file in proper intervals.  At the same time,
+       Asterisk must also continuously service the incoming audio from the channel since
+       it will continue to arrive in real time.  However, in this scenario, it will just
+       get thrown away.
+ -# <b>Hang up the Call:</b> Once the <code>Playback()</code> application has finished,
+    the dialplan execution loop continues to the next step in the dialplan, which is
+    <code>Hangup()</code>.  This operates in a very similar manner to <code>Answer()</code>
+    in that it handles channel type agnostic hangup handling, and then calls down into
+    the SIP channel interface to handle SIP specific hangup processing.  At this point,
+    even if there were more steps in the dialplan, processing would stop since the channel
+    has been hung up.  The channel thread will exit the dialplan processing loop and
+    destroy the ast_channel data structure.
+
+\subsection ArchCodeFlowBridge SIP to IAX2 Bridged Call
+
+This example consists of a call that comes in to Asterisk via the SIP protocol.  Asterisk
+then makes an outbound call via the IAX2 protocol.  When the far end over IAX2 answers,
+the call is bridged.
+
+Example dialplan:
+
+<code>exten => 5551212,n,Dial(IAX2/mypeer)</code><br/>
+
+ -# <b>Call Setup:</b> An incoming SIP INVITE begins this scenario.  It is received by
+    the SIP channel driver (chan_sip.c).  Specifically, the monitor thread in chan_sip
+    is responsible for handling this incoming request.  Further, the monitor thread
+    is responsible for completing any handshake necessary to complete the call setup
+    process.
+ -# <b>Accept Call:</b> Once the SIP channel driver has completed the call setup process,
+    it accepts the call and initiates the call handling process in Asterisk.  To do so,
+    it must allocate an instance of an abstract channel (ast_channel) using the
+    ast_channel_alloc() API call.  This instance of an ast_channel will be referred to
+    as a SIP channel.  The SIP channel driver will take care of SIP specific channel
+    initialization.  Once the channel has been created and initialized, a channel thread
+    is created to handle the call (ast_pbx_start()).
+ -# <b>Run the Dialplan:</b>: The main loop that runs in the channel thread is the code
+    responsible for looking for the proper extension and then executing it.  This loop
+    lives in ast_pbx_run() in main/pbx.c.
+ -# <b>Execute Dial()</b>: The only step in this dialplan is to execute the
+    <code>Dial()</code> application.
+    -# <b>Create an Outbound Channel:</b> The <code>Dial()</code> application needs to
+       create an outbound ast_channel.  It does this by first using the ast_request()
+       API call to request a channel called <code>IAX2/mypeer</code>.  This API call
+       is a part of the core channel API (include/asterisk/channel.h).  It will find
+       a channel driver of type <code>IAX2</code> and then execute the request callback
+       in the appropriate ast_channel_tech interface.  In this case, it is iax2_request()
+       in channels/chan_iax2.c.  This asks the IAX2 channel driver to allocate an
+       ast_channel of type IAX2 and initialize it.  The <code>Dial()</code> application
+       will then execute the ast_call() API call for this new ast_channel.  This will
+       call into the call callback of the ast_channel_tech, iax2_call(), which requests
+       that the IAX2 channel driver initiate the outbound call.
+    -# <b>Wait for Answer:</b> At this point, the Dial() application waits for the
+       outbound channel to answer the call.  While it does this, it must continue to
+       service the incoming audio on both the inbound and outbound channels.  The loop
+       that does this is very similar to every other channel servicing loop in Asterisk.
+       The core features of a channel servicing loop include ast_waitfor() to wait for
+       frames on a channel, and then ast_read() on a channel once frames are available.
+    -# <b>Handle Answer:</b> Once the far end answers the call, the <code>Dial()</code>
+       application will communicate this back to the inbound SIP channel.  It does this
+       by calling the ast_answer() core channel API call.
+    -# <b>Make Channels Compatible:</b> Before the two ends of the call can be connected,
+       Asterisk must make them compatible to talk to each other.  Specifically, the two
+       channels may be sending and expecting to receive audio in a different format than
+       the other channel.  The API call ast_channel_make_compatible() sets up translation
+       paths for each channel by instantiating codec translators as necessary.
+    -# <b>Bridge the Channels:</b> Now that both the inbound and outbound channels are
+       fully established, they can be connected together.  This connection between the
+       two channels so that they can pass audio and signaling back and forth is referred
+       to as a bridge.  The API call that handles the bridge is ast_channel_bridge().
+       In this case, the main loop of the bridge is a generic bridge, ast_generic_bridge(),
+       which is the type of bridge that works regardless of the two channel types.  A
+       generic bridge will almost always be used if the two channels are not of the same
+       type.  The core functionality of a bridge loop is ast_waitfor() on both channels.
+       Then, when frames arrive on a channel, they are read using ast_read().  After reading
+       a frame, they are written to the other channel using ast_write().
+    -# <b>Breaking the Bridge</b>: This bridge will continue until some event occurs that
+       causes the bridge to be broken, and control to be returned back down to the
+       <code>Dial()</code> application.  For example, if one side of the call hangs up,
+       the bridge will stop.
+ -# <b>Hanging Up:</b>: After the bridge stops, control will return to the
+    <code>Dial()</code> application.  The application owns the outbound channel since
+    that is where it was created.  So, the outbound IAX2 channel will be destroyed
+    before <code>Dial()</code> is complete.  Destroying the channel is done by using
+    the ast_hangup() API call.  The application will return back to the dialplan
+    processing loop.  From there, the loop will see that there is nothing else to
+    execute, so it will hangup on the inbound channel as well using the ast_hangup()
+    function.  ast_hangup() performs a number of channel type independent hangup
+    tasks, but also executes the hangup callback of ast_channel_tech (sip_hangup()).
+    Finally, the channel thread exits.
+
+
+\section ArchDataStructures Asterisk Data Structures
+
+Asterisk provides generic implementations of a number of data structures.
+
+\subsection ArchAstobj2 Astobj2
+
+Astobj2 stands for the Asterisk Object model, version 2.  The API is defined in
+include/asterisk/astobj2.h.  Some internal implementation details for astobj2 can
+be found in main/astobj2.c.  There is a version 1, and it still exists in the
+source tree.  However, it is considered deprecated.
+
+Astobj2 provides reference counted object handling.  It also provides a container
+interface for astobj2 objects.  The container provided is a hash table.
+
+See the astobj2 API for more details about how to use it.  Examples can be found
+all over the code base.
+
+\subsection ArchLinkedLists Linked Lists
+
+Asterisk provides a set of macros for handling linked lists.  They are defined in
+include/asterisk/linkedlists.h.
+
+\subsection ArchDLinkedLists Doubly Linked Lists
+
+Asterisk provides a set of macros for handling doubly linked lists, as well.  They
+are defined in include/asterisk/dlinkedlists.h.
+
+\subsection ArchHeap Heap
+
+Asterisk provides an implementation of the max heap data structure.  The API is defined
+in include/asterisk/heap.h.  The internal implementation details can be found in
+main/heap.c.
+
+
+\section ArchDebugging Asterisk Debugging Tools
+
+Asterisk includes a %number of built in debugging tools to help in diagnosing common
+types of problems.
+
+\subsection ArchThreadDebugging Thread Debugging
+
+Asterisk keeps track of a list of all active threads on the system.  A list of threads
+can be viewed from the Asterisk CLI by running the command
+<code>core show threads</code>.
+
+Asterisk has a compile time option called <code>DEBUG_THREADS</code>.  When this is on,
+the pthread wrapper API in Asterisk keeps track of additional information related to
+threads and locks to aid in debugging.  In addition to just keeping a list of threads,
+Asterisk also maintains information about every lock that is currently held by any
+thread on the system.  It also knows when a thread is blocking while attempting to
+acquire a lock.  All of this information is extremely useful when debugging a deadlock.
+This data can be acquired from the Asterisk CLI by running the
+<code>core show locks</code> CLI command.
+
+The definitions of these wrappers can be found in <code>include/asterisk/lock.h</code>
+and <code>include/asterisk/utils.h</code>.  Most of the implementation details can be
+found in <code>main/utils.c</code>.
+
+\subsection ArchMemoryDebugging Memory debugging
+
+Dynamic memory management in Asterisk is handled through a %number of wrappers defined
+in <code>include/asterisk/utils.h</code>.  By default, all of these wrappers use the
+standard C library malloc(), free(), etc. functions.  However, if Asterisk is compiled
+with the MALLOC_DEBUG option enabled, additional memory debugging is included.
+
+The Asterisk memory debugging system provides the following features:
+
+ - Track all current allocations including their size and the file, function, and line
+   %number where they were initiated.
+ - When releasing memory, do some basic fence checking to see if anything wrote into the
+   few bytes immediately surrounding an allocation.
+ - Get notified when attempting to free invalid memory.
+
+A %number of CLI commands are provided to access data on the current set of memory
+allocations.  Those are:
+
+ - <code>memory show summary</code>
+ - <code>memory show allocations</code>
+
+The implementation of this memory debugging system can be found in
+<code>main/astmm.c</code>.
+
+
+<hr/>
+Return to the \ref ArchTOC
+ */
+

include/asterisk/doxyref.h

@@ -658,6 +658,11 @@
  * \arg \ref codecs 
  */
 
+/*! 
+ * \addtogroup rtp_engines Module: RTP Engines
+ * \section rtp_engine_blah Asterisk RTP Engines
+ */
+
 /*! 
  * \page AstHTTP AMI over HTTP support
  * The http.c file includes support for manager transactions over

main/asterisk.c

@@ -19,7 +19,7 @@
 
 /* Doxygenified Copyright Header */
 /*!
- * \mainpage Asterisk -- An Open Source Telephony Toolkit
+ * \mainpage Asterisk -- The Open Source Telephony Project
  *
  * \par Developer Documentation for Asterisk
  *
@@ -30,6 +30,8 @@
  * please see the appendices for information on coding guidelines, 
  * release management, commit policies, and more.
  *
+ * \arg \ref AsteriskArchitecture
+ *
  * \par Additional documentation
  * \arg \ref Licensing
  * \arg \ref DevDoc 

res/res_rtp_asterisk.c

@@ -24,6 +24,8 @@
  * \author Mark Spencer <markster@digium.com>
  *
  * \note RTP is defined in RFC 3550.
+ *
+ * \ingroup rtp_engines
  */
 
 #include "asterisk.h"

res/res_rtp_multicast.c

@@ -24,6 +24,8 @@
  *
  * \author Joshua Colp <jcolp@digium.com>
  * \author Andreas 'MacBrody' Brodmann <andreas.brodmann@gmail.com>
+ *
+ * \ingroup rtp_engines
  */
 
 #include "asterisk.h"