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

Typical call flow with NvSciIpc library

1) Init mode

• NvSciEventLoopServiceCreateSafe()
• NvSciIpcInit()
• NvSciIpcOpenEndpointWithEventService()
• NvSciIpcGetEventNotifier()
• NvSciEventNotifier::SetHandler() // This is optional for event handler
• NvSciIpcGetEndpointInfo()
• NvSciIpcResetEndpoint()
• Ensure a channel is established

  loop {
      NvSciIpcGetEvent()
      if (event & NV_SCI_IPC_EVENT_CONN_EST_ALL) break
      else {
          // The event handler will be called inside of WaitForXXX() if
          // the handler is registered by NvSciEventNotifier::SetHandler()
          // and the corresponding event is detected
          NvSciEventLoopService::WaitForEvent()
          or
          NvSciEventLoopService::WaitForMultipleEvents()
          or
          NvSciEventLoopService::WaitForMultipleEventsExt()
      }
  }

2) Runtime mode (loop)

• NvSciIpcGetEvent()
• If an event is not desired, NvSciEventLoopService::WaitForEvent() or NvSciEventLoopService::WaitForMultipleEvents() or NvSciEventLoopService::WaitForMultipleEventsExt()
• NvSciIpcRead() or NvSciIpcWrite()

3) Deinit mode

• If an eventNotifier is not required any more, NvSciEventNotifier::Delete()
• NvSciIpcCloseEndpoint()
• NvSciIpcDeinit()
• NvSciEventService::Delete()

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 168 of file nvscievent.h.

NV_SCI_EVENT_PRIORITIES

#define NV_SCI_EVENT_PRIORITIES   4

Definition at line 169 of file nvscievent.h.

Typedef Documentation

NvSciEventLoopService

typedef struct NvSciEventLoopService NvSciEventLoopService

Definition at line 173 of file nvscievent.h.

NvSciEventNotifier

typedef struct NvSciEventNotifier NvSciEventNotifier

Definition at line 172 of file nvscievent.h.

NvSciEventService

typedef struct NvSciEventService NvSciEventService

Definition at line 171 of file nvscievent.h.

NvSciLocalEvent

typedef struct NvSciLocalEvent NvSciLocalEvent

Definition at line 175 of file nvscievent.h.

NvSciNativeEvent

typedef struct NvSciNativeEvent NvSciNativeEvent

Definition at line 174 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: 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.

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.

Parameters

[in]	maxEventLoops	The number of event loops, it must be 1.
[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.

Precondition

None.

Usage considerations

• Allowed context for the API call
  • Interrupt: 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

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; // initialize using SIGEV_SEM_INIT() macro unsigned num_pulses; // threshold to trigger semaphore event unsigned rearm_threshold; // 0 ~ num_pulses unsigned options; // _NTO_CHO_CUSTOM_EVENT unsigned reserved[3]; }

If you're experienced pulse pool shortage issue in normal operation, increase num_pulses by double of previous setting.

More information can be found in QNX OS manual page.

In order to detect event storm, 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.

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

None.

Usage considerations

• Allowed context for the API call
  • Interrupt: 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.

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()
• WaitWaitForMultipleEvents()
• WaitForMultipleEventsExt()

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

None.

Usage considerations

• Allowed context for the API call
  • Interrupt: 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.

When this API is called, no event associated with the event notifier should being waited in the EventService and be sent by remote peer. Otherwise, the event may be lost. NvSciIpc APIs using the same endpoint will be blocked till this API returns.

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.

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.

Usage considerations

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