nvscievent.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: Copyright (c) 2019-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 * SPDX-License-Identifier: LicenseRef-NvidiaProprietary
 *
 * NVIDIA CORPORATION and its licensors retain all intellectual property
 * and proprietary rights in and to this software, related documentation
 * and any modifications thereto.  Any use, reproduction, disclosure or
 * distribution of this software and related documentation without an express
 * license agreement from NVIDIA CORPORATION is strictly prohibited.
 */
 
#ifndef INCLUDED_NVSCIEVENT_H
#define INCLUDED_NVSCIEVENT_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <string.h>
#include <stdint.h>
#include <stdlib.h>
#include <stdbool.h>
#include "nvscierror.h"
 
/*
 * use constant global version variable instead of macro for consistency with
 * version check API of existing NvSci family
 */
 
static const uint32_t NvSciEventMajorVersion = 1U;
 
static const uint32_t NvSciEventMinorVersion = 5U;
 
/*******************************************************************/
/********************* ACCESS CONTROL ******************************/
/*******************************************************************/
 
/*****************************************************************************/
/*                               DATA TYPES                                  */
/*****************************************************************************/
 
#define NV_SCI_EVENT_INFINITE_WAIT -1
#define NV_SCI_EVENT_PRIORITIES 4
 
typedef struct NvSciEventService NvSciEventService;
typedef struct NvSciEventNotifier NvSciEventNotifier;
typedef struct NvSciEventLoopService NvSciEventLoopService;
typedef struct NvSciNativeEvent NvSciNativeEvent;
typedef struct NvSciLocalEvent NvSciLocalEvent;
 
typedef struct NvSciTimerEvent NvSciTimerEvent;
typedef struct NvSciEventLoop NvSciEventLoop;
 
struct NvSciLocalEvent {
    NvSciEventNotifier* eventNotifier;
 
    NvSciError (*Signal)(NvSciLocalEvent* thisLocalEvent);
 
    void (*Delete)(NvSciLocalEvent* thisLocalEvent);
};
 
struct NvSciEventService {
    NvSciError (*CreateNativeEventNotifier)(
            NvSciEventService* thisEventService,
            NvSciNativeEvent* nativeEvent,
            NvSciEventNotifier** newEventNotifier);
 
    NvSciError (*CreateLocalEvent)(
            NvSciEventService* thisEventService,
            NvSciLocalEvent** newLocalEvent);
 
    NvSciError (*CreateTimerEvent)(
            NvSciEventService* thisEventService,
            NvSciTimerEvent** newTimerEvent);
 
    void (*Delete)(NvSciEventService* thisEventService);
};
 
struct NvSciEventNotifier {
    NvSciError (*SetHandler)(NvSciEventNotifier* thisEventNotifier,
            void (*callback)(void* cookie),
            void* cookie,
            uint32_t priority);
 
    void (*Delete)(NvSciEventNotifier* thisEventNotifier);
};
 
NvSciError NvSciEventLoopServiceCreate(
        size_t maxEventLoops,
        NvSciEventLoopService** newEventLoopService);
 
NvSciError NvSciEventLoopServiceCreateSafe(
        size_t maxEventLoops,
        void* config,
        NvSciEventLoopService** newEventLoopService);
 
NvSciError NvSciEventLoopServiceCreateSafeX(
        size_t maxEventLoops,
        void* config,
        NvSciEventLoopService** newEventLoopService);
 
struct NvSciEventLoopService {
    NvSciEventService EventService;
 
    NvSciError (*CreateEventLoop)(NvSciEventLoopService* eventLoopService,
            NvSciEventLoop** eventLoop);
 
    NvSciError (*WaitForEvent)(
            NvSciEventNotifier* eventNotifier,
            int64_t microseconds);
 
    NvSciError (*WaitForMultipleEvents)(
            NvSciEventNotifier* const * eventNotifierArray,
            size_t eventNotifierCount,
            int64_t microseconds,
            bool* newEventArray);
 
    NvSciError (*WaitForMultipleEventsExt)(
            NvSciEventService *eventService,
            NvSciEventNotifier* const * eventNotifierArray,
            size_t eventNotifierCount,
            int64_t microseconds,
            bool* newEventArray);
 
#ifndef __QNX__
    /* Since an array is used to notify what events have occured or not,
     * the index of array becomes the default priority for handling of
     * events. In such a case, the possibility for event starvation might
     * arise. The user should keep in mind this possibility before calling
     * this API.
     */
#endif /* __QNX__ */
     /*
     * Each event notifier in @a eventNotifierArray must have been created
     * through EventService.
     *
     * On a successful return, for all integer `i` in the range
     * `[0, eventNotifierCount-1]`, there will be only one `newEventArray[i]`
     * true.
     *
     * @param[in]  eventNotifierArray Array of NvSciEventNotifier object
     *                                pointers. If it is NULL,
     *                                @a eventNotifierCount should be zero and
     *                                @a newEventArray should be NULL together.
     * @param[in]  eventNotifierCount Event notifier count in eventNotifierArray.
     * @param[in]  microseconds  A 64-bit integer timeout in microsecond.
     *                           Set to -1 for infinite timeout, for example,
     *                           the value @ref NV_SCI_EVENT_INFINITE_WAIT.
     *                           Timeout must be 2msec or greater as high
     *                           precision timer is not supported in DRIVE OS.
     * @param[out] newEventArray Array of event occurrence.
     *
     * @return ::NvSciError, the completion code of operations:
     * - ::NvSciError_Success            Indicates a successful operation.
     * - ::NvSciError_BadParameter       Indicates an invalid input parameter.
     * - ::NvSciError_InvalidState       Indicates an invalid operation state.
     * - ::NvSciError_NotSupported       Indicates another thread already
     *                                   waiting for events.
     * - ::NvSciError_Timeout            Indicates a timeout occurrence.
     * - ::NvSciError_ResourceError      Indicates not enough system resources.
     * - ::NvSciError_InterruptedCall    Indicates an interrupt occurred.
     *
     * @pre NvSciEventLoopServiceCreateSafe() must be called.
     *      NvSciIpcGetEventNotifier() must be called for NvSciNativeEvent.
     *      NvSciEventService::CreateLocalEvent() must be called
     *      for NvSciLocalEvent.
     *
     * @usage
     * - 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: No
     *   - Runtime: Yes
     *   - De-Init: No
     */
    NvSciError (*WaitForAnyEvent)(
            NvSciEventNotifier* const * eventNotifierArray,
            size_t eventNotifierCount,
            int64_t microseconds,
            bool* newEventArray);
 
};
 
#ifdef __QNX__
 
NvSciError NvSciEventInspect(
        NvSciEventService *thisEventService,
        uint32_t numEvents,
        uint32_t eventNotifierCount,
        NvSciEventNotifier** eventNotifierArray);
#endif /* __QNX__ */
 
NvSciError NvSciEventMoveNotifier(
        NvSciEventService *oldEventService,
        NvSciEventService *newEventService,
        NvSciEventNotifier *eventNotifier);
 
NvSciError NvSciEventCheckVersionCompatibility(
    uint32_t majorVer,
    uint32_t minorVer,
    bool* isCompatible);
 
#ifdef __cplusplus
}
#endif
#endif /* INCLUDED_NVSCIEVENT_H */