index acf4293e40bb6772c90066e15e6981d5d85b0e70..dca17a3e8acc7f53f650bd93883280a2c95cf67e 100644 (file)
--- a/packages/ti/ipc/Notify.h
+++ b/packages/ti/ipc/Notify.h
* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
* 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
*
*
* @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
* 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
* 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
* 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
*
* 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:
* 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 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
* - 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().
* - 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.
*
* - 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
* 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
* @code
* #include <ti/ipc/Notify.h>
* @endcode
- *
- * @version 0.00.01
- *
- * ============================================================================
*/
#ifndef ti_ipc_Notify__include
*/
#ifndef ti_ipc_Notify__include
/*!
* @brief The resource is still in use
*/
/*!
* @brief The resource is still in use
*/
-#define Notify_S_BUSY 2
+#define Notify_S_BUSY (2)
/*!
* @brief Module already set up
*/
/*!
* @brief Module already set up
*/
-#define Notify_S_ALREADYSETUP 1
+#define Notify_S_ALREADYSETUP (1)
/*!
* @brief Operation is successful.
*/
/*!
* @brief Operation is successful.
*/
-#define Notify_S_SUCCESS 0
+#define Notify_S_SUCCESS (0)
/*!
* @brief Generic failure.
*/
/*!
* @brief Generic failure.
*/
-#define Notify_E_FAIL -1
+#define Notify_E_FAIL (-1)
/*!
* @brief Argument passed to function is invalid.
*/
/*!
* @brief Argument passed to function is invalid.
*/
-#define Notify_E_INVALIDARG -2
+#define Notify_E_INVALIDARG (-2)
/*!
* @brief Operation resulted in memory failure.
*/
/*!
* @brief Operation resulted in memory failure.
*/
-#define Notify_E_MEMORY -3
+#define Notify_E_MEMORY (-3)
/*!
* @brief The specified entity already exists.
*/
/*!
* @brief The specified entity already exists.
*/
-#define Notify_E_ALREADYEXISTS -4
+#define Notify_E_ALREADYEXISTS (-4)
/*!
* @brief Unable to find the specified entity.
*/
/*!
* @brief Unable to find the specified entity.
*/
-#define Notify_E_NOTFOUND -5
+#define Notify_E_NOTFOUND (-5)
/*!
* @brief Operation timed out.
*/
/*!
* @brief Operation timed out.
*/
-#define Notify_E_TIMEOUT -6
+#define Notify_E_TIMEOUT (-6)
/*!
* @brief Module is not initialized.
*/
/*!
* @brief Module is not initialized.
*/
-#define Notify_E_INVALIDSTATE -7
+#define Notify_E_INVALIDSTATE (-7)
/*!
* @brief A failure occurred in an OS-specific call
*/
/*!
* @brief A failure occurred in an OS-specific call
*/
-#define Notify_E_OSFAILURE -8
+#define Notify_E_OSFAILURE (-8)
/*!
* @brief The module has been already setup
*/
/*!
* @brief The module has been already setup
*/
-#define Notify_E_ALREADYSETUP -9
+#define Notify_E_ALREADYSETUP (-9)
/*!
* @brief Specified resource is not available
*/
/*!
* @brief Specified resource is not available
*/
-#define Notify_E_RESOURCE -10
+#define Notify_E_RESOURCE (-10)
/*!
* @brief Operation was interrupted. Please restart the operation
*/
/*!
* @brief Operation was interrupted. Please restart the operation
*/
-#define Notify_E_RESTART -11
+#define Notify_E_RESTART (-11)
/*!
* @brief The resource is still in use
*/
/*!
* @brief The resource is still in use
*/
-#define Notify_E_BUSY -12
+#define Notify_E_BUSY (-12)
/*!
* @brief Driver corresponding to the specified eventId is not registered
*/
/*!
* @brief Driver corresponding to the specified eventId is not registered
*/
-#define Notify_E_DRIVERNOTREGISTERED -13
+#define Notify_E_DRIVERNOTREGISTERED (-13)
/*!
* @brief Event not registered
*/
/*!
* @brief Event not registered
*/
-#define Notify_E_EVTNOTREGISTERED -14
+#define Notify_E_EVTNOTREGISTERED (-14)
/*!
* @brief Event is disabled
*/
/*!
* @brief Event is disabled
*/
-#define Notify_E_EVTDISABLED -15
+#define Notify_E_EVTDISABLED (-15)
/*!
* @brief Remote notification is not initialized
*/
/*!
* @brief Remote notification is not initialized
*/
-#define Notify_E_NOTINITIALIZED -16
+#define Notify_E_NOTINITIALIZED (-16)
/*!
* @brief Trying to illegally use a reserved event
*/
/*!
* @brief Trying to illegally use a reserved event
*/
-#define Notify_E_EVTRESERVED -17
+#define Notify_E_EVTRESERVED (-17)
/* =============================================================================
* Macros
/* =============================================================================
* Macros
* with Notify with the associated eventId and source
* processor id are called.
*
* 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
* 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
* 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
* - #Notify_E_NOTINITIALIZED: remote driver has not yet been
* initialized
* - #Notify_E_EVTDISABLED: remote event is disabled
* - #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,
* - #Notify_S_SUCCESS: event successfully sent
*/
Int Notify_sendEvent(UInt16 procId, UInt16 lineId, UInt32 eventId,