NVIDIA DRIVE OS Linux SDK API Reference

6.0.9 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:

Typical call flow with NvSciIpc library

1) Init mode

2) Runtime mode (loop)

3) Deinit mode

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

Typedef Documentation

◆ NvSciEventLoopService

Definition at line 173 of file nvscievent.h.

◆ NvSciEventNotifier

Definition at line 172 of file nvscievent.h.

◆ NvSciEventService

Definition at line 171 of file nvscievent.h.

◆ NvSciLocalEvent

Definition at line 175 of file nvscievent.h.

◆ 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]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: 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]maxEventLoopsThe number of event loops, it must be 1.
[out]newEventLoopServiceNvSciEventNotifier object double pointer.
Returns
NvSciError, the completion code of operations:
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]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
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]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
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]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.


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
NvSciEventLoopService::WaitForEvent
NvSciError(* WaitForEvent)(NvSciEventNotifier *eventNotifier, int64_t microseconds)
Waits up to a configurable timeout for a particular event notification, servicing events with configu...
Definition: nvscievent.h:754
NvSciIpcGetEvent
NvSciError NvSciIpcGetEvent(NvSciIpcEndpoint handle, uint32_t *events)
Get Events.
NvSciEventLoopService
An abstract interface that event consumer can wait for events using event notifier in event loop.
Definition: nvscievent.h:688
NV_SCI_IPC_EVENT_CONN_EST_ALL
#define NV_SCI_IPC_EVENT_CONN_EST_ALL
Specifies single event mask to check IPC connection establishment.
Definition: nvsciipc.h:356