More minor coding convention fixes
[ipc/ipcdev.git] / packages / ti / ipc / Ipc.h
index ba0c708e68c38c8ca18bbaa9a47794c156b36d8e..445a7476764a488418a56a30ee9990c2b211bb6e 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,88 +60,74 @@ extern "C" {
  */
 
 /*!
- *  @def    Ipc_S_BUSY
  *  @brief  The resource is still in use
  */
-#define Ipc_S_BUSY              2
+#define Ipc_S_BUSY              (2)
 
 /*!
- *  @def    Ipc_S_ALREADYSETUP
  *  @brief  The module has been already setup
  */
-#define Ipc_S_ALREADYSETUP      1
+#define Ipc_S_ALREADYSETUP      (1)
 
 /*!
- *  @def    Ipc_S_SUCCESS
  *  @brief  Operation is successful.
  */
-#define Ipc_S_SUCCESS           0
+#define Ipc_S_SUCCESS           (0)
 
 /*!
- *  @def    Ipc_E_FAIL
  *  @brief  Generic failure.
  */
-#define Ipc_E_FAIL             -1
+#define Ipc_E_FAIL             (-1)
 
 /*!
- *  @def    Ipc_E_INVALIDARG
  *  @brief  Argument passed to function is invalid.
  */
-#define Ipc_E_INVALIDARG       -2
+#define Ipc_E_INVALIDARG       (-2)
 
 /*!
- *  @def    Ipc_E_MEMORY
  *  @brief  Operation resulted in memory failure.
  */
-#define Ipc_E_MEMORY           -3
+#define Ipc_E_MEMORY           (-3)
 
 /*!
- *  @def    Ipc_E_ALREADYEXISTS
  *  @brief  The specified entity already exists.
  */
-#define Ipc_E_ALREADYEXISTS    -4
+#define Ipc_E_ALREADYEXISTS    (-4)
 
 /*!
- *  @def    Ipc_E_NOTFOUND
  *  @brief  Unable to find the specified entity.
  */
-#define Ipc_E_NOTFOUND         -5
+#define Ipc_E_NOTFOUND         (-5)
 
 /*!
- *  @def    Ipc_E_TIMEOUT
  *  @brief  Operation timed out.
  */
-#define Ipc_E_TIMEOUT          -6
+#define Ipc_E_TIMEOUT          (-6)
 
 /*!
- *  @def    Ipc_E_INVALIDSTATE
  *  @brief  Module is not initialized or in an invalid state.
  */
-#define Ipc_E_INVALIDSTATE     -7
+#define Ipc_E_INVALIDSTATE     (-7)
 
 /*!
- *  @def    Ipc_E_OSFAILURE
  *  @brief  A failure occurred in an OS-specific call
  */
-#define Ipc_E_OSFAILURE        -8
+#define Ipc_E_OSFAILURE        (-8)
 
 /*!
- *  @def    Ipc_E_RESOURCE
  *  @brief  Specified resource is not available
  */
-#define Ipc_E_RESOURCE         -9
+#define Ipc_E_RESOURCE         (-9)
 
 /*!
- *  @def    Ipc_E_RESTART
  *  @brief  Operation was interrupted. Please restart the operation
  */
-#define Ipc_E_RESTART          -10
+#define Ipc_E_RESTART          (-10)
 
 /*!
- *  @def    Ipc_E_NOTREADY
  *  @brief  Operation was not ready.
  */
-#define Ipc_E_NOTREADY         -11
+#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);