NVIDIA DRIVE OS Linux SDK API Reference

6.0.10.0 Release

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:

Note
For startup-up sequence with NvSciEventService library, refer to "Start-up sequence" in NvSciIpc library
Precondition
No nested call to waiting for events
No multi-thread call to waiting for events

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

◆ NV_SCI_EVENT_PRIORITIES

#define NV_SCI_EVENT_PRIORITIES   4

Definition at line 157 of file nvscievent.h.

Typedef Documentation

◆ NvSciEventLoopService

Definition at line 161 of file nvscievent.h.

◆ NvSciEventNotifier

Definition at line 160 of file nvscievent.h.

◆ NvSciEventService

Definition at line 159 of file nvscievent.h.

◆ NvSciLocalEvent

Definition at line 163 of file nvscievent.h.

◆ 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]majorVerbuild major version.
[in]minorVerbuild minor version.
[out]isCompatibleboolean value stating if loaded NvSciEvent library is compatible or not.
Returns
NvSciError, the completion code of the operation:
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]maxEventLoopsThe number of event loops, it must be 1.
[in]configOS-specific configuration parameter. It should NULL in Linux.
[out]newEventLoopServiceNvSciEventNotifier object double pointer.
Returns
NvSciError, the completion code of operations:
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]maxEventLoopsThe number of event loops, it must be 1.
[in]configOS-specific configuration parameter. It should NULL in Linux.
[out]newEventLoopServiceNvSciEventNotifier object double pointer.
Returns
NvSciError, the completion code of operations:
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]oldEventServiceNvSciEventService object pointer to export event notifier
[in]newEventServiceNvSciEventService object pointer to import event notifier
[in]eventNotifierEvent notifier object pointer.
Returns
NvSciError, the completion code of the operation:
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
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