Event Service APIs

Detailed Description

The NvSciEventService library provides the ability to build portable event-driven applications. An event is any significant occurrence or change in the state for system hardware or software. An event notification is a message or notification sent by one software part to another to convey that an event has taken place. An event-driven model consists of an event producer and event consumers. Once an event producer detects an event, it represents the event as a message (or notification). An event is transmitted from an event producer to event consumers through an OS-specific event channel. Event consumers must be informed when an event has occurred. NvSciEventService will execute the correct response (or callback) to an event.

NvSciEventService provides a mandatory abstract interface between other SCI technologies (especially NvSciIpc and NvSciStreams) and the application-provided event loop that services them.

The following common object type(s) are implemented:

• User-visible object types (for application use)
  • NvSciEventService: An object that subsumes all state that commonly would have been maintained in global variables.
  • NvSciEventNotifier: An object that a library creates using an NvSciEventService and then provides to the user, and with which the user registers an event handler that is invoked whenever the library generates an event.
  • NvSciLocalEvent: An object representing a local event with which a library can signal events directly, without going through environment-specific mechanisms. Local events are limited to cases where the signaler and waiter are in the same process, but may be more efficient than environment-specific notifiers (which typically pass through an OS).
• Non-user-visible object types (for integrating libraries with an NvSciEventService)
  • NvSciNativeEvent: An object representing a native event that a library fills in with environment-specific information that is necessary for an event service to wait for environment-specific events (from OS or other event producers).

Note

For startup-up sequence with NvSciEventService library, refer to "Start-up sequence" in NvSciIpc library

Precondition

No nested call to waiting for events

• These three APIs in waiting for events must not be called from an event handler registered with NvSciEventNotifier.
  • NvSciEventLoopService::WaitForEvent()
  • NvSciEventLoopService::WaitForMultipleEvents()
  • NvSciEventLoopService::WaitForMultipleEventsExt()

No multi-thread call to waiting for events

• These three APIs in waiting for events must not be called from multiple thread if same NvSciEventLoopSerivce instance is used.
  • NvSciEventLoopService::WaitForEvent()
  • NvSciEventLoopService::WaitForMultipleEvents()
  • NvSciEventLoopService::WaitForMultipleEventsExt()

Data Structures
struct	NvSciLocalEvent
	An OS-agnostic object that sends signal to another thread in the same process. More...
struct	NvSciEventService
	An abstract interface for a program's event handling infrastructure. More...
struct	NvSciEventNotifier
	An abstract interface to notify event to event consumer and to register event handler of the event consumer client process. More...
struct	NvSciEventLoopService
	An abstract interface that event consumer can wait for events using event notifier in event loop. More...

Macros
#define	NV_SCI_EVENT_INFINITE_WAIT   -1
	Infinite timeout for NvSciEventLoopService::WaitForEvent() or NvSciEventLoopService::WaitForMultipleEvents(). More...
#define	NV_SCI_EVENT_PRIORITIES   4

Typedefs
typedef struct NvSciEventService	NvSciEventService
typedef struct NvSciEventNotifier	NvSciEventNotifier
typedef struct NvSciEventLoopService	NvSciEventLoopService
typedef struct NvSciNativeEvent	NvSciNativeEvent
typedef struct NvSciLocalEvent	NvSciLocalEvent

Functions
NvSciError	NvSciEventLoopServiceCreate (size_t maxEventLoops, NvSciEventLoopService **newEventLoopService)
	Creates a new event loop service. More...
NvSciError	NvSciEventLoopServiceCreateSafe (size_t maxEventLoops, void *config, NvSciEventLoopService **newEventLoopService)
	Creates a new event loop service. More...
NvSciError	NvSciEventLoopServiceCreateSafeX (size_t maxEventLoops, void *config, NvSciEventLoopService **newEventLoopService)
	Creates a new event loop service that has the same properties as created by NvSciEventLoopServiceCreateSafe(), but supports faster local event. More...
NvSciError	NvSciEventMoveNotifier (NvSciEventService *oldEventService, NvSciEventService *newEventService, NvSciEventNotifier *eventNotifier)
	Move event notifier. More...
NvSciError	NvSciEventCheckVersionCompatibility (uint32_t majorVer, uint32_t minorVer, bool *isCompatible)
	Check NvSciEventSerivice library version compatibility. More...

Macro Definition Documentation

NV_SCI_EVENT_INFINITE_WAIT

#define NV_SCI_EVENT_INFINITE_WAIT   -1

Infinite timeout for NvSciEventLoopService::WaitForEvent() or NvSciEventLoopService::WaitForMultipleEvents().

Definition at line 156 of file nvscievent.h.

NV_SCI_EVENT_PRIORITIES

#define NV_SCI_EVENT_PRIORITIES   4

Definition at line 157 of file nvscievent.h.

Typedef Documentation

NvSciEventLoopService

typedef struct NvSciEventLoopService NvSciEventLoopService

Definition at line 161 of file nvscievent.h.

NvSciEventNotifier

typedef struct NvSciEventNotifier NvSciEventNotifier

Definition at line 160 of file nvscievent.h.

NvSciEventService

typedef struct NvSciEventService NvSciEventService

Definition at line 159 of file nvscievent.h.

NvSciLocalEvent

typedef struct NvSciLocalEvent NvSciLocalEvent

Definition at line 163 of file nvscievent.h.

NvSciNativeEvent

typedef struct NvSciNativeEvent NvSciNativeEvent

Definition at line 162 of file nvscievent.h.

Function Documentation

NvSciEventCheckVersionCompatibility()

NvSciError NvSciEventCheckVersionCompatibility	(	uint32_t	majorVer,
		uint32_t	minorVer,
		bool *	isCompatible
	)

Check NvSciEventSerivice library version compatibility.

Checks if loaded NvSciEvent library version is compatible with the version the application was compiled against. This function checks loaded NvSciEvent library version with input NvSciEvent library version and sets output variable true provided major version of the loaded library is same as majorVer and minor version of the loaded library is not less than minorVer, else sets output to false

Parameters

[in]	majorVer	build major version.
[in]	minorVer	build minor version.
[out]	isCompatible	boolean value stating if loaded NvSciEvent library is compatible or not.

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • isCompatible is NULL

Precondition

None

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes
  • Async/Sync: Sync
• Required Privileges(QNX): None
• API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

NvSciEventLoopServiceCreate()

NvSciError NvSciEventLoopServiceCreate	(	size_t	maxEventLoops,
		NvSciEventLoopService **	newEventLoopService
	)

Creates a new event loop service.

The number of event loops that can be created in the new event loop service will be limited to at most maxEventLoops.

Warning

This API is deprecated and returns NvSciError_NotSupported without doing anything in safety build. Use NvSciEventLoopServiceCreateSafe() instead of this.

NvSciEventLoopServiceCreateSafe()

NvSciError NvSciEventLoopServiceCreateSafe	(	size_t	maxEventLoops,
		void *	config,
		NvSciEventLoopService **	newEventLoopService
	)

Creates a new event loop service.

The number of event loops that can be created in the new event loop service will be limited to at most maxEventLoops.

This function creates a new event loop service newEventLoopService which is a primary instance of event service. An application must call event service functions along with newEventLoopService. The number of event loops that can be created in the new event loop service will be limited to at most maxEventLoops.

Note

The following information is specific to QNX and about config. It uses ChannelCreatePulsePool() to create channel with the private pulse pool. The ChannelCreatePulsePool() needs this parameter to specify the attributes of the private pulse pool, including what to do when there are no available pulses and config is used to pass it.

struct nto_channel_config {
    struct sigevent event;
    unsigned num_pulses;
    unsigned rearm_threshold;
    unsigned options;
    unsigned reserved[3];
}

More information can be found in QNX OS manual page.

Parameters

[in]	maxEventLoops	The number of event loops, it must be 1.
[in]	config	OS-specific configuration parameter. It should NULL in Linux.
[out]	newEventLoopService	NvSciEventNotifier object double pointer.

Returns

NvSciError, the completion code of operations:

• NvSciError_Success Indicates a successful operation.
• NvSciError_InsufficientMemory Indicates memory is not sufficient.
• NvSciError_NotSupported Indicates a condition is unsupported.
• NvSciError_InvalidState Indicates an invalid operation state.
• NvSciError_BadParameter Indicates an invalid or NULL argument.
• NvSciError_ResourceError Indicates not enough system resources.
• NvSciError_NotPermitted Indicates incorrect API group usage.

Precondition

Threshold of pulse number in private pulse pool

• num_pulses in nto_channel_config shall be decided based on how many event notifications can happen simulatenously. For native event, there are three event notifications, reset/read/write. Considering native and local event together, the formula is

  num_pulses = 3 * native events (same as endpoints) + local events

This formula gives you a bottom line of how many pulses you need. If you experience a pulse shortage in normal operation, you may need more pulses, e.g. increasing num_pulses by double of previous setting.

Precondition

Handle an event storm

• If a user wants to detect an event strom and stop the event from being notified, the user needs to create a separate thread to receive semaphore event which is set in nto_channel_config structure and call sem_wait() in that thread. When the thread is awaken by the semaphore event, it can call NvSciEventInspect() API to handle event storm.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes
  • Async/Sync: Sync
• Required Privileges(QNX): PROCMGR_AID_PUBLIC_CHANNEL
• API Group
  • Init: Yes
  • Runtime: No
  • De-Init: No

NvSciEventLoopServiceCreateSafeX()

NvSciError NvSciEventLoopServiceCreateSafeX	(	size_t	maxEventLoops,
		void *	config,
		NvSciEventLoopService **	newEventLoopService
	)

Creates a new event loop service that has the same properties as created by NvSciEventLoopServiceCreateSafe(), but supports faster local event.

For a detailed description of the API, see NvSciEventLoopServiceCreateSafe().

Note

In case of Linux/x86, This is just for API parity and not benefit in terms of local event performance.

Parameters

[in]	maxEventLoops	The number of event loops, it must be 1.
[in]	config	OS-specific configuration parameter. It should NULL in Linux.
[out]	newEventLoopService	NvSciEventNotifier object double pointer.

Returns

NvSciError, the completion code of operations:

• NvSciError_Success Indicates a successful operation.
• NvSciError_InsufficientMemory Indicates memory is not sufficient.
• NvSciError_NotSupported Indicates a condition is unsupported.
• NvSciError_InvalidState Indicates an invalid operation state.
• NvSciError_BadParameter Indicates an invalid or NULL argument.
• NvSciError_ResourceError Indicates not enough system resources.
• NvSciError_NotPermitted Indicates incorrect API group usage.

Precondition

No infinite timeout with fast local event

• The following waiting functions of the event loop service created with NvSciEventLoopServiceCreateSafeX() do not support infinite timeout and will return NvSciError_BadParameter when they are called with infinite timeout.
  • WaitForEvent()
  • WaitForMultipleEvents()
  • WaitForMultipleEventsExt()

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes
  • Async/Sync: Sync
• Required Privileges(QNX): PROCMGR_AID_PUBLIC_CHANNEL
• API Group
  • Init: Yes
  • Runtime: No
  • De-Init: No

NvSciEventMoveNotifier()

NvSciError NvSciEventMoveNotifier	(	NvSciEventService *	oldEventService,
		NvSciEventService *	newEventService,
		NvSciEventNotifier *	eventNotifier
	)

Move event notifier.

This API exports event Notifier from old EventService and import the Notifier to new EventService. After the event notifier is migrated, the old EventService can not wait the event associated with the notifier. Instead, use the new EventService waits for the event.

Note

This API supports local event and native event notifier only. In case of native event, limited to Intra-VM and Inter-VM backend only.

Parameters

[in]	oldEventService	NvSciEventService object pointer to export event notifier
[in]	newEventService	NvSciEventService object pointer to import event notifier
[in]	eventNotifier	Event notifier object pointer.

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success Indicates a successful operation.
• NvSciError_BadParameter Indicates an invalid or NULL argument.
• NvSciError_InvalidState Indicates an invalid operation state.
• NvSciError_InsufficientMemory Indicates memory is not sufficient.
• NvSciError_NotPermitted Indicates incorrect API group usage.

Precondition

NvSciEventLoopServiceCreateSafe() must be successful per oldEventService and newEventService.

No pending event before moving notifier

• When this API is called, no local and native event associated with the event notifier must be waited in the EventService and sent by remote peer. NvSciIpc APIs using the same endpoint will be blocked till this API returns.

Complete moving notifier

• To complete sequence of this API for native event, client process shall call NvSciIpcGetEventSafe() till NvSciIpcGetEventSafe() returns one of NV_SCI_IPC_EVENT_CONN_EST_ALL events after this API. This can be done by calling NvSciIpcGetEventSafe() and WaitForEvent() family API pair, or calling NvSciIpcGetEventSafe() with sleep in polling mode (with disabled notification mode).

Handshake to ensure no data transaction before moving notifier

• Before calling this API to move native event notifier, user shall make sure that channel connection is established and there is no more outstanding data transaction between two endpoints through any handshaking mechanism at client level. If this is not guranteed, pending notification of remote endpoint might fail since local endpoint already enters move-notifier sequence. NV_SCI_IPC_EVENT_WRITE_EMPTY of NvSciIpcGetEventSafe() can be used to make sure if remote endpoint read all sent data.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: No
  • Async/Sync: Sync
• Required Privileges(QNX): None
• API Group
  • Init: Yes
  • Runtime: No
  • De-Init: No