X-Git-Url: https://git.ti.com/gitweb?p=ipc%2Fipcdev.git;a=blobdiff_plain;f=packages%2Fti%2Fipc%2FNotify.h;h=dca17a3e8acc7f53f650bd93883280a2c95cf67e;hp=acf4293e40bb6772c90066e15e6981d5d85b0e70;hb=1d3ba1288663722b944215fbb6a99b5b65a5cdeb;hpb=54fa164e681c60a356a108118f22fea32773ccb7 diff --git a/packages/ti/ipc/Notify.h b/packages/ti/ipc/Notify.h index acf4293..dca17a3 100644 --- a/packages/ti/ipc/Notify.h +++ b/packages/ti/ipc/Notify.h @@ -29,11 +29,13 @@ * 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 @@ -64,28 +66,24 @@ * 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 @@ -95,10 +93,6 @@ * @code * #include * @endcode - * - * @version 0.00.01 - * - * ============================================================================ */ #ifndef ti_ipc_Notify__include @@ -116,102 +110,102 @@ extern "C" { /*! * @brief The resource is still in use */ -#define Notify_S_BUSY 2 +#define Notify_S_BUSY (2) /*! * @brief Module already set up */ -#define Notify_S_ALREADYSETUP 1 +#define Notify_S_ALREADYSETUP (1) /*! * @brief Operation is successful. */ -#define Notify_S_SUCCESS 0 +#define Notify_S_SUCCESS (0) /*! * @brief Generic failure. */ -#define Notify_E_FAIL -1 +#define Notify_E_FAIL (-1) /*! * @brief Argument passed to function is invalid. */ -#define Notify_E_INVALIDARG -2 +#define Notify_E_INVALIDARG (-2) /*! * @brief Operation resulted in memory failure. */ -#define Notify_E_MEMORY -3 +#define Notify_E_MEMORY (-3) /*! * @brief The specified entity already exists. */ -#define Notify_E_ALREADYEXISTS -4 +#define Notify_E_ALREADYEXISTS (-4) /*! * @brief Unable to find the specified entity. */ -#define Notify_E_NOTFOUND -5 +#define Notify_E_NOTFOUND (-5) /*! * @brief Operation timed out. */ -#define Notify_E_TIMEOUT -6 +#define Notify_E_TIMEOUT (-6) /*! * @brief Module is not initialized. */ -#define Notify_E_INVALIDSTATE -7 +#define Notify_E_INVALIDSTATE (-7) /*! * @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 */ -#define Notify_E_ALREADYSETUP -9 +#define Notify_E_ALREADYSETUP (-9) /*! * @brief Specified resource is not available */ -#define Notify_E_RESOURCE -10 +#define Notify_E_RESOURCE (-10) /*! * @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 */ -#define Notify_E_BUSY -12 +#define Notify_E_BUSY (-12) /*! * @brief Driver corresponding to the specified eventId is not registered */ -#define Notify_E_DRIVERNOTREGISTERED -13 +#define Notify_E_DRIVERNOTREGISTERED (-13) /*! * @brief Event not registered */ -#define Notify_E_EVTNOTREGISTERED -14 +#define Notify_E_EVTNOTREGISTERED (-14) /*! * @brief Event is disabled */ -#define Notify_E_EVTDISABLED -15 +#define Notify_E_EVTDISABLED (-15) /*! * @brief Remote notification is not initialized */ -#define Notify_E_NOTINITIALIZED -16 +#define Notify_E_NOTINITIALIZED (-16) /*! * @brief Trying to illegally use a reserved event */ -#define Notify_E_EVTRESERVED -17 +#define Notify_E_EVTRESERVED (-17) /* ============================================================================= * Macros @@ -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,