nvmedia_dla.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: Copyright (c) 2017-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 * SPDX-License-Identifier: LicenseRef-NvidiaProprietary
 *
 * NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
 * property and proprietary rights in and to this material, related
 * documentation and any modifications thereto. Any use, reproduction,
 * disclosure or distribution of this material and related documentation
 * without an express license agreement from NVIDIA CORPORATION or
 * its affiliates is strictly prohibited.
 */
 
#ifndef NVMEDIA_DLA_H
#define NVMEDIA_DLA_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "nvmedia_core.h"
#include "nvmedia_tensor.h"
 
#define NVMEDIA_DLA_VERSION_MAJOR   4
 
#define NVMEDIA_DLA_VERSION_MINOR   0
 
#define NVMEDIA_DLA_VERSION_PATCH   0
 
#define NVMEDIA_DLA_TENSOR_DESC_NAME_MAX_LEN (80U)
 
#define NVMEDIA_DLA_DEFAULT_TASKTIMEOUT (100000U)
 
typedef struct NvMediaDla NvMediaDla;
 
typedef struct {
    uint8_t major;
    uint8_t minor;
    uint8_t subMinor;
} NvMediaDlaUMDVersion;
 
typedef enum {
    NVMEDIA_DLA_DATA_TYPE_TENSOR
} NvMediaDlaDataType;
 
typedef struct {
    NvMediaTensor *tensor;
} NvMediaDlaDataPointer;
 
typedef struct {
    NvMediaDlaDataType type;
    NvMediaDlaDataPointer pointer;
} NvMediaDlaData;
 
typedef struct NvMediaDlaLoadable NvMediaDlaLoadable;
 
typedef struct {
    uint8_t const *loadable;
    uint64_t loadableSize;
} NvMediaDlaBinaryLoadable;
 
typedef struct {
    NvMediaDlaData *dlaData;
    uint32_t numArgs;
} NvMediaDlaArgs;
 
typedef struct {
    char name[NVMEDIA_DLA_TENSOR_DESC_NAME_MAX_LEN + 1];
    NvMediaTensorAttr tensorAttrs[NVM_TENSOR_ATTR_MAX];
    uint32_t numAttrs;
} NvMediaDlaTensorDescriptor;
 
NvMediaStatus
NvMediaDlaGetVersion(
    NvMediaVersion *version
);
 
NvMediaStatus
NvMediaDlaPingById(
    const uint32_t dlaId
);
 
NvMediaDla *
NvMediaDlaCreate(void);
 
NvMediaStatus
NvMediaDlaDestroy(
     NvMediaDla *dla
);
 
NvMediaStatus
NvMediaDlaGetUMDVersion(
    const NvMediaDla *dla,
    NvMediaDlaUMDVersion *version
);
 
NvMediaStatus
NvMediaDlaGetNumEngines(
    const NvMediaDla *dla,
    uint16_t *numEngines
);
 
NvMediaStatus
NvMediaDlaGetMaxOutstandingTasks(
    const NvMediaDla *dla,
    uint32_t *maxOutstandingTasks
);
 
NvMediaStatus
NvMediaDlaInit(
    NvMediaDla *dla,
    uint32_t dlaId,
    uint32_t numTasks
);
 
NvMediaStatus
NvMediaDlaGetInstanceId(
    const NvMediaDla *dla,
    uint32_t *dlaId
);
 
NvMediaStatus
NvMediaDlaGetNumTasks(
    const NvMediaDla *dla,
    uint32_t *numTasks
);
 
NvMediaStatus
NvMediaDlaLoadableCreate(
    NvMediaDla *dla,
    NvMediaDlaLoadable **loadable
);
 
NvMediaStatus
NvMediaDlaLoadableDestroy(
    const NvMediaDla *dla,
    NvMediaDlaLoadable *loadable
);
 
NvMediaStatus
NvMediaDlaAppendLoadable(
    const NvMediaDla *dla,
    const NvMediaDlaBinaryLoadable binaryLoadable,
    NvMediaDlaLoadable *loadable
);
 
NvMediaStatus
NvMediaDlaAppendDiagnosticLoadable(
    const NvMediaDla *dla,
    NvMediaDlaLoadable *loadable
);
 
NvMediaStatus
NvMediaDlaSetCurrentLoadable(
    NvMediaDla *dla,
    const NvMediaDlaLoadable *loadable
);
 
NvMediaStatus
NvMediaDlaGetNumOfInputTensors(
    const NvMediaDla *dla,
    int32_t *numOfInputTensors
);
 
NvMediaStatus
NvMediaDlaGetInputTensorDescriptor(
    const NvMediaDla *dla,
    const uint32_t idx,
    NvMediaDlaTensorDescriptor *descriptor
);
 
NvMediaStatus
NvMediaDlaGetNumOfOutputTensors(
    const NvMediaDla *dla,
    int32_t *numOfOutputTensors
);
 
NvMediaStatus
NvMediaDlaGetOutputTensorDescriptor(
    const NvMediaDla *dla,
    const uint32_t idx,
    NvMediaDlaTensorDescriptor *descriptor
);
 
NvMediaStatus
NvMediaDlaDataRegister(
    const NvMediaDla *dla,
    const NvMediaDlaData *dlaData,
    uint32_t flags
);
 
NvMediaStatus
NvMediaDlaDataUnregister(
    const NvMediaDla *dla,
    const NvMediaDlaData *dlaData
);
 
NvMediaStatus
NvMediaDlaLoadLoadable(
    NvMediaDla *dla
);
 
NvMediaStatus
NvMediaDlaRemoveLoadable(
    NvMediaDla *dla
);
 
NvMediaStatus
NvMediaDlaSubmit(
    NvMediaDla *dla,
    const NvMediaDlaArgs *inputArgs,
    const NvMediaDlaArgs *scratchpadArgs,
    const NvMediaDlaArgs *outputArgs,
    uint32_t taskTimeout
);
 
NvMediaStatus
NvMediaDlaSubmitBypass(
    NvMediaDla *dla,
    const NvMediaDlaArgs *inputArgs,
    const NvMediaDlaArgs *scratchpadArgs,
    const NvMediaDlaArgs *outputArgs
);
 
/*
 * \defgroup history_nvmedia_dla History
 * Provides change history for the NvMedia DLA API.
 *
 * \section history_nvmedia_dla Version History
 *
 * <b> Version 1.0 </b> Oct 31, 2017
 * - Initial Release.
 *
 * <b> Version 1.1 </b> Feb 12, 2018
 * - Add separate functionality to load from memory.
 *
 * <b> Version 1.2 </b> Mar 12, 2018
 * - Add query API's for version, num engines, maxOutstandingRequests.
 *
 * <c> Version 1.3 </b> Mar 26, 2018
 * - Add helper to query tensor descriptor.
 *
 * <c> Version 1.4 </b> May 3, 2018
 * - Add dynamic task timeout support.
 *
 * <c> Version 2.0 </b> June 26, 2018
 * - Remove load using filename functionality.
 *
 * <c> Version 2.1 </b> August 13, 2018
 * - Add NvMediaDlaPingById. NvMediaDlaPing will be deprecated in the future.
 *
 * <c> Version 2.2 </b> Oct 1, 2018
 * - Add new API NvMediaDlaGetUMDVersion and data structure NvMediaDlaUMDVersion.
 *
 * <c> Version 2.3 </b> Dec 14, 2018
 * - Add new API NvMediaLoadableIdCreate, NvMediaLoadableIdDestroy,
 *   NvMediaDlaAppendLoadable, NvMediaDlaLoadLoadable, NvMediaDlaSetCurrentLoadable,
 *   NvMediaDlaInit, NvMediaDlaGetScratchpadDescriptor and NvMediaDlaBindScratchpad.
 * - Add new structure NvMediaDlaLoadableId, NvMediaDlaLoadable and NvMediaDlaScratchpadDescriptor.
 *
 * <c> Version 2.4 </b> Jan 9, 2019
 * - Remove NvMediaImage as Dla data.
 *
 * <c> Version 2.5 </b> Mar 7, 2019
 * - Rename NvMediaLoadableIdCreate to NvMediaDlaLoadableIdCreate.
 * - Rename NvMediaLoadableIdDestroy to NvMediaDlaLoadableIdDestroy.
 *
 * <c> Version 2.6 </b> Mar 11, 2019
 * - Add new API NvMediaDlaDataRegister and NvMediaDlaDataUnRegister.
 *
 * <c> Version 2.7 </b> Mar 13, 2019
 * - Deprecate NvMediaDlaPing API.
 *
 * <c> Version 2.8 </b> Mar 14, 2019
 * - Deprecate NvMediaDlaSubmit API.
 *
 * <c> Version 3.0 </b> April 19, 2019
 * - Add NvMediaDlaSubmit as new API for task submission.
 * - Move to new APIs for NvMediaDla programming.
 * - Mark NvMediaDlaLoadFromMemory, NvMediaDlaSubmitTimeout
 *   and NvMediaDlaGetMaxOutstandingRequests as deprecated APIs.
 *
 * <c> Version 3.1 </b> July 08, 2019
 * - Remove the restriction of calling sequence for data registration.
 *
 * <c> Version 3.2 </b> July 30, 2019
 * - Deleting NvMediaDlaGetScratchpadDescriptor and NvMediaDlaBindScratchpad.
 * - added const for parameters in APIs that do not modify the parameter
 *
 * <c> Version 3.3 </b> Sep 9th, 2019
 * - Deprecate following APIs: NvMediaDlaLoadFromMemory, NvMediaDlaSubmitTimeout
 *   and NvMediaDlaGetMaxOutstandingRequests
 *
 * <c> Version 3.4 </b> Jan 22, 2020
 * - Add const to NvMediaDlaSubmit to comply with MISRA rule 8.13
 *
 * <c> Version 3.5 </b> Mar 28, 2020
 * - Update possible return status of NvMediaDlaGetNumEngines, NvMediaDlaGetInstanceId,
 *   NvMediaDlaGetNumTasks, NvMediaDlaSubmit.
 *
 * <c> Version 3.6 </b> Apr 24, 2020
 * - Removed const from NvMediaDlaSetCurrentLoadable and
 *   NvMediaDlaRemoveLoadable to support new functionality
 *
 * <c> Version 3.7 </b> Nov 30, 2020
 * - Updated doxygen comments for NvMediaDlaSubmit.
 *
 * <c> Version 3.8 </b> Jan 5, 2021
 * - Updated last sentence of NvMediaDlaSubmit restrictions.
 *
 * <c> Version 3.9 </b> Mar 1, 2021
 * - Updated doxy comments for NvMediaDlaSubmit,NvMediaDlaGetInput/OutputTensorDescriptor.
 *
 * <c> Version 3.10 </b> Mar 22, 2021
 * - Updated doxy comments for NvMediaDlaAppendLoadable.
 *
 * <c> Version 3.11 </b> Jul 20, 2021
 * - Added "submit with bypass execution" feature (NvMediaDlaSubmitBypass).
 *
 * <b> Version 3.12 </b> August 20, 2021
 * - Update doxygen comments for All APIs to have Thread safety information and API Group information
 *
 * <b> Version 4.0 </b> September 2, 2021
 * - Adding Const Qualifier for loadable member in NvMediaDlaBinaryLoadable
 *
  * <b> Version 4.0 </b> February 08, 2022
 * - Updated the doxygen comments with usage considerations for all APIs.
 *
 * <b> Version 4.0 </b> April 04, 2022
 * - Updated doxy comments for NvMediaDlaAppendLoadable, NvMediaDlaRemoveLoadable.
 * - Updated valid range for structures.
 *
 * <b> Version 4.0.0 </b> May 10, 2022
 * - Added patch version number macro: NVMEDIA_DLA_VERSION_PATCH.
 *
 */
#ifdef __cplusplus
}
#endif
 
#endif // NVMEDIA_DLA_H