SysLink API Reference  2.21.03.11
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Macros | Typedefs | Functions
Notify.h File Reference

Detailed Description

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:

#include <ti/ipc/Notify.h>
Version:
0.00.01

============================================================================

This graph shows which files directly or indirectly include this file:

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.

Macro Definition Documentation

#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.


Typedef Documentation

Notify_FnNotifyCbck

Signature of any callback function that can be registered with the Notify component.

Parameters:
[in]procIdRemote processor id
[in]lineIdLine id
[in]eventIdEvent id (minus system key if reserved event)
[in]argArgument specified in the registerEvent
[in]payloadPayload specified in the sendEvent

Function Documentation

Int Notify_attach ( UInt16  remoteProcId,
Ptr  sharedAddr 
)

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.

Parameters:
[in]remoteProcIdRemote processor id
[in]sharedAddrShared address to use if any driver requires shared memory
Returns:
Notify status:
UInt Notify_disable ( UInt16  procId,
UInt16  lineId 
)

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.

Parameters:
[in]procIdRemote processor id
[in]lineIdLine id
Returns:
Key that must be used in Notify_restore()
See also:
Notify_restore()
Void Notify_disableEvent ( UInt16  procId,
UInt16  lineId,
UInt32  eventId 
)

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.

Parameters:
[in]procIdRemote processor id
[in]lineIdLine id
[in]eventIdEvent id
See also:
Notify_enableEvent()
Void Notify_enableEvent ( UInt16  procId,
UInt16  lineId,
UInt32  eventId 
)

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.

Parameters:
[in]procIdRemote processor id
[in]lineIdLine id
[in]eventIdEvent id
See also:
Notify_disableEvent()
Bool Notify_eventAvailable ( UInt16  procId,
UInt16  lineId,
UInt32  eventId 
)

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:

  • The corresponding interrupt line is available. Notifications over an interrupt line to a remote processor are typically made available by calling Notify_attach() or Ipc_attach().
  • The event is not a reserved event
  • The event is a reserved event and Notify_SYSTEMKEY has been passed as the upper 16 bits of the 32-bit eventId argument
  • No callback functions have been registered to the event If any of the above conditions is false, this function will return FALSE. Note that an event may still be registered using Notify_registerEvent() while the last condition is false if the existing callback function(s) were registered using Notify_registerEvent() (not Notify_registerEventSingle()).
Parameters:
[in]procIdRemote processor id
[in]lineIdLine id
[in]eventIdEvent id
Returns:
TRUE if an unused event is available, FALSE otherwise
Bool Notify_intLineRegistered ( UInt16  procId,
UInt16  lineId 
)

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.

Parameters:
[in]procIdRemote processor id
[in]lineIdLine id
Returns:
TRUE if registered, FALSE otherwise
UInt16 Notify_numIntLines ( UInt16  procId)

Returns number of interrupt lines to remote processor.

This function returns the number of available interrupt lines to a remote processor.

Parameters:
[in]procIdRemote processor id
Returns:
Number of interrupt lines
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.

Parameters:
[in]procIdRemote processor id
[in]lineIdLine id (0 for most systems)
[in]eventIdEvent id
[in]fnNotifyCbckPointer to callback function
[in]cbckArgCallback function argument
Returns:
Notify status:
See also:
Notify_unregisterEvent()
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.

Parameters:
[in]procIdRemote processor id
[in]lineIdLine id (0 for most systems)
[in]eventIdEvent id
[in]fnNotifyCbckPointer to callback function
[in]cbckArgCallback function argument
Returns:
Notify status:
See also:
Notify_unregisterEventSingle()
Void Notify_restore ( UInt16  procId,
UInt16  lineId,
UInt  key 
)

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.

Parameters:
[in]procIdRemote processor id
[in]lineIdLine id
[in]keyKey returned by Notify_disable()
See also:
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.

Parameters:
[in]procIdRemote processor id
[in]lineIdLine id
[in]eventIdEvent id
[in]payloadPayload to be sent along with the event.
[in]waitClearIndicates whether to spin waiting for the remote core to process previous events
Returns:
Notify status:
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.

Parameters:
[in]procIdRemote processor id
[in]lineIdLine id
[in]eventIdEvent id
[in]fnNotifyCbckPointer to callback function
[in]cbckArgCallback function argument
Returns:
Notify status:
See also:
Notify_registerEvent()
Int Notify_unregisterEventSingle ( UInt16  procId,
UInt16  lineId,
UInt32  eventId 
)

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.

Parameters:
[in]procIdRemote processor id
[in]lineIdLine id
[in]eventIdEvent id that is being unregistered
Returns:
Notify status:
See also:
Notify_registerEventSingle()
Copyright 2014, Texas Instruments Incorporated