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	NvSciEventCheckVersionCompatibility (uint32_t majorVer, uint32_t minorVer, bool *isCompatible)

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

◆ NV_SCI_EVENT_PRIORITIES

#define NV_SCI_EVENT_PRIORITIES 4

Definition at line 166 of file nvscievent.h.

Typedef Documentation

◆ NvSciEventLoopService

typedef struct NvSciEventLoopService NvSciEventLoopService

Definition at line 170 of file nvscievent.h.

◆ NvSciEventNotifier

typedef struct NvSciEventNotifier NvSciEventNotifier

Definition at line 169 of file nvscievent.h.

◆ NvSciEventService

typedef struct NvSciEventService NvSciEventService

Definition at line 168 of file nvscievent.h.

◆ NvSciLocalEvent

typedef struct NvSciLocalEvent NvSciLocalEvent

Definition at line 172 of file nvscievent.h.

◆ NvSciNativeEvent

typedef struct NvSciNativeEvent NvSciNativeEvent

Definition at line 171 of file nvscievent.h.

Function Documentation

◆ NvSciEventCheckVersionCompatibility()

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

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