|
|
|
SysLink API Reference
2.21.03.11
|
Notification manager for IPC.
============================================================================
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 using Notify_registerEvent(). The Notify_registerEvent() 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.
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 are both enabled, all callback functions registered to the event will be called sequentially.
A specific event may be disabled or enabled using the Notify_disableEvent() and Notify_enableEvent() calls. An entire interrupt line may be disabled or restored using the Notify_disable() or Notify_restore() calls. Notify_disable() does not alter the state of individual events. Instead, it just disables the ability of the Notify module to receive events on the interrupt line.
Notify APIs should never be called within an Hwi context. All API calls should be made within main(), a Task or a Swi with the exception of Notify_sendEvent() which may also be called within a Hwi.
"Loopback" functionality allows Notifications to be registered and sent locally. This is accomplished by supplying our own MultiProc id 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:
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. 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 Notify_attach() for more information.
The Notify header should be included in an application as follows:
============================================================================
Go to the source code of this file.
Macros | |
| #define | Notify_S_BUSY 2 |
| The resource is still in use. | |
| #define | Notify_S_ALREADYSETUP 1 |
| Module already set up. | |
| #define | Notify_S_SUCCESS 0 |
| Operation is successful. | |
| #define | Notify_E_FAIL -1 |
| Generic failure. | |
| #define | Notify_E_INVALIDARG -2 |
| Argument passed to function is invalid. | |
| #define | Notify_E_MEMORY -3 |
| Operation resulted in memory failure. | |
| #define | Notify_E_ALREADYEXISTS -4 |
| The specified entity already exists. | |
| #define | Notify_E_NOTFOUND -5 |
| Unable to find the specified entity. | |
| #define | Notify_E_TIMEOUT -6 |
| Operation timed out. | |
| #define | Notify_E_INVALIDSTATE -7 |
| Module is not initialized. | |
| #define | Notify_E_OSFAILURE -8 |
| A failure occurred in an OS-specific call. | |
| #define | Notify_E_ALREADYSETUP -9 |
| The module has been already setup. | |
| #define | Notify_E_RESOURCE -10 |
| Specified resource is not available. | |
| #define | Notify_E_RESTART -11 |
| Operation was interrupted. Please restart the operation. | |
| #define | Notify_E_BUSY -12 |
| The resource is still in use. | |
| #define | Notify_E_DRIVERNOTREGISTERED -13 |
| Driver corresponding to the specified eventId is not registered. | |
| #define | Notify_E_EVTNOTREGISTERED -14 |
| Event not registered. | |
| #define | Notify_E_EVTDISABLED -15 |
| Event is disabled. | |
| #define | Notify_E_NOTINITIALIZED -16 |
| Remote notification is not initialized. | |
| #define | Notify_E_EVTRESERVED -17 |
| Trying to illegally use a reserved event. | |
| #define | Notify_MAXEVENTS (UInt16)32 |
| Maximum number of events supported by the Notify module. | |
| #define | Notify_MAX_INTLINES 4u |
| Maximum number of IPC interrupt lines for any pair of processors. | |
| #define | Notify_SYSTEMKEY ((UInt16)0xC1D2) |
| This key must be provided as the upper 16 bits of the eventId when registering for an event, if any reserved event numbers are to be used. | |
Typedefs | |
| typedef Void(* | Notify_FnNotifyCbck )(UInt16, UInt16, UInt32, UArg, UInt32) |
| Signature of any callback function that can be registered with the Notify component. | |
Functions | |
| Int | Notify_attach (UInt16 remoteProcId, Ptr sharedAddr) |
| Creates notify drivers and registers them with Notify. | |
| UInt | Notify_disable (UInt16 procId, UInt16 lineId) |
| Disable ability to receive interrupts on an interrupt line. | |
| Void | Notify_disableEvent (UInt16 procId, UInt16 lineId, UInt32 eventId) |
| Disable an event. | |
| Void | Notify_enableEvent (UInt16 procId, UInt16 lineId, UInt32 eventId) |
| Enable an event. | |
| Bool | Notify_eventAvailable (UInt16 procId, UInt16 lineId, UInt32 eventId) |
| Whether an unused event is available on an interrupt line. | |
| Bool | Notify_intLineRegistered (UInt16 procId, UInt16 lineId) |
| Whether notification via interrupt line has been registered. | |
| UInt16 | Notify_numIntLines (UInt16 procId) |
| Returns number of interrupt lines to remote processor. | |
| Int | Notify_registerEvent (UInt16 procId, UInt16 lineId, UInt32 eventId, Notify_FnNotifyCbck fnNotifyCbck, UArg cbckArg) |
| Register a callback for an event (supports multiple callbacks) | |
| Int | Notify_registerEventSingle (UInt16 procId, UInt16 lineId, UInt32 eventId, Notify_FnNotifyCbck fnNotifyCbck, UArg cbckArg) |
| Register a single callback for an event. | |
| Void | Notify_restore (UInt16 procId, UInt16 lineId, UInt key) |
| Restore ability to receive interrupts on an interrupt line. | |
| Int | Notify_sendEvent (UInt16 procId, UInt16 lineId, UInt32 eventId, UInt32 payload, Bool waitClear) |
| Send an event on an interrupt line. | |
| Int | Notify_unregisterEvent (UInt16 procId, UInt16 lineId, UInt32 eventId, Notify_FnNotifyCbck fnNotifyCbck, UArg cbckArg) |
| Remove an event listener from an event. | |
| Int | Notify_unregisterEventSingle (UInt16 procId, UInt16 lineId, UInt32 eventId) |
| Remove an event listener from an event. | |
| #define Notify_S_BUSY 2 |
The resource is still in use.
| #define Notify_S_ALREADYSETUP 1 |
Module already set up.
| #define Notify_S_SUCCESS 0 |
Operation is successful.
| #define Notify_E_FAIL -1 |
Generic failure.
| #define Notify_E_INVALIDARG -2 |
Argument passed to function is invalid.
| #define Notify_E_MEMORY -3 |
Operation resulted in memory failure.
| #define Notify_E_ALREADYEXISTS -4 |
The specified entity already exists.
| #define Notify_E_NOTFOUND -5 |
Unable to find the specified entity.
| #define Notify_E_TIMEOUT -6 |
Operation timed out.
| #define Notify_E_INVALIDSTATE -7 |
Module is not initialized.
| #define Notify_E_OSFAILURE -8 |
A failure occurred in an OS-specific call.
| #define Notify_E_ALREADYSETUP -9 |
The module has been already setup.
| #define Notify_E_RESOURCE -10 |
Specified resource is not available.
| #define Notify_E_RESTART -11 |
Operation was interrupted. Please restart the operation.
| #define Notify_E_BUSY -12 |
The resource is still in use.
| #define Notify_E_DRIVERNOTREGISTERED -13 |
Driver corresponding to the specified eventId is not registered.
| #define Notify_E_EVTNOTREGISTERED -14 |
Event not registered.
| #define Notify_E_EVTDISABLED -15 |
Event is disabled.
| #define Notify_E_NOTINITIALIZED -16 |
Remote notification is not initialized.
| #define Notify_E_EVTRESERVED -17 |
Trying to illegally use a reserved event.
| #define Notify_MAXEVENTS (UInt16)32 |
Maximum number of events supported by the Notify module.
| #define Notify_MAX_INTLINES 4u |
Maximum number of IPC interrupt lines for any pair of processors.
| #define Notify_SYSTEMKEY ((UInt16)0xC1D2) |
This key must be provided as the upper 16 bits of the eventId when registering for an event, if any reserved event numbers are to be used.
| Notify_FnNotifyCbck |
Signature of any callback function that can be registered with the Notify component.
| [in] | procId | Remote processor id |
| [in] | lineId | Line id |
| [in] | eventId | Event id (minus system key if reserved event) |
| [in] | arg | Argument specified in the registerEvent |
| [in] | payload | Payload specified in the sendEvent |
Creates notify drivers and registers them with Notify.
This function must be called before other Notify API calls are invoked. Performing a attach invokes a device-specific Notify initialization routine that creates required drivers and registers those drivers with the Notify module. If the drivers require shared memory, a shared address must be supplied.
Notify_attach() is typically called internally as part of the IPC initialization sequence. Any memory required for Notify drivers is reserved by SharedRegion and passed to Notify_attach(). However, if it is necessary to pass a specific base address to Notify_attach() (i.e. if the shared region is not valid yet), then Notify_attach() should be called before Ipc_start() with this address. When Ipc_start() is eventually called, Notify_attach() will be internally bypassed since it was directly called by the user.
| [in] | remoteProcId | Remote processor id |
| [in] | sharedAddr | Shared address to use if any driver requires shared memory |
Disable ability to receive interrupts on an interrupt line.
This function disables a NotifyDriver from processing received events. The key that is returned from this call must be used in the Notify_restore() function.
Notify supports nested disable/restore calls. The value of the returned key is the nesting depth.
If Notify_disable() is called upon an interrupt line that is already disabled, then the corresponding Notify_restore() will not re-enable notifications. Only the restore call that corresponds to the Notify_disable() that actually disabled notifications will re-enable notifications on the interrupt line.
| [in] | procId | Remote processor id |
| [in] | lineId | Line id |
Disable an event.
This function allows the disabling of a single event number from the specified source processor. Sending to a disabled event will return Notify_E_EVTDISABLED on the sender if waitClear is false. Notify_disableEvent() and Notify_enableEvent() may not be supported by all Notify drivers. Consult the documentation for the Notify driver to determine whether it supports this API call.
An event is, by default, enabled upon driver initialization. Calling Notify_disableEvent() upon an event that is already disabled results in no change in state.
Note that callbacks may be registered to an event or removed from the event even while the event has been disabled.
| [in] | procId | Remote processor id |
| [in] | lineId | Line id |
| [in] | eventId | Event id |
Enable an event.
This function re-enables an event that has been previously disabled using disableEvent(). Calling Notify_enableEvent() upon an event that is already enabled results in no change in state. An event is, by default, enabled upon driver initialization.
Notify_disableEvent() and Notify_enableEvent() may not be supported by all Notify drivers. Consult the documentation for the Notify driver to determine whether it supports this API call.
| [in] | procId | Remote processor id |
| [in] | lineId | Line id |
| [in] | eventId | Event id |
Whether an unused event is available on an interrupt line.
This function can be used to determine whether an unused eventId for a specific interrupt line is available for use in Notify_registerEvent() or Notify_registerEventSingle(). This function will return TRUE if and only if the following conditions are simultaneously TRUE:
| [in] | procId | Remote processor id |
| [in] | lineId | Line id |
| [in] | eventId | Event id |
Whether notification via interrupt line has been registered.
This function will return TRUE if and only if a notify driver has been registered for the interrupt line identified by the supplied procId and lineId. The interrupt line corresponding to loopback functionality is always registered. A value of FALSE indicates that either Notify_attach() has not yet been called or that notification to the remote processor is unsupported.
| [in] | procId | Remote processor id |
| [in] | lineId | Line id |
Returns number of interrupt lines to remote processor.
This function returns the number of available interrupt lines to a remote processor.
| [in] | procId | Remote processor id |
| Int Notify_registerEvent | ( | UInt16 | procId, |
| UInt16 | lineId, | ||
| UInt32 | eventId, | ||
| Notify_FnNotifyCbck | fnNotifyCbck, | ||
| UArg | cbckArg | ||
| ) |
Register a callback for an event (supports multiple callbacks)
This function registers a callback to a specific event number, processor id and interrupt line. When the event is received by the specified processor, the callback is called.
The callback function prototype is of type Notify_FnNotifyCbck. This function must be non-blocking.
It is important to note that multiple callbacks may be registered with a single event. This is accomplished by simply calling Notify_registerEvent() for each combination of callback functions and callback arguments as needed.
It is important to note that interrupts are disabled during the entire duration of this function's execution.
| [in] | procId | Remote processor id |
| [in] | lineId | Line id (0 for most systems) |
| [in] | eventId | Event id |
| [in] | fnNotifyCbck | Pointer to callback function |
| [in] | cbckArg | Callback function argument |
| Int Notify_registerEventSingle | ( | UInt16 | procId, |
| UInt16 | lineId, | ||
| UInt32 | eventId, | ||
| Notify_FnNotifyCbck | fnNotifyCbck, | ||
| UArg | cbckArg | ||
| ) |
Register a single callback for an event.
This function registers a callback to a specific event number, processor id and interrupt line. When the event is received by the specified processor, the callback is called.
The callback function prototype is of type Notify_FnNotifyCbck. The callback function must be non-blocking.
Only one callback may be registered with this API.
Use Notify_registerEvent() to register multiple callbacks for a single event.
| [in] | procId | Remote processor id |
| [in] | lineId | Line id (0 for most systems) |
| [in] | eventId | Event id |
| [in] | fnNotifyCbck | Pointer to callback function |
| [in] | cbckArg | Callback function argument |
Restore ability to receive interrupts on an interrupt line.
This function re-enables receiving notifications on a specific interrupt line.
Notify supports nested disable/restore calls. The last restore call will re-enable Notifications.
| [in] | procId | Remote processor id |
| [in] | lineId | Line id |
| [in] | key | Key returned by Notify_disable() |
| Int Notify_sendEvent | ( | UInt16 | procId, |
| UInt16 | lineId, | ||
| UInt32 | eventId, | ||
| UInt32 | payload, | ||
| Bool | waitClear | ||
| ) |
Send an event on an interrupt line.
This function sends an event to a processor via an interrupt line identified by a processor id and line id. A payload may be optionally sent to the the remote processor if supported by the device.
On the destination processor, the callback functions registered with Notify with the associated eventId and source processor id are called.
For example, when using 'NotifyDriverShm', a '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 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 payload should never be sent with 'waitClear = FALSE.'
On the other hand, other notify drivers that use a FIFO to transmit events will spin if waitClear is TRUE until the FIFO has enough room to accept the event being sent. If waitClear is FALSE, Notify_sendEvent() will return Notify_E_FAIL if the FIFO does not have room for the event.
Refer to the documentation for the Notify drivers for more information about the effect of the waitClear flag in Notify_sendEvent().
Notify_sendEvent can be called from a Hwi context unlike other Notify APIs.
| [in] | procId | Remote processor id |
| [in] | lineId | Line id |
| [in] | eventId | Event id |
| [in] | payload | Payload to be sent along with the event. |
| [in] | waitClear | Indicates whether to spin waiting for the remote core to process previous events |
| Int Notify_unregisterEvent | ( | UInt16 | procId, |
| UInt16 | lineId, | ||
| UInt32 | eventId, | ||
| Notify_FnNotifyCbck | fnNotifyCbck, | ||
| UArg | cbckArg | ||
| ) |
Remove an event listener from an event.
This function unregisters a single callback that was registered to an event using Notify_registerEvent(). The procId, lineId, eventId, fnNotifyCbck and cbckArg must exactly match with the registered one.
This API is used to unregister events that were registered with Notify_registerEvent(). If this is the last event, then Notify_unregisterEventSingle() is called to completely remove the event.
| [in] | procId | Remote processor id |
| [in] | lineId | Line id |
| [in] | eventId | Event id |
| [in] | fnNotifyCbck | Pointer to callback function |
| [in] | cbckArg | Callback function argument |
Remove an event listener from an event.
This function removes a previously registered callback registered with Notify_registerEventSingle(). The procId, lineId, and eventId must exactly match the registered one.
| [in] | procId | Remote processor id |
| [in] | lineId | Line id |
| [in] | eventId | Event id that is being unregistered |
