Docs: Updated doxygen documentation
authorChris Ring <cring@ti.com>
Fri, 26 Apr 2013 21:29:15 +0000 (14:29 -0700)
committerChris Ring <cring@ti.com>
Fri, 26 Apr 2013 21:29:15 +0000 (14:29 -0700)
Doxygen-related review and cleanup.  In some cases, added notes that
some APIs are only available on SYS/BIOS, others only on Linux/QNX.

16 files changed:
packages/ti/grcm/RcmServer.h
packages/ti/grcm/RcmTypes.h
packages/ti/ipc/GateMP.h
packages/ti/ipc/HeapBufMP.h
packages/ti/ipc/HeapMemMP.h
packages/ti/ipc/HeapMultiBufMP.h
packages/ti/ipc/Ipc.h
packages/ti/ipc/ListMP.h
packages/ti/ipc/MessageQ.h
packages/ti/ipc/MultiProc.h
packages/ti/ipc/NameServer.h
packages/ti/ipc/Notify.h
packages/ti/ipc/SharedRegion.h
packages/ti/ipc/mm/MmRpc.h
packages/ti/ipc/mm/MmServiceMgr.h
packages/ti/ipc/mm/MmType.h

index 10dafea9d8ea600fec8bf23db918ff53cd3de5d2..8ee84fb14cc4bd26e6a1113824ef9cc5441acc2f 100644 (file)
  *  @brief Remote Command Message Server Module. An RcmServer processes
  *  inbound messages received from an RcmClient.
  *
+ *  @note With the exception of RcmServer_Params, the RcmServer API is
+ *  an internal implementation detail of MmServiceMgr and may be changed at
+ *  will.
+ *
  *  The RcmServer processes inbound messages received from an RcmClient.
  *  After processing a message, the server will return the message to
  *  the client.
- *
- *  @sa RcmClient.h <br>
- *  @ref ti_grcm "RCM Overview"
  */
 
 /*!
  *  @brief Remote Command Message Server Module. An RcmServer processes
  *  inbound messages received from an RcmClient.
  *
- *  The RcmServer module is used to create an server instance. RcmClients
- *  send their messages to only one RcmServer instance for processing. The
- *  server instance can be created with a function dispatch table and
- *  additional tables can be added as requested by the clients.
- *
- *  Diagnostics
- *
- *  Diags_INFO - full detail log events
- *  Diags_USER1 - message processing
- *
- *  @sa ti_grcm_RcmClient <br>
- *  @ref ti_grcm "RCM Overview"
+ *  @note With the exception of RcmServer_Params, the RcmServer API is
+ *  an internal implementation detail of MmServiceMgr and may be changed at
+ *  will.
  */
 
 #ifndef ti_grcm_RcmServer__include
@@ -87,9 +79,7 @@
 extern "C" {
 #endif
 
-
-// -------- success and failure codes --------
-
+/** @cond INTERNAL */
 /*!
  *  @brief Success return code
  */
@@ -160,6 +150,7 @@ typedef Int32 (*RcmServer_MsgFxn)(UInt32, UInt32 *);
 typedef Int32 (*RcmServer_MsgCreateFxn)(Void *, UInt32, UInt32 *);
 #endif
 
+/** @endcond INTERNAL */
 
 
 /*!
@@ -275,11 +266,15 @@ typedef struct {
 } RcmServer_ThreadPoolDescAry;
 
 
+/** @cond INTERNAL */
+
 /*!
  *  @brief RcmServer instance object handle
  */
 typedef struct RcmServer_Object_tag *RcmServer_Handle;
 
+/** @endcond INTERNAL */
+
 /*!
  *  @brief RcmServer Instance create parameters
  */
@@ -370,6 +365,8 @@ typedef struct {
 
 } RcmServer_Params;
 
+/** @cond INTERNAL */
+
 /*!
  *  @brief Opaque client structure large enough to hold an instance object
  *
@@ -642,6 +639,8 @@ UInt16  RcmServer_getRemoteProc(
 
 #endif
 
+/** @endcond INTERNAL */
+
 
 #if defined (__cplusplus)
 }
index 876d3862f1d8daa0a5cd15efea0e256f7d8b3cc4..5d16cc0d499988cd30516743e4cc93649f6a0087 100644 (file)
  *  ======== RcmTypes.h ========
  *
  */
+/*!
+ *  @file ti/grcm/RcmTypes.h
+ *
+ *  @brief Remote Command Message Types.
+ */
 
 #ifndef ti_grcm_RcmTypes_h
 #define ti_grcm_RcmTypes_h
index ed86259869a5ae1eef36a6907f97338480a6ed09..6feff19a58ba1b75fa233692ffd733ab00867a46 100644 (file)
  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/** ============================================================================
- *  @file       GateMP.h
+/**
+ *  @file       ti/ipc/GateMP.h
  *
  *  @brief      Multiple processor gate that provides local and remote context
  *              protection.
  *
+ *  @note       GateMP is currently only available for SYS/BIOS.
+ *
  *  A GateMP instance can be used to enforce both local and remote context
  *  context protection.  That is, entering a GateMP can prevent preemption by
  *  another thread running on the same processor and simultaneously prevent a
  *  to protect reads/writes to a shared resource, such as shared memory.
  *
  *  Creating a GateMP requires supplying the following configuration
- *      - Instance name (see #GateMP_Params::name)
- *      - Region id (see #GateMP_Params::regionId)
+ *      - Instance name (see #GateMP_Params.name)
+ *      - Region id (see #GateMP_Params.regionId)
+ *
  *  In addition, the following parameters should be configured as necessary:
  *      - The level of local protection (interrupt, thread, tasklet, process
- *        or none) can be configured using the #GateMP_Params::localProtect
+ *        or none) can be configured using the #GateMP_Params.localProtect
  *        config parameter.
  *      - The type of remote system gate that can be used.  Most devices will
  *        typically have a single type of system gate so this configuration
- *        should typically be left alone.  See #GateMP_Params::remoteProtect for
+ *        should typically be left alone.  See #GateMP_Params.remoteProtect for
  *        more information.
 
- *  Once created GateMP allows the gate to be opened on another processor
+ *  Once created, GateMP allows the gate to be opened on another processor
  *  using GateMP_open() and the name that was used in GateMP_create().
  *
  *  A GateMP can be entered and left using GateMP_enter() and GateMP_leave()
  *  @code
  *  #include <ti/ipc/GateMP.h>
  *  @endcode
- *
- *
- *  @version        0.00.01
- *
- *  ============================================================================
  */
 
 #ifndef ti_ipc_GateMP__include
@@ -165,18 +163,6 @@ extern "C" {
  *  Each member corresponds to a specific local processor gates used for
  *  local protection.
  *
- *  In Linux user mode, the following are the mapping for the constants
- *      - INTERRUPT -> [N/A]
- *      - TASKLET   -> [N/A]
- *      - THREAD    -> GateMutex
- *      - PROCESS   -> GateMutex
- *
- *  In Linux kernel mode, the following are the mapping for the constants
- *      - INTERRUPT -> [Interrupts disabled]
- *      - TASKLET   -> GateMutex
- *      - THREAD    -> GateMutex
- *      - PROCESS   -> GateMutex
- *
  *  For SYS/BIOS users, the following are the mappings for the constants
  *      - INTERRUPT -> GateAll: disables interrupts, Swis and Tasks
  *      - TASKLET   -> GateSwi: disables Swis and Tasks
@@ -209,7 +195,7 @@ typedef enum GateMP_LocalProtect {
  *  Each enum value corresponds to the following remote protection levels:
  *      - NONE      -> No remote protection (the GateMP instance will
  *                     exclusively offer local protection configured in
- *                     #GateMP_Params::localProtect
+ *                     #GateMP_Params.localProtect
  *      - SYSTEM    -> Use the SYSTEM remote protection level (default for
  *                     remote protection
  *      - CUSTOM1   -> Use the CUSTOM1 remote protection level
@@ -218,7 +204,7 @@ typedef enum GateMP_LocalProtect {
 typedef enum GateMP_RemoteProtect {
     GateMP_RemoteProtect_NONE     = 0,
     /*!< No remote protection (the GateMP instance will exclusively
-     *  offer local protection configured in #GateMP_Params::localProtect)
+     *  offer local protection configured in #GateMP_Params.localProtect)
      */
 
     GateMP_RemoteProtect_SYSTEM   = 1,
@@ -271,7 +257,7 @@ typedef struct GateMP_Params {
      *  it must be from a valid SharedRegion and the regionId is ignored.
      *  If sharedAddr is null, then shared memory for a new instance is
      *  allocated from the heap belonging to the region identified by
-     *  #GateMP_Params::regionId.  The amount of shared memory allocated
+     *  #GateMP_Params.regionId.  The amount of shared memory allocated
      *  can be determined by calling GateMP_sharedMemReq().
      */
     /*! @endcond */
index 9542089a3f95e1efd6600a2792aa2ae72a7f9e4d..e8a49c683daf954c2cf8c2c83ce4869da8e6cfce 100644 (file)
  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/** ============================================================================
- *  @file       HeapBufMP.h
+/**
+ *  @file       ti/ipc/HeapBufMP.h
  *
  *  @brief      Multi-processor fixed-size buffer heap implementation
  *
+ *  @note       HeapBufMP is currently only available for SYS/BIOS.
+ *
  *  Heap implementation that manages fixed size buffers that can be used
  *  in a multiprocessor system with shared memory.
  *
@@ -50,8 +52,8 @@
  *  store instance information when an instance is created.  The name supplied
  *  must be unique for all HeapBufMP instances.
  *
- *  The #HeapBufMP_create call initializes the shared memory as needed. Once an
- *  instance is created, a #HeapBufMP_open can be performed. The
+ *  HeapBufMP_create() initializes the shared memory as needed. Once an
+ *  instance is created, HeapBufMP_open() can be performed. The
  *  open is used to gain access to the same HeapBufMP instance.
  *  Generally an instance is created on one processor and opened on the
  *  other processor(s).
  *  @code
  *  #include <ti/ipc/HeapBufMP.h>
  *  @endcode
- *
- *  @version        0.00.01
  */
 
-
 #ifndef ti_ipc_HeapBufMP__include
 #define ti_ipc_HeapBufMP__include
 
@@ -83,78 +82,68 @@ extern "C" {
  */
 
 /*!
- *  @def    HeapBufMP_S_BUSY
  *  @brief  The resource is still in use
  */
 #define HeapBufMP_S_BUSY               2
 
 /*!
- *  @def    HeapBufMP_S_ALREADYSETUP
  *  @brief  The module has been already setup
  */
 #define HeapBufMP_S_ALREADYSETUP       1
 
 /*!
- *  @def    HeapBufMP_S_SUCCESS
  *  @brief  Operation is successful.
  */
 #define HeapBufMP_S_SUCCESS            0
 
 /*!
- *  @def    HeapBufMP_E_FAIL
  *  @brief  Generic failure.
  */
 #define HeapBufMP_E_FAIL              -1
 
 /*!
- *  @def    HeapBufMP_E_INVALIDARG
  *  @brief  Argument passed to function is invalid.
  */
 #define HeapBufMP_E_INVALIDARG        -2
 
 /*!
- *  @def    HeapBufMP_E_MEMORY
  *  @brief  Operation resulted in memory failure.
  */
 #define HeapBufMP_E_MEMORY            -3
 
 /*!
- *  @def    HeapBufMP_E_ALREADYEXISTS
  *  @brief  The specified entity already exists.
  */
 #define HeapBufMP_E_ALREADYEXISTS     -4
 
 /*!
- *  @def    HeapBufMP_E_NOTFOUND
  *  @brief  Unable to find the specified entity.
  */
 #define HeapBufMP_E_NOTFOUND          -5
 
 /*!
- *  @def    HeapBufMP_E_TIMEOUT
  *  @brief  Operation timed out.
  */
 #define HeapBufMP_E_TIMEOUT           -6
 
 /*!
- *  @def    HeapBufMP_E_INVALIDSTATE
  *  @brief  Module is not initialized.
  */
 #define HeapBufMP_E_INVALIDSTATE      -7
 
 /*!
- *  @def    HeapBufMP_E_OSFAILURE
- *  @brief  A failure occurred in an OS-specific call  */
+ *  @brief  A failure occurred in an OS-specific call
+ */
 #define HeapBufMP_E_OSFAILURE         -8
 
 /*!
- *  @def    HeapBufMP_E_RESOURCE
- *  @brief  Specified resource is not available  */
+ *  @brief  Specified resource is not available
+ */
 #define HeapBufMP_E_RESOURCE          -9
 
 /*!
- *  @def    HeapBufMP_E_RESTART
- *  @brief  Operation was interrupted. Please restart the operation  */
+ *  @brief  Operation was interrupted. Please restart the operation
+ */
 #define HeapBufMP_E_RESTART           -10
 
 /* =============================================================================
@@ -168,11 +157,13 @@ extern "C" {
 typedef struct HeapBufMP_Object *HeapBufMP_Handle;
 
 /*!
- *  @brief  Structure defining parameters for the HeapBufMP module.
+ *  @brief  Structure defining parameters for the HeapBufMP module
+ *
+ *  @sa     HeapBufMP_create()
  */
 typedef struct HeapBufMP_Params {
     String name;
-    /*!< Name of this instance.
+    /*!< @brief Name of this instance.
      *
      *  The name (if not NULL) must be unique among all HeapBufMP
      *  instances in the entire system.  When creating a new
@@ -183,7 +174,7 @@ typedef struct HeapBufMP_Params {
      */
 
     UInt16 regionId;
-    /*!< Shared region ID
+    /*!< @brief Shared region ID
      *
      *  The index corresponding to the shared region from which shared memory
      *  will be allocated.
@@ -191,17 +182,17 @@ typedef struct HeapBufMP_Params {
 
     /*! @cond */
     Ptr sharedAddr;
-    /*!< Physical address of the shared memory
+    /*!< @brief Physical address of the shared memory
      *
      *  This value can be left as 'null' unless it is required to place the
      *  heap at a specific location in shared memory.  If sharedAddr is null,
      *  then shared memory for a new instance will be allocated from the
-     *  heap belonging to the region identified by #HeapBufMP_Params::regionId.
+     *  heap belonging to the region identified by #HeapBufMP_Params.regionId.
      */
     /*! @endcond */
 
     SizeT blockSize;
-    /*!< Size (in MAUs) of each block.
+    /*!< @brief Size (in MAUs) of each block.
      *
      *  HeapBufMP will round the blockSize up to the nearest multiple of the
      *  alignment, so the actual blockSize may be larger. When creating a
@@ -214,13 +205,13 @@ typedef struct HeapBufMP_Params {
      */
 
     UInt numBlocks;
-    /*!<Number of fixed-size blocks.
+    /*!< @brief Number of fixed-size blocks.
      *
      *  This is a required parameter for all new HeapBufMP instances.
      */
 
     SizeT align;
-    /*!< Alignment (in MAUs) of each block.
+    /*!< @brief Alignment (in MAUs) of each block.
      *
      *  The alignment must be a power of 2. If the value 0 is specified,
      *  the value will be changed to meet minimum structure alignment
@@ -231,7 +222,7 @@ typedef struct HeapBufMP_Params {
      */
 
     Bool exact;
-    /*!< Use exact matching
+    /*!< @brief Use exact matching
      *
      *  Setting this flag will allow allocation only if the requested size
      *  is equal to (rather than less than or equal to) the buffer's block
@@ -239,7 +230,7 @@ typedef struct HeapBufMP_Params {
      */
 
     GateMP_Handle gate;
-    /*!< GateMP used for critical region management of the shared memory
+    /*!< @brief GateMP used for critical region management of the shared memory
      *
      *  Using the default value of NULL will result in use of the GateMP
      *  system gate for context protection.
@@ -248,7 +239,9 @@ typedef struct HeapBufMP_Params {
 } HeapBufMP_Params;
 
 /*!
- *  @brief  Stats structure for the HeapBufMP_getExtendedStats API.
+ *  @brief  Stats structure for HeapBufMP_getExtendedStats()
+ *
+ *  @sa     HeapBufMP_getExtendedStats()
  */
 typedef struct HeapBufMP_ExtendedStats {
     UInt maxAllocatedBlocks;
@@ -274,13 +267,13 @@ typedef struct HeapBufMP_ExtendedStats {
  *  instance. All opened instances should be closed before the instance
  *  is deleted.
  *
- *  @param[in,out]  handlePtr   Pointer to HeapBufMP handle typically returned
- *                              from #HeapBufMP_open
+ *  @param[in,out]  handlePtr   Pointer to handle returned from
+ *                              HeapBufMP_open()
  *
  *  @return     HeapBufMP status:
  *              - #HeapBufMP_S_SUCCESS: Heap successfully closed
  *
- *  @sa         HeapBufMP_open
+ *  @sa         HeapBufMP_open()
  */
 Int HeapBufMP_close(HeapBufMP_Handle *handlePtr);
 
@@ -290,6 +283,8 @@ Int HeapBufMP_close(HeapBufMP_Handle *handlePtr);
  *  @param[in]  params      HeapBufMP parameters
  *
  *  @return     HeapBufMP Handle
+ *
+ *  @sa         HeapBufMP_delete()
  */
 HeapBufMP_Handle HeapBufMP_create(const HeapBufMP_Params *params);
 
@@ -300,6 +295,8 @@ HeapBufMP_Handle HeapBufMP_create(const HeapBufMP_Params *params);
  *
  *  @return     HeapBufMP status:
  *              - #HeapBufMP_S_SUCCESS: Heap successfully deleted
+ *
+ *  @sa         HeapBufMP_create()
  */
 Int HeapBufMP_delete(HeapBufMP_Handle *handlePtr);
 
@@ -325,7 +322,7 @@ Int HeapBufMP_delete(HeapBufMP_Handle *handlePtr);
  *              - #HeapBufMP_E_NOTFOUND: Heap is not yet ready to be opened.
  *              - #HeapBufMP_E_FAIL: A general failure has occurred
  *
- *  @sa         HeapBufMP_close
+ *  @sa         HeapBufMP_close()
  */
 Int HeapBufMP_open(String name, HeapBufMP_Handle *handlePtr);
 
@@ -337,8 +334,9 @@ Int HeapBufMP_openByAddr(Ptr sharedAddr, HeapBufMP_Handle *handlePtr);
 /*!
  *  @brief      Initialize a HeapBufMP parameters struct
  *
- *  @param[out] params      Pointer to GateMP parameters
+ *  @param[out] params      Pointer to creation parameters
  *
+ *  @sa         HeapBufMP_create()
  */
 Void HeapBufMP_Params_init(HeapBufMP_Params *params);
 
@@ -364,9 +362,9 @@ SizeT HeapBufMP_sharedMemReq(const HeapBufMP_Params *params);
  *  @brief      Allocate a block of memory of specified size and alignment
  *
  *  The actual block returned may be larger than requested to satisfy
- *  alignment requirements. NULL is returned if alloc fails.
+ *  alignment requirements. NULL is returned if the allocation fails.
  *
- *  HeapBufMP_alloc will lock the heap using the HeapBufMP gate
+ *  HeapBufMP_alloc() will lock the heap using the HeapBufMP gate
  *  while it traverses the list of free blocks to find a large enough block
  *  for the request.
  *
@@ -374,8 +372,8 @@ SizeT HeapBufMP_sharedMemReq(const HeapBufMP_Params *params);
  *      - If possible, allocate larger blocks first. Previous allocations
  *        of small memory blocks can reduce the size of the blocks
  *        available for larger memory allocations.
- *      - Realize that alloc() can fail even if the heap contains a
- *        sufficient absolute amount of unalloccated space. This is
+ *      - Realize that allocation can fail even if the heap contains a
+ *        sufficient absolute amount of unallocated space. This is
  *        because the largest free memory block may be smaller than
  *        total amount of unallocated memory.
  *
@@ -383,44 +381,43 @@ SizeT HeapBufMP_sharedMemReq(const HeapBufMP_Params *params);
  *  @param[in]  size      Size to be allocated (in MADUs)
  *  @param[in]  align     Alignment for allocation (power of 2)
  *
- *  @sa         HeapBufMP_free
+ *  @sa         HeapBufMP_free()
  */
 Void *HeapBufMP_alloc(HeapBufMP_Handle handle, SizeT size, SizeT align);
 
 /*!
  *  @brief      Frees a block of memory.
  *
- *  free() places the memory block specified by addr and size back into the
- *  free pool of the heap specified. The newly freed block is combined with
- *  any adjacent free blocks. The space is then available for further
- *  allocation by alloc().
+ *  HeapBufMP_free() places the memory block specified by addr and size back
+ *  into the free pool of the heap specified. The newly freed block is combined
+ *  with any adjacent free blocks. The space is then available for future
+ *  allocations.
  *
- *  #HeapBufMP_free will lock the heap using the HeapBufMP gate if one is
+ *  HeapBufMP_free() will lock the heap using the HeapBufMP gate if one is
  *  specified or the system GateMP if not.
  *
  *  @param[in]  handle    Handle to previously created/opened instance.
  *  @param[in]  block     Block of memory to be freed.
  *  @param[in]  size      Size to be freed (in MADUs)
  *
- *  @sa         HeapBufMP_alloc
+ *  @sa         HeapBufMP_alloc()
  */
 Void HeapBufMP_free(HeapBufMP_Handle handle, Ptr block, SizeT size);
 
 /*!
  *  @brief      Get extended memory statistics
  *
- *  This function retrieves the extended statistics for a HeapBufMP
- *  instance.  It does not retrieve the standard Memory_Stats
- *  information.  Refer to #HeapBufMP_ExtendedStats for more information
+ *  This function retrieves extended statistics for a HeapBufMP
+ *  instance. Refer to #HeapBufMP_ExtendedStats for more information
  *  regarding what information is returned.
  *
- *  In BIOS, HeapBufMP.trackAllocs needs to be set to 'true' in the
+ *  In SYS/BIOS, HeapBufMP.trackAllocs needs to be set to 'true' in the
  *  configuration to get meaningful extended stats.
  *
  *  @param[in]  handle    Handle to previously created/opened instance.
  *  @param[out] stats     ExtendedStats structure
  *
- *  @sa     HeapBufMP_getStats
+ *  @sa     HeapBufMP_getStats()
  */
 Void HeapBufMP_getExtendedStats(HeapBufMP_Handle handle,
                                 HeapBufMP_ExtendedStats *stats);
@@ -431,7 +428,7 @@ Void HeapBufMP_getExtendedStats(HeapBufMP_Handle handle,
  *  @param[in]  handle    Handle to previously created/opened instance.
  *  @param[out] stats     Memory statistics structure
  *
- *  @sa     HeapBufMP_getExtendedStats
+ *  @sa     HeapBufMP_getExtendedStats()
  */
 Void HeapBufMP_getStats(HeapBufMP_Handle handle, Ptr stats);
 
index 1de7f3dffd4eea229c88c1f625b8ab8ecce4c517..c85f5d119583139eb67181454106225c269d41fe 100644 (file)
  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/** ============================================================================
- *  @file       HeapMemMP.h
+/**
+ *  @file       ti/ipc/HeapMemMP.h
  *
  *  @brief      Multi-processor variable size buffer heap implementation
  *
+ *  @note       HeapMemMP is currently only available for SYS/BIOS.
+ *
  *  HeapMemMP is a heap implementation that manages variable size buffers that
  *  can be used in a multiprocessor system with shared memory. HeapMemMP
  *  manages a single buffer in shared memory from which blocks of user-
@@ -43,8 +45,8 @@
  *  store instance information when an instance is created.  The name supplied
  *  must be unique for all HeapMemMP instances.
  *
- *  The #HeapMemMP_create call initializes the shared memory as needed. Once an
- *  instance is created, an #HeapMemMP_open can be performed. The
+ *  HeapMemMP_create() initializes the shared memory as needed. Once an
+ *  instance is created, HeapMemMP_open() can be called. The
  *  open is used to gain access to the same HeapMemMP instance.
  *  Generally an instance is created on one processor and opened on the
  *  other processor(s).
  *  @code
  *  #include <ti/ipc/HeapMemMP.h>
  *  @endcode
- *
- *  @version        0.00.01
- *
- *  ============================================================================
  */
 
-
 #ifndef ti_ipc_HeapMemMP__include
 #define ti_ipc_HeapMemMP__include
 
@@ -84,77 +81,64 @@ extern "C" {
  */
 
 /*!
- *  @def    HeapMemMP_S_BUSY
  *  @brief  The resource is still in use
  */
 #define HeapMemMP_S_BUSY               2
 
 /*!
- *  @def    HeapMemMP_S_ALREADYSETUP
  *  @brief  The module has been already setup
  */
 #define HeapMemMP_S_ALREADYSETUP       1
 
 /*!
- *  @def    HeapMemMP_S_SUCCESS
  *  @brief  Operation is successful.
  */
 #define HeapMemMP_S_SUCCESS            0
 
 /*!
- *  @def    HeapMemMP_E_FAIL
  *  @brief  Generic failure.
  */
 #define HeapMemMP_E_FAIL              -1
 
 /*!
- *  @def    HeapMemMP_E_INVALIDARG
  *  @brief  Argument passed to function is invalid.
  */
 #define HeapMemMP_E_INVALIDARG        -2
 
 /*!
- *  @def    HeapMemMP_E_MEMORY
  *  @brief  Operation resulted in memory failure.
  */
 #define HeapMemMP_E_MEMORY            -3
 
 /*!
- *  @def    HeapMemMP_E_ALREADYEXISTS
  *  @brief  The specified entity already exists.
  */
 #define HeapMemMP_E_ALREADYEXISTS     -4
 
 /*!
- *  @def    HeapMemMP_E_NOTFOUND
  *  @brief  Unable to find the specified entity.
  */
 #define HeapMemMP_E_NOTFOUND          -5
 
 /*!
- *  @def    HeapMemMP_E_TIMEOUT
  *  @brief  Operation timed out.
  */
 #define HeapMemMP_E_TIMEOUT           -6
 
 /*!
- *  @def    HeapMemMP_E_INVALIDSTATE
  *  @brief  Module is not initialized.
  */
 #define HeapMemMP_E_INVALIDSTATE      -7
 
 /*!
- *  @def    HeapMemMP_E_OSFAILURE
  *  @brief  A failure occurred in an OS-specific call  */
 #define HeapMemMP_E_OSFAILURE         -8
 
 /*!
- *  @def    HeapMemMP_E_RESOURCE
  *  @brief  Specified resource is not available  */
 #define HeapMemMP_E_RESOURCE          -9
 
 /*!
- *  @def    HeapMemMP_E_RESTART
  *  @brief  Operation was interrupted. Please restart the operation  */
 #define HeapMemMP_E_RESTART           -10
 
@@ -170,6 +154,8 @@ typedef struct HeapMemMP_Object *HeapMemMP_Handle;
 
 /*!
  *  @brief  Structure defining parameters for the HeapMemMP module.
+ *
+ *  @sa     HeapMemMP_create()
  */
 typedef struct HeapMemMP_Params {
     String name;
@@ -197,8 +183,7 @@ typedef struct HeapMemMP_Params {
      *  This value can be left as 'null' unless it is required to place the
      *  heap at a specific location in shared memory.  If sharedAddr is null,
      *  then shared memory for a new instance will be allocated from the
-     *  heap belonging to the region identified by
-     *  #HeapMemMP_Params::regionId.
+     *  heap belonging to the region identified by #HeapMemMP_Params.regionId.
      */
     /*! @endcond */
 
@@ -226,7 +211,9 @@ typedef struct HeapMemMP_Params {
 } HeapMemMP_Params;
 
 /*!
- *  @brief  Stats structure for the HeapMemMP_getExtendedStats API.
+ *  @brief  Stats structure for HeapMemMP_getExtendedStats()
+ *
+ *  @sa     HeapMemMP_getExtendedStats()
  */
 typedef struct HeapMemMP_ExtendedStats {
     Ptr   buf;
@@ -248,10 +235,13 @@ typedef struct HeapMemMP_ExtendedStats {
  *  instance. All opened instances should be closed before the instance
  *  is deleted.
  *
- *  @param[in,out]  handlePtr   Pointer to handle returned from #HeapMemMP_open
+ *  @param[in,out]  handlePtr   Pointer to handle returned from
+ *                              HeapMemMP_open()
  *
  *  @return     HeapMemMP status:
  *              - #HeapMemMP_S_SUCCESS: Heap successfully closed
+ *
+ *  @sa         HeapMemMP_open()
  */
 Int HeapMemMP_close(HeapMemMP_Handle *handlePtr);
 
@@ -261,16 +251,20 @@ Int HeapMemMP_close(HeapMemMP_Handle *handlePtr);
  *  @param[in]  params      HeapMemMP parameters
  *
  *  @return     HeapMemMP Handle
+ *
+ *  @sa         HeapMemMP_delete()
  */
 HeapMemMP_Handle HeapMemMP_create(const HeapMemMP_Params *params);
 
 /*!
  *  @brief      Delete a created HeapMemMP instance
  *
- *  @param[in,out]      handlePtr   Pointer to handle to delete.
+ *  @param[in,out]  handlePtr   Pointer to handle to delete.
  *
  *  @return     HeapMemMP status:
  *              - #HeapMemMP_S_SUCCESS: Heap successfully deleted
+ *
+ *  @sa         HeapMemMP_create()
  */
 Int HeapMemMP_delete(HeapMemMP_Handle *handlePtr);
 
@@ -308,8 +302,9 @@ Int HeapMemMP_openByAddr(Ptr sharedAddr, HeapMemMP_Handle *handlePtr);
 /*!
  *  @brief      Initialize a HeapMemMP parameters struct
  *
- *  @param[out] params      Pointer to GateMP parameters
+ *  @param[out] params      Pointer to creation parameters
  *
+ *  @sa         HeapMemMP_create()
  */
 Void HeapMemMP_Params_init(HeapMemMP_Params *params);
 
@@ -345,8 +340,8 @@ SizeT HeapMemMP_sharedMemReq(const HeapMemMP_Params *params);
  *      - If possible, allocate larger blocks first. Previous allocations
  *        of small memory blocks can reduce the size of the blocks
  *        available for larger memory allocations.
- *      - Realize that alloc() can fail even if the heap contains a
- *        sufficient absolute amount of unalloccated space. This is
+ *      - Realize that allocation can fail even if the heap contains a
+ *        sufficient absolute amount of unallocated space. This is
  *        because the largest free memory block may be smaller than
  *        total amount of unallocated memory.
  *
@@ -354,26 +349,26 @@ SizeT HeapMemMP_sharedMemReq(const HeapMemMP_Params *params);
  *  @param[in]  size      Size to be allocated (in MADUs)
  *  @param[in]  align     Alignment for allocation (power of 2)
  *
- *  @sa         HeapMemMP_free
+ *  @sa         HeapMemMP_free()
  */
 Void *HeapMemMP_alloc(HeapMemMP_Handle handle, SizeT size, SizeT align);
 
 /*!
  *  @brief      Frees a block of memory.
  *
- *  free() places the memory block specified by addr and size back into the
- *  free pool of the heap specified. The newly freed block is combined with
- *  any adjacent free blocks. The space is then available for further
- *  allocation by alloc().
+ *  HeapMemMP_free() places the memory block specified by addr and size back
+ *  into the free pool of the heap specified. The newly freed block is combined
+ *  with any adjacent free blocks. The space is then available for future
+ *  allocations.
  *
- *  #HeapMemMP_free will lock the heap using the HeapMemMP gate if one is
+ *  HeapMemMP_free() will lock the heap using the HeapMemMP gate if one is
  *  specified or the system GateMP if not.
  *
  *  @param[in]  handle    Handle to previously created/opened instance.
  *  @param[in]  block     Block of memory to be freed.
  *  @param[in]  size      Size to be freed (in MADUs)
  *
- *  @sa         HeapMemMP_alloc
+ *  @sa         HeapMemMP_alloc()
  */
 Void HeapMemMP_free(HeapMemMP_Handle handle, Ptr block, SizeT size);
 
@@ -398,7 +393,7 @@ Void HeapMemMP_getExtendedStats(HeapMemMP_Handle handle,
  *  @param[in]  handle    Handle to previously created/opened instance.
  *  @param[out] stats     Memory statistics structure
  *
- *  @sa     HeapMemMP_getExtendedStats
+ *  @sa     HeapMemMP_getExtendedStats()
  */
 Void HeapMemMP_getStats(HeapMemMP_Handle handle, Ptr stats);
 
index 785086e6c6c25d67fb7f733bb931bf33dc62d166..e3ed2c02fe0bc44ce54e8c6220696029587862c3 100644 (file)
  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/** ============================================================================
- *  @file       HeapMultiBufMP.h
+/**
+ *  @file       ti/ipc/HeapMultiBufMP.h
  *
  *  @brief      Multiple fixed size buffer heap implementation.
  *
+ *  @note       HeapBufMP is currently only available for SYS/BIOS.
+ *
  *  The HeapMultiBufMP manager provides functions to allocate and free storage
  *  from a shared memory heap of type HeapMultiBufMP which inherits from IHeap.
  *  HeapMultiBufMP manages multiple fixed-size memory buffers. Each buffer
  *  Allocating from HeapMultiBufMP will try to return a block from the first
  *  buffer which has:
  *
- *    1. A block size that is >= to the requested size
- *
- *    AND
- *
+ *    1. A block size that is >= to the requested size, and
  *    2. An alignment that is >= to the requested alignment
  *
  *  Buffer configuration for a new instance is primarily supplied via the
- *  #HeapMultiBufMP_Params::bucketEntries instance configuration parameter.
+ *  #HeapMultiBufMP_Params.bucketEntries instance configuration parameter.
  *  Once buckets are adjusted for size and alignment, buffers with equal sizes
  *  and alignments are combined.
  *
@@ -77,8 +76,8 @@
  *        will be merged. If this is a problem, consider managing these buffers
  *        directly with HeapBufMP objects.
  *
- *  In addition to the buffer configuration, a #HeapMultiBufMP_Params::name
- *  and a #HeapMultiBufMP_Params::regionId (from which shared memory is
+ *  In addition to the buffer configuration, a #HeapMultiBufMP_Params.name
+ *  and a #HeapMultiBufMP_Params.regionId (from which shared memory is
  *  allocated) must be supplied when creating an instance.
  *
  *  Once an instance is created, HeapMultiBufMP_open() can be performed using the
  *  @code
  *  #include <ti/ipc/HeapMultiBufMP.h>
  *  @endcode
- *
- *  @version        0.00.01
- *
- *  ============================================================================
  */
 
-
 #ifndef ti_ipc_HeapMultiBufMP__include
 #define ti_ipc_HeapMultiBufMP__include
 
@@ -205,7 +199,7 @@ typedef struct HeapMultiBufMP_Object *HeapMultiBufMP_Handle;
  *  HeapMultiBufMP instance.  The fields of each bucket correspond
  *  to the attributes of each buffer in the HeapMultiBufMP.  The actual
  *  block sizes and alignments may be adjusted per the process described
- *  at #HeapMultiBufMP_Params::bucketEntries.
+ *  at #HeapMultiBufMP_Params.bucketEntries.
  */
 typedef struct HeapMultiBufMP_Bucket {
     SizeT blockSize;    /*!< Size of each block in this bucket (in MADUs)   */
@@ -218,21 +212,21 @@ typedef struct HeapMultiBufMP_Bucket {
  */
 typedef struct HeapMultiBufMP_Params {
     GateMP_Handle gate;
-    /*!< GateMP used for critical region management of the shared memory
+    /*!< @brief GateMP used for critical region management of the shared memory
      *
      *  Using the default value of NULL will result in use of the GateMP
      *  system gate for context protection.
      */
 
     Bool exact;
-    /*!< Use exact matching
+    /*!< @brief Use exact matching
      *
      *  Setting this flag will allow allocation only if the requested size
      *  is equal to (rather than less than or equal to) a buffer's block size.
      */
 
     String name;
-    /*!< Name of this instance.
+    /*!< @brief Name of this instance.
      *
      *  The name (if not NULL) must be unique among all HeapMultiBufMP
      *  instances in the entire system.  When creating a new
@@ -243,13 +237,13 @@ typedef struct HeapMultiBufMP_Params {
      */
 
     Int numBuckets;
-    /*!< Number of buckets in #HeapMultiBufMP_Params::bucketEntries
+    /*!< @brief Number of buckets in #HeapMultiBufMP_Params.bucketEntries
      *
      *  This parameter is required to create any instance.
      */
 
     HeapMultiBufMP_Bucket *bucketEntries;
-    /*!< Bucket Entries
+    /*!< @brief Bucket Entries
      *
      *  The bucket entries are an array of #HeapMultiBufMP_Bucket whose values
      *  correspond to the desired alignment, block size and length for each
@@ -267,7 +261,7 @@ typedef struct HeapMultiBufMP_Params {
      */
 
     UInt16 regionId;
-    /*!<Shared region ID
+    /*!< @brief Shared region ID
      *
      *  The index corresponding to the shared region from which shared memory
      *  will be allocated.
@@ -281,7 +275,7 @@ typedef struct HeapMultiBufMP_Params {
      *  heap at a specific location in shared memory.  If sharedAddr is null,
      *  then shared memory for a new instance will be allocated from the
      *  heap belonging to the region identified by
-     *  #HeapMultiBufMP_Params::regionId.
+     *  #HeapMultiBufMP_Params.regionId.
      */
     /*! @endcond */
 
@@ -330,7 +324,7 @@ typedef struct HeapMultiBufMP_ExtendedStats {
  *  @param[in,out]  handlePtr   Pointer to handle returned from
  *                              #HeapMultiBufMP_open
  *
- *  @sa         HeapMultiBufMP_open
+ *  @sa         HeapMultiBufMP_open()
  */
 Int HeapMultiBufMP_close(HeapMultiBufMP_Handle *handlePtr);
 
@@ -340,6 +334,8 @@ Int HeapMultiBufMP_close(HeapMultiBufMP_Handle *handlePtr);
  *  @param[in]  params      HeapMultiBufMP parameters
  *
  *  @return     HeapMultiBufMP Handle
+ *
+ *  @sa         HeapMultiBufMP_delete()
  */
 HeapMultiBufMP_Handle HeapMultiBufMP_create(const HeapMultiBufMP_Params *params);
 
@@ -375,7 +371,7 @@ Int HeapMultiBufMP_delete(HeapMultiBufMP_Handle *handlePtr);
  *              - #HeapMultiBufMP_E_NOTFOUND: Heap is not yet ready to be opened.
  *              - #HeapMultiBufMP_E_FAIL: A general failure has occurred
  *
- *  @sa         HeapMultiBufMP_close
+ *  @sa         HeapMultiBufMP_close()
  */
 Int HeapMultiBufMP_open(String name, HeapMultiBufMP_Handle *handlePtr);
 
@@ -419,7 +415,7 @@ SizeT HeapMultiBufMP_sharedMemReq(const HeapMultiBufMP_Params *params);
  *  @param[in] size      Size to be allocated (in MADUs)
  *  @param[in] align     Alignment for allocation (power of 2)
  *
- *  @sa         HeapMultiBufMP_free
+ *  @sa         HeapMultiBufMP_free()
  */
 Void *HeapMultiBufMP_alloc(HeapMultiBufMP_Handle handle, SizeT size,
                            SizeT align);
@@ -431,7 +427,7 @@ Void *HeapMultiBufMP_alloc(HeapMultiBufMP_Handle handle, SizeT size,
  *  @param[in]  block     Block of memory to be freed.
  *  @param[in]  size      Size to be freed (in MADUs)
  *
- *  @sa         HeapMultiBufMP_alloc
+ *  @sa         HeapMultiBufMP_alloc()
  */
 Void HeapMultiBufMP_free(HeapMultiBufMP_Handle handle, Ptr block, SizeT size);
 
index ba0c708e68c38c8ca18bbaa9a47794c156b36d8e..4d2aee88470ae4df4c9601bcaa7bc35729753daf 100644 (file)
  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/** ===========================================================================
- *  @file       Ipc.h
+/**
+ *  @file       ti/ipc/Ipc.h
  *
  *  @brief      Ipc Manager.
  *
  *  This module is primarily used to configure IPC, synchronize processors, and
- *  initialize the IPC runtime.  The memory for SharedRegion zero must be valid
+ *  initialize the IPC runtime.
+ *
+ *  On SYS/BIOS, the memory for SharedRegion zero must be valid
  *  before Ipc_start() can be called.  Ipc_start() must be called before any
  *  other IPC APIs are used.
  *
@@ -43,8 +45,6 @@
  *  @code
  *  #include <ti/ipc/Ipc.h>
  *  @endcode
- *
- *  ============================================================================
  */
 
 #ifndef ti_ipc_Ipc__include
@@ -60,85 +60,71 @@ extern "C" {
  */
 
 /*!
- *  @def    Ipc_S_BUSY
  *  @brief  The resource is still in use
  */
 #define Ipc_S_BUSY              2
 
 /*!
- *  @def    Ipc_S_ALREADYSETUP
  *  @brief  The module has been already setup
  */
 #define Ipc_S_ALREADYSETUP      1
 
 /*!
- *  @def    Ipc_S_SUCCESS
  *  @brief  Operation is successful.
  */
 #define Ipc_S_SUCCESS           0
 
 /*!
- *  @def    Ipc_E_FAIL
  *  @brief  Generic failure.
  */
 #define Ipc_E_FAIL             -1
 
 /*!
- *  @def    Ipc_E_INVALIDARG
  *  @brief  Argument passed to function is invalid.
  */
 #define Ipc_E_INVALIDARG       -2
 
 /*!
- *  @def    Ipc_E_MEMORY
  *  @brief  Operation resulted in memory failure.
  */
 #define Ipc_E_MEMORY           -3
 
 /*!
- *  @def    Ipc_E_ALREADYEXISTS
  *  @brief  The specified entity already exists.
  */
 #define Ipc_E_ALREADYEXISTS    -4
 
 /*!
- *  @def    Ipc_E_NOTFOUND
  *  @brief  Unable to find the specified entity.
  */
 #define Ipc_E_NOTFOUND         -5
 
 /*!
- *  @def    Ipc_E_TIMEOUT
  *  @brief  Operation timed out.
  */
 #define Ipc_E_TIMEOUT          -6
 
 /*!
- *  @def    Ipc_E_INVALIDSTATE
  *  @brief  Module is not initialized or in an invalid state.
  */
 #define Ipc_E_INVALIDSTATE     -7
 
 /*!
- *  @def    Ipc_E_OSFAILURE
  *  @brief  A failure occurred in an OS-specific call
  */
 #define Ipc_E_OSFAILURE        -8
 
 /*!
- *  @def    Ipc_E_RESOURCE
  *  @brief  Specified resource is not available
  */
 #define Ipc_E_RESOURCE         -9
 
 /*!
- *  @def    Ipc_E_RESTART
  *  @brief  Operation was interrupted. Please restart the operation
  */
 #define Ipc_E_RESTART          -10
 
 /*!
- *  @def    Ipc_E_NOTREADY
  *  @brief  Operation was not ready.
  */
 #define Ipc_E_NOTREADY         -11
@@ -152,8 +138,10 @@ extern "C" {
 /*!
  *  @brief      Attach to remote processor
  *
- *  This function uses shared memory to synchronize self with the remote
- *  processor.  Both processors must call this function to attach to each
+ *  @note       This function is currently only supported on SYS/BIOS.
+ *
+ *  This function synchronizes with the remote processor, typically via
+ *  shared memory.  Both processors must call this function to attach to each
  *  other.  Ipc_start() must be called before calling Ipc_attach().
  *  A processor must attach to the owner of SharedRegion zero before
  *  it can successfully attach to another processor.  Attempting to
@@ -165,13 +153,13 @@ extern "C" {
  *  processor in SharedRegion zero heap.  The user's Ipc attach function
  *  is called.
  *
- *  For BIOS, this function should be called within a 'while' loop
+ *  On SYS/BIOS, this function should be called within a 'while' loop
  *  within a Task.  A Task_sleep() or Task_yield() should be called
  *  within the loop to allow other threads in the system to execute.
  *  This function needs to be called in a loop because the remote
  *  processor may not be in a ready state.
  *
- *  Note:  For BIOS, if the config parameter Ipc.procSync is set to
+ *  @note For SYS/BIOS, if the config parameter Ipc.procSync is set to
  *  Ipc.ProcSync_ALL, there is no need to call this function as it is
  *  internally called by Ipc_start().
  *
@@ -190,13 +178,16 @@ extern "C" {
  *              - #Ipc_E_FAIL: General failure
  *              - #Ipc_E_NOTREADY: remote processor not ready
  *
- *  @sa         Ipc_detach Ipc_isAttached
+ *  @sa         Ipc_detach()
+ *  @sa         Ipc_isAttached()
  */
 Int Ipc_attach(UInt16 remoteProcId);
 
 /*!
  *  @brief      Detach from the remote processor
  *
+ *  @note       This function is currently only supported on SYS/BIOS.
+ *
  *  A processor must detach from all other processors before it can
  *  successfully detach from the owner of SharedRegion zero.  Attempting to
  *  detach from the owner of SharedRegion zero first returns #Ipc_E_FAIL.
@@ -218,7 +209,7 @@ Int Ipc_attach(UInt16 remoteProcId);
  *  this function deletes the instances created for communicating with the
  *  specified remote processor.
  *
- *  For BIOS, this function should be called within a 'while' loop in a Task
+ *  For SYS/BIOS, this function should be called within a 'while' loop in a Task
  *  because the slave may have to wait for the master to detach.  Furthermore,
  *  a Task_sleep() or Task_yield() should be called within the same 'while'
  *  loop to allow other threads in the system to execute.
@@ -247,29 +238,34 @@ Int Ipc_attach(UInt16 remoteProcId);
  *              - #Ipc_E_FAIL: operation failed
  *              - #Ipc_E_NOTREADY: processor not ready to detach
  *
- *  @sa         Ipc_attach Ipc_isAttached
+ *  @sa         Ipc_attach()
+ *  @sa         Ipc_isAttached()
  */
 Int Ipc_detach(UInt16 remoteProcId);
 
 /*!
  *  @brief      Query whether attached to a remote processor
  *
- *  Returns TRUE if attached to a remote processor and FALSE otherwise.  If
- *  remoteProcId == MultiProc_self(), FALSE is always returned.
+ *  @note       This function is currently only supported on SYS/BIOS.
  *
  *  @param      remoteProcId  remote processor's MultiProc id
  *
  *  @return     TRUE if attached, FALSE if not attached
  *
- *  @sa         Ipc_attach Ipc_detach
+ *  @remark     If @c remoteProcId == MultiProc_self(), FALSE is always returned.
+ *
+ *  @sa         Ipc_attach()
+ *  @sa         Ipc_detach()
  */
 Bool Ipc_isAttached(UInt16 remoteProcId);
 
 /*!
  *  @brief      Reads the config entry from the config area.
  *
+ *  @note       This function is currently only supported on SYS/BIOS.
+ *
  *  For more information about this API, refer to the documentation for
- *  #Ipc_writeConfig
+ *  Ipc_writeConfig()
  *
  *  @param      remoteProcId  remote processor's MultiProc id
  *  @param      tag           tag to identify a config entry
@@ -291,7 +287,7 @@ Int Ipc_readConfig(UInt16 remoteProcId, UInt32 tag, Ptr cfg, SizeT size);
  *  only be called once, unless the return value is #Ipc_E_NOTREADY.
  *  This indicates that either the SharedRegion zero is not valid or
  *  has not been setup yet so Ipc_start may be called again. Once
- *  sucessfully started, subsequent calls returns #Ipc_S_ALREADYSETUP.
+ *  successfully started, subsequent calls returns #Ipc_S_ALREADYSETUP.
  *
  *  Ipc reserves some shared memory in SharedRegion zero for synchronization.
  *  GateMP reserves some shared memory for managing the gates and for the
@@ -300,7 +296,7 @@ Int Ipc_readConfig(UInt16 remoteProcId, UInt32 tag, Ptr cfg, SizeT size);
  *  memory and creates the default GateMP. The default heap for each
  *  SharedRegion is created by the owner of each SharedRegion.
  *
- *  Note:  For BIOS, if the config parameter Ipc.procSync is set to
+ *  @note For SYS/BIOS, if the config parameter Ipc.procSync is set to
  *  Ipc.ProcSync_ALL, this function calls Ipc_attach() internally.
  *
  *  @return     Status
@@ -308,6 +304,8 @@ Int Ipc_readConfig(UInt16 remoteProcId, UInt32 tag, Ptr cfg, SizeT size);
  *              - #Ipc_S_ALREADYSETUP: already successfully called
  *              - #Ipc_E_NOTREADY: shared memory is not ready
  *              - #Ipc_E_FAIL: operation failed
+ *
+ *  @sa         Ipc_stop()
  */
 Int Ipc_start(Void);
 
@@ -320,27 +318,31 @@ Int Ipc_start(Void);
  *
  *  @return     Status
  *              - #Ipc_S_SUCCESS: operation was successful
+ *
+ *  @sa         Ipc_start()
  */
 Int Ipc_stop(Void);
 
 /*!
  *  @brief      Writes the config entry to the config area.
  *
- *  The #Ipc_writeConfig and #Ipc_readConfig APIs are used to pass
+ *  @note       This function is currently only supported on SYS/BIOS.
+ *
+ *  Ipc_writeConfig() and Ipc_readConfig() are used to pass
  *  configuration information from one core to another.  This 'information'
  *  is passed via a pointer to shared memory with a given size and is
  *  identified via a unique tag.  A typical use case of this API would be
- *  passing configuration information from a Slave core to the Host at
- *  startup-time.  For example, if MessageQ is used, this information
- *  might include the queue name, message heap sizes, etc.
+ *  passing configuration information at startup-time.  For example, if
+ *  MessageQ is used, this information might include the queue name, message
+ *  heap sizes, etc.
  *
- *  For #Ipc_writeConfig, if 'NULL' is passed in for the cfg parameter,
+ *  For Ipc_writeConfig(), if 'NULL' is passed in for the cfg parameter,
  *  it attempts to free the shared memory that is allocated by a previous
- *  #Ipc_writeConfig call. The remoteProcId, tag, and size must match
- *  the previous #Ipc_writeConfig call.
+ *  Ipc_writeConfig() call. The @c remoteProcId, @c tag, and @c size must match
+ *  the previous Ipc_writeConfig() call.
  *
- *  The #Ipc_writeConfig API writes into SharedRegion 0 (SR0) and uses
- *  the tag to uniquely identify the structure (cfg) and size written
+ *  Ipc_writeConfig() writes into SharedRegion 0 (SR0) and uses
+ *  @c tag to uniquely identify the structure (@c cfg) and @c size written
  *  into SR0 which both sides must agree on.
  *
  *  @param      remoteProcId  remote processor's MultiProc id
@@ -352,7 +354,7 @@ Int Ipc_stop(Void);
  *              - #Ipc_S_SUCCESS: if operation was successful
  *              - #Ipc_E_FAIL: if operation failed
  *
- *  @sa         Ipc_readConfig
+ *  @sa         Ipc_readConfig()
  */
 Int Ipc_writeConfig(UInt16 remoteProcId, UInt32 tag, Ptr cfg, SizeT size);
 
index 0a84d869a42ac766f7f23df2897f6b9ad7cbf8f6..702d7a0252e7440e4e0673a214decc7672f1d470 100644 (file)
  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/** ===========================================================================
- *  @file       ListMP.h
+/**
+ *  @file       ti/ipc/ListMP.h
  *
  *  @brief      Multiple processor shared memory list
  *
+ *  @note       ListMP is currently only available for SYS/BIOS.
+ *
  *  ListMP is a doubly linked-list based module designed to be used
  *  in a multi-processor environment.  It provides a way for
  *  multiple processors to create, access, and manipulate the same link
@@ -61,8 +63,6 @@
  *  @code
  *  #include <ti/ipc/ListMP.h>
  *  @endcode
- *
- *  ============================================================================
  */
 
 #ifndef ti_ipc_ListMP__include
@@ -81,79 +81,66 @@ extern "C" {
  */
 
 /*!
- *  @def    ListMP_S_BUSY
  *  @brief  The resource is still in use
  */
 #define ListMP_S_BUSY            2
 
 /*!
- *  @def    ListMP_S_ALREADYSETUP
  *  @brief  The module has been already setup
  */
 #define ListMP_S_ALREADYSETUP    1
 
 /*!
- *  @def    ListMP_S_SUCCESS
  *  @brief  Operation is successful.
  */
 #define ListMP_S_SUCCESS         0
 
 /*!
- *  @def    ListMP_E_FAIL
  *  @brief  Generic failure.
  */
 #define ListMP_E_FAIL           -1
 
 /*!
- *  @def    ListMP_E_INVALIDARG
  *  @brief  Argument passed to function is invalid.
  */
 #define ListMP_E_INVALIDARG     -2
 
 /*!
- *  @def    ListMP_E_MEMORY
  *  @brief  Operation resulted in memory failure.
  */
 #define ListMP_E_MEMORY         -3
 
 /*!
- *  @def    ListMP_E_ALREADYEXISTS
  *  @brief  The specified entity already exists.
  */
 #define ListMP_E_ALREADYEXISTS  -4
 
 /*!
- *  @def    ListMP_E_NOTFOUND
  *  @brief  Unable to find the specified entity.
  */
 #define ListMP_E_NOTFOUND       -5
 
 /*!
- *  @def    ListMP_E_TIMEOUT
  *  @brief  Operation timed out.
  */
 #define ListMP_E_TIMEOUT        -6
 
 /*!
- *  @def    ListMP_E_INVALIDSTATE
  *  @brief  Module is not initialized.
  */
 #define ListMP_E_INVALIDSTATE   -7
 
 /*!
- *  @def    ListMP_E_OSFAILURE
  *  @brief  A failure occurred in an OS-specific call
  */
 #define ListMP_E_OSFAILURE      -8
 
 /*!
- *  @def    ListMP_E_RESOURCE
  *  @brief  Specified resource is not available
  */
 #define ListMP_E_RESOURCE       -9
 
 /*!
- *  @def    ListMP_E_RESTART
  *  @brief  Operation was interrupted. Please restart the operation
  */
 #define ListMP_E_RESTART        -10
@@ -242,7 +229,7 @@ Void ListMP_Params_init(ListMP_Params *params);
  *
  *  @return     ListMP instance handle.  NULL if create failed.
  *
- *  @sa         ListMP_delete
+ *  @sa         ListMP_delete()
  */
 ListMP_Handle ListMP_create(const ListMP_Params *params);
 
@@ -260,7 +247,7 @@ ListMP_Handle ListMP_create(const ListMP_Params *params);
  *              - #ListMP_S_SUCCESS:  ListMP successfully closed
  *              - #ListMP_E_FAIL:  A general failure has occurred
  *
- *  @sa         ListMP_open
+ *  @sa         ListMP_open()
  */
 Int ListMP_close(ListMP_Handle *handlePtr);
 
@@ -273,7 +260,7 @@ Int ListMP_close(ListMP_Handle *handlePtr);
  *              - #ListMP_S_SUCCESS:  ListMP successfully deleted
  *                  - #ListMP_E_FAIL:  ListMP delete failed
  *
- *  @sa         ListMP_create
+ *  @sa         ListMP_create()
  */
 Int ListMP_delete(ListMP_Handle *handlePtr);
 
@@ -307,7 +294,8 @@ Int ListMP_delete(ListMP_Handle *handlePtr);
  *              - #ListMP_E_NOTFOUND: ListMP is not yet ready to be opened.
  *              - #ListMP_E_FAIL: A general failure has occurred
  *
- *  @sa         ListMP_create
+ *  @sa         ListMP_close()
+ *  @sa         ListMP_create()
  */
 Int ListMP_open(String name, ListMP_Handle *handlePtr);
 
@@ -387,12 +375,11 @@ GateMP_Handle ListMP_getGate(ListMP_Handle handle);
  *
  *  Atomically removes the element from the front of a
  *  ListMP instance and returns a pointer to it.
- *  Uses #ListMP_Params#gate for critical region management.
+ *  Uses #ListMP_Params.gate for critical region management.
  *
  *  @param  handle  a ListMP handle.
  *
- *  @return     pointer to former first element.
- *              -NULL if the ListMP is empty.
+ *  @return     pointer to former first element. NULL if the ListMP is empty.
  */
 Ptr ListMP_getHead(ListMP_Handle handle);
 
@@ -401,22 +388,21 @@ Ptr ListMP_getHead(ListMP_Handle handle);
  *
  *  Atomically removes the element from the back of a
  *  ListMP instance and returns a pointer to it.
- *  Uses #ListMP_Params#gate for critical region management.
+ *  Uses #ListMP_Params.gate for critical region management.
  *
  *  @param      handle  a ListMP handle.
  *
- *  @return     pointer to former last element
- *              -NULL if the ListMP is empty.
+ *  @return     pointer to former last element.  NULL if the ListMP is empty.
  */
 Ptr ListMP_getTail(ListMP_Handle handle);
 
 /*!
  *  @brief      Insert an element into a ListMP instance
  *
- *  Atomically inserts `newElem` in the instance in front of `curElem`.
+ *  Atomically inserts @c newElem in the instance in front of @c curElem.
  *  To place an element at the back of a ListMP instance, use
- *  #ListMP_putTail.  To place an element at the front of a
- *  ListMP instance, use #ListMP_putHead.
+ *  ListMP_putTail().  To place an element at the front of a
+ *  ListMP instance, use ListMP_putHead().
  *
  *  The following code shows an example.
  *
@@ -523,7 +509,7 @@ Ptr ListMP_prev(ListMP_Handle handle, ListMP_Elem *elem);
  *  @brief      Put an element at head of a ListMP instance
  *
  *  Atomically places the element at the front of a ListMP instance.
- *  Uses #ListMP_Params#gate for critical region management.
+ *  Uses #ListMP_Params.gate for critical region management.
  *
  *  @param      handle  a ListMP handle
  *  @param      elem    pointer to new ListMP element
@@ -538,7 +524,7 @@ Int ListMP_putHead(ListMP_Handle handle, ListMP_Elem *elem);
  *  @brief      Put an element at back of a ListMP instance
  *
  *  Atomically places the element at the back of a ListMP instance.
- *  Uses #ListMP_Params#gate for critical region management.
+ *  Uses #ListMP_Params.gate for critical region management.
  *
  *  @param      handle  a ListMP handle
  *  @param      elem    pointer to new ListMP element
@@ -554,7 +540,7 @@ Int ListMP_putTail(ListMP_Handle handle, ListMP_Elem *elem);
  *
  *  Atomically removes an element from a ListMP.
  *
- *  The `elem` parameter is a pointer to an existing element to be removed
+ *  The @c elem parameter is a pointer to an existing element to be removed
  *  from a ListMP instance.
  *
  *  @param      handle  a ListMP handle
index 4a6623d2f7a856f44452d29850b9659956f51b5a..820713ca19d915848b5803cab03fbba9eb67fa9b 100644 (file)
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
-/** ============================================================================
- *  @file       MessageQ.h
+/**
+ *  @file       ti/ipc/MessageQ.h
  *
  *  @brief      MessageQ Manager
  *
  *  The MessageQ module supports the structured sending and receiving of
  *  variable length messages. This module can be used for homogeneous
- *  (DSP to DSP)  or heterogeneous (Arm to DSP) multi-processor messaging.
+ *  (e.g. DSP to DSP) or heterogeneous (e.g. ARM to DSP) multi-processor
+ *  messaging.
  *
  *  MessageQ provides more sophisticated messaging than other modules. It is
  *  typically used for complex situations such as multi-processor messaging.
  *
  *  MessageQ supports reads/writes of different thread models. This is
  *  accomplished by having the creator of the message queue specify a
- *  synchronizer via the #MessageQ_Params::synchronizer
+ *  synchronizer via the #MessageQ_Params.synchronizer
  *  configuration parameter. The synchronizer is signaled whenever the
  *  MessageQ_put() is called. The synchronizer waits if MessageQ_get() is called
  *  and there are no messages.
  *
  *  Since ISyncs are binary, the reader must drain the message queue of all
  *  messages before waiting for another signal. For example, if the reader
- *  was a SYSBIOS Swi, the synchronizer instance could be a SyncSwi.
- *  If a #MessageQ_put was called, the Swi_post() would
- *  be called. The Swi would run and it must call #MessageQ_get until no
+ *  was a SYS/BIOS Swi, the synchronizer instance could be a SyncSwi.
+ *  If a MessageQ_put() was called, the Swi_post() would
+ *  be called. The Swi would run and it must call MessageQ_get() until no
  *  messages are returned.
  *
  *  The MessageQ header should be included in an application as follows:
  *  @code
  *  #include <ti/ipc/MessageQ.h>
  *  @endcode
- *
- *  @version        0.00.01
- *
- *  ============================================================================
  */
 
 #ifndef ti_ipc_MessageQ__include
@@ -356,7 +353,7 @@ extern "C" {
  *  into the message with the MessageQ_setReplyQueue() function. The receiver of
  *  the message can extract the message queue ID with this function.
  *
- *  This method is particularing useful in a client/server relationship where
+ *  This method is particularly useful in a client/server relationship where
  *  the server does not want to know who the clients are. The clients can embed
  *  their message queue into the message to the server and the server extracts
  *  it and uses it to reply.
@@ -457,7 +454,7 @@ typedef MessageQ_MsgHeader *MessageQ_Msg;
 typedef enum {
     MessageQ_NORMALPRI      = 0,    /*!< Normal Priority                  */
     MessageQ_HIGHPRI        = 1,    /*!< High Priority                    */
-    MessageQ_RESERVEDPRI    = 2,    /*!< Reserved Priorit                 */
+    MessageQ_RESERVEDPRI    = 2,    /*!< Reserved Priority                 */
     MessageQ_URGENTPRI      = 3     /*!< Urgent Priority                  */
 } MessageQ_Priority;
 
@@ -710,7 +707,7 @@ Int MessageQ_get(MessageQ_Handle handle, MessageQ_Msg *msg, UInt timeout);
  *  - MessageQ_getDstQueue()
  *
  *  After the message is placed onto the final destination, the queue's
- *  #MessageQ_Params::synchronizer signal function is called.
+ *  #MessageQ_Params.synchronizer signal function is called.
  *
  *  The application loses ownership of the message once MessageQ_put() is called.
  *
index a86b9ac5cd85633e1c741da903e8f38130fe4288..cda9a74182234c7d971f775304f78a52b6aed134 100644 (file)
  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/** ===========================================================================
- *  @file       MultiProc.h
+/**
+ *  @file       ti/ipc/MultiProc.h
  *
  *  @brief      Processor ID Manager
  *
  *  Many IPC modules require the ability to uniquely specify and identify
  *  processors in a multi-processor environment. The MultiProc module
- *  centeralizes processor id management into one module.  Since this
+ *  centralizes processor id management into one module.  Since this
  *  configuration is almost always universally required, most IPC applications
  *  require supplying configuration of this module.
  *
  *  Each processor in the MultiProc module may be uniquely identified by
  *  either a name string or an integer ranging from 0 to NUMPROCESSORS - 1.
  *
- *  At runtime, the #MultiProc_getId call returns the MultiProc id for any
+ *  At runtime, the MultiProc_getId() call returns the MultiProc id for any
  *  processor given its name.
  *
  *  The MultiProc header should be included in an application as follows:
@@ -65,79 +65,66 @@ extern "C" {
  */
 
 /*!
- *  @def    MultiProc_S_BUSY
  *  @brief  The resource is still in use
  */
 #define MultiProc_S_BUSY                 2
 
 /*!
- *  @def    MultiProc_S_ALREADYSETUP
  *  @brief  The module has been already setup
  */
 #define MultiProc_S_ALREADYSETUP         1
 
 /*!
- *  @def    MultiProc_S_SUCCESS
  *  @brief  Operation is successful.
  */
 #define MultiProc_S_SUCCESS              0
 
 /*!
- *  @def    MultiProc_E_FAIL
  *  @brief  Generic failure.
  */
 #define MultiProc_E_FAIL                -1
 
 /*!
- *  @def    MultiProc_E_INVALIDARG
  *  @brief  Argument passed to function is invalid.
  */
 #define MultiProc_E_INVALIDARG          -2
 
 /*!
- *  @def    MultiProc_E_MEMORY
  *  @brief  Operation resulted in memory failure.
  */
 #define MultiProc_E_MEMORY              -3
 
 /*!
- *  @def    MultiProc_E_ALREADYEXISTS
  *  @brief  The specified entity already exists.
  */
 #define MultiProc_E_ALREADYEXISTS       -4
 
 /*!
- *  @def    MultiProc_E_NOTFOUND
  *  @brief  Unable to find the specified entity.
  */
 #define MultiProc_E_NOTFOUND            -5
 
 /*!
- *  @def    MultiProc_E_TIMEOUT
  *  @brief  Operation timed out.
  */
 #define MultiProc_E_TIMEOUT             -6
 
 /*!
- *  @def    MultiProc_E_INVALIDSTATE
  *  @brief  Module is not initialized.
  */
 #define MultiProc_E_INVALIDSTATE        -7
 
 /*!
- *  @def    MultiProc_E_OSFAILURE
  *  @brief  A failure occurred in an OS-specific call
  */
 #define MultiProc_E_OSFAILURE           -8
 
 /*!
- *  @def    MultiProc_E_RESOURCE
  *  @brief  Specified resource is not available
  */
 #define MultiProc_E_RESOURCE            -9
 
 /*!
- *  @def    MultiProc_E_RESTART
  *  @brief  Operation was interrupted. Please restart the operation
  */
 #define MultiProc_E_RESTART             -10
@@ -148,7 +135,6 @@ extern "C" {
  */
 
 /*!
- *  @def    MultiProc_INVALIDID
  *  @brief  Invalid processor id.
  */
 #define MultiProc_INVALIDID             (0xFFFF)
@@ -225,7 +211,7 @@ UInt16 MultiProc_self(Void);
  *  @param      baseId  The MultiProc base id of the cluster
  *
  *  @return     MultiProc status:
- *              - #MultiProc_S_SUCCESS: sucessfully set base id of cluster
+ *              - #MultiProc_S_SUCCESS: successfully set base id of cluster
  *              - #MultiProc_E_FAIL:    failed to set base id of cluster
  */
 Int MultiProc_setBaseIdOfCluster(UInt16 baseId);
index 7055f500b85e1a72adef95cf788532b395b80aa1..7e8666c93a12ce3f14ade9825f11c83cc8bf7605 100644 (file)
  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/** ===========================================================================
- *  @file       NameServer.h
+/**
+ *  @file       ti/ipc/NameServer.h
  *
  *  @brief      NameServer Manager
  *
  *  The NameServer module manages local name/value pairs that
  *  enables an application and other modules to store and
  *  retrieve values based on a name. The module supports different
- *  lengths of values. The #NameServer_add and #NameServer_get
- *  functions are for variable length values. The #NameServer_addUInt32 and
- *  #NameServer_getUInt32 functions are optimized for UInt32 variables
+ *  lengths of values. The NameServer_add() and NameServer_get()
+ *  functions are for variable length values. The NameServer_addUInt32() and
+ *  NameServer_getUInt32() functions are optimized for UInt32 variables
  *  and constants.
  *
  *  The NameServer module maintains thread-safety for the APIs. However,
@@ -68,7 +68,7 @@
  *  The NameServer module uses the MultiProc module for
  *  identifying the different processors. Which remote processors and
  *  the order they are queried is determined by the procId array in the
- *  #NameServer_get function.
+ *  NameServer_get() function.
  *
  *  Currently there is no endian or wordsize conversion performed by the
  *  NameServer module. Also there is no asynchronous support at this time.
@@ -92,79 +92,66 @@ extern "C" {
  */
 
 /*!
- *  @def    NameServer_S_BUSY
  *  @brief  The resource is still in use
  */
 #define NameServer_S_BUSY                2
 
 /*!
- *  @def    NameServer_S_ALREADYSETUP
  *  @brief  The module has been already setup
  */
 #define NameServer_S_ALREADYSETUP        1
 
 /*!
- *  @def    NameServer_S_SUCCESS
  *  @brief  Operation is successful.
  */
 #define NameServer_S_SUCCESS             0
 
 /*!
- *  @def    NameServer_E_FAIL
  *  @brief  Generic failure.
  */
 #define NameServer_E_FAIL               -1
 
 /*!
- *  @def    NameServer_E_INVALIDARG
  *  @brief  Argument passed to function is invalid.
  */
 #define NameServer_E_INVALIDARG         -2
 
 /*!
- *  @def    NameServer_E_MEMORY
  *  @brief  Operation resulted in memory failure.
  */
 #define NameServer_E_MEMORY             -3
 
 /*!
- *  @def    NameServer_E_ALREADYEXISTS
  *  @brief  The specified entity already exists.
  */
 #define NameServer_E_ALREADYEXISTS      -4
 
 /*!
- *  @def    NameServer_E_NOTFOUND
  *  @brief  Unable to find the specified entity.
  */
 #define NameServer_E_NOTFOUND           -5
 
 /*!
- *  @def    NameServer_E_TIMEOUT
  *  @brief  Operation timed out.
  */
 #define NameServer_E_TIMEOUT            -6
 
 /*!
- *  @def    NameServer_E_INVALIDSTATE
  *  @brief  Module is not initialized.
  */
 #define NameServer_E_INVALIDSTATE       -7
 
 /*!
- *  @def    NameServer_E_OSFAILURE
  *  @brief  A failure occurred in an OS-specific call
  */
 #define NameServer_E_OSFAILURE          -8
 
 /*!
- *  @def    NameServer_E_RESOURCE
  *  @brief  Specified resource is not available
  */
 #define NameServer_E_RESOURCE           -9
 
 /*!
- *  @def    NameServer_E_RESTART
  *  @brief  Operation was interrupted. Please restart the operation
  */
 #define NameServer_E_RESTART            -10
@@ -175,13 +162,11 @@ extern "C" {
  */
 
 /*!
- *  @def    NameServer_ALLOWGROWTH
  *  @brief  Allow dynamic growth of the NameServer instance table
  */
 #define NameServer_ALLOWGROWTH          (~0)
 
 /*!
- *  @def    NameServer_Params_MAXNAMELEN
  *  @brief  The default maximum length of the name for the name/value pair
  */
 #define NameServer_Params_MAXNAMELEN    16
@@ -201,7 +186,7 @@ typedef struct NameServer_Object *NameServer_Handle;
  */
 typedef struct NameServer_Params {
     UInt maxRuntimeEntries;
-    /*!< Maximum number of name/value pairs that can be dynamically created.
+    /*!< @brief Maximum name/value pairs that can be dynamically created.
      *
      *  This parameter allows NameServer to pre-allocate memory.
      *  When NameServer_add() or NameServer_addUInt32() is
@@ -210,18 +195,18 @@ typedef struct NameServer_Params {
      *  If the number of pairs is not known at configuration time, set this
      *  value to #NameServer_ALLOWGROWTH. This instructs NameServer
      *  to grow the table as needed. NameServer will allocate memory from the
-     *  #NameServer_Params#tableHeap when a name/value pair is added.
+     *  #NameServer_Params.tableHeap when a name/value pair is added.
      *
      *  The default is #NameServer_ALLOWGROWTH.
      */
 
     Ptr  tableHeap;
-    /*!< Name/value table is allocated from this heap.
+    /*!< @brief Name/value table is allocated from this heap.
      *
      *  The instance table and related buffers are allocated out of this heap
      *  during the dynamic create. This heap is also used to allocate new
      *  name/value pairs when #NameServer_ALLOWGROWTH for
-     *  #NameServer_Params#maxRuntimeEntries
+     *  #NameServer_Params.maxRuntimeEntries
      *
      *  The default is to use the same heap that instances are allocated
      *  from which can be configured via the
@@ -229,7 +214,7 @@ typedef struct NameServer_Params {
      */
 
     Bool checkExisting;
-    /*!< Check if a name already exists in the name/value table.
+    /*!< @brief Check if a name already exists in the name/value table.
      *
      *  When a name/value pair is added during runtime, if this boolean is
      *  true, the table is searched to see if the name already exists. If
@@ -246,13 +231,13 @@ typedef struct NameServer_Params {
      */
 
     UInt maxValueLen;
-    /*!< Length, in MAUs, of the value field in the table.
+    /*!< @brief Length, in MAUs, of the value field in the table.
      *
      *  Any value less than sizeof(UInt32) will be rounded up to sizeof(UInt32)
      */
 
     UInt maxNameLen;
-    /*!< Length, in MAUs, of the name field in the table.
+    /*!< @brief Length, in MAUs, of the name field in the table.
      *
      *  The maximum length of the name portion of the name/value
      *  pair.  The length includes the null terminator ('\\0').
@@ -271,7 +256,7 @@ typedef struct NameServer_Params {
  *
  *  @param      params  Instance param structure
  *
- *  @sa         NameServer_create
+ *  @sa         NameServer_create()
  */
 Void NameServer_Params_init(NameServer_Params *params);
 
@@ -283,7 +268,7 @@ Void NameServer_Params_init(NameServer_Params *params);
  *
  *  @return     NameServer handle
  *
- *  @sa         NameServer_delete
+ *  @sa         NameServer_delete()
  */
 NameServer_Handle NameServer_create(String name,
                                     const NameServer_Params *params);
@@ -300,7 +285,7 @@ NameServer_Handle NameServer_create(String name,
  *              - #NameServer_S_SUCCESS:  Instance successfully deleted
  *              - #NameServer_E_FAIL:  Instance delete failed
  *
- *  @sa         NameServer_create
+ *  @sa         NameServer_create()
  */
 Int NameServer_delete(NameServer_Handle *handlePtr);
 
@@ -335,13 +320,13 @@ NameServer_Handle NameServer_getHandle(String name);
  *  @brief  Adds a variable length value into the local NameServer table
  *
  *  This function adds a variable length value into the local table.
- *  If the #NameServer_Params#checkExisting flag was true on
+ *  If the #NameServer_Params.checkExisting flag was true on
  *  creation, this function searches the table to make sure the name
  *  does not already exist.  If it does, the name/value pair is not
  *  added and the #NameServer_E_ALREADYEXISTS error is returned.
  *
  *  There is memory allocation during this function if
- *  #NameServer_Params#maxRuntimeEntries is set to
+ *  #NameServer_Params.maxRuntimeEntries is set to
  *  #NameServer_ALLOWGROWTH.
  *
  *  This function copies the name and buffer into the name/value table,
@@ -357,8 +342,8 @@ NameServer_Handle NameServer_getHandle(String name);
  *
  *  @return     Unique entry identifier
  *
- *  @sa         NameServer_addUInt32,
- *              NameServer_get,
+ *  @sa         NameServer_addUInt32()
+ *  @sa         NameServer_get()
  */
 Ptr NameServer_add(NameServer_Handle handle, String name, Ptr buf, UInt32 len);
 
@@ -370,7 +355,7 @@ Ptr NameServer_add(NameServer_Handle handle, String name, Ptr buf, UInt32 len);
  *  that allows a convenient way to add UInt32 bit values without needing
  *  to specify the address of a UInt32 local variable.
  *
- *  If the #NameServer_Params#checkExisting flag was true on
+ *  If the #NameServer_Params.checkExisting flag was true on
  *  creation, this function searches the table to make sure the name does
  *  not already exist.  If it does, the name/value pair is not added and the
  *  #NameServer_E_ALREADYEXISTS error is returned.
@@ -378,7 +363,7 @@ Ptr NameServer_add(NameServer_Handle handle, String name, Ptr buf, UInt32 len);
  *  This function copies the name into the name/value table.
  *
  *  There is memory allocation during this function if
- *  #NameServer_Params#maxRuntimeEntries is set to
+ *  #NameServer_Params.maxRuntimeEntries is set to
  *  #NameServer_ALLOWGROWTH.
  *
  *  The function does not query remote processors to make sure the
@@ -390,8 +375,8 @@ Ptr NameServer_add(NameServer_Handle handle, String name, Ptr buf, UInt32 len);
  *
  *  @return     Unique entry identifier
  *
- *  @sa         NameServer_add,
- *              NameServer_getUInt32
+ *  @sa         NameServer_add()
+ *  @sa         NameServer_getUInt32()
  */
 Ptr NameServer_addUInt32(NameServer_Handle handle, String name, UInt32 value);
 
@@ -412,7 +397,7 @@ Ptr NameServer_addUInt32(NameServer_Handle handle, String name, UInt32 value);
  *  sleep/wait between successive NameServer_get[UInt32] operations if polling
  *  on the success of this call.  This helps ensure that remote cores
  *  are not inundated by a flood of incoming notifications and helps
- *  reduce the possiblity of deadlocks.
+ *  reduce the possibility of deadlocks.
  *
  *  The processors to query is determined by the procId array.
  *  The array is used to specify which processors to query and the order.
@@ -443,8 +428,8 @@ Ptr NameServer_addUInt32(NameServer_Handle handle, String name, UInt32 value);
  *              - #NameServer_E_NOTFOUND: Entry was not found, len unchanged
  *              - #NameServer_E_FAIL: Error searching for entry
  *
- *  @sa         NameServer_add,
- *              NameServer_getLocal
+ *  @sa         NameServer_add()
+ *  @sa         NameServer_getLocal()
  */
 Int NameServer_get(NameServer_Handle handle,
                    String name,
@@ -467,7 +452,7 @@ Int NameServer_get(NameServer_Handle handle,
  *  sleep/wait between successive NameServer_get[UInt32] operations if polling
  *  on the success of this call.  This helps ensure that remote cores
  *  are not inundated by a flood of incoming notifications and helps
- *  reduce the possiblity of deadlocks.
+ *  reduce the possibility of deadlocks.
  *
  *  The processors to query is determined by the procId array.
  *  The array is used to specify which processors to query and the order.
@@ -496,8 +481,8 @@ Int NameServer_get(NameServer_Handle handle,
  *              - #NameServer_E_NOTFOUND: Entry was not found
  *              - #NameServer_E_FAIL: Error searching for entry
  *
- *  @sa         NameServer_addUInt32,
- *              NameServer_getLocalUInt32
+ *  @sa         NameServer_addUInt32()
+ *  @sa         NameServer_getLocalUInt32()
  */
 Int NameServer_getUInt32(NameServer_Handle handle,
                          String name,
@@ -528,8 +513,8 @@ Int NameServer_getUInt32(NameServer_Handle handle,
  *              - #NameServer_E_NOTFOUND:  Entry was not found, len remains
  *                                     unchanged.
  *
- *  @sa         NameServer_add,
- *              NameServer_get
+ *  @sa         NameServer_add()
+ *  @sa         NameServer_get()
  */
 Int NameServer_getLocal(NameServer_Handle handle,
                         String name,
@@ -555,8 +540,8 @@ Int NameServer_getLocal(NameServer_Handle handle,
  *              - #NameServer_S_SUCCESS:  Successfully found entry
  *              - #NameServer_E_NOTFOUND:  Entry was not found
  *
- *  @sa         NameServer_addUInt32,
- *              NameServer_getUInt32
+ *  @sa         NameServer_addUInt32()
+ *  @sa         NameServer_getUInt32()
  */
 Int NameServer_getLocalUInt32(NameServer_Handle handle,
                               String name,
@@ -587,7 +572,7 @@ Int NameServer_match(NameServer_Handle handle, String name, UInt32 *value);
  *
  *  This function removes a name/value pair from the table.
  *
- *  If #NameServer_Params#maxRuntimeEntries is set to
+ *  If #NameServer_Params.maxRuntimeEntries is set to
  *  #NameServer_ALLOWGROWTH,
  *  memory will be freed which was allocated in NameServer_add().
  *  Otherwise, no memory is freed during this call.
@@ -622,7 +607,7 @@ Int NameServer_remove(NameServer_Handle handle, String name);
  *  When another NameServer_add() occurs, it will reuse the
  *  empty entry.
  *
- *  Once an Entry is removed from the NameServer table, it cannot be
+ *  Once an entry is removed from the NameServer table, it cannot be
  *  removed again (just like you cannot free the same block of memory
  *  twice).
  *
@@ -634,7 +619,7 @@ Int NameServer_remove(NameServer_Handle handle, String name);
  *                                        entry does not exists
  *              - #NameServer_E_FAIL:  Operation failed
  *
- *  @sa         NameServer_add
+ *  @sa         NameServer_add()
  */
 Int NameServer_removeEntry(NameServer_Handle handle, Ptr entry);
 
index acf4293e40bb6772c90066e15e6981d5d85b0e70..e629aa275e7711270911baa91445ed89480e43fe 100644 (file)
  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/** ============================================================================
- *  @file       Notify.h
+/**
+ *  @file       ti/ipc/Notify.h
  *
  *  @brief      Notification manager for IPC
  *
+ *  @note       Notify is currently only available for SYS/BIOS.
+ *
  *  The Notify module manages the multiplexing/demultiplexing of software
  *  interrupts over hardware interrupts.  In order to receive notifications,
  *  a processor registers one or more callback functions to an eventId
@@ -41,7 +43,7 @@
  *  call (like most other Notify APIs) uses a MultiProc id and
  *  line id to target a specific interrupt line to/from a specific processor
  *  on a device.  The Notify_eventAvailable() API may be used to query whether
- *  an event id is availble for use before registration.
+ *  an event id is available for use before registration.
  *
  *  Once an event has been registered, a remote processor may send an event
  *  using the Notify_sendEvent() call.  If the event and the interrupt line
  *  to Notify APIs. Line id #0 is always used for local notifications.  It is
  *  important to be aware of some subtle (but important) differences between
  *  remote and local notifications:
- *
  *      - Loopback callback functions will execute in the same thread in which
  *        Notify_sendEvent() is called.  This is in contrast to callback
  *        functions that are called due to another processor's sent
  *        notification- these 'remote' callback functions will execute in an
  *        ISR context.
- *
  *      - Loopback callback functions will execute with interrupts disabled
- *
  *      - Disabling the local interrupt line will cause all notifications that
  *        are sent to the local processor to be lost.  By contrast, a
  *        notification sent to an enabled event on a remote processor that has
  *        called Notify_disable() results in a pending notifications until the
  *        disabled processor has called Notify_restore().
- *
  *      - Local notifications do not support events of different priorities.
  *        By contrast, Notify driver implementations may correlate event ids
  *        with varying priorities.
  *
- *  In order to use any Notify APIs on DSP/BIOS, IPC/SysLink must first be
- *  started.  This will internally call Notify_attach() which sets up
- *  all necessary Notify drivers, shared memory and interprocessor interrupts.
+ *  In order to use any Notify APIs all necessary Notify drivers, shared memory
+ *  and interprocessor interrupts must be initialized.  This is typically done
+ *  by Ipc_start(), which internally call Notify_attach().
  *  It is possible for a user application to call Notify_attach() directly
  *  (before Ipc_attach() or Ipc_start()) if notifications must be set up prior
  *  to runtime SharedRegion initialization. Refer to the documentation for
  *  @code
  *  #include <ti/ipc/Notify.h>
  *  @endcode
- *
- *  @version  0.00.01
- *
- *  ============================================================================
  */
 
 #ifndef ti_ipc_Notify__include
@@ -525,10 +519,10 @@ Void Notify_restore(UInt16 procId, UInt16 lineId, UInt key);
  *  with Notify with the associated eventId and source
  *  processor id are called.
  *
- *  For example, when using 'NotifyDriverShm', a 'waitClear' value of 'TRUE'
+ *  For example, when using 'NotifyDriverShm', a @c waitClear value of 'TRUE'
  *  indicates that, if an event was previously sent to the same eventId,
  *  sendEvent should spin until the previous event has been acknowledged by the
- *  remote processor. If 'waitClear' is FALSE, a pending event with the same
+ *  remote processor. If @c waitClear is FALSE, a pending event with the same
  *  eventId will be overwritten by the event currently being sent. When in
  *  doubt, a value of TRUE should be used because notifications may be
  *  potentially dropped when FALSE is used.  When using NotifyDriverShm, a
@@ -557,7 +551,7 @@ Void Notify_restore(UInt16 procId, UInt16 lineId, UInt key);
  *              - #Notify_E_NOTINITIALIZED: remote driver has not yet been
  *                initialized
  *              - #Notify_E_EVTDISABLED: remote event is disabled
- *              - #Notify_E_TIMEOUT: timeout occured (when waitClear is TRUE)
+ *              - #Notify_E_TIMEOUT: timeout occurred (when waitClear is TRUE)
  *              - #Notify_S_SUCCESS: event successfully sent
  */
 Int Notify_sendEvent(UInt16 procId, UInt16 lineId, UInt32 eventId,
index bf01a95ded3d59562da683c180d81d7ea46a7bb5..0df4dcfef6ad69cf2b95fe0b1f05f6199e329d8b 100644 (file)
  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/** ===========================================================================
- *  @file       SharedRegion.h
+/**
+ *  @file       ti/ipc/SharedRegion.h
  *
- *  @brief      Shared memory manager and address translator.
+ *  @brief      Shared memory manager and address translator
+ *
+ *  @note       SharedRegion is currently only available for SYS/BIOS.
  *
  *  The SharedRegion module is designed to be used in a multi-processor
  *  environment in which memory regions are shared and accessed
  *  Note:  The number of entries must be the same on all processors.
  *
  *  Each shared region contains the following:
- *  @li @b base - The base address
- *  @li @b len - The length
- *  @li @b name - The name of the region
- *  @li @b isValid - Whether the region is valid
- *  @li @b ownerProcId - The id of the processor which owns the region
- *  @li @b cacheEnable - Whether the region is cacheable
- *  @li @b cacheLineSize - The cache line size
- *  @li @b createHeap - Whether a heap is created for the region.
+ *    - @b base - The base address
+ *    - @b len - The length
+ *    - @b name - The name of the region
+ *    - @b isValid - Whether the region is valid
+ *    - @b ownerProcId - The id of the processor which owns the region
+ *    - @b cacheEnable - Whether the region is cacheable
+ *    - @b cacheLineSize - The cache line size
+ *    - @b createHeap - Whether a heap is created for the region.
  *
  *  A region is added using the SharedRegion_setEntry() API.
  *  The length of a region must be the same across all processors.
@@ -94,8 +96,6 @@
  *  @code
  *  #include <ti/ipc/SharedRegion.h>
  *  @endcode
- *
- *  ============================================================================
  */
 
 #ifndef ti_ipc_SharedRegion__include
@@ -201,27 +201,27 @@ typedef Bits32 SharedRegion_SRPtr;
  */
 typedef struct SharedRegion_Entry {
     Ptr base;
-    /*!< The base address of the region */
+    /*!< @brief The base address of the region */
 
     SizeT len;
-    /*!< The length of the region
+    /*!< @brief The length of the region
      *
-     *  Ths length of a region must be the same across all
+     *  The length of a region must be the same across all
      *  processors in the system.
      */
 
     UInt16 ownerProcId;
-    /*!< The MultiProc id of the owner of the region
+    /*!< @brief The MultiProc id of the owner of the region
      *
      *  The owner id for a shared region must be the same across
      *  all processors in the system.
      */
 
     Bool isValid;
-    /*!< Whether the region is valid */
+    /*!< @brief Whether the region is valid */
 
     Bool cacheEnable;
-    /*!< Whether to perform cache operations for the region
+    /*!< @brief Whether to perform cache operations for the region
      *
      *  If 'TRUE', a cache invalidate is performed before any read
      *  and a cache write back invalidate is performed after any
@@ -230,7 +230,7 @@ typedef struct SharedRegion_Entry {
      */
 
     SizeT cacheLineSize;
-    /*!< The cache line size of the region
+    /*!< @brief The cache line size of the region
      *
      *  The cache line size for a region must be the same across
      *  all processors in the system.  It is used for structure
@@ -238,7 +238,7 @@ typedef struct SharedRegion_Entry {
      */
 
     Bool createHeap;
-    /*!< Whether a heap is created for the region
+    /*!< @brief Whether a heap is created for the region
      *
      *  If 'TRUE', a HeapMemMP instance is created with the size
      *  spanning the length of the shared region minus any memory
@@ -247,7 +247,7 @@ typedef struct SharedRegion_Entry {
      */
 
     String name;
-    /*!< The name of the region.
+    /*!< @brief The name of the region.
      *
      *  The name must be in persistent memory.  It is used for
      *  displaying in ROV.
@@ -261,7 +261,7 @@ typedef struct SharedRegion_Entry {
  */
 
 /*!
- *  @brief      Clears the entry at the specified region id
+ *  @brief      Clears the @c regionid entry
  *
  *  SharedRegion_clearEntry() is used to render invalid a shared region that is
  *  currently valid.  If the region has a heap, it will either be closed or
@@ -270,7 +270,7 @@ typedef struct SharedRegion_Entry {
  *  Calling SharedRegion_clearEntry() upon a region that is already invalid
  *  simply resets the region attributes to their defaults.
  *
- *  NOTE: Region #0 is special and can neither be cleared nor set.
+ *  @note Region #0 is special and can neither be cleared nor set.
  *
  *  @param      regionId  the region id
  *
@@ -320,24 +320,14 @@ Int SharedRegion_getEntry(UInt16 regionId, SharedRegion_Entry *entry);
 /*!
  *  @brief      Gets the heap associated with the specified region id
  *
- *  If running on BIOS, the heap handle returned is of type xdc.runtime.IHeap.
- *  This handle type can be used with xdc.runtime.Memory. However, if running
- *  on Linux, the heap handle is of type ti.syslink.utils.IHeap.  This handle
- *  type cannot be used with xdc.runtime.Memory, but can be used with
- *  ti.syslink.utils.Memory. The handle type is determined at compile time
- *  and cannot be deferred until runtime. The correct header file must be
- *  included to get the right type.
+ *  The heap handle returned is of type xdc.runtime.IHeap.
+ *  This handle type can be used with xdc.runtime.Memory.
  *
  *  The following code shows an example.
  *
  *  @code
- *  #if defined(ti_sdo_ipc)
  *  #include <xdc/runtime/IHeap.h>
  *  #include <xdc/runtime/Memory.h>
- *  #elif defined(ti_syslink)
- *  #include <ti/syslink/utils/IHeap.h>
- *  #include <ti/syslink/utils/Memory.h>
- *  #endif
  *  #include <ti/ipc/SharedRegion.h>
  *
  *  IHeap_Handle heap;
index 2bdc1afc96e5463799947b3d501a2e8f96c6724c..d6f6c7c77723e07168587100d9af9e14a35a5e83 100644 (file)
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
-/** ============================================================================
- *  @file       MmRpc.h
+/**
+ *  @file       ti/ipc/mm/MmRpc.h
  *
  *  @brief      Multi-Media derived Remote Procedure Call
  *
- *  ============================================================================
+ *  @note       MmRpc is currently only available for Linux and QNX.
+ *
+ *
  */
 
 #ifndef ti_ipc_mm_MmRpc__include
@@ -77,15 +79,17 @@ extern "C" {
 /*!
  *  @brief  Macro for computing offset to a field of a structure.
  *
- *          struct foobar {
- *              int a;
- *              int *p;
- *          };
+ *  @code
+ *  struct foobar {
+ *      int a;
+ *      int *p;
+ *  };
  *
- *          struct foobar *sp = ...;
- *          offset = MmRpc_OFFSET(sp, &sp->p);
- *          struct foobar st = ...;
- *          offset = MmRpc_OFFSET(&st, &st.p);
+ *  struct foobar *sp = ...;
+ *  offset = MmRpc_OFFSET(sp, &sp->p);
+ *  struct foobar st = ...;
+ *  offset = MmRpc_OFFSET(&st, &st.p);
+ *  @endcode
  */
 #define MmRpc_OFFSET(base, field) ((unsigned int)(field)-(unsigned int)(base))
 
index 954a96647ec35007b43c4631fb79e31603032a01..a2d9564fe44e867606a0ed4d380c7cc7e7c87dcf 100644 (file)
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
-/** ============================================================================
- *  @file       MmServiceMgr.h
+/**
+ *  @file       ti/ipc/mm/MmServiceMgr.h
  *
  *  @brief      Multi-Media Service Manager
  *
- *  ============================================================================
+ *  @note       MmServiceMgr is currently only available for SYS/BIOS, when
+ *              providing services for an MmRpc client on Linux or QNX.
+ *
  */
 
 #ifndef ti_ipc_mm_MmServiceMgr__include
index 94a78c54dede8959eeeb1ffd92d9e8d8309982d9..b60e866c797f17eda898f6d87f69ac581104cb82 100644 (file)
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
-/** ============================================================================
- *  @file       MmType.h
+/**
+ *  @file       ti/ipc/mm/MmType.h
  *
  *  @brief      Specific types to support the MmRpc and MmServiceMgr modules
  *
- *  ============================================================================
+ *
  */
 
 #ifndef ti_ipc_mm_MmType__include