diff --git a/commitFile.txt b/commitFile.txt new file mode 100644 index 0000000..b2aa972 --- /dev/null +++ b/commitFile.txt @@ -0,0 +1,11 @@ +Updating prebuilts and/or headers + +30539c9e44aa07fd4e6587195a5760c9e2e4300d - nvscievent.h +5b2f58a4d46aa8e4f7610c81f4c93cafe0c29c90 - nvsciipc.cfg +8dbc8e93caaeb5f0b725d5a678756784223571dd - nvscisync.h +8a0a9a6809e4f94fef5a607d13f779c37d922b85 - nvscistream_api.h +6b8809ed1b39dcb64c4da2f34ffee2aec10bb0b1 - nvscistream.h +65d2229d2171080ced54ef04a228a1daa0cf79a2 - nvsciipc.h +f81df24708896d40238fd172f21c52905e1d7011 - nvscistream_types.h +cf447a1331d4725724fa47122ea5b821c126054c - nvscierror.h +b90f6b262aa3621031036ee780d8815cde1f7857 - nvscibuf.h diff --git a/nvsci_headers_README.txt b/nvsci_headers_README.txt new file mode 100644 index 0000000..0545a05 --- /dev/null +++ b/nvsci_headers_README.txt @@ -0,0 +1,15 @@ +# +# SPDX-FileCopyrightText: Copyright (c) 2021 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. + +* nvsci_headers.tbz2 contains NvSci headers and a sample nvsciipc.cfg. +* nvsciipc.cfg has to be put in /etc/. + Use the below command to copy the file to /etc directory: + $sudo cp ./nvsciipc.cfg /etc/nvsciipc.cfg diff --git a/nvscibuf.h b/nvscibuf.h new file mode 100644 index 0000000..9a0089a --- /dev/null +++ b/nvscibuf.h @@ -0,0 +1,5542 @@ +/* + * Header file for NvSciBuf APIs + * + * Copyright (c) 2018-2023, NVIDIA CORPORATION. All rights reserved. + * + * 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. + */ +/** + * @file + * + * @brief NVIDIA Software Communications Interface (SCI) : NvSciBuf + * + * Allows applications to allocate and exchange buffers in memory. + */ +#ifndef INCLUDED_NVSCIBUF_H +#define INCLUDED_NVSCIBUF_H + +#include +#include +#include +#include "nvscierror.h" +#include + +#if defined(__cplusplus) +extern "C" +{ +#endif + +#if defined __GNUC__ + #define PACK_BUF( __Declaration__ ) __Declaration__ __attribute__((packed)) +#else + #define PACK_BUF( __Declaration__ ) __pragma(pack(push, 1)) __Declaration__ __pragma(pack(pop)) +#endif + +/** + * @defgroup nvscibuf_blanket_statements NvSciBuf blanket statements. + * Generic statements applicable for NvSciBuf interfaces. + * @ingroup nvsci_buf + * @{ + */ + +/** + * \page nvscibuf_page_blanket_statements NvSciBuf blanket statements + * \section nvscibuf_in_params Input parameters + * - NvSciBufModule passed as input parameter to an API is valid input if it is + * returned from a successful call to NvSciBufModuleOpen() and has not yet been + * deallocated using NvSciBufModuleClose(). + * - NvSciIpcEndpoint passed as input parameter to an API is valid if it is + * obtained from successful call to NvSciIpcOpenEndpoint() and has not yet been + * freed using NvSciIpcCloseEndpointSafe(). + * - NvSciBufObj is valid if it is obtained from a successful call to + * NvSciBufObjAlloc() or if it is obtained from a successful call to + * NvSciBufAttrListReconcileAndObjAlloc() or if it is obtained from a + * successful call to NvSciBufObjIpcImport() or if it is obtained from a + * successful call to NvSciBufObjDup() or if it is obtained from a successful + * call to NvSciBufObjDupWithReducePerm() and has not been deallocated + * using NvSciBufObjFree(). + * - Unreconciled NvSciBufAttrList is valid if it is obtained from successful + * call to NvSciBufAttrListCreate() or if it is obtained from successful call to + * NvSciBufAttrListClone() where input to NvSciBufAttrListClone() is valid + * unreconciled NvSciBufAttrList or if it is obtained from successful call to + * NvSciBufAttrListIpcImportUnreconciled() and has not been deallocated using + * NvSciBufAttrListFree(). + * - Reconciled NvSciBufAttrList is valid if it is obtained from successful call + * to NvSciBufAttrListReconcile() or if it is obtained from successful call to + * NvSciBufAttrListClone() where input to NvSciBufAttrListClone() is valid + * reconciled NvSciBufAttrList or if it is obtained from successful call to + * NvSciBufAttrListIpcImportReconciled() and has not been deallocated using + * NvSciBufAttrListFree(). + * - If the valid range for the input parameter is not explicitly mentioned in + * the API specification or in the blanket statements then it is considered that + * the input parameter takes any value from the entire range corresponding to + * its datatype as the valid value. Please note that this also applies to the + * members of a structure if the structure is taken as an input parameter. + * - NvSciBufModule is not sharable accross processes. User must create a new + * NvSciBufModule using NvSciBufModuleOpen() in every process. + * + * \section nvscibuf_out_params Output parameters + * - In general, output parameters are passed by reference through pointers. + * Also, since a null pointer cannot be used to convey an output parameter, API + * functions typically return an error code if a null pointer is supplied for a + * required output parameter unless otherwise stated explicitly. Output + * parameter is valid only if error code returned by an API is + * NvSciError_Success unless otherwise stated explicitly. + * + * \section nvscibuf_concurrency Concurrency + * - Every individual function can be called concurrently with itself without + * any side-effects unless otherwise stated explicitly in the interface + * specifications. + * - The conditions for combinations of functions that cannot be called + * concurrently or calling them concurrently leads to side effects are + * explicitly stated in the interface specifications. + */ + +/** + * @} + */ + +/** + * @defgroup nvsci_buf Buffer Allocation APIs + * + * The NvSciBuf library contains the APIs for applications to allocate + * and exchange buffers in memory. + * + * @ingroup nvsci_group_stream + * @{ + */ +/** + * @defgroup nvscibuf_datatype NvSciBuf Datatype Definitions + * Contains a list of all NvSciBuf datatypes. + * @{ + */ + +/** + * @brief Enum definitions of NvSciBuf datatypes. + * + * @implements{17824095} + */ +typedef enum { + /** Reserved for General keys. + * Shouldn't be used as valid value for NvSciBufGeneralAttrKey_Types. + */ + NvSciBufType_General = 0U, + NvSciBufType_RawBuffer = 1U, + NvSciBufType_Image = 2U, + NvSciBufType_Tensor = 3U, + NvSciBufType_Array = 4U, + NvSciBufType_Pyramid = 5U, + NvSciBufType_MaxValid = 6U, + NvSciBufType_UpperBound = 6U, +} NvSciBufType; + +/** + * @} + */ + +/** + * @defgroup nvscibuf_constants NvSciBuf Global Constants + * Definitions of all NvSciBuf Global Constants/Macros + * + * @{ + */ +/** + * @brief NvSciBuf API Major version number. + * + * @implements{18840105} + */ +static const uint32_t NvSciBufMajorVersion = 2U; + +/** + * @brief NvSciBuf API Minor version number. + * + * @implements{18840108} + */ +static const uint32_t NvSciBufMinorVersion = 10U; + +#if defined(__cplusplus) + +/** + * @brief Maximum number of dimensions supported by tensor datatype. + */ +static const int NV_SCI_BUF_TENSOR_MAX_DIMS = 8; + +/** + * @brief Maximum number of planes supported by image datatype. + */ +static const int NV_SCI_BUF_IMAGE_MAX_PLANES = 3; + +/** + * @brief Maximum number of levels supported by pyramid datatype. + */ +static const int NV_SCI_BUF_PYRAMID_MAX_LEVELS = 10; + +/** + * @brief Indicates the size of export descriptor. + */ +static const int NVSCIBUF_EXPORT_DESC_SIZE = 32; + +/** + * @brief Maxium number of peer info supported. + */ +static const uint32_t NV_SCI_BUF_PEER_INFO_MAX_NUMBER = 128U; + +/** + * @brief Self SOC ID value if the late peer is from same SoC. + */ +static const uint32_t NV_SCI_BUF_PEER_INFO_SELF_SOCID = 0xFFFFFFFFu; + +/** + * @brief Self VM ID value if the late peer is from same VM. + */ +static const uint32_t NV_SCI_BUF_PEER_INFO_SELF_VMID = 0xFFFFFFFFu; + +/** + * @brief Maximum number of HW Engines supported + */ +static const int NV_SCI_BUF_PEER_HW_ENGINE_MAX_NUMBER = 128U; + +/** + * Maximum number of GPUs that can share the NvSciBufObj. + * @implements{} + */ +static const uint32_t NV_SCI_BUF_MAX_GPUS = 16u; + +/** + * @brief Indicates number of bits used for defining an attribute key. + * Note: Maximum 16K attribute Keys per datatype. + */ +static const int NV_SCI_BUF_ATTRKEY_BIT_COUNT = 16; + +/** + * @brief Indicates number of bits used for defining an datatype of a key. + * Note: Maximum 1K datatypes. + */ +static const int NV_SCI_BUF_DATATYPE_BIT_COUNT = 10; + +/** + * @brief Indicates the attribute key is a public key type. + */ +static const int NV_SCI_BUF_ATTR_KEY_TYPE_PUBLIC = 0; + +/* + * @brief Global constant to specify the start-bit of attribute Keytype. + */ +static const int NV_SCI_BUF_KEYTYPE_BIT_START = + (NV_SCI_BUF_DATATYPE_BIT_COUNT + NV_SCI_BUF_ATTRKEY_BIT_COUNT); + +/** + * @brief Indicates starting value of General attribute keys. + */ +static const int NV_SCI_BUF_GENERAL_ATTR_KEY_START = + (NV_SCI_BUF_ATTR_KEY_TYPE_PUBLIC << NV_SCI_BUF_KEYTYPE_BIT_START) | + (NvSciBufType_General << NV_SCI_BUF_ATTRKEY_BIT_COUNT); + +/** + * @brief Indicates the start of Raw-buffer Datatype keys. + */ +static const int NV_SCI_BUF_RAW_BUF_ATTR_KEY_START = + (NV_SCI_BUF_ATTR_KEY_TYPE_PUBLIC << NV_SCI_BUF_KEYTYPE_BIT_START) | + (NvSciBufType_RawBuffer << NV_SCI_BUF_ATTRKEY_BIT_COUNT); + +/** + * @brief Indicates the start of Image Datatype keys. + */ +static const int NV_SCI_BUF_IMAGE_ATTR_KEY_START = + (NV_SCI_BUF_ATTR_KEY_TYPE_PUBLIC << NV_SCI_BUF_KEYTYPE_BIT_START) | + (NvSciBufType_Image << NV_SCI_BUF_ATTRKEY_BIT_COUNT); + +/** + * @brief Indicates the start of ImagePyramid Datatype keys. + */ +static const int NV_SCI_BUF_PYRAMID_ATTR_KEY_START = + (NV_SCI_BUF_ATTR_KEY_TYPE_PUBLIC << NV_SCI_BUF_KEYTYPE_BIT_START) | + (NvSciBufType_Pyramid << NV_SCI_BUF_ATTRKEY_BIT_COUNT); + +/** + * @brief Indicates the start of NvSciBuf Array Datatype keys. + */ +static const int NV_SCI_BUF_ARRAY_ATTR_KEY_START = + (NV_SCI_BUF_ATTR_KEY_TYPE_PUBLIC << NV_SCI_BUF_KEYTYPE_BIT_START) | + (NvSciBufType_Array << NV_SCI_BUF_ATTRKEY_BIT_COUNT); + +/** + * @brief Indicates the start of Tensor Datatype keys. + */ +static const int NV_SCI_BUF_TENSOR_ATTR_KEY_START = + (NV_SCI_BUF_ATTR_KEY_TYPE_PUBLIC << NV_SCI_BUF_KEYTYPE_BIT_START) | + (NvSciBufType_Tensor << NV_SCI_BUF_ATTRKEY_BIT_COUNT); + +#else + +/** + * @brief Maximum number of dimensions supported by NvSciBufType_Tensor. + * + * @implements{18840096} + */ +#define NV_SCI_BUF_TENSOR_MAX_DIMS 8u + +/** + * @brief Maximum number of planes supported by NvSciBufType_Image. + * + * @implements{18840099} + */ +#define NV_SCI_BUF_IMAGE_MAX_PLANES 3u + +/** + * @brief Maximum number of levels supported by NvSciBufType_Pyramid. + */ +#define NV_SCI_BUF_PYRAMID_MAX_LEVELS 10u + +/** + * @brief Indicates the size of export descriptor. + */ +#define NVSCIBUF_EXPORT_DESC_SIZE 32u + +/** + * @brief Maxium number of peer info supported. + */ +#define NV_SCI_BUF_PEER_INFO_MAX_NUMBER 128u + +/** + * @brief Self SOC ID value if the late peer is from same SoC. + */ +#define NV_SCI_BUF_PEER_INFO_SELF_SOCID 0xFFFFFFFFu + +/** + * @brief Self VM ID value if the late peer is from same VM. + */ +#define NV_SCI_BUF_PEER_INFO_SELF_VMID 0xFFFFFFFFu + +/** + * @brief Global Constant to define maximum number of NvSciBufPeerHwEngine + * supported. + */ +#define NV_SCI_BUF_PEER_HW_ENGINE_MAX_NUMBER 128U + +/** + * Maximum number of GPUs that can share the NvSciBufObj. + * @implements{} + */ +#define NV_SCI_BUF_MAX_GPUS 16 + +/** + * @brief Global constant to indicate number of bits used for + * defining an attribute key. Note: Maximum 16K attribute keys + * per NvSciBufType. + */ +#define NV_SCI_BUF_ATTRKEY_BIT_COUNT 16u + +/** + * @brief Global constant to indicate number of bits used for + * defining NvSciBufType of an attribute key. Note: Maximum 1K + * NvSciBufType(s). + */ +#define NV_SCI_BUF_DATATYPE_BIT_COUNT 10u + +/** + * @brief Global constant to indicate the attribute key type is public. + */ +#define NV_SCI_BUF_ATTR_KEY_TYPE_PUBLIC 0u + +/** + * @brief Global constant to specify the start-bit of attribute key type. + */ +#define NV_SCI_BUF_KEYTYPE_BIT_START \ + (NV_SCI_BUF_DATATYPE_BIT_COUNT + NV_SCI_BUF_ATTRKEY_BIT_COUNT) + +/** + * @brief Indicates starting value of NvSciBufAttrKey for NvSciBufType_General. + */ +#define NV_SCI_BUF_GENERAL_ATTR_KEY_START \ + ((NV_SCI_BUF_ATTR_KEY_TYPE_PUBLIC << NV_SCI_BUF_KEYTYPE_BIT_START) | \ + (NvSciBufType_General << NV_SCI_BUF_ATTRKEY_BIT_COUNT)) + +/** + * @brief Indicates starting value of NvSciBufAttrKey for NvSciBufType_RawBuffer. + */ +#define NV_SCI_BUF_RAW_BUF_ATTR_KEY_START \ + ((NV_SCI_BUF_ATTR_KEY_TYPE_PUBLIC << NV_SCI_BUF_KEYTYPE_BIT_START) | \ + (NvSciBufType_RawBuffer << NV_SCI_BUF_ATTRKEY_BIT_COUNT)) + +/** + * @brief Indicates the starting value of NvSciBufAttrKey for NvSciBufType_Image. + */ +#define NV_SCI_BUF_IMAGE_ATTR_KEY_START \ + ((NV_SCI_BUF_ATTR_KEY_TYPE_PUBLIC << NV_SCI_BUF_KEYTYPE_BIT_START) | \ + (NvSciBufType_Image << NV_SCI_BUF_ATTRKEY_BIT_COUNT)) + +/** + * @brief Indicates the starting value of NvSciBufAttrKey for NvSciBufType_Pyramid. + */ +#define NV_SCI_BUF_PYRAMID_ATTR_KEY_START \ + ((NV_SCI_BUF_ATTR_KEY_TYPE_PUBLIC << NV_SCI_BUF_KEYTYPE_BIT_START) | \ + (NvSciBufType_Pyramid << NV_SCI_BUF_ATTRKEY_BIT_COUNT)) + +/** + * @brief Indicates the starting value of NvSciBufAttrKey for NvSciBufType_Array. + */ +#define NV_SCI_BUF_ARRAY_ATTR_KEY_START \ + ((NV_SCI_BUF_ATTR_KEY_TYPE_PUBLIC << NV_SCI_BUF_KEYTYPE_BIT_START) | \ + (NvSciBufType_Array << NV_SCI_BUF_ATTRKEY_BIT_COUNT)) + +/** + * @brief Indicates the starting value of NvSciBufAttrKey for NvSciBufType_Tensor. + */ +#define NV_SCI_BUF_TENSOR_ATTR_KEY_START \ + ((NV_SCI_BUF_ATTR_KEY_TYPE_PUBLIC << NV_SCI_BUF_KEYTYPE_BIT_START) | \ + (NvSciBufType_Tensor << NV_SCI_BUF_ATTRKEY_BIT_COUNT)) + +#endif + +/** + * @} + */ + +/** + * @defgroup nvscibuf_attr_key NvSciBuf Enumerations for Attribute Keys + * List of all NvSciBuf enumerations for attribute keys. + * @{ + */ + +/** + * @brief Describes the NvSciBuf public attribute keys holding corresponding + * values specifying buffer constraints. + * The accessibility property of an attribute refers to whether the value of an + * attribute is accessible in an NvSciBufAttrList. Input attribute keys specify + * desired buffer constraints from client and can be set/retrieved by client + * to/from unreconciled NvSciBufAttrList using + * NvSciBufAttrListSetAttrs()/NvSciBufAttrListGetAttrs() respectively. + * Output attribute keys specify actual buffer constraints computed by NvSciBuf + * if reconciliation succeeds. Output attributes can be retrieved from + * reconciled NvSciBufAttrList using NvSciBufAttrListGetAttrs(). + * The presence property of an attribute refers to whether the value of an + * attribute having accessibility as input needs to be present in at least one + * of the unreconciled attribute lists for reconciliation. + * The presence property of an attribute can have one of the three values: + * Mandatory/Optional/Conditional. + * Mandatory implies that it is mandatory that the value of an attribute be set + * in at least one of the unreconciled NvSciBufAttrLists involved in + * reconciliation. Failing to set mandatory input attribute in at least one of + * the input unreconciled NvSciBufAttrLists results in reconciliation failure. + * Optional implies that it is not mandatory that value of an attribute be set + * in at least of the unreconciled NvSciBufAttrLists involved in reconciliation. + * If the optional input attribute is not set in any of the input unreconciled + * NvSciBufAttrLists, NvSciBuf uses default value of such attribute to + * calculate/reconcile output attributes dependent on such input attribute. + * Conditional implies that the presence of an attribute is mandatory if + * condition associated with its presence is satisfied, otherwise its optional. + * + * @implements{17824098} + */ +typedef enum { + /** + * Specifies the lower bound value to check for a valid NvSciBuf attribute + * key type. + */ + NvSciBufAttrKey_LowerBound = NV_SCI_BUF_GENERAL_ATTR_KEY_START, + + /** An array of all types that the buffer is expected to have. For each type + * the buffer has, the associated attributes are valid. In order to set + * @a NvSciBufAttrKeys corresponding to the NvSciBufType, NvSciBufType must + * be set first using this key. + * NOTE: A single buffer may have multiple types. For example, a buffer may + * simultaneously be a NvSciBufType_Image (for integration with NvMedia), a + * NvSciBufType_Tensor (for integration with TensorRT or NvMedia), and a + * NvSciBufType_RawBuffer (for integration with CUDA kernels that will + * directly access it). + * + * During reconciliation, if all the NvSciBufTypes + * specified by all the unreconciled NvSciBufAttrLists are same, this + * key outputs the specified NvSciBufType. If all NvSciBufTypes are + * not same, reconciliation succeeds only if the set of NvSciBufTypes + * contains NvSciBufType_Image and NvSciBufType_Tensor only otherwise + * reconciliation fails. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if value of this + * attribute set in any of the input unreconciled NvSciBufAttrList(s) is + * not present in the set of values of this attribute in the provided + * reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Mandatory + * + * Value: @ref NvSciBufType[] + * + * valid input value: All values defined by NvSciBufType for safety build + * such that NvSciBufType_General < value < NvSciBufType_MaxValid + */ + NvSciBufGeneralAttrKey_Types, + + /** Specifies if CPU access is required for the buffer. If this attribute is + * set to @c true, then the CPU will be able to obtain a pointer to the + * buffer from NvSciBufObjGetConstCpuPtr() if at least read permissions are + * granted or from NvSciBufObjGetCpuPtr() if read/write permissions are + * granted. + * + * During reconciliation, reconciler sets value of this key to true in the + * reconciled NvSciBufAttrList if any of the unreconciled + * NvSciBufAttrList(s) involved in reconciliation that is owned by the + * reconciler has this key set to true, otherwise it is set to false in + * reconciled NvSciBufAttrList. + * + * When importing the reconciled NvSciBufAttrList, for every peer owning the + * unreconciled NvSciBufAttrList(s) involved in reconciliation, if any of + * the unreconciled NvSciBufAttrList(s) owned by the peer set the key to + * true then value of this key is true in the reconciled NvSciBufAttrList + * imported by the peer otherwise its false. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if value of this + * attribute set in any of the unreconciled NvSciBufAttrList(s) belonging + * to NvSciIpc channel owner is true and value of the same attribute in + * reconciled NvSciBufAttrList is false. + * + * Accessibility: Input/Output attribute + * Presence: Optional + * + * Value: @c bool + */ + NvSciBufGeneralAttrKey_NeedCpuAccess, + + /** Specifies buffer access permissions. + * If reconciliation succeeds, granted buffer permissions are reflected in + * NvSciBufGeneralAttrKey_ActualPerm. If + * NvSciBufGeneralAttrKey_NeedCpuAccess is true and write permission + * are granted, then NvSciBufObjGetCpuPtr() can be used to obtain a + * non-const pointer to the buffer. + * NOTE: Whether this key is present in reconciled attribute lists is + * unspecified, as is its value if it is present. + * + * Accessibility: Input attribute + * Presence: Optional + * + * Value: @ref NvSciBufAttrValAccessPerm + * + * valid input value: NvSciBufAccessPerm_Readonly or + * NvSciBufAccessPerm_ReadWrite + */ + NvSciBufGeneralAttrKey_RequiredPerm, + + /** Specifies whether to enable/disable CPU caching. + * If set to @c true: + * + * The CPU must perform write-back caching of the buffer to the greatest + * extent possible considering all the CPUs that are sharing the buffer. + * Coherency is guaranteed with: + * - Other CPU accessors. + * - All I/O-Coherent accessors that do not have CPU-invisible + * caches. + * + * If set to @c false: + * + * The CPU must not access the caches at all on read or write accesses + * to the buffer from applications. + * Coherency is guaranteed with: + * - Other CPU accessors. + * - All I/O accessors (whether I/O-coherent or not) that do not + * have CPU-invisible caches. + * + * During reconciliation, this key is set to true in reconciled + * NvSciBufAttrList if any of the unreconciled NvSciBufAttrList owned by any + * peer set it to true, otherwise it is set to false. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if value of this + * attribute set in any of the unreconciled NvSciBufAttrList(s) is true and + * value of the same attribute in reconciled NvSciBufAttrList is false. + * + * Accessibility: Input/Output attribute + * Presence: Optional + * + * Value: @c bool + */ + NvSciBufGeneralAttrKey_EnableCpuCache, + + /** GpuIDs of the GPUs in the system that will access the buffer. + * In a multi GPU System, if multiple GPUs are supposed to access + * the buffer, then provide the GPU IDs of all the GPUs that + * need to access the buffer. The GPU which is not specified in the + * list of GPUIDs may not be able to access the buffer. + * + * During reconciliation, the value of this attribute in reconciled + * NvSciBufAttrList is equivalent to the aggregate of all the values + * specified by all the unreconciled NvSciBufAttrLists involved in + * reconciliation that have this attribute set. The value of this attribute + * is set to implementation chosen default value if none of the unreconciled + * NvSciBufAttrLists specify this attribute. Note that the default value + * chosen by the implementation must be an invalid NvSciRmGpuId value. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if value of this + * attribute set in any of the input unreconciled NvSciBufAttrList(s) is + * not present in the set of values of this attribute in the provided + * reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Optional + * + * Value: @ref NvSciRmGpuId[] + * + * valid input value: Valid NvSciRmGpuId of the GPU(s) present in the + * system. + */ + NvSciBufGeneralAttrKey_GpuId, + + /** Indicates whether the CPU is required to flush before reads and + * after writes. This can be accomplished using + * NvSciBufObjFlushCpuCacheRange(), or (if the application prefers) with + * OS-specific flushing functions. It is set to true in reconciled + * NvSciBufAttrList if both NvSciBufGeneralAttrKey_EnableCpuCache and + * NvSciBufGeneralAttrKey_NeedCpuAccess are requested by setting them + * to true in any of the unreconciled NvSciBufAttrList(s) from which + * reconciled NvSciBufAttrList is obtained and any of the ISO engines would + * operate on the buffer. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if value of this + * attribute reconciled from the input unreconciled NvSciBufAttrList(s) is + * true and value of the same attribute in the provided reconciled + * NvSciBufAttrList is false. + * + * Accessibility: Output attribute + * + * Value: @c bool + */ + NvSciBufGeneralAttrKey_CpuNeedSwCacheCoherency, + + /** Specifies the buffer access permissions to the NvSciBufObj. + * This key is only valid in reconciled NvSciBufAttrList + * and undefined in unreconciled NvSciBufAttrList. + * + * During reconciliation, this attribute is set to the maximum value of the + * requested permission set in NvSciBufGeneralAttrKey_RequiredPerm of all + * the unreconciled NvSciBufAttrLists are involved in the reconciliation. + * This attribute is set to default value of NvSciBufAccessPerm_Readonly if + * none of the unreconciled NvSciBufAttrLists specify value of the + * NvSciBufGeneralAttrKey_RequiredPerm attribute. + * + * If NvSciBufObj is obtained by calling NvSciBufObjAlloc(), + * NvSciBufGeneralAttrKey_ActualPerm is set to NvSciBufAccessPerm_ReadWrite + * in the reconciled NvSciBufAttrList corresponding to it since allocated + * NvSciBufObj gets read-write permissions by default. + * + * For any peer importing the reconciled NvSciBufAttrList, this key is set + * to maximum value of the requested permission set in + * NvSciBufGeneralAttrKey_RequiredPerm of all the unreconciled + * NvSciBufAttrLists that were exported by the peer for reconciliation. + * The key is set by the reconciler when exporting the reconciled + * NvSciBufAttrList. + * + * For any peer importing the NvSciBufObj, this key is set in the reconciled + * NvSciBufAttrList to the permissions associated with + * NvSciBufObjIpcExportDescriptor. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if value of this + * attribute reconciled from the input unreconciled NvSciBufAttrList(s) is + * greater than the value of the same attribute in the provided reconciled + * NvSciBufAttrList. + * + * Accessibility: Output attribute + * + * Value: NvSciBufAttrValAccessPerm + */ + NvSciBufGeneralAttrKey_ActualPerm, + + /** GPU ID of dGPU from which vidmem allocation should come when multiple + * GPUs are sharing buffer. This key should be empty if multiple GPUs + * access shared buffer from sysmem. + * + * If more than one unreconciled NvSciBufAttrLists specify this input + * attribute, reconciliation is successful if all the input attributes of + * this type match. This attribute is set to implementation chosen default + * value if none of the unreconciled NvSciBufAttrLists involved in + * reconciliation specify this attribute. Note that the default value + * chosen by the implementation must be an invalid NvSciRmGpuId value. + * + * Accessibility: Input/Output attribute + * Presence: Optional + * + * Value: NvSciRmGpuId + * + * valid input value: Valid NvSciRmGpuId of the dGPU present in the system. + */ + NvSciBufGeneralAttrKey_VidMem_GpuId, + + /** + * An array of NvSciBufAttrValGpuCache[] specifying GPU cacheability + * requirements. + * + * Currently, NvSciBuf supports cacheability control for single iGPU and + * thus if user decides to request cacheability control via this attribute + * then an array, NvSciBufAttrValGpuCache[] shall provide a single value + * where GPU ID specified in it is of type iGPU and is part of GPU IDs + * specified in NvSciBufGeneralAttrKey_GpuId. Not satisfying any of the + * above conditions results in reconciliation failure. + * + * During reconciliation, for all the unreconciled NvSciBufAttrLists + * involved in reconciliation, the input values of this attribute for a + * particular GPU ID are taken from + * a) Value specified by unreconciled NvSciBufAttrLists + * b) Default value based on table specified below if particular + * unreconciled NvSciBufAttrList does not specify it. + * The set of input values are then reconciled using AND policy. + * The policy specified above is applied for ALL the GPU IDs specified in + * NvSciBufGeneralAttrKey_GpuId. + * + * |----------|---------------|-----------|---------------| + * | GPU TYPE | MEMORY DOMAIN | PLATFORM | DEFAULT VALUE | + * |----------|---------------|-----------|---------------| + * | iGPU | Sysmem | Tegra | TRUE | + * |----------|---------------|-----------|---------------| + * | dGPU | Sysmem | Tegra/X86 | FALSE | + * |----------|---------------|-----------|---------------| + * | dGPU | Vidmem | Tegra/X86 | TRUE | + * |----------|---------------|-----------|---------------| + * + * Type: Input/Output attribute + * Presence: Optional + * + * Datatype: NvSciBufAttrValGpuCache[] + */ + NvSciBufGeneralAttrKey_EnableGpuCache, + + /** + * An attribute indicating whether application needs to perform GPU cache + * maintenance before read and after writes. The value of this attribute is + * set in reconciled NvSciBufAttrList as follows: + * The value in NvSciBufAttrValGpuCache is set to TRUE for a particular + * GPU ID in the same struct if, + * 1) Memory domain is Sysmem AND that particular GPU ID in the + * NvSciBufGeneralAttrKey_EnableGpuCache has cacheability value set to + * TRUE AND + * a) At least one of the GPU IDs in the + * NvSciBufGeneralAttrKey_EnableGpuCache has cacheability set to + * FALSE. OR + * b) At least one of the unreconciled NvSciBufAttrList has requested + * CPU access via NvSciBufGeneralAttrKey_NeedCpuAccess OR + * c) At least one HW engine will be accessing the buffer. + * 2) Memory domain is Vidmem AND that particular GPU ID in the + * NvSciBufGeneralAttrKey_EnableGpuCache has cacheability value set to + * TRUE AND + * a) Any of the HW engines accessing the buffer are not cache coherent + * with Vidmem + * It is set to FALSE otherwise. + * + * Type: Output attribute + * Datatype: NvSciBufAttrValGpuCache[] + */ + NvSciBufGeneralAttrKey_GpuSwNeedCacheCoherency, + + /** + * Specifies whether to enable/disable GPU compression for the particular + * GPU. + * User can specify the value of this attribute in terms of an + * array of @a NvSciBufAttrValGpuCompression. + * + * During reconciliation, if any of the following conditions are satisfied, + * the reconciliation fails: + * 1. The GPU ID specified as the member of @a NvSciBufAttrValGpuCompression + * does not match with any of the GPU ID values specified as an array in + * NvSciBufGeneralAttrKey_GpuId attribute. + * 2. For the particular GPU ID specified in the + * @a NvSciBufAttrValGpuCompression, the value of @a NvSciBufCompressionType + * is not the same for that particular GPU ID in all of the unreconciled + * NvSciBufAttrLists that have specified it. + * + * If none of the conditions mentioned above for reconciliation failure are + * met then this attribute is reconciled as follows: + * 1. If multiple GPUs request compression via + * NvSciBufGeneralAttrKey_EnableGpuCompression, reconciliation fills + * NvSciBufCompressionType_None (aka compression is not enabled) for all + * GPUs specified in NvSciBufGeneralAttrKey_GpuId. + * 2. If UMDs set any of the non-GPU HW engines in the unreconciled + * NvSciBufAttrLists implying that at least one non-GPU engine is going to + * access the buffer represented by NvSciBufObj, + * reconciliation fills NvSciBufCompressionType_None (aka compression is not + * enabled) for all GPUs specified in NvSciBufGeneralAttrKey_GpuId. + * 3. If NvSciBufGeneralAttrKey_NeedCpuAccess attribute is set in at least + * one of the unreconciled NvSciBufAttrLists implying that CPU access to the + * buffer represented by NvSciBufObj is needed, reconciliation fills + * NvSciBufCompressionType_None (aka compression is not enabled) for all + * GPUs specified in NvSciBufGeneralAttrKey_GpuId. + * 4. If none of the above conditions are satisfied then the value of + * NvSciBufCompressionType for that particular GPU ID is set as the matching + * value specified by all the unreconciled NvSciBufAttrLists that have set + * it. NvSciBuf then queries lower level NVIDIA driver stack to check if + * reconciled NvSciBufCompressionType is allowed for the particular GPU. + * NvSciBuf keeps the reconciled value of NvSciBufCompressionType if this + * compression type is supported, otherwise NvSciBuf falls back to + * NvSciBufCompressionType_None. + * 5. For a particular GPU ID specified in NvSciBufGeneralAttrKey_GpuId, + * if none of the unreconciled NvSciBufAttrLists specify the compression + * type needed for that GPU ID via this attribute then NvSciBuf fills + * the default value of NvSciBufCompressionType_None for that GPU ID in the + * reconciled NvSciBufAttrList. + * + * The number of elements in the array value + * @a NvSciBufAttrValGpuCompression[] of + * NvSciBufGeneralAttrKey_EnableGpuCompression attribute in the reconciled + * NvSciBufAttrList is equal to the number of GPU IDs specified in the + * NvSciBufGeneralAttrKey_GpuId attribute. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * input unreconciled NvSciBufAttrLists yield + * @a NvSciBufAttrValGpuCompression value of NvSciBufCompressionType_None + * for the particular GPU ID while value of the same GPU ID in the + * reconciled NvSciBufAttrList is other than NvSciBufCompressionType_None. + * + * Type: Input/Output attribute + * Presence: Optional + * + * Datatype: NvSciBufAttrValGpuCompression[] + */ + NvSciBufGeneralAttrKey_EnableGpuCompression, + + /** An attribute indicating location information of late attaching peer(s) + * which are going to gain access to the allocated NvScibufObj using + * NvSciBufObjAttachPeer() API. + * + * During reconciliation, the value of this attribute in reconciled + * NvSciBufAttrList is equivalent to the aggregate of all the values + * specified by all the unreconciled NvSciBufAttrLists involved in + * reconciliation that have this attribute set. + * + * Note: + * During reconciliation, + * if NvSciBufGeneralAttrKey_PeerHwEngineArray is not set: + * NvSciBuf will consider all Hw engines, + * which are reconcilable with other Hw engines present in other + * unreconciled NvSciBufAttrList, to align buffer attributes. + * else if NvSciBufGeneralAttrKey_PeerHwEngineArray is set: + * NvSciBuf only consider Hw engines from + * NvSciBufGeneralAttrKey_PeerHwEngineArray which are reconcilable with + * other Hw engines present in other unreconciled NvSciBufAttrList, + * to align buffer attributes. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if value of this + * attribute set in any of the input unreconciled NvSciBufAttrList(s) is + * not present in the set of values of this attribute in the provided + * reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * + * Presence: Optional + * Value: @ref NvSciBufPeerLocationInfo[] + */ + NvSciBufGeneralAttrKey_PeerLocationInfo, + + /** An attribute indicating list of hardware engines which will access + * the allocated buffer on late attaching peer(s). These late attaching + * peer(s) will gain access to the allocated NvSciBufObj using + * NvSciBufObjAttachPeer() API. + * + * During reconciliation, the value of this attribute in reconciled + * NvSciBufAttrList is equivalent to the aggregate of all the values + * specified by all the unreconciled NvSciBufAttrLists involved in + * reconciliation that have this attribute set. + * + * Note: During reconciliation, NvSciBuf will consider all Hw engines, + * which are reconcilable with other Hw engines present in other + * unreconciled NvSciBufAttrList, to align buffer attributes. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if value of this + * attribute set in any of the input unreconciled NvSciBufAttrList(s) is + * not present in the set of values of this attribute in the provided + * reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * + * Presence: Optional + * Value: @ref NvSciBufPeerHwEngine[] + */ + NvSciBufGeneralAttrKey_PeerHwEngineArray, + + /** + * Specifies the size of the NvSciBufType_RawBuffer NvSciBufObj that + * the underlying buffer allocation satisfies. The input size specified + * in unreconciled NvSciBufAttrList(s) should be greater than 0. + * + * If more than one unreconciled NvSciBufAttrLists specify this input + * attribute, reconciliation is successful if all the input attributes of + * this type match. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) yields NvSciBufType_RawBuffer and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Mandatory + * Unit: byte + * + * Value: @c uint64_t + */ + NvSciBufRawBufferAttrKey_Size = NV_SCI_BUF_RAW_BUF_ATTR_KEY_START, + + /** Specifies the alignment requirement of NvSciBufType_RawBuffer. Input + * alignment should be power of 2. If more than one unreconciled + * NvSciBufAttrLists specify this input attribute, value in the reconciled + * NvSciBufAttrList corresponds to maximum of the values specified in all of + * the unreconciled NvSciBufAttrLists. The value of this attribute is set to + * default alignment with which buffer is allocated if none of the + * unreconciled NvSciBufAttrList(s) involved in reconciliation specify this + * attribute. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) yields NvSciBufType_RawBuffer and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Optional + * Unit: byte + * + * Value: @c uint64_t + * + * valid input value: value is power of 2. + */ + NvSciBufRawBufferAttrKey_Align, + + /** Specifies the layout of NvSciBufType_Image: Block-linear or + * Pitch-linear. If more than one unreconciled NvSciBufAttrLists specify + * this input attribute, reconciliation is successful if all the input + * attributes of this type match. + * + * Only pitch-linear layout is supported for image-tensor buffer type + * reconciliation. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Mandatory + * + * Value: @ref NvSciBufAttrValImageLayoutType + * + * valid input value: Any value defined by NvSciBufAttrValImageLayoutType + * enum. + */ + NvSciBufImageAttrKey_Layout = NV_SCI_BUF_IMAGE_ATTR_KEY_START, + + /** Specifies the top padding for the NvSciBufType_Image. If more than one + * unreconciled NvSciBufAttrLists specify this input attribute, + * reconciliation is successful if all the input attributes of this + * type match. This attribute is set to default value of 0 if none of the + * unreconciled NvSciBufAttrList(s) involved in reconciliation specify the + * attribute. + * + * Padding is not allowed to be specified for image-tensor reconciliation. + * It is allowed for image only buffer reconciliation. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. This is Optional when surface-based image + * attributes are not used, and should not be specified otherwise. + * Unit: pixel + * + * Value: @c uint64_t[] + */ + NvSciBufImageAttrKey_TopPadding, + + /** Specifies the bottom padding for the NvSciBufType_Image. If more than + * one unreconciled NvSciBufAttrLists specify this input attribute, + * reconciliation is successful if all the input attributes of this + * type match. This attribute is set to default value of 0 if none of the + * unreconciled NvSciBufAttrList(s) involved in reconciliation specify the + * attribute. + * + * Padding is not allowed to be specified for image-tensor reconciliation. + * It is allowed for image only buffer reconciliation. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. This is Optional when surface-based image + * attributes are not used, and should not be specified otherwise. + * Unit: pixel + * + * Value: uint64_t[] + */ + NvSciBufImageAttrKey_BottomPadding, + + /** Specifies the left padding for the NvSciBufType_Image. If more than one + * unreconciled NvSciBufAttrLists specify this input attribute, + * reconciliation is successful if all the input attributes of this + * type match. This attribute is set to default value of 0 if none of the + * unreconciled NvSciBufAttrList(s) involved in reconciliation specify the + * attribute. + * + * Padding is not allowed to be specified for image-tensor reconciliation. + * It is allowed for image only buffer reconciliation. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. This is Optional when surface-based image + * attributes are not used, and should not be specified otherwise. + * Unit: pixel + * + * Value: @c uint64_t[] + */ + NvSciBufImageAttrKey_LeftPadding, + + /** Specifies the right padding for the NvSciBufType_Image. If more than one + * unreconciled NvSciBufAttrLists specify this input attribute, + * reconciliation is successful if all the input attributes of this + * type match. This attribute is set to default value of 0 if none of the + * unreconciled NvSciBufAttrList(s) involved in reconciliation specify the + * attribute. + * + * Padding is not allowed to be specified for image-tensor reconciliation. + * It is allowed for image only buffer reconciliation. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. This is Optional when surface-based image + * attributes are not used, and should not be specified otherwise. + * Unit: pixel + * + * Value: @c uint64_t[] + */ + NvSciBufImageAttrKey_RightPadding, + + /** Specifies the VPR flag for the NvSciBufType_Image. + * + * During reconciliation, this key is set to true in reconciled + * NvSciBufAttrList if any of the unreconciled NvSciBufAttrList owned by any + * peer set it to true, otherwise it is set to false. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is true and value of same attribute in the + * provided reconciled NvSciBufAttrList is false. + * + * Accessibility: Input/Output attribute + * Presence: Optional + * + * Value: @c bool + */ + NvSciBufImageAttrKey_VprFlag, + + /** + * Specifies the size of the NvSciBufType_Image NvSciBufObj that the + * underlying buffer allocation satisfies after successful reconciliation. + * The output size for this key is computed by aggregating the size of + * all the planes in the output key NvSciBufImageAttrKey_PlaneAlignedSize. + * + * The size is calculated the following way: + * NvSciBufImageAttrKey_Size = sum of NvSciBufImageAttrKey_PlaneAlignedSize + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * Unit: byte + * + * Value: @c uint64_t + */ + NvSciBufImageAttrKey_Size, + + /** Output alignment of the NvSciBufType_Image after successful + * reconciliation. + * The output value of this key is same as alignment value of the first + * plane in the key NvSciBufImageAttrKey_PlaneBaseAddrAlign after + * reconciliation. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * Unit: byte + * + * Value: @c uint64_t + */ + NvSciBufImageAttrKey_Alignment, + + /** Specifies the number of planes for NvSciBufType_Image. If more than one + * unreconciled NvSciBufAttrLists specify this input attribute, + * reconciliation is successful if all the input attributes of this + * type match. If NvSciBufType_Image and NvSciBufType_Tensor are involved in + * reconciliation and if this attribute is set in any of unreconciled + * NvSciBufAttrList(s) to be reconciled, the value of this attribute should + * be 1. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. This is Mandatory when surface-based image + * attributes are not used, and should not be specified otherwise. + * + * Value: @c uint32_t + * + * valid input value: 1 <= value <= NV_SCI_BUF_IMAGE_MAX_PLANES + */ + NvSciBufImageAttrKey_PlaneCount, + + /** Specifies the NvSciBufAttrValColorFmt of the NvSciBufType_Image plane. + * If more than one unreconciled NvSciBufAttrLists specify this input + * attribute, reconciliation is successful if all the input attributes of + * this type match. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. This is Mandatory when surface-based image + * attributes are not used, and should not be specified otherwise. + * + * Value: @ref NvSciBufAttrValColorFmt[] + * + * valid input value: NvSciColor_LowerBound < value < NvSciColor_UpperBound + */ + NvSciBufImageAttrKey_PlaneColorFormat, + + /** Specifies a set of plane color standards. If more than + * one unreconciled NvSciBufAttrLists specify this input attribute, + * reconciliation is successful if all the input attributes of this + * type match. This attribute is set to implementation chosen default value + * if none of the unreconciled NvSciBufAttrList(s) involved in + * reconciliation specify this attribute. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. This is Optional when surface-based image + * attributes are not used, and should not be specified otherwise. + * + * Value: @ref NvSciBufAttrValColorStd[] + * + * valid input value: Any value defined by NvSciBufAttrValColorStd enum. + */ + NvSciBufImageAttrKey_PlaneColorStd, + + /** Specifies the NvSciBufType_Image plane base address alignment for every + * plane in terms of an array. Input alignment must be power of 2. + * If more than one unreconciled NvSciBufAttrLists specify this attribute, + * reconciled NvSciBufAttrList has maximum alignment value per array index + * of the values specified in unreconciled NvSciBufAttrLists for the same + * array index. On top of that, for all the HW engines for which buffer is + * being allocated, if the maximum start address alignment constraint of all + * the engines taken together is greater than the reconciled alignment value + * at any index, it is replaced with start address alignment value. In other + * words, + * reconciled alignment per array index = + * MAX(MAX(alignments in unreconciled list at the same index), + * MAX(start address alignment constraint of all the engines)) + * The value of this attribute is set to default alignment with which buffer + * is allocated if none of the unreconciled NvSciBufAttrList(s) involved in + * reconciliation specify this attribute. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. This is Optional when surface-based image + * attributes are not used, and should not be specified otherwise. + * Unit: byte + * + * Value: @c uint32_t[] + * + * valid input value: value is power of 2. + */ + NvSciBufImageAttrKey_PlaneBaseAddrAlign, + + /** Specifies the NvSciBufType_Image plane width in pixels. If more than + * one unreconciled NvSciBufAttrLists specify this input attribute, + * reconciliation is successful if all the input attributes of this + * type match. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. This is Mandatory when surface-based image + * attributes are not used, and should not be specified otherwise. + * Unit: pixel + * + * Value: @c uint32_t[] + */ + NvSciBufImageAttrKey_PlaneWidth, + + /** Specifies the NvSciBufType_Image plane height in number of pixels. If + * more than one unreconciled NvSciBufAttrLists specify this input + * attribute, reconciliation is successful if all the input attributes of + * this type match. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. This is Mandatory when surface-based image + * attributes are not used, and should not be specified otherwise. + * Unit: pixel + * + * Value: @c uint32_t[] + */ + NvSciBufImageAttrKey_PlaneHeight, + + /** Specifies the NvSciBufType_Image scan type: Progressive or Interlaced. + * If more than one unreconciled NvSciBufAttrLists specify this input + * attribute, reconciliation is successful if all the input attributes + * of this type match. + * + * @note NvSciBufImageAttrKey_PlaneScanType is deprecated and may be + * removed in some future release. Use NvSciBufImageAttrKey_ScanType + * wherever possible. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Mandatory + * + * Value: @ref NvSciBufAttrValImageScanType + * + * valid input value: Any value defined by NvSciBufAttrValImageScanType + * enum. + */ + NvSciBufImageAttrKey_PlaneScanType = 0x2000e, + NvSciBufImageAttrKey_ScanType = NvSciBufImageAttrKey_PlaneScanType, + + /** Outputs number of bits per pixel corresponding to the + * NvSciBufAttrValColorFmt for each plane specified in + * NvSciBufImageAttrKey_PlaneColorFormat. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * + * Value: @c uint32_t[] + */ + NvSciBufImageAttrKey_PlaneBitsPerPixel, + + /** Indicates the starting offset of the NvSciBufType_Image plane from the + * first plane. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * Unit: byte + * + * Value: @c uint64_t[] + */ + NvSciBufImageAttrKey_PlaneOffset, + + /** Outputs the NvSciBufAttrValDataType of each plane based on the + * NvSciBufAttrValColorFmt provided in + * NvSciBufImageAttrKey_PlaneColorFormat for every plane. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * + * Value: @ref NvSciBufAttrValDataType[] + */ + NvSciBufImageAttrKey_PlaneDatatype, + + /** Outputs number of channels per plane. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * + * Value: @c uint8_t[] + */ + NvSciBufImageAttrKey_PlaneChannelCount, + + /** Indicates the offset of the start of the second field, 0 for progressive + * valid for interlaced. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * Unit: byte + * + * Value: @c uint64_t[] + */ + NvSciBufImageAttrKey_PlaneSecondFieldOffset, + + /** Outputs the pitch (aka width in bytes) for every plane. + * + * The pitch is calculated the following way (prior to additional alignment + * constraints from the hardware engines accessing the buffer being + * considered), such that the pitch is at least: + * + * NvSciBufImageAttrKey_PlanePitch = + * (NvSciBufImageAttrKey_PlaneWidth * (Bits per pixel for + * NvSciBufImageAttrKey_PlaneColorFormat)) / 8 + * + * This value is then aligned to the maximum of the pitch alignment + * constraint value of all the HW engines that are going to operate on the + * buffer using extra padding bytes. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * Unit: byte + * + * Value: @c uint32_t[] + */ + NvSciBufImageAttrKey_PlanePitch, + + /** Outputs the aligned height of every plane in terms of number of pixels. + * This height is calculated by aligning value for every plane provided in + * NvSciBufImageAttrKey_PlaneHeight with maximum of the height alignment + * constraints of all the engines that are going to operate on the buffer. + * + * The height is calculated the following way: + * If (NvSciBufImageAttrKey_ScanType == NvSciBufScan_InterlaceType) + * NvSciBufImageAttrKey_PlaneAlignedHeight = + * (NvSciBufImageAttrKey_PlaneHeight / 2) + * This value is aligned to highest height HW constraints among all + * the HW engines accessing the buffer + * Else + * NvSciBufImageAttrKey_PlaneAlignedHeight = + * NvSciBufImageAttrKey_PlaneHeight + * This value is aligned to highest height HW constraints among all + * the HW engines accessing the buffer + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * Unit: pixel + * + * Value: @c uint32_t[] + */ + NvSciBufImageAttrKey_PlaneAlignedHeight, + + /** Indicates the aligned size of every plane. The size is calculated from + * the value of NvSciBufImageAttrKey_PlanePitch and + * NvSciBufImageAttrKey_PlaneAlignedHeight. + * + * The size is calculated the following way: + * If (NvSciBufImageAttrKey_ScanType == NvSciBufScan_InterlaceType) + * NvSciBufImageAttrKey_PlaneAlignedSize = + * NvSciBufImageAttrKey_PlanePitch * + * NvSciBufImageAttrKey_PlaneAlignedHeight * 2 + * This value is aligned to highest size HW constraints among all + * the HW engines accessing the buffer + * Else + * NvSciBufImageAttrKey_PlaneAlignedSize = + * NvSciBufImageAttrKey_PlanePitch * + * NvSciBufImageAttrKey_PlaneAlignedHeight + * This value is aligned to highest size HW constraints among all + * the HW engines accessing the buffer + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * Unit: byte + * + * Value: @c uint64_t[] + */ + NvSciBufImageAttrKey_PlaneAlignedSize, + + /** Attribute to specify number of NvSciBufType_Image(s) for which buffer + * should be allocated. If more than one unreconciled NvSciBufAttrLists + * specify this input attribute, reconciliation is successful if all the + * input attributes of this type match. This attribute is set to default + * value of 1 if none of the unreconciled NvSciBufAttrList(s) specify this + * attribute and the condition for the optional presence of this attribute + * is satisfied. + * NvSciBuf supports allocating buffer for single image only and thus, this + * attribute should be set to 1. A single buffer cannot be allocated for + * multiple images. Allocating 'N' buffers corresponding to 'N' images is + * allowed. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. Mandatory for Image/Tensor reconciliation, + * Optional otherwise. + * + * Value: @c uint64_t + * + * valid input value: 1 + */ + NvSciBufImageAttrKey_ImageCount, + + /** + * Specifies the NvSciBufSurfType. If more than one unreconciled + * NvSciBufAttrList specifies this input attribute, reconciliation is + * successful if all the input attributes of this type match. This value is + * set on the reconciled NvSciBufAttrList. This attribute is unset in the + * reconciled NvSciBufAttrList if no surface-based image attributes were + * requested in the unreconciled NvSciBufAttrList(s). + * + * During validation of a reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList + * when it is set in at least one of the unreconciled NvSciBufAttrList(s) + * that are being verified against this reconciled NvSciBufAttrList + * - The value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * @note This is a convenience attribute key. Such surface-based attribute + * keys are mutually exclusive with the plane-based attribute keys. If both + * types of attribute keys are specified then reconciliation will fail. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. Mandatory when surface-based image attributes are + * used, and should not be specified otherwise. + * + * Value: @ref NvSciBufSurfType + */ + NvSciBufImageAttrKey_SurfType, + + /** + * Specifies the NvSciBufSurfMemLayout. If more than one unreconciled + * NvSciBufAttrList specifies this input attribute, reconciliation is + * successful if all the input attributes of this type match. This value is + * set on the reconciled NvSciBufAttrList. This attribute is unset in the + * reconciled NvSciBufAttrList if no surface-based image attributes were + * requested in the unreconciled NvSciBufAttrList(s). + * + * During validation of a reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList + * when it is set in at least one of the unreconciled NvSciBufAttrList(s) + * that are being verified against this reconciled NvSciBufAttrList + * - The value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * @note This is a convenience attribute key. Such surface-based attribute + * keys are mutually exclusive with the plane-based attribute keys. If both + * types of attribute keys are specified then reconciliation will fail. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. Mandatory when surface-based image attributes are + * used, and should not be specified otherwise. + * + * Value: @ref NvSciBufSurfMemLayout + */ + NvSciBufImageAttrKey_SurfMemLayout, + + /** + * Specifies the NvSciBufSurfSampleType. If more than one unreconciled + * NvSciBufAttrList specifies this input attribute, reconciliation is + * successful if all the input attributes of this type match. This value is + * set on the reconciled NvSciBufAttrList. This attribute is unset in the + * reconciled NvSciBufAttrList if no surface-based image attributes were + * requested in the unreconciled NvSciBufAttrList(s). + * + * During validation of a reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList + * when it is set in at least one of the unreconciled NvSciBufAttrList(s) + * that are being verified against this reconciled NvSciBufAttrList + * - The value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * @note This is a convenience attribute key. Such surface-based attribute + * keys are mutually exclusive with the plane-based attribute keys. If both + * types of attribute keys are specified then reconciliation will fail. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. Mandatory when surface-based image attributes are + * used, and should not be specified otherwise. + * + * Value: @ref NvSciBufSurfSampleType + * + * valid input value: + */ + NvSciBufImageAttrKey_SurfSampleType, + + /** + * Specifies the NvSciBufSurfBPC. If more than one unreconciled + * NvSciBufAttrList specifies this input attribute, reconciliation is + * successful if all the input attributes of this type match. This value is + * set on the reconciled NvSciBufAttrList. This attribute is unset in the + * reconciled NvSciBufAttrList if no surface-based image attributes were + * requested in the unreconciled NvSciBufAttrList(s). + * + * During validation of a reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList + * when it is set in at least one of the unreconciled NvSciBufAttrList(s) + * that are being verified against this reconciled NvSciBufAttrList + * - The value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * @note This is a convenience attribute key. Such surface-based attribute + * keys are mutually exclusive with the plane-based attribute keys. If both + * types of attribute keys are specified then reconciliation will fail. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. Mandatory when surface-based image attributes are + * used, and should not be specified otherwise. + * + * Value: @ref NvSciBufSurfBPC + */ + NvSciBufImageAttrKey_SurfBPC, + + /** + * Specifies the NvSciSurfComponentOrder. If more than one unreconciled + * NvSciBufAttrList specifies this input attribute, reconciliation is + * successful if all the input attributes of this type match. This value is + * set on the reconciled NvSciBufAttrList. This attribute is unset in the + * reconciled NvSciBufAttrList if no surface-based image attributes were + * requested in the unreconciled NvSciBufAttrList(s). + * + * During validation of a reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList + * when it is set in at least one of the unreconciled NvSciBufAttrList(s) + * that are being verified against this reconciled NvSciBufAttrList + * - The value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * @note This is a convenience attribute key. Such surface-based attribute + * keys are mutually exclusive with the plane-based attribute keys. If both + * types of attribute keys are specified then reconciliation will fail. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. Mandatory when surface-based image attributes are + * used, and should not be specified otherwise. + * + * Value: @ref NvSciBufSurfComponentOrder + */ + NvSciBufImageAttrKey_SurfComponentOrder, + + /** + * Specifies the surface base width. If more than one unreconciled + * NvSciBufAttrList specifies this input attribute, reconciliation is + * successful if all the input attributes of this type match. This value is + * set on the reconciled NvSciBufAttrList. This attribute is unset in the + * reconciled NvSciBufAttrList if no surface-based image attributes were + * requested in the unreconciled NvSciBufAttrList(s). + * + * During validation of a reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList + * when it is set in at least one of the unreconciled NvSciBufAttrList(s) + * that are being verified against this reconciled NvSciBufAttrList + * - The value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * @note This is a convenience attribute key. Such surface-based attribute + * keys are mutually exclusive with the plane-based attribute keys. If both + * types of attribute keys are specified then reconciliation will fail. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. Mandatory when surface-based image attributes are + * used, and should not be specified otherwise. + * Unit: pixel + * + * Value: @c uint32_t + */ + NvSciBufImageAttrKey_SurfWidthBase, + + /** + * Specifies the Surface base height. If more than one unreconciled + * NvSciBufAttrList specifies this input attribute, reconciliation is + * successful if all the input attributes of this type match. This value is + * set on the reconciled NvSciBufAttrList. This attribute is unset in the + * reconciled NvSciBufAttrList if no surface-based image attributes were + * requested in the unreconciled NvSciBufAttrList(s). + * + * During validation of a reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList + * when it is set in at least one of the unreconciled NvSciBufAttrList(s) + * that are being verified against this reconciled NvSciBufAttrList + * - The value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * @note This is a convenience attribute key. Such surface-based attribute + * keys are mutually exclusive with the plane-based attribute keys. If both + * types of attribute keys are specified then reconciliation will fail. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. Mandatory when surface-based image attributes are + * used, and should not be specified otherwise. + * Unit: pixel + * + * Value: @c uint32_t + */ + NvSciBufImageAttrKey_SurfHeightBase, + + /** + * Specifies the NvSciBufAttrValColorStd applicable to all the surface's + * planes. If more than one unreconciled NvSciBufAttrList specifies this + * input attribute, reconciliation is successful if all the input + * attributes of this type match. This value is set on the reconciled + * NvSciBufAttrList. This attribute is unset in the reconciled + * NvSciBufAttrList if no surface-based image attributes were requested in + * the unreconciled NvSciBufAttrList(s). + * + * During validation of a reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Image and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList + * when it is set in at least one of the unreconciled NvSciBufAttrList(s) + * that are being verified against this reconciled NvSciBufAttrList + * - The value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * @note This is a convenience attribute key. Such surface-based attribute + * keys are mutually exclusive with the plane-based attribute keys. If both + * types of attribute keys are specified then reconciliation will fail. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. Optional when surface-based image attributes are + * used, and should not be specified otherwise. + * + * Value: @ref NvSciBufAttrValColorStd + * + * valid input value: Any value defined by NvSciBufAttrValColorStd enum. + */ + NvSciBufImageAttrKey_SurfColorStd, + + /** Specifies the tensor data type. + * If more than one unreconciled NvSciBufAttrLists specify this input + * attribute, reconciliation is successful if all the input attributes of + * this type match. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Tensor and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Mandatory + * + * Value: @ref NvSciBufAttrValDataType + * + * valid input value: NvSciDataType_Int4 <= value <= NvSciDataType_Float32 + */ + NvSciBufTensorAttrKey_DataType = NV_SCI_BUF_TENSOR_ATTR_KEY_START, + + /** Specifies the number of tensor dimensions. A maximum of 8 dimensions are + * allowed. If more than one unreconciled NvSciBufAttrLists specify this + * input attribute, reconciliation is successful if all the input attributes + * of this type match. + * If NvSciBufType_Image and NvSciBufType_Tensor NvSciBufTypes are used + * in reconciliation, reconciliation succeeds only if this key is set + * to 4, since NvSciBuf only supports reconciliation of NvSciBufType_Tensor + * of NHWC type with NvSciBufType_Image. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Tensor and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Mandatory + * + * Value: @c uint32_t + * + * valid input value: 1 <= value <= NV_SCI_BUF_TENSOR_MAX_DIMS + */ + NvSciBufTensorAttrKey_NumDims, + + /** Specifies the size of each tensor dimension. + * This attribute takes size value in terms of an array. + * If more than one unreconciled NvSciBufAttrLists specify this input + * attribute, reconciliation is successful if all the input attributes of + * this type match. Number of elements in value array of this attribute + * should not be less than value specified by NvSciBufTensorAttrKey_NumDims + * attribute. + * @note Array indices are not tied to the semantics of the + * dimension if NvSciBufType_Tensor is the only NvSciBufType involved + * in reconciliation. If NvSciBufType_Tensor and NvSciBufType_Image + * are involved in reconciliation, NvSciBuf only supports + * reconciliation of NvSciBufType_Image with NHWC NvSciBufType_Tensor + * where N=1 and thus reconciliation succeeds only if value of + * dimension 0 is 1 and it matches with value of + * NvSciBufImageAttrKey_ImageCount, value of dimension 1 matches with value + * of NvSciBufImageAttrKey_PlaneHeight, value of dimension 2 matches with + * value of NvSciBufImageAttrKey_PlaneWidth and dimension 3 specifies + * channel count for NvSciBufAttrValColorFmt specified in + * NvSciBufTensorAttrKey_PixelFormat key + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Tensor and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Mandatory + * + * Value: @c uint64_t[] + */ + NvSciBufTensorAttrKey_SizePerDim, + + /** Specifies the alignment constraints per tensor dimension. + * Number of elements in value array of this attribute should not be less + * than value specified by NvSciBufTensorAttrKey_NumDims attribute. Value of + * every element in the value array should be power of two. If more than one + * unreconciled NvSciBufAttrLists specify this input attribute, value in the + * reconciled NvSciBufAttrList corresponds to maximum of the values + * specified in all of the unreconciled NvSciBufAttrLists that have set this + * attribute. The value of this attribute is set to default alignment with + * which buffer is allocated if none of the unreconciled NvSciBufAttrList(s) + * involved in reconciliation specify this attribute and condition for the + * optional presence of this attribute is satisfied. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Tensor and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. Mandatory for Tensor only reconciliation, optional + * otherwise. + * Unit: byte + * + * Value: @c uint32_t[] + * + * valid input value: value is power of 2. + */ + NvSciBufTensorAttrKey_AlignmentPerDim, + + /** Returns the stride value (in bytes) for each tensor dimension. + * @note The returned array contains stride values in decreasing order. + * In other words, the index @em 0 of the array will have the largest + * stride while [@em number-of-dims - 1] index will have the smallest stride. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Tensor and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * Unit: byte + * + * Value: @c uint64_t[] + */ + NvSciBufTensorAttrKey_StridesPerDim, + + /** Attribute providing pixel format of the tensor. This key needs to be + * set only if NvSciBufType_Image and NvSciBufType_Tensor are involved in + * reconciliation. + * If more than one unreconciled NvSciBufAttrLists specify this input + * attribute, reconciliation is successful if all the input attributes of + * this type match. Additionally, reconciliation succeeds only if value of + * this attribute matches with the value of + * NvSciBufImageAttrKey_PlaneColorFormat in all the input unreconciled + * NvSciBufAttrList(s) that have set it. + * Image/Tensor reconciliation only supports NvSciColor_A8B8G8R8 and + * NvSciColor_Float_A16B16G16R16 color formats as of now. This attribute is + * set to default value if none of the unreconciled NvSciBufAttrList(s) + * involved in reconciliation specify this attribute and condition for the + * optional presence of this attribute is satisfied. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Tensor and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Conditional. Mandatory for Image/Tensor reconciliation, + * optional otherwise. + * + * Value: @ref NvSciBufAttrValColorFmt + * + * valid input value: NvSciColor_LowerBound < value < NvSciColor_UpperBound + */ + NvSciBufTensorAttrKey_PixelFormat, + + /** Attribute providing base address alignment requirements for tensor. + * Input value provided for this attribute must be power of two. Output + * value of this attribute is always power of two. If more than one + * unreconciled NvSciBufAttrLists specify this input attribute, value in the + * reconciled NvSciBufAttrList corresponds to maximum of the values + * specified in all of the unreconciled NvSciBufAttrLists that have set this + * attribute. + * The value of this attribute is set to default alignment with + * which buffer is allocated if none of the unreconciled NvSciBufAttrList(s) + * involved in reconciliation specify this attribute and condition for the + * optional presence of this attribute is satisfied. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Tensor and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Optional + * Unit: byte + * + * Value: @c uint64_t + * + * valid input value: value is power of 2. + */ + NvSciBufTensorAttrKey_BaseAddrAlign, + + /** + * Specifies the size of the NvSciBufType_Tensor NvSciBufObj with + * NvSciBufTensorAttrKey_NumDims tensor dimensions that the underlying + * buffer allocation satisfies after successful reconciliation. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) contains NvSciBufType_Tensor and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * Unit: byte + * + * Value: @c uint64_t + */ + NvSciBufTensorAttrKey_Size, + + /** Specifies the data type of a NvSciBufType_Array. + * + * If more than one unreconciled NvSciBufAttrLists specify this input + * attribute, reconciliation is successful if all the input attributes of + * this type match. Upon successful reconciliation, the reconciled value of + * this attribute is equal to the value of the same attribute in one of the + * unreconciled NvSciBufAttrLists. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) yields NvSciBufType_Array and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Mandatory + * + * Value: @ref NvSciBufAttrValDataType + * + * valid input value: NvSciDataType_Int4 <= value <= NvSciDataType_Bool + */ + NvSciBufArrayAttrKey_DataType = NV_SCI_BUF_ARRAY_ATTR_KEY_START, + + /** Specifies the stride of each element in the NvSciBufType_Array. + * Stride must be greater than or equal to size of datatype specified by + * NvSciBufArrayAttrKey_DataType. + * + * If more than one unreconciled NvSciBufAttrLists specify this input + * attribute, reconciliation is successful if all the input attributes of + * this type match. Upon successful reconciliation, the reconciled value of + * this attribute is equal to the value of the same attribute in one of the + * unreconciled NvSciBufAttrLists. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) yields NvSciBufType_Array and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Mandatory + * Unit: byte + * + * Value: @c uint64_t + */ + NvSciBufArrayAttrKey_Stride, + + /** Specifies the NvSciBufType_Array capacity. + * + * If more than one unreconciled NvSciBufAttrLists specify this input + * attribute, reconciliation is successful if all the input attributes of + * this type match. Upon successful reconciliation, the reconciled value of + * this attribute is equal to the value of the same attribute in one of the + * unreconciled NvSciBufAttrLists. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) yields NvSciBufType_Array and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Mandatory + * + * Value: @c uint64_t + */ + NvSciBufArrayAttrKey_Capacity, + + /** + * Specifies the size of the NvSciBufType_Array NvSciBufObj that + * the underlying buffer allocation satisfies after successful + * reconciliation. + * + * During reconciliation, the size is calculated as follows: + * NvSciBufArrayAttrKey_Size = reconciled value of + * NvSciBufArrayAttrKey_Capacity * reconciled value of + * NvSciBufArrayAttrKey_Stride. + * This value is then aligned to highest data alignment constraints among + * all the HW engines accessing the buffer. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) yields NvSciBufType_Array and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * Unit: byte + * + * Value: @c uint64_t + */ + NvSciBufArrayAttrKey_Size, + + /** Indicates the base alignment of a NvSciBufType_Array. + * + * During reconciliation, the value of this attribute is set as the highest + * start address alignment among all the HW engines accessing the buffer. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) yields NvSciBufType_Array and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * Unit: byte + * + * Value: @c uint64_t + */ + NvSciBufArrayAttrKey_Alignment, + + /** Specifies the number of levels of images in a pyramid. + * + * If more than one unreconciled NvSciBufAttrLists specify this input + * attribute, reconciliation is successful if all the input attributes of + * this type match. Upon successful reconciliation, the reconciled value of + * this attribute is equal to the value of the same attribute in one of the + * unreconciled NvSciBufAttrLists. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) yields NvSciBufType_Pyramid and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Mandatory + * + * Value: @c uint32_t + * + * valid input value: 1 <= value <= NV_SCI_BUF_PYRAMID_MAX_LEVELS + */ + NvSciBufPyramidAttrKey_NumLevels = NV_SCI_BUF_PYRAMID_ATTR_KEY_START, + + /** Specifies the scaling factor by which each successive image in a + * pyramid must be scaled. + * + * If more than one unreconciled NvSciBufAttrLists specify this input + * attribute, reconciliation is successful if all the input attributes of + * this type match. Upon successful reconciliation, the reconciled value of + * this attribute is equal to the value of the same attribute in one of the + * unreconciled NvSciBufAttrLists. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) yields NvSciBufType_Pyramid and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute set in any of the input unreconciled + * NvSciBufAttrList(s) is not equal to the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Input/Output attribute + * Presence: Mandatory + * + * Value: @c float + * + * valid input value: 0.0f < value <= 1.0f + */ + NvSciBufPyramidAttrKey_Scale, + + /** Buffer offset per level. + * + * During reconciliation, value of this attribute is calculated per level + * such that offset per level is equal to the number of offset bytes that + * need to be added from the starting buffer address of the first level to + * jump to the starting buffer address of the current level. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) yields NvSciBufType_Pyramid and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * Unit: byte + * + * Value: @c uint64_t[] + */ + NvSciBufPyramidAttrKey_LevelOffset, + + /** Buffer size per pyramid level. + * + * During reconciliation, values of NvSciBufImageAttrKey_PlaneWidth and + * NvSciBufImageAttrKey_PlaneHeight in reconciled NvSciBufAttrList are + * considered for computation of image size for the first level. For + * subsequent levels, the width and height are scaled down from the previous + * level by the factor specified in reconciled value of + * NvSciBufPyramidAttrKey_Scale and buffer size of image for each level is + * computed as specified in NvSciBufImageAttrKey_Size. The reconciled value + * of this attribute contains the buffer size of the image for each level. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) yields NvSciBufType_Pyramid and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * Unit: byte + * + * Value: @c uint64_t[] + */ + NvSciBufPyramidAttrKey_LevelSize, + + /** Alignment attribute of pyramid. + * + * During reconciliation, the value of this attribute is assigned the value + * equal to the value of NvSciBufImageAttrKey_Alignment in the + * reconciled NvSciBufAttrList. + * + * During validation of reconciled NvSciBufAttrList against input + * unreconciled NvSciBufAttrList(s), validation fails if reconciliation of + * NvSciBufGeneralAttrKey_Types attribute from the input unreconciled + * NvSciBufAttrList(s) yields NvSciBufType_Pyramid and any of the + * following conditions is satisfied: + * - This attribute is not set in the provided reconciled NvSciBufAttrList. + * - Value of this attribute reconciled from input unreconciled + * NvSciBufAttrList(s) is greater than the value of same attribute in the + * provided reconciled NvSciBufAttrList. + * + * Accessibility: Output attribute + * Unit: byte + * + * Value: uint64_t + */ + NvSciBufPyramidAttrKey_Alignment, + + /** Specifies the maximum number of NvSciBuf attribute keys. + * The total space for keys is 32K. + * + * Value: None + */ + NvSciBufAttrKey_UpperBound = 0x3ffffffU, + +} NvSciBufAttrKey; + +/** + * @} + */ + +/** + * @addtogroup nvscibuf_datatype + * @{ + */ + +/** + * @brief Defines buffer access permissions for NvSciBufObj. + * + * @implements{18840072} + */ +typedef enum { + NvSciBufAccessPerm_Readonly = 1, + NvSciBufAccessPerm_ReadWrite = 3, + /** Usage of Auto permissions is restricted only for export, import APIs + * and shouldn't be used to set value for + * NvSciBufGeneralAttrKey_RequiredPerm Attribute */ + NvSciBufAccessPerm_Auto, + NvSciBufAccessPerm_Invalid, +} NvSciBufAttrValAccessPerm; + +/** + * @brief Defines the image layout type for NvSciBufType_Image. + * + * @implements{18840075} + */ +typedef enum { + /** + * Block linear layout format. + * A hardware-optimized image layout. + */ + NvSciBufImage_BlockLinearType, + /** + * Pitch linear layout format. + */ + NvSciBufImage_PitchLinearType, +} NvSciBufAttrValImageLayoutType; + +/** + * @brief Defines the image scan type for NvSciBufType_Image. + * + * @implements{18840078} + */ +typedef enum { + NvSciBufScan_ProgressiveType, + NvSciBufScan_InterlaceType, +} NvSciBufAttrValImageScanType; + +/** + * @brief Defines the image color formats for NvSciBufType_Image. + * + * Color units are composed of sequences of 'words'. + * Words correspond to 8-, 16-, 32-, or 64-bit data types, + * though the specific type depends on the color format. + * + * Words are separated by underscores. + * Example : NvSciColor_U8_V8 + * + * Within a word, color components are ordered from most-significant bit to + * least-significant bit when reading from left to right. + * Example: + * Bit ordering for little endian machine is as follows + * for NvSciColor_V10U10 + * pattern VVVVVVVV VV****** UUUUUUUU UU****** + * +------+ +------+ +------+ +------+ + * bit 31 24 23 16 15 8 7 0 + * +---------------------------------+ + * pixel 0 + * + * Exceptions: + * 1. NvSciColor_Y8U8Y8V8, NvSciColor_Y8V8Y8U8, NvSciColor_U8Y8V8Y8, NvSciColor_V8Y8U8Y8 follow different component order. + * NvSciColor_U8Y8V8Y8 is equavalent to 2 words with Y unique and U/V shared between the words. + * NvSciColor_U8Y8V8Y8 : word 0 = NvSciColor_U8_Y8, word 1 = NvSciColor_V8_Y8 + * + * '*' means undefined bit value + * + * + * NV12 : YUV420 semi-planar surface with U component occupying Least Significant Bit(s) + * NV21 : YUV420 semi-planar surface with V component occupying Least Significant Bit(s) + * NV16 : YUV422 semi-planar surface with U component occupying Least Significant Bit(s) + * NV61 : YUV422 semi-planar surface with V component occupying Least Significant Bit(s) + * YV12 : YUV420 full planar surface with plane 0 = Y component, plane 1 = U component, plane 2 = V component + * YV16 : YUV422 full planar surface with plane 0 = Y component, plane 1 = U component, plane 2 = V component + * YV24 : YUV444 full planar surface with plane 0 = Y component, plane 1 = U component, plane 2 = V component + * + * + * @implements{18840081} + */ +typedef enum { + NvSciColor_LowerBound, + /* RAW PACKED */ + /* Bit ordering for little endian machine is as follows + * for NvSciColor_X12Bayer20GBRG + * pattern BBBBBBBB BBBBBBBB BBBB**** ******** GGGGGGGG GGGGGGGG GGGG**** ******** + * +------+ +------+ +------+ +------+ +------+ +------+ +------+ +------+ + * bit 63 56 55 48 47 40 39 32 31 24 23 16 15 8 7 0 + * +---------------------------------+ +---------------------------------+ + * pixel 1 0 + * +---------------------------------------------------------------------+ + * pitch 0 + * + * pattern GGGGGGGG GGGGGGGG GGGG**** ******** RRRRRRRR RRRRRRRR RRRR**** ******** + * +------+ +------+ +------+ +------+ +------+ +------+ +------+ +------+ + * bit 63 56 55 48 47 40 39 32 31 24 23 16 15 8 7 0 + * +---------------------------------+ +---------------------------------+ + * pixel 1 0 + * +---------------------------------------------------------------------+ + * pitch 1 + * + * '*' means undefined bit value + */ + NvSciColor_Bayer8RGGB, + NvSciColor_Bayer8CCCC, + NvSciColor_Bayer8BGGR, + NvSciColor_Bayer8GBRG, + NvSciColor_Bayer8GRBG, + NvSciColor_Bayer16BGGR, + NvSciColor_Bayer16CCCC, + NvSciColor_Bayer16GBRG, + NvSciColor_Bayer16GRBG, + NvSciColor_Bayer16RGGB, + NvSciColor_Bayer16RCCB, + NvSciColor_Bayer16BCCR, + NvSciColor_Bayer16CRBC, + NvSciColor_Bayer16CBRC, + NvSciColor_Bayer16RCCC, + NvSciColor_Bayer16CCCR, + NvSciColor_Bayer16CRCC, + NvSciColor_Bayer16CCRC, + NvSciColor_X2Bayer14GBRG, + NvSciColor_X4Bayer12GBRG, + NvSciColor_X6Bayer10GBRG, + NvSciColor_X2Bayer14GRBG, + NvSciColor_X4Bayer12GRBG, + NvSciColor_X6Bayer10GRBG, + NvSciColor_X2Bayer14BGGR, + NvSciColor_X4Bayer12BGGR, + NvSciColor_X6Bayer10BGGR, + NvSciColor_X2Bayer14RGGB, + NvSciColor_X4Bayer12RGGB, + NvSciColor_X6Bayer10RGGB, + NvSciColor_X2Bayer14CCCC, + NvSciColor_X4Bayer12CCCC, + NvSciColor_X6Bayer10CCCC, + NvSciColor_X4Bayer12RCCB, + NvSciColor_X4Bayer12BCCR, + NvSciColor_X4Bayer12CRBC, + NvSciColor_X4Bayer12CBRC, + NvSciColor_X4Bayer12RCCC, + NvSciColor_X4Bayer12CCCR, + NvSciColor_X4Bayer12CRCC, + NvSciColor_X4Bayer12CCRC, + NvSciColor_Signed_X2Bayer14CCCC, + NvSciColor_Signed_X4Bayer12CCCC, + NvSciColor_Signed_X6Bayer10CCCC, + NvSciColor_Signed_Bayer16CCCC, + NvSciColor_FloatISP_Bayer16CCCC, + NvSciColor_FloatISP_Bayer16RGGB, + NvSciColor_FloatISP_Bayer16BGGR, + NvSciColor_FloatISP_Bayer16GRBG, + NvSciColor_FloatISP_Bayer16GBRG, + NvSciColor_FloatISP_Bayer16RCCB, + NvSciColor_FloatISP_Bayer16BCCR, + NvSciColor_FloatISP_Bayer16CRBC, + NvSciColor_FloatISP_Bayer16CBRC, + NvSciColor_FloatISP_Bayer16RCCC, + NvSciColor_FloatISP_Bayer16CCCR, + NvSciColor_FloatISP_Bayer16CRCC, + NvSciColor_FloatISP_Bayer16CCRC, + NvSciColor_X12Bayer20CCCC, + NvSciColor_X12Bayer20BGGR, + NvSciColor_X12Bayer20RGGB, + NvSciColor_X12Bayer20GRBG, + NvSciColor_X12Bayer20GBRG, + NvSciColor_X12Bayer20RCCB, + NvSciColor_X12Bayer20BCCR, + NvSciColor_X12Bayer20CRBC, + NvSciColor_X12Bayer20CBRC, + NvSciColor_X12Bayer20RCCC, + NvSciColor_X12Bayer20CCCR, + NvSciColor_X12Bayer20CRCC, + NvSciColor_X12Bayer20CCRC, + NvSciColor_Signed_X12Bayer20CCCC, + /* + * Note: This is currently not supported, and setting this attribute key + * will fail. + */ + NvSciColor_Signed_X12Bayer20GBRG, + + /* Semiplanar formats */ + /* Bit ordering for little endian machine is as follows + * for NvSciColor_V8U8 + * pattern VVVVVVVV UUUUUUUU + * +------+ +------+ + * bit 15 8 7 0 + * +---------------+ + * pixel 0 + * + * for NvSciColor_U8_V8 + * pattern VVVVVVVV UUUUUUUU + * +------+ +------+ + * bit 15 8 7 0 + * +---------------+ + * pixel 0 + * + * for NvSciColor_V10U10 + * pattern VVVVVVVV VV****** UUUUUUUU UU****** + * +------+ +------+ +------+ +------+ + * bit 31 24 23 16 15 8 7 0 + * +---------------------------------+ + * pixel 0 + * + * '*' means undefined bit value + */ + NvSciColor_U8V8, + /** Note : NvSciColor_U8_V8 will be deprecated in future release. + * NvSciColor_V8U8 color format should be used as a replacement. + * NvSciColor_U8_V8 and NvSciColor_V8U8 have same bit ordering. + */ + NvSciColor_U8_V8, + NvSciColor_V8U8, + /** Note : NvSciColor_V8_U8 will be deprecated in future release. + * NvSciColor_U8V8 color format should be used as a replacement. + * NvSciColor_V8_U8 and NvSciColor_U8V8 have same bit ordering. + */ + NvSciColor_V8_U8, + NvSciColor_U10V10, + NvSciColor_V10U10, + NvSciColor_U12V12, + NvSciColor_V12U12, + NvSciColor_U16V16, + NvSciColor_V16U16, + + /* PLANAR formats */ + /* Bit ordering for little endian machine is as follows + * for NvSciColor_Y12 + * pattern YYYYYYYY YYYY**** + * +------+ +------+ + * bit 15 8 7 0 + * +---------------+ + * pixel 0 + * '*' means undefined bit value + */ + NvSciColor_Y8, + NvSciColor_Y10, + NvSciColor_Y12, + NvSciColor_Y16, + NvSciColor_U8, + NvSciColor_V8, + NvSciColor_U10, + NvSciColor_V10, + NvSciColor_U12, + NvSciColor_V12, + NvSciColor_U16, + NvSciColor_V16, + + /* Packed YUV formats */ + /* NvSciColor_Y8U8Y8V8, NvSciColor_Y8V8Y8U8, NvSciColor_U8Y8V8Y8, NvSciColor_V8Y8U8Y8 follow + * different component order than generic word representation. + * + * Bit ordering for little endian machine is as follows + * for NvSciColor_U8Y8V8Y8 + * pattern YYYYYYYY VVVVVVVV YYYYYYYY UUUUUUUU + * +------+ +------+ +------+ +------+ + * bit 31 24 23 16 15 8 7 0 + * +---------------------------------+ + * pixel 0 + * + * for NvSciColor_A16Y16U16V16 + * pattern AAAAAAAAAAAAAAAA YYYYYYYYYYYYYYYY UUUUUUUUUUUUUUUU VVVVVVVVVVVVVVVV + * +--------------+ +--------------+ +--------------+ +--------------+ + * bit 63 48 47 32 31 16 15 0 + * +-----------------------------------------------------------------+ + * pixel 0 + * + */ + NvSciColor_A8Y8U8V8, + NvSciColor_Y8U8Y8V8, + NvSciColor_Y8V8Y8U8, + NvSciColor_U8Y8V8Y8, + NvSciColor_V8Y8U8Y8, + NvSciColor_A16Y16U16V16, + + /* RGBA PACKED */ + /* Bit ordering for little endian machine is as follows + * for NvSciColor_A2R10G10B10 + * pattern AARRRRRR RRRRGGGG GGGGGGBB BBBBBBBB + * +------+ +------+ +------+ +------+ + * bit 31 24 23 16 15 8 7 0 + * +---------------------------------+ + * pixel 0 + * + */ + NvSciColor_A8, + NvSciColor_Signed_A8, + NvSciColor_B8G8R8A8, + NvSciColor_A8R8G8B8, + NvSciColor_A8B8G8R8, + NvSciColor_A2R10G10B10, + NvSciColor_A16, + NvSciColor_Signed_A16, + NvSciColor_Signed_R16G16, + NvSciColor_A16B16G16R16, + NvSciColor_Signed_A16B16G16R16, + NvSciColor_Float_A16B16G16R16, + NvSciColor_A32, + NvSciColor_Signed_A32, + NvSciColor_Float_A16, + + /* 10-bit 4x4 RGB-IR Bayer formats */ + /* Bit ordering for little endian machine is as follows + * for NvSciColor_X6Bayer10BGGI_RGGI + * pattern GGGGGGGG GG****** RRRRRRRR RR****** GGGGGGGG GG****** BBBBBBBB BB****** + * +------+ +------+ +------+ +------+ +------+ +------+ +------+ +------+ + * bit 63 56 55 48 47 40 39 32 31 24 23 16 15 8 7 0 + * +---------------+ +---------------+ +---------------+ +---------------+ + * pixel 3 2 1 0 + * +---------------------------------------------------------------------+ + * pitch 0 + * + * pattern IIIIIIII II****** GGGGGGGG GG****** IIIIIIII II****** GGGGGGGG GG****** + * +------+ +------+ +------+ +------+ +------+ +------+ +------+ +------+ + * bit 63 56 55 48 47 40 39 32 31 24 23 16 15 8 7 0 + * +---------------+ +---------------+ +---------------+ +---------------+ + * pixel 3 2 1 0 + * +---------------------------------------------------------------------+ + * pitch 1 + * + * pattern GGGGGGGG GG****** BBBBBBBB BB****** GGGGGGGG GG****** RRRRRRRR RR****** + * +------+ +------+ +------+ +------+ +------+ +------+ +------+ +------+ + * bit 63 56 55 48 47 40 39 32 31 24 23 16 15 8 7 0 + * +---------------+ +---------------+ +---------------+ +---------------+ + * pixel 3 2 1 0 + * +---------------------------------------------------------------------+ + * pitch 2 + * + * pattern IIIIIIII II****** GGGGGGGG GG****** IIIIIIII II****** GGGGGGGG GG****** + * +------+ +------+ +------+ +------+ +------+ +------+ +------+ +------+ + * bit 63 56 55 48 47 40 39 32 31 24 23 16 15 8 7 0 + * +---------------+ +---------------+ +---------------+ +---------------+ + * pixel 3 2 1 0 + * +---------------------------------------------------------------------+ + * pitch 3 + * + * '*' means undefined bit value + */ + NvSciColor_X6Bayer10BGGI_RGGI, + NvSciColor_X6Bayer10GBIG_GRIG, + NvSciColor_X6Bayer10GIBG_GIRG, + NvSciColor_X6Bayer10IGGB_IGGR, + NvSciColor_X6Bayer10RGGI_BGGI, + NvSciColor_X6Bayer10GRIG_GBIG, + NvSciColor_X6Bayer10GIRG_GIBG, + NvSciColor_X6Bayer10IGGR_IGGB, + + /* 12-bit 4x4 RGB-IR Bayer formats */ + NvSciColor_X4Bayer12BGGI_RGGI, + NvSciColor_X4Bayer12GBIG_GRIG, + NvSciColor_X4Bayer12GIBG_GIRG, + NvSciColor_X4Bayer12IGGB_IGGR, + NvSciColor_X4Bayer12RGGI_BGGI, + NvSciColor_X4Bayer12GRIG_GBIG, + NvSciColor_X4Bayer12GIRG_GIBG, + NvSciColor_X4Bayer12IGGR_IGGB, + + /* 14-bit 4x4 RGB-IR Bayer formats */ + NvSciColor_X2Bayer14BGGI_RGGI, + NvSciColor_X2Bayer14GBIG_GRIG, + NvSciColor_X2Bayer14GIBG_GIRG, + NvSciColor_X2Bayer14IGGB_IGGR, + NvSciColor_X2Bayer14RGGI_BGGI, + NvSciColor_X2Bayer14GRIG_GBIG, + NvSciColor_X2Bayer14GIRG_GIBG, + NvSciColor_X2Bayer14IGGR_IGGB, + + /* 16-bit 4x4 RGB-IR Bayer formats */ + NvSciColor_Bayer16BGGI_RGGI, + NvSciColor_Bayer16GBIG_GRIG, + NvSciColor_Bayer16GIBG_GIRG, + NvSciColor_Bayer16IGGB_IGGR, + NvSciColor_Bayer16RGGI_BGGI, + NvSciColor_Bayer16GRIG_GBIG, + NvSciColor_Bayer16GIRG_GIBG, + NvSciColor_Bayer16IGGR_IGGB, + + /* Right-justified Bayer RAW format */ + /* Bit ordering for little endian machine is as follows + * for NvSciColor_X4Bayer12RGGB_RJ + * pattern ****GGGG GGGGGGGG ****RRRR RRRRRRRR + * +------+ +------+ +------+ +------+ + * bit 31 24 23 16 15 8 7 0 + * +---------------+ +---------------+ + * pixel 1 0 + * +---------------------------------+ + * pitch 0 + * + * pattern ****BBBB BBBBBBBB ****GGGG GGGGGGGG + * +------+ +------+ +------+ +------+ + * bit 31 24 23 16 15 8 7 0 + * +---------------+ +---------------+ + * pixel 1 0 + * +---------------------------------+ + * pitch 1 + * + * '*' means undefined bit value + */ + NvSciColor_X4Bayer12RGGB_RJ, + + /* RGB PLANAR */ + NvSciColor_R8, + NvSciColor_G8, + NvSciColor_B8, + + NvSciColor_UpperBound +} NvSciBufAttrValColorFmt; + +/** + * @brief Defines the image color standard for NvSciBufType_Image. + * + * @implements{18840084} + */ +typedef enum { + NvSciColorStd_SRGB, + NvSciColorStd_REC601_SR, + NvSciColorStd_REC601_ER, + NvSciColorStd_REC709_SR, + NvSciColorStd_REC709_ER, + NvSciColorStd_REC2020_RGB, + NvSciColorStd_REC2020_SR, + NvSciColorStd_REC2020_ER, + NvSciColorStd_YcCbcCrc_SR, + NvSciColorStd_YcCbcCrc_ER, + NvSciColorStd_SENSOR_RGBA, + NvSciColorStd_REQ2020PQ_ER, +} NvSciBufAttrValColorStd; + +/** + * @brief Surface types + * + * @implements{} + */ +typedef enum { + /** YUV surface */ + NvSciSurfType_YUV, + /** + * RGBA surface + * + * Note: This is currently not supported, and setting this attribute key + * will fail. + */ + NvSciSurfType_RGBA, + /** + * RAW surface + * + * Note: This is currently not supported, and setting this attribute key + * will fail. + */ + NvSciSurfType_RAW, + NvSciSurfType_MaxValid, +} NvSciBufSurfType; + +/** + * @brief Memory type + * + * @implements{} + */ +typedef enum { + /** + * Packed format + * + * Note: Reconciliation of packed types is supported only for YUV formats (YUV 400). + */ + NvSciSurfMemLayout_Packed, + /** + * Semi-planar format + */ + NvSciSurfMemLayout_SemiPlanar, + /** + * Planar format + */ + NvSciSurfMemLayout_Planar, + NvSciSurfMemLayout_MaxValid, +} NvSciBufSurfMemLayout; + +/** + * @brief Subsampling type + * + * @implements{} + */ +typedef enum { + /** 4:2:0 subsampling */ + NvSciSurfSampleType_420, + /** 4:2:2 subsampling */ + NvSciSurfSampleType_422, + /** 4:4:4 subsampling */ + NvSciSurfSampleType_444, + /** 4:2:2 (transposed) subsampling */ + NvSciSurfSampleType_422R, + /** 4:0:0 subsampling */ + NvSciSurfSampleType_400, + NvSciSurfSampleType_MaxValid, +} NvSciBufSurfSampleType; + +/** + * @brief Bits Per Component + * + * @implements{} + */ +typedef enum { + /** 16:8:8 bits per component layout */ + NvSciSurfBPC_Layout_16_8_8, + /** 10:8:8 bits per component layout */ + NvSciSurfBPC_Layout_10_8_8, + /** 8 bits per component */ + NvSciSurfBPC_8, + /** 10 bits per component */ + NvSciSurfBPC_10, + /** 12 bits per component */ + NvSciSurfBPC_12, + /** 14 bits per component + * + * Note: This is aliased to behave the same way as NvSciSurfBPC_16 to + * represent hardware where 2 bits are unused. */ + NvSciSurfBPC_14, + /** 16 bits per component */ + NvSciSurfBPC_16, + NvSciSurfBPC_MaxValid, +} NvSciBufSurfBPC; + +/** + * @brief Component ordering + * + * @implements{} + */ +typedef enum { + /** YUV component order */ + NvSciSurfComponentOrder_YUV, + /** YVU component order */ + NvSciSurfComponentOrder_YVU, + /** Luma-only ordering */ + NvSciSurfComponentOrder_Luma, + NvSciSurfComponentOrder_MaxValid, +} NvSciBufSurfComponentOrder; + +/** + * @brief Defines various numeric datatypes for NvSciBuf. + * + * @implements{18840087} + */ +typedef enum { + NvSciDataType_Int4, + NvSciDataType_Uint4, + NvSciDataType_Int8, + NvSciDataType_Uint8, + NvSciDataType_Int16, + NvSciDataType_Uint16, + NvSciDataType_Int32, + NvSciDataType_Uint32, + NvSciDataType_Float16, + NvSciDataType_Float32, + NvSciDataType_FloatISP, + NvSciDataType_Bool, + NvSciDataType_UpperBound +} NvSciBufAttrValDataType; + +/** + * @brief an enum spcifying various GPU compression values supported by NvSciBuf + */ +typedef enum { + /** + * Default value spcifying that GPU compression defaults to incompressible + * kind. NvSciBuf fills this value in the reconciled NvSciBufAttrList if + * the GPU compression is not granted for the particular GPU. + * If compression is not needed, user does not have to explicitly + * specify this value in the unreconciled NvSciBufAttrList. NvSciBuf does + * not allow setting this value in the unreconciled NvSciBufAttrList. + * Attempting to do so results in NvSciBufAttrListSetAttrs() returning an + * error. + */ + NvSciBufCompressionType_None, + + /** + * Enum to request all possible GPU compression including enabling PLC (Post + * L-2 Compression). + * CUDA can read/write the GPU compressible memory with PLC enabled. + * Vulkan can also read/write the GPU compressible memory with PLC + * enabled. + * This compression can be requested in CUDA to CUDA, CUDA to Vulkan and + * Vulkan to Vulkan interop use-cases. + */ + NvSciBufCompressionType_GenericCompressible, +} NvSciBufCompressionType; + +/** + * @brief Defines GPU ID structure. This structure is used to + * set the value for NvSciBufGeneralAttrKey_GpuId attribute. + * + * @implements{18840093} + */ +typedef struct { + /** GPU ID. This member is initialized by the successful + * call to cuDeviceGetUuid() for CUDA usecases */ + uint8_t bytes[16]; +} NvSciRmGpuId; + +/** + * Datatype specifying GPU cacheability preference for a particular GPU ID. + * + * @implements{} + */ +typedef struct { + /** + * GPU ID for which cache preference need to be specified + */ + NvSciRmGpuId gpuId; + + /** + * boolean value specifying cacheability preference. TRUE implies caching + * needs to be enabled, FALSE indicates otherwise. + */ + bool cacheability; +} NvSciBufAttrValGpuCache; + +/** + * @brief Datatype specifying compression type needed for a particular GPU ID. + */ +typedef struct { + /** + * GPU ID for which compression needs to be specified + */ + NvSciRmGpuId gpuId; + + /** + * Type of compression + */ + NvSciBufCompressionType compressionType; +} NvSciBufAttrValGpuCompression; + +/** + * @brief Datatype specifying the surface co-ordinates for + * @ref NvSciBufObjGetPixels / @ref NvSciBufObjPutPixels functionality. + * The first pixel in the user-provided plane will be equal to the first pixel + * represented in the region specified by the NvSciBufRect. + */ +typedef struct { + /** Left X co-ordinate. Inclusive. */ + uint64_t x0; + /** Top Y co-ordinate. Inclusive. */ + uint64_t y0; + /** Right X co-ordinate. Exclusive. */ + uint64_t x1; + /** Bottom Y co-ordinate. Exclusive. */ + uint64_t y1; +} NvSciBufRect; + +/** + * @brief Enum to identify hardware engines + * + * @implements{18840123} + */ +typedef enum { + NvSciBufHwEngName_Invalid = 0, + NvSciBufHwEngName_Display = 4, + NvSciBufHwEngName_Isp = 11, + NvSciBufHwEngName_Vi = 12, + NvSciBufHwEngName_Csi = 30, + NvSciBufHwEngName_Vic = 106, + NvSciBufHwEngName_Gpu = 107, + NvSciBufHwEngName_MSENC = 109, + NvSciBufHwEngName_NVDEC = 117, + NvSciBufHwEngName_NVJPG = 118, + NvSciBufHwEngName_PVA = 121, + NvSciBufHwEngName_DLA = 122, + NvSciBufHwEngName_PCIe = 123, + NvSciBufHwEngName_OFA = 124, + NvSciBufHwEngName_NPM = 125, + NvSciBufHwEngName_Num = 126 +} NvSciBufHwEngName; + +/** + * @brief Enum to identify the platform on which late attaching peer(s) is + * running. + */ +typedef enum { + NvSciBufPlatformName_LowerBound, + /** Late attaching peer(s) runs on DRIVEOS Orin platform **/ + NvSciBufPlatformName_Orin, + /** Late attaching peer(s) runs on x86 PG189 platform **/ + NvSciBufPlatformName_PG189, + /** Late attaching peer(s) runs on x86 PG199 platform **/ + NvSciBufPlatformName_PG199, + NvSciBufPlatformName_UpperBound +} NvSciBufPlatformName; + +/** + * @brief Datatype specifying hardware engines which will access NvSciBufObj by + * late attaching peer(s). + */ +PACK_BUF(typedef struct { + /** Hardware engine identifier which will access the buffer from late + * attaching peer(s). + */ + NvSciBufHwEngName engName; + /** Platform identifier which will access the buffer from late attaching + * peer(s). + */ + NvSciBufPlatformName platName; +}) NvSciBufPeerHwEngine; + +/** + * @} + */ + +/** + * @defgroup nvscibuf_attr_datastructures NvSciBuf Data Structures + * Specifies NvSciBuf data structures. + * @{ + */ + +/** + * @brief top-level container for the following set of + * resources: NvSciBufAttrLists, memory objects, and NvSciBufObjs. + * Any @ref NvSciBufAttrList created or imported using a particular @ref NvSciBufModule + * is bound to it, along with any @ref NvSciBufObj created or + * imported using those NvSciBufAttrList(s). + * + * @note For any NvSciBuf API call that has more than one input of type + * NvSciBufModule, NvSciBufAttrList, and/or NvSciBufObj, all such inputs + * must agree on the NvSciBufModule instance. + */ +typedef struct NvSciBufModuleRec* NvSciBufModule; + +/** + * @brief This structure defines a key/value pair used to get or set + * the NvSciBufAttrKey(s) and their corresponding values from or to + * NvSciBufAttrList. + * + * @note An array of this structure need to be set in order to + * allocate a buffer. + * + * @implements{18840090} + */ +typedef struct { + /** NvSciBufAttrKey for which value needs to be set/retrieved. This member + * is initialized to any one of the NvSciBufAttrKey other than + * NvSciBufAttrKey_LowerBound and NvSciBufAttrKey_UpperBound */ + NvSciBufAttrKey key; + + /** Pointer to the value corresponding to the attribute. + * If the value is an array, the pointer points to the first element. */ + const void* value; + + /** Length of the value in bytes */ + size_t len; +} NvSciBufAttrKeyValuePair; + +/** + * A memory object is a container holding the reconciled NvSciBufAttrList + * defining constraints of the buffer, the handle of the allocated buffer + * enforcing the buffer access permissions represented by + * NvSciBufGeneralAttrKey_ActualPerm key in reconciled NvSciBufAttrList + * and the buffer properties. + */ + +/** + * @brief A reference to a particular Memory object. + * + * @note Every @ref NvSciBufObj that has been created but not freed + * holds a reference to the @ref NvSciBufModule, preventing it + * from being de-initialized. + */ +typedef struct NvSciBufObjRefRec* NvSciBufObj; + +/** + * @brief A reference, that is not modifiable, to a particular Memory Object. + */ +typedef const struct NvSciBufObjRefRec* NvSciBufObjConst; + + +/** + * @brief A container constituting an attribute list which contains + * - set of NvSciBufAttrKey attributes defining buffer constraints + * - slotcount defining number of slots in an attribute list + * - flag specifying if attribute list is reconciled or unreconciled + * + * @note Every @ref NvSciBufAttrList that has been created but not freed + * holds a reference to the @ref NvSciBufModule, preventing it + * from being de-initialized. + */ +typedef struct NvSciBufAttrListRec* NvSciBufAttrList; + +/** + * @brief Defines the exported form of NvSciBufObj intended to be + * shared across an NvSciIpc channel. On successful execution of the + * NvSciBufObjIpcExport(), the permission requested via this API is stored + * in the NvSciBufObjIpcExportDescriptor to be granted to the NvSciBufObj + * on import provided the permission requested via the API is not + * NvSciBufAccessPerm_Auto. If the NvSciBufAccessPerm_Auto permission is + * requested via the API then the permission stored in the + * NvSciBufObjIpcExportDescriptor is equal to the maximum value of the + * permissions requested via NvSciBufGeneralAttrKey_RequiredPerm attribute in + * all of the unreconciled NvSciBufAttrLists that were exported by the peer to + * which the NvSciBufObjIpcExportDescriptor is being exported. + * + * @implements{18840114} + */ +PACK_BUF(typedef struct { + /** Exported data (blob) for NvSciBufObj */ + uint64_t data[NVSCIBUF_EXPORT_DESC_SIZE]; +}) NvSciBufObjIpcExportDescriptor; + +/** @brief Defines Peer location info structure. This structure is used + * to set location information of late attaching peer to NvScibufObj using + * NvSciBufObjAttachPeer() API + * + * @implements{} + */ +PACK_BUF(typedef struct { + /** ID of peer SoC, as configured during bind_partition */ + uint32_t socID; + /** ID of peer guest VM as mentioned in PCT config */ + uint32_t vmID; + /** Reserved, do not use */ + uint64_t reserved; +}) NvSciBufPeerLocationInfo; + +/** + * @} + */ + +/** + * @defgroup nvscibuf_attr_list_api NvSciBuf Attribute List APIs + * Methods to perform operations on NvSciBuf attribute lists. + * @{ + */ + +/** + * @brief Creates a new, single slot, unreconciled NvSciBufAttrList associated + * with the input NvSciBufModule with empty NvSciBufAttrKeys. + * + * @param[in] module NvSciBufModule to associate with the newly + * created NvSciBufAttrList. + * @param[out] newAttrList The new NvSciBufAttrList. + * + * @return ::NvSciError, the completion status of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a module is NULL + * - @a newAttrList is NULL + * - ::NvSciError_InsufficientMemory if insufficient system memory to + * create a NvSciBufAttrList. + * - ::NvSciError_InvalidState if a new NvSciBufAttrList cannot be associated + * with the given NvSciBufModule. + * - ::NvSciError_ResourceError if system lacks resource other than memory. + * - panics if @a module is invalid. + * + * @pre + * - Valid NvSciBufModule is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufAttrListCreate( + NvSciBufModule module, + NvSciBufAttrList* newAttrList); + +/** + * @brief Frees the NvSciBufAttrList and removes its association with the + * NvSciBufModule with which it was created. + * + * @note Every owner of the NvSciBufAttrList shall call NvSciBufAttrListFree() + * only after all the functions invoked by the owner with NvSciBufAttrList as + * an input are completed. + * + * @param[in] attrList The NvSciBufAttrList to be freed. + * + * @return void + * - Panics if: + * - NvSciBufAttrList is invalid. + * - if Init Mode API is called in Runtime Mode. + * + * @pre + * - Valid NvSciBufAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the input + * NvSciBufAttrList @a attrList + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +void NvSciBufAttrListFree( + NvSciBufAttrList attrList); + +/** + * @brief Sets the values for NvSciBufAttrKey(s) in the NvSciBufAttrList. + * It only reads values from NvSciBufAttrKeyValuePair array and + * saves copies during this call. + * + * @note All combinations of NvSciBufAttrListSetAttrs(), + * NvSciBufAttrListGetAttrs(), NvSciBufAttrListAppendUnreconciled() + * and NvSciBufAttrListReconcile() can be called concurrently, + * however, function completion order is not guaranteed by NvSciBuf + * and thus outcome of calling these functions concurrently is + * undefined. + * + * @param[in] attrList Unreconciled NvSciBufAttrList. + * @param[in] pairArray Array of NvSciBufAttrKeyValuePair structures. + * Valid value: pairArray is valid input if it is not NULL and + * key member of every NvSciBufAttrKeyValuePair in the array is a valid enumeration + * value defined by the NvSciBufAttrKey enum and value member of every + * NvSciBufAttrKeyValuePair in the array is not NULL. + * @param[in] pairCount Number of elements/entries in @a pairArray. + * Valid value: pairCount is valid input if it is non-zero. + * + * @return ::NvSciError, the completion status of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a attrList is NULL + * - @a attrList is reconciled + * - @a attrList is an unreconciled NvSciBufAttrList obtained from + * NvSciBufAttrListAppendUnreconciled or + * NvSciBufAttrListIpcImportUnreconciled + * - @a pairArray is NULL + * - @a pairCount is 0 + * - any of the NvSciBufAttrKey(s) specified in the NvSciBufAttrKeyValuePair + * array is output only + * - any of the NvSciBufAttrKey(s) specified in the NvSciBufAttrKeyValuePair + * array has already been set + * - the NvSciBufGeneralAttrKey_Types key set (or currently being set) on + * @a attrList does not contain the NvSciBufType of the datatype + * NvSciBufAttrKey(s) + * - any of the NvSciBufAttrKey(s) specified in the NvSciBufAttrKeyValuePair + * array occurs more than once + * - any of the NvSciBufAttrKey(s) specified in @a pairArray is not a + * valid enumeration value defined by the NvSciBufAttrKey enum + * - length(s) set for NvSciBufAttrKey(s) in @a pairArray are invalid + * - value(s) set for NvSciBufAttrKey(s) in @a pairArray are invalid + * - ::NvSciError_InsufficientMemory if not enough system memory. + * - Panics if any of the following occurs: + * - @a attrList is not valid + * + * @pre + * - Valid unreconciled NvSciBufAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufAttrListSetAttrs( + NvSciBufAttrList attrList, + NvSciBufAttrKeyValuePair* pairArray, + size_t pairCount); + +/** + * @brief Returns the slot count per NvSciBufAttrKey in a NvSciBufAttrList. + * + * @param[in] attrList The NvSciBufAttrList to retrieve the slot count from. + * + * @return size_t + * - Number of slots in the NvSciBufAttrList + * - panics if: + * - @a attrList is invalid + * + * @pre + * - Valid NvSciBufAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +size_t NvSciBufAttrListGetSlotCount( + NvSciBufAttrList attrList); + +/** + * @brief Returns an array of NvSciBufAttrKeyValuePair for a given set of NvSciBufAttrKey(s). + * This function accepts a set of NvSciBufAttrKey(s) passed in the @ref NvSciBufAttrKeyValuePair + * structure. The return values, stored back into @ref NvSciBufAttrKeyValuePair, consist of + * @c const @c void* pointers to the attribute values from the @ref NvSciBufAttrList. + * The application must not write to this data. + * + * @param[in] attrList NvSciBufAttrList to fetch the NvSciBufAttrKeyValuePair(s) from. + * @param[in,out] pairArray Array of NvSciBufAttrKeyValuePair. + * Valid value: pairArray is valid input if it is not NULL and key member + * of every NvSciBufAttrKeyValuePair in the array is a valid enumeration value + * defined by the NvSciBufAttrKey enum. + * @param[in] pairCount Number of elements/entries in @a pairArray. + * Valid value: pairCount is valid input if it is non-zero. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a attrList is NULL + * - @a pairArray is NULL + * - @a pairCount is 0 + * - any of the NvSciBufAttrKey(s) in @a pairArray is not a valid + * enumeration value defined by the NvSciBufAttrKey enum + * - @a attrList is reconciled and any of the NvSciBufAttrKey(s) specified + * in NvSciBufAttrKeyValuePair is input only + * - @a attrList is unreconciled and any of the NvSciBufAttrKey(s) + * specified in NvSciBufAttrKeyValuePair is output only + * - Panics if any of the following occurs: + * - @a attrList is invalid + * + * @pre + * - Valid NvSciBufAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciBufAttrListGetAttrs( + NvSciBufAttrList attrList, + NvSciBufAttrKeyValuePair* pairArray, + size_t pairCount); + +/** + * @brief Returns an array of NvSciBufAttrKeyValuePair(s) from input + * NvSciBufAttrList at the given slot index. The return values, stored in @ref + * NvSciBufAttrKeyValuePair, consist of @c const @c void* pointers to the attribute values + * from the NvSciBufAttrList. The application must not write to this data. + * + * @note When exporting an array containing multiple unreconciled NvSciBufAttrList(s), + * the importing endpoint still imports just one unreconciled NvSciBufAttrList. + * This unreconciled NvSciBufAttrList is referred to as a multi-slot + * NvSciBufAttrList. It logically represents an array of NvSciBufAttrList(s), where + * each key has an array of values, one per slot. + * + * @param[in] attrList NvSciBufAttrList to fetch the NvSciBufAttrKeyValuePair(s) from. + * @param[in] slotIndex Index in the NvSciBufAttrList. + * Valid value: 0 to slot count of NvSciBufAttrList - 1. + * @param[in,out] pairArray Array of NvSciBufAttrKeyValuePair. Holds the NvSciBufAttrKey(s) + * passed into the function and returns an array of NvSciBufAttrKeyValuePair structures. + * Valid value: pairArray is valid input if it is not NULL and key member + * of every NvSciBufAttrKeyValuePair is a valid enumeration value defined by the + * NvSciBufAttrKey enum + * @param[in] pairCount Number of elements/entries in pairArray. + * Valid value: pairCount is valid input if it is non-zero. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a attrList is NULL + * - @a pairArray is NULL + * - any of the NvSciBufAttrKey(s) in @a pairArray is not a valid + * enumeration value defined by the NvSciBufAttrKey enum + * - @a pairCount is 0 + * - @a slotIndex >= slot count of NvSciBufAttrList + * - NvSciBufAttrKey specified in @a pairArray is invalid. + * - @a attrList is reconciled and any of the NvSciBufAttrKey(s) specified + * in NvSciBufAttrKeyValuePair is input only + * - @a attrList is unreconciled and any of the NvSciBufAttrKey(s) + * specified in NvSciBufAttrKeyValuePair is output only + * - Panics if any of the following occurs: + * - @a attrList is invalid + * + * @pre + * - Valid NvSciBufAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciBufAttrListSlotGetAttrs( + NvSciBufAttrList attrList, + size_t slotIndex, + NvSciBufAttrKeyValuePair* pairArray, + size_t pairCount); + +#if (NV_IS_SAFETY == 0) +/** + * @brief Allocates a buffer and then dumps the contents of the specified + * attribute list into the buffer. + * + * @param[in] attrList Attribute list to fetch contents from. + * @param[out] buf A pointer to the buffer allocated for the debug dump. + * @param[out] len The length of the buffer allocated for the debug dump. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if @a attrList is invalid. + * + * @note This API is deprecated and will be removed in a future version. This + * prototype is only provided to not break compiliation of older code. Its use + * is not supported. Do not rely on using this API. + * + * @pre + * - Valid unreconciled NvSciBufAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufAttrListDebugDump( + NvSciBufAttrList attrList, + void** buf, + size_t* len); +#endif + +/** + * @brief Reconciles the given unreconciled NvSciBufAttrList(s) into a new + * reconciled NvSciBufAttrList. + * On success, this API call returns reconciled NvSciBufAttrList, which has to + * be freed by the caller using NvSciBufAttrListFree(). + * + * @param[in] inputArray Array containing unreconciled NvSciBufAttrList(s) to be + * reconciled. @a inputArray is valid if it is non-NULL. + * @param[in] inputCount The number of unreconciled NvSciBufAttrList(s) in + * @a inputArray. This value must be non-zero. For a single + * NvSciBufAttrList, the count must be set 1. + * @param[out] newReconciledAttrList Reconciled NvSciBufAttrList. This field + * is populated only if the reconciliation succeeded. + */ +#if (NV_IS_SAFETY == 0) +/** + * @param[out] newConflictList Unreconciled NvSciBufAttrList consisting of the + * key/value pairs which caused the reconciliation failure. This field is + * populated only if the reconciliation failed. + */ +#else +/** + * @param[out] newConflictList unused. + */ +#endif +/** + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a inputArray[] is NULL + * - @a inputCount is 0 + * - @a newReconciledAttrList is NULL + * - any of the NvSciBufAttrList in @a inputArray is reconciled. + * - not all the NvSciBufAttrLists in @a inputArray are bound to the + * same NvSciBufModule. + * - an NvSciBufAttrList appears multiple times in @a inputArray[] + * - an attribute key necessary for reconciling against the given data + * type(s) of the NvSciBufAttrList(s) involved in reconciliation is + * unset + * - an attribute key is set to an unsupported value considering the data + * type(s) of the NvSciBufAttrList(s) involved in reconciliation + */ +#if (NV_IS_SAFETY == 0) +/** - @a newConflictList is NULL + */ +#endif +/** + * - ::NvSciError_InsufficientMemory if not enough system memory. + * - ::NvSciError_InvalidState if a new NvSciBufAttrList cannot be associated + * with the NvSciBufModule associated with the NvSciBufAttrList(s) in the + * given @a inputArray to create a new reconciled NvSciBufAttrList + * - ::NvSciError_NotSupported if an attribute key is set resulting in a + * combination of given constraints that are not supported + * - ::NvSciError_Overflow if internal integer overflow is detected. + * - ::NvSciError_ReconciliationFailed if reconciliation failed. + * - ::NvSciError_ResourceError if, + * - System lacks resource other than memory. + * - NVIDIA driver stack failed during this operation. + * - Panic if: + * - @a unreconciled NvSciBufAttrList(s) in inputArray is not valid. + * + * @pre + * - Valid unreconciled NvSciBufAttrList(s) are obtained. + + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufAttrListReconcile( + const NvSciBufAttrList inputArray[], + size_t inputCount, + NvSciBufAttrList* newReconciledAttrList, + NvSciBufAttrList* newConflictList); + +/** + * @brief Clones an unreconciled/reconciled NvSciBufAttrList. The resulting + * NvSciBufAttrList contains all the values of the input NvSciBufAttrList. + * If the input NvSciBufAttrList is an unreconciled NvSciBufAttrList, then + * modification to the output NvSciBufAttrList will be allowed using + * NvSciBufAttrListSetAttrs(). + * + * @param[in] origAttrList NvSciBufAttrList to be cloned. + * + * @param[out] newAttrList The new NvSciBufAttrList. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a origAttrList is NULL + * - @a newAttrList is NULL + * - the NvSciBufGeneralAttrKey_Types key is not set on @a origAttrList + * - ::NvSciError_InsufficientMemory if there is insufficient system memory + * to create a new NvSciBufAttrList. + * - ::NvSciError_InvalidState if a new NvSciBufAttrList cannot be associated + * with the NvSciBufModule of @a origAttrList to create the new + * NvSciBufAttrList. + * - ::NvSciError_ResourceError if system lacks resource other than memory. + * - panics if @a origAttrList is invalid + * + * @pre + * - Valid NvSciBufAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufAttrListClone( + NvSciBufAttrList origAttrList, + NvSciBufAttrList* newAttrList); + +/** + * @brief Appends multiple unreconciled NvSciBufAttrList(s) together, forming a + * single new unreconciled NvSciBufAttrList with a slot count equal to the + * sum of all the slot counts of NvSciBufAttrList(s) in the input array and + * containing the contents of all the NvSciBufAttrList(s) in the input array. + * + * @param[in] inputUnreconciledAttrListArray[] Array containing the + * unreconciled NvSciBufAttrList(s) to be appended together. + * Valid value: Array of valid NvSciBufAttrList(s) where the array + * size is at least 1. + * @param[in] inputUnreconciledAttrListCount Number of unreconciled + * NvSciBufAttrList(s) in @a inputUnreconciledAttrListArray. + * Valid value: inputUnreconciledAttrListCount is valid input if it + * is non-zero. + * + * @param[out] newUnreconciledAttrList Appended NvSciBufAttrList. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a inputUnreconciledAttrListArray is NULL + * - @a inputUnreconciledAttrListCount is 0 + * - @a newUnreconciledAttrList is NULL + * - any of the NvSciBufAttrList(s) in @a inputUnreconciledAttrListArray + * is reconciled + * - not all the NvSciBufAttrLists in @a inputUnreconciledAttrListArray + * are bound to the same NvSciBufModule instance. + * - an NvSciBufAttrList appears multiple times in @a inputUnreconciledAttrListArray + * - the NvSciBufGeneralAttrKey_Types key is not set on any of the + * NvSciBufAttrList(s) in @a inputUnreconciledAttrListArray + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_InvalidState if a new NvSciBufAttrList cannot be associated + * with the NvSciBufModule associated with the NvSciBufAttrList(s) in the + * given @a inputUnreconciledAttrListArray to create the new NvSciBufAttrList. + * - ::NvSciError_ResourceError if system lacks resource other than memory. + * - panics if @a any NvSciBufAttrList in the @a + * inputUnreconciledAttrListArray is invalid + * + * @pre + * - Valid unreconciled NvSciBufAttrList(s) are obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufAttrListAppendUnreconciled( + const NvSciBufAttrList inputUnreconciledAttrListArray[], + size_t inputUnreconciledAttrListCount, + NvSciBufAttrList* newUnreconciledAttrList); + +/** + * @brief Checks if the NvSciBufAttrList is reconciled. + * + * @param[in] attrList NvSciBufAttrList to check. + * @param[out] isReconciled boolean value indicating whether the + * @a attrList is reconciled or not. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a attrList is NULL + * - @a isReconciled is NULL + * - panics if @a attrList is invalid + * + * @pre + * - Valid NvSciBufAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufAttrListIsReconciled( + NvSciBufAttrList attrList, + bool* isReconciled); + +/** + * @brief Validates a reconciled NvSciBufAttrList against a set of + * unreconciled NvSciBufAttrList(s). + * + * @param[in] reconciledAttrList Reconciled NvSciBufAttrList list to be + * validated. + * @param[in] unreconciledAttrListArray Set of unreconciled NvSciBufAttrList(s) + * that need to be used for validation. @a unreconciledAttrListArray + * is valid if it is non-NULL. + * @param[in] unreconciledAttrListCount Number of unreconciled + * NvSciBufAttrList(s). This value must be non-zero. + * For a single NvSciBufAttrList, the count must be set to 1. + * @param[out] isReconcileListValid Flag indicating if the reconciled + * NvSciBufAttrList satisfies the constraints of set of + * unreconciled NvSciBufAttrList(s). + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a reconciledAttrList is NULL or + * - @a unreconciledAttrListArray[] is NULL or + * - @a unreconciledAttrListCount is zero or + * - @a isReconcileListValid is NULL + * - any of the NvSciBufAttrList in @a unreconciledAttrListArray is + * reconciled. + * - not all the NvSciBufAttrLists in @a unreconciledAttrListArray are + * bound to the same NvSciBufModule. + * - an NvSciBufAttrList appears multiple times in @a unreconciledAttrListArray + * - ::NvSciError_ReconciliationFailed if validation of reconciled + * NvSciBufAttrList failed against input unreconciled NvSciBufAttrList(s). + * - ::NvSciError_InsufficientMemory if internal memory allocation failed. + * - ::NvSciError_Overflow if internal integer overflow occurs. + * - Panics if: + * - @a unreconciled NvSciBufAttrList(s) in unreconciledAttrListArray + * is invalid. + * - @a reconciledAttrList is not valid. + * + * @pre + * - Valid reconciled NvSciBufAttrList is obtained. + * - Valid unreconciled NvSciBufAttrList(s) are obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufAttrListValidateReconciled( + NvSciBufAttrList reconciledAttrList, + const NvSciBufAttrList unreconciledAttrListArray[], + size_t unreconciledAttrListCount, + bool* isReconcileListValid); + +/** + * @} + */ + +/** + * @defgroup nvscibuf_obj_api NvSciBuf Object APIs + * List of APIs to create/operate on NvSciBufObj. + * @{ + */ + +/** + * @brief Creates a new NvSciBufObj holding reference to the same + * Memory object to which input NvSciBufObj holds the reference. + * + * @note The new NvSciBufObj created with NvSciBufObjDup() has same + * NvSciBufAttrValAccessPerm as the input NvSciBufObj. + * + * @param[in] bufObj NvSciBufObj from which new NvSciBufObj needs + * to be created. + * @param[out] dupObj The new NvSciBufObj. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a bufObj is NULL + * - @a dupObj is NULL + * - ::NvSciError_InsufficientMemory if memory allocation is failed. + * - ::NvSciError_InvalidState if the total number of NvSciBufObjs referencing + * the memory object is INT32_MAX and the caller tries to take one more + * reference using this API. + * - ::NvSciError_ResourceError if system lacks resource other than memory + * - Panics if @a bufObj is invalid. + * + * @pre + * - Valid NvSciBufObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufObjDup( + NvSciBufObj bufObj, + NvSciBufObj* dupObj); + +/** + * @brief Reconciles the input unreconciled NvSciBufAttrList(s) into a new + * reconciled NvSciBufAttrList and allocates NvSciBufObj that meets all the + * constraints in the reconciled NvSciBufAttrList. + * + * @note This interface just combines NvSciBufAttrListReconcile() and + * NvSciBufObjAlloc() interfaces together. + * + * @param[in] attrListArray Array containing unreconciled NvSciBufAttrList(s) to + * reconcile. Valid value: Array of valid unreconciled NvSciBufAttrList(s) where + * array size is at least 1. + * @param[in] attrListCount The number of unreconciled NvSciBufAttrList(s) in + * @c attrListArray. Valid value: 1 to SIZE_MAX. + * + * @param[out] bufObj The new NvSciBufObj. + */ +#if (NV_IS_SAFETY == 0) +/** + * @param[out] newConflictList Unreconciled NvSciBufAttrList consisting of the + * key/value pairs which caused the reconciliation failure. This field is + * populated only if the reconciliation failed. + */ +#else +/** + * @param[out] newConflictList unused. + */ +#endif +/** + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a attrListCount is 0 + * - @a attrListArray is NULL + * - @a bufObj is NULL + * - any of the NvSciBufAttrList in @a attrListArray is reconciled. + * - not all the NvSciBufAttrLists in @a attrListArray are bound to + * the same NvSciBufModule. + * - an NvSciBufAttrList appears multiple times in @a attrListArray + * - an attribute key necessary for reconciling against the given data + * type(s) of the NvSciBufAttrList(s) involved in reconciliation is + * unset + * - an attribute key is set to an unsupported value considering the data + * type(s) of the NvSciBufAttrList(s) involved in reconciliation + */ +#if (NV_IS_SAFETY == 0) +/** + * - @a newConflictList is NULL + */ +#endif +/** + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_InvalidState if a new NvSciBufAttrList cannot be associated + * with the NvSciBufModule associated with the NvSciBufAttrList(s) in the + * given @a attrListArray to create the new NvSciBufAttrList. + * - ::NvSciError_NotSupported if an attribute key is set specifying a + * combination of constraints that are not supported + * - ::NvSciError_Overflow if internal integer overflow is detected. + * - ::NvSciError_ReconciliationFailed if reconciliation failed. + * - ::NvSciError_ResourceError if any of the following occurs: + * - NVIDIA driver stack failed during buffer allocation + * - system lacks resource other than memory + * - Panics if any of the unreconciled NvSciBufAttrLists is invalid. + * + * @pre + * - Valid unreconciled NvSciBufAttrList(s) are obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufAttrListReconcileAndObjAlloc( + const NvSciBufAttrList attrListArray[], + size_t attrListCount, + NvSciBufObj* bufObj, + NvSciBufAttrList* newConflictList); + +/** + * @brief Removes reference to the Memory object by destroying the NvSciBufObj. + * + * @note Every owner of the NvSciBufObj shall call NvSciBufObjFree() + * only after all the functions invoked by the owner with NvSciBufObj + * as an input are completed. + * + * \param[in] bufObj The NvSciBufObj to deallocate. + * + * @return void + * - Panics if: + * - if Init Mode API is called in Runtime Mode. + * - @a bufObj is invalid. + * + * @pre + * - Valid NvSciBufObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the NvSciBufAttrList + * obtained from NvSciBufObjGetAttrList() to be freed, since the + * lifetime of that reconciled NvSciBufAttrList is tied to the + * associated NvSciBufObj + * - Provided there is no active operation involving the NvSciBufObj to be + * freed + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +void NvSciBufObjFree( + NvSciBufObj bufObj); + +/** + * @brief Retrieves the reconciled NvSciBufAttrList whose attributes define + * the constraints of the allocated buffer from the NvSciBufObj. + * + * @note The retrieved NvSciBufAttrList from an NvSciBufObj is read-only, + * and the attribute values in the list cannot be modified using + * set attribute APIs. In addition, the retrieved NvSciBufAttrList must + * not be freed with NvSciBufAttrListFree. + * + * @param[in] bufObj The NvSciBufObj to retrieve the NvSciBufAttrList from. + * @param[out] bufAttrList The retrieved reconciled NvSciBufAttrList. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a bufObj is NULL. + * - @a bufAttrList is NULL. + * - Panics if @a bufObj is invalid. + * + * @pre + * - Valid NvSciBufObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciBufObjGetAttrList( + NvSciBufObj bufObj, + NvSciBufAttrList* bufAttrList); + +/** + * @brief Gets the CPU virtual address (VA) of the read/write buffer + * referenced by the NvSciBufObj. + * + * @note This interface can be called successfully only if NvSciBufObj + * was obtained from successful call to NvSciBufObjAlloc() or + * NvSciBufObj was obtained from successful call to NvSciBufObjIpcImport()/ + * NvSciBufIpcImportAttrListAndObj() where NvSciBufAccessPerm_ReadWrite + * permissions are granted to the imported NvSciBufObj (The permissions + * of the NvSciBufObj are indicated by NvSciBufGeneralAttrKey_ActualPerm + * key in the reconciled NvSciBufAttrList associated with it) and CPU + * access is requested by setting NvSciBufGeneralAttrKey_NeedCpuAccess + * to true. + * + * @param[in] bufObj The NvSciBufObj. + * + * @param[out] ptr The CPU virtual address (VA). + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a bufObj is NULL. + * - @a ptr is NULL. + * - ::NvSciError_BadParameter NvSciBufObj either did not request + * for CPU access by setting NvSciBufGeneralAttrKey_NeedCpuAccess + * to true OR does not have NvSciBufAccessPerm_ReadWrite to the + * buffer. + * - Panics if @a bufObj is invalid. + * + * @pre + * - Valid NvSciBufObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciBufObjGetCpuPtr( + NvSciBufObj bufObj, + void** ptr); + +/** + * @brief Gets the CPU virtual address (VA) of the read-only buffer + * referenced by the NvSciBufObj. + * + * @note This interface can be called successfully only if NvSciBufObj + * was obtained from successful call to NvSciBufObjAlloc() or + * NvSciBufObj was obtained from successful call to NvSciBufObjIpcImport()/ + * NvSciBufIpcImportAttrListAndObj() where at least NvSciBufAccessPerm_Readonly + * permissions are granted to the imported NvSciBufObj (The permissions of the + * NvSciBufObj are indicated by NvSciBufGeneralAttrKey_ActualPerm key in the + * reconciled NvSciBufAttrList associated with it) and CPU access is + * requested by setting NvSciBufGeneralAttrKey_NeedCpuAccess to true. + * + * @param[in] bufObj The NvSciBufObj. + * + * @param[out] ptr the CPU virtual address (VA). + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a bufObj is NULL. + * - @a ptr is NULL. + * - ::NvSciError_BadParameter NvSciBufObj either did not request + * for CPU access by setting NvSciBufGeneralAttrKey_NeedCpuAccess + * to true OR does not have at least NvSciBufAccessPerm_ReadOnly + * permissions to the buffer. + * - Panics if @a bufObj is invalid. + * + * @pre + * - Valid NvSciBufObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciBufObjGetConstCpuPtr( + NvSciBufObj bufObj, + const void** ptr); + +/** + * @brief Flushes the given @c len bytes at starting @c offset in the + * buffer referenced by the NvSciBufObj. Flushing is done only when + * NvSciBufGeneralAttrKey_CpuNeedSwCacheCoherency key is set in + * reconciled NvSciBufAttrList to true. + * + * @param[in] bufObj The NvSciBufObj. + * @param[in] offset The starting offset in memory of the NvSciBufObj. + * Valid value: 0 to buffer size - 1. + * @param[in] len The length (in bytes) to flush. + * Valid value: 1 to buffer size - offset. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a bufObj is NULL + * - @a len is zero + * - @a offset + @a len > buffer size. + * - ::NvSciError_NotPermitted if buffer referenced by @a bufObj is + * not mapped to CPU. + * - ::NvSciError_NotSupported if NvSciBufAllocIfaceType associated with the + * NvSciBufObj is not supported. + * - ::NvSciError_Overflow if @a offset + @a len exceeds UINT64_MAX + * - ::NvSciError_ResourceError if NVIDIA driver stack could not flush the + * CPU cache range. + * - Panics if @a bufObj is invalid. + * + * @pre + * - Valid NvSciBufObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciBufObjFlushCpuCacheRange( + NvSciBufObj bufObj, + uint64_t offset, + uint64_t len); + +/** + * @brief Allocates a buffer that satisfies all the constraints defined by + * the attributes of the specified reconciled NvSciBufAttrList, and outputs + * a new NvSciBufObj referencing the Memory object containing the allocated + * buffer properties. + * + * @note It is not guaranteed that the input reconciled NvSciBufAttrList in + * this API is the same NvSciBufAttrList that is ultimately associated with the + * allocated NvSciBufObj. If the user needs to query attributes from an + * NvSciBufAttrList associated with an NvSciBufObj after allocation, they must + * first obtain the reconciled NvSciBufAttrList from the NvSciBufObj using + * NvSciBufObjGetAttrList(). + * + * @param[in] reconciledAttrList The reconciled NvSciBufAttrList. + * + * @param[out] bufObj The new NvSciBufObj. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a reconciledAttrList is NULL + * - @a reconciledAttrList is not a reconciled NvSciBufAttrList + * - @a bufObj is NULL + * - ::NvSciError_InsufficientMemory if there is insufficient memory + * to complete the operation. + * - ::NvSciError_InvalidState if a new NvSciBufObj cannot be associated + * with the NvSciBufModule with which @a reconciledAttrList is associated to + * create the new NvSciBufObj. + * - ::NvSciError_ResourceError if any of the following occurs: + * - NVIDIA driver stack failed during buffer allocation + * - system lacks resource other than memory + * - Panics if @a reconciledAttrList is invalid. + * + * @pre + * - Valid reconciled NvSciBufAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufObjAlloc( + NvSciBufAttrList reconciledAttrList, + NvSciBufObj* bufObj); + +/** + * @brief Creates a new memory object containing a buffer handle representing + * the new NvSciBufAttrValAccessPerm to the same buffer for the buffer + * handle contained in the input memory object referenced by the input + * NvSciBufObj and creates a new NvSciBufObj referencing it provided + * NvSciBufAttrValAccessPerm are less than permissions represented by buffer + * handle in the memory object referenced by input NvSciBufObj. When this is the + * case, the new memory object will contains a new NvSciBufAttrList which is + * cloned from the original NvSciBufAttrList associated with the input + * NvSciBufObj, but with the requested NvSciBufAttrValAccessPerm. + * + * This interface has same effect as calling NvSciBufObjDup() if + * NvSciBufAttrValAccessPerm are the same as the permissions represented by + * the buffer handle in the memory object referenced by the input NvSciBufObj. + * + * @param[in] bufObj NvSciBufObj. + * @param[in] reducedPerm Reduced access permissions that need to be imposed on + * the new NvSciBufObj (see @ref NvSciBufAttrValAccessPerm). + * Valid value: NvSciBufAccessPerm_Readonly or NvSciBufAccessPerm_ReadWrite, + * which is <= NvSciBufAttrValAccessPerm represented by the value of the + * NvSciBufGeneralAttrKey_ActualPerm key in the reconciled NvSciBufAttrList + * associated with the input NvSciBufObj. + * \param[out] newBufObj The new NvSciBufObj with new permissions. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a bufObj is NULL + * - @a newBufObj is NULL + * - @a reducedPerm is not NvSciBufAccessPerm_Readonly or + * NvSciBufAccessPerm_ReadWrite + * - @a reducedPerm is greater than the permissions specified in the value + * of the NvSciBufGeneralAttrKey_ActualPerm key + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_InvalidState if any of the following occurs: + * - the total number of NvSciBufObj(s) referencing the memory object is + * INT32_MAX and the caller tries to take one more reference using this + * API. + * - a new NvSciBufObj cannot be associated with the NvSciBufModule with + * which @a bufObj is associated to create the new NvSciBufAttrList + * when the requested access permissions are less than the permissions + * represented by the input NvSciBufObj + * - ::NvSciError_ResourceError if any of the following occurs: + * - NVIDIA driver stack failed while assigning new permission to the buffer handle + * - system lacks resource other than memory + */ +#if (NV_IS_SAFETY == 0) +/** + * - ::NvSciError_NotSupported if this API is called for NvSciBufObj imported + * from the remote Soc. + */ +#endif +/** + * - Panics of @a bufObj is invalid. + * + * @pre + * - Valid NvSciBufObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufObjDupWithReducePerm( + NvSciBufObj bufObj, + NvSciBufAttrValAccessPerm reducedPerm, + NvSciBufObj* newBufObj); + +/** + * @brief Gets pixels from the buffer represented by memory object pointed to + * by @a bufObj provided NvSciBufGeneralAttrKey_Types is set to + * NvSciBufType_Image and CPU access to the buffer is requested via + * NvSciBufGeneralAttrKey_NeedCpuAccess in the unreconciled NvSciBufAttrList(s) + * used for @a bufObj allocation by the peer intending to call this API. + * + * @note User must ensure to read the + * NvSciBufGeneralAttrKey_CpuNeedSwCacheCoherency attribute from the + * NvSciBufAttrList associated with the @a bufObj and perform CPU cache flush + * operation before calling NvSciBufObjGetPixels() if the attribute is set to + * TRUE. + * + * @param[in] bufObj NvSciBufObj. + * @param[in] rect NvSciBufRect defining the subset of the surface to be copied + * to user provided surface. + * Valid value: @a rect can be NULL. If rect is NULL, then entire surface + * represented by NvSciBufObj is copied to user surface. @a rect can only be + * non-NULL for NvSciSurfType_RGBA or NvSciSurfType_RAW, it must + * be NULL for NvSciSurfType_YUV. + * If rect is non-NULL then x0 or x1 co-ordinate shall not exceed the + * plane width represented by NvSciBufImageAttrKey_PlaneWidth. Similarly, y0 or + * y1 co-ordinate shall not exceed the plane height represented by + * NvSciBufImageAttrKey_PlaneHeight. x0 co-ordinate cannot be greater than x1 + * co-ordinate. Similarly, y0 co-ordinate cannot be greater than y1 co-ordinate. + * Width represented by @a rect (x1 - x0) in bytes shall not exceed the + * @a dstPitches supplied by user. + * @param[out] dstPtrs an array of pointers to user's planes. + * For RGBA, RAW and single plane YUV images, it is assumed that the array + * will have single member representing single user plane. For YUV surfaces + * with more than one plane, it is assumed that user provides separate + * plane pointers for Y, U and V planes (where Y is the first plane, U + * is the second plane, and V is the third plane). For RGB surfaces + * with three planes, it is assumed that user provides separate + * plane pointers for R, G and B planes (where R is the first plane, G + * is the second plane, and B is the third plane) + * Valid value: @a dstPtrs must be non-NULL. Every array member of @a dstPtrs + * must be non-NULL. + * @a param[in] dstPtrSizes an array of plane's sizes. Each size in the + * @a dstPtrSizes array shall correspond to the plane at the same index in + * @a dstPtrs. + * Valid value: @a dstPtrSizes must be non-NULL. Each array member of the + * @a dstPtrSizes must be non-zero. + * @param[in] dstPitches an array of pitches. Each member in array shall + * correspond to the pitch of plane at the same index in @a dstPtrs. + * Valid value: dstPitches must be non-NULL. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a bufObj is NULL. + * - NvSciBufAttrList associated with @a bufObj is NULL. + * - @a rect is non-NULL and NvSciBufSurfType is + * NvSciSurfType_YUV . + * - @a rect is non-NULL and x0 or x1 is greater than plane width + * represented by NvSciBufImageAttrKey_PlaneWidth. + * - @a rect is non-NULL and y0 or y1 is greater than plane height + * represented by NvSciBufImageAttrKey_PlaneHeight. + * - @a rect is non-NULL and x0 > x1. + * - @a rect is non-NULL and y0 > y1. + * - @a rect is non-NULL and width in bytes represented by (x1 - x0) is + * is greater than that specified in @a dstPitches for uses planes. + * - @a dstPtrs is NULL. + * - An array member of @a dstPtrs is NULL. + * - @a dstPtrSizes is NULL. + * - An array member of @a dstPtrSizes is zero. + * - @a dstPtrs for any of the planes overlap. + * - @a dstPtrs overlap with the memory represented by @a bufObj. + * - The size of the plane as specified in @a dstPtrSizes is smaller than + * the destination surface to be copied. + * - @a dstPitches is NULL. + * - An array member of @a dstPitches is zero. + * - @a NvSciBufType is not NvSciBufType_Image in the NvSciBufAttrList + * associated with the @a bufObj. + * - CPU access is not requested in unreconciled NvSciBufAttrList of the + * peer calling this API via NvSciBufGeneralAttrKey_NeedCpuAccess. + * - ::NvSciError_NotSupported if any of the following occurs: + * - @a bufObj represents an image that this API does not understand + * - Panics if any of the following occurs: + * - @a bufObj is invalid. + * - @a NvSciBufAttrList associated with the @a bufObj is invalid. + * + * @pre + * - NvSciBufType requested via NvSciBufGeneralAttrKey_Types by the unreconciled + * NvSciBufAttrList(s) is NvSciBufType_Image. + * - CPU access is requested via NvSciBufGeneralAttrKey_NeedCpuAccess by + * at least one unreconciled NvSciBufAttrList belonging to the SoC on which + * below API will be called. + * - Valid NvSciBufObj is obtained such that the reconciled NvSciBufAttrList + * associated with the NvSciBufObj is reconciled from the + * unreconciled NvSciBufAttrList(s) satisfying the conditions stated above. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciBufObjGetPixels( + NvSciBufObj bufObj, + const NvSciBufRect* rect, + void** dstPtrs, + const uint32_t* dstPtrSizes, + const uint32_t* dstPitches); + +/** + * @brief Writes pixels to the buffer represented by memory object pointed to + * by @a bufObj provided NvSciBufGeneralAttrKey_Types is set to + * NvSciBufType_Image, NvSciBufAccessPerm_ReadWrite permissions are requested + * for the @a bufObj via NvSciBufGeneralAttrKey_RequiredPerm and CPU access to + * the buffer is requested via NvSciBufGeneralAttrKey_NeedCpuAccess in the + * unreconciled NvSciBufAttrList(s) used for @a bufObj allocation by the peer + * intending to call this API. + * + * @note User must ensure to read the + * NvSciBufGeneralAttrKey_CpuNeedSwCacheCoherency attribute from the + * NvSciBufAttrList associated with the @a bufObj and perform CPU cache flush + * operation after calling NvSciBufObjPutPixels() if the attribute is set to + * TRUE. + * + * @param[in] bufObj NvSciBufObj. + * @param[in] rect NvSciBufRect defining the subset of the surface to be copied + * from user provided surface. + * Valid value: @a rect can be NULL. If rect is NULL, then entire user surface + * is copied to @a bufObj. @a rect can only be + * non-NULL for NvSciSurfType_RGBA or NvSciSurfType_RAW, it must + * be NULL for NvSciSurfType_YUV. + * If rect is non-NULL then x0 or x1 co-ordinate shall not exceed the + * plane width represented by NvSciBufImageAttrKey_PlaneWidth. Similarly, y0 or + * y1 co-ordinate shall not exceed the plane height represented by + * NvSciBufImageAttrKey_PlaneHeight. x0 co-ordinate cannot be greater than x1 + * co-ordinate. Similarly, y0 co-ordinate cannot be greater than y1 co-ordinate. + * Width represented by @a rect (x1 - x0) in bytes shall not exceed the + * @a srcPitches supplied by user. + * @param[in] srcPtrs an array of pointers to user's planes. + * For RGBA, RAW and single plane YUV images, it is assumed that the array + * will have single member representing single user plane. For YUV surfaces + * with more than one plane, it is assumed that user provides separate + * plane pointers for Y, U and V planes (where Y is the first plane, U + * is the second plane, and V is the third plane). For RGB surfaces + * with three planes, it is assumed that user provides separate + * plane pointers for R, G and B planes (where R is the first plane, G + * is the second plane, and B is the third plane) +* Valid value: @a srcPtrs must be non-NULL. Every array member of srcPtrs must + * be non-NULL. + * @a param[in] srcPtrSizes an array of plane's sizes. Each size in the + * @a srcPtrSizes array shall correspond to the plane at the same index in + * @a srcPtrs. + * Valid value: @a srcPtrSizes must be non-NULL. Each array member of the + * @a srcPtrSizes must be non-zero. + * @param[in] srcPitches an array of pitches. Each member in array shall + * correspond to the pitch of plane at the same index in @a srcPtrs. + * Valid value: srcPitches must be non-NULL. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a bufObj is NULL. + * - NvSciBufAttrList associated with @a bufObj is NULL. + * - @a rect is non-NULL and NvSciBufSurfType is + * NvSciSurfType_YUV . + * - @a rect is non-NULL and x0 or x1 is greater than plane width + * represented by NvSciBufImageAttrKey_PlaneWidth. + * - @a rect is non-NULL and y0 or y1 is greater than plane height + * represented by NvSciBufImageAttrKey_PlaneHeight. + * - @a rect is non-NULL and x0 > x1. + * - @a rect is non-NULL and y0 > y1. + * - @a rect is non-NULL and width in bytes represented by (x1 - x0) is + * is greater than that specified in @a srcPitches for uses planes. + * - @a srcPtrs is NULL. + * - An array member of @a srcPtrs is NULL. + * - @a srcPtrSizes is NULL. + * - An array member of @a srcPtrSizes is zero. + * - @a srcPtrs for any of the planes overlap. + * - @a srcPtrs overlap with the memory represented by @a bufObj. + * - The size of the plane as specified in @a srcPtrSizes is smaller than + * the source surface to be copied. + * - @a srcPitches is NULL. + * - An array member of @a srcPitches is zero. + * - @a NvSciBufType is not NvSciBufType_Image in the NvSciBufAttrList + * associated with the @a bufObj. + * - NvSciBufAccessPerm_ReadWrite is not requested in unreconciled + * NvSciBufAttrList of the peer calling this API via + * NvSciBufGeneralAttrKey_RequiredPerm. + * - CPU access is not requested in unreconciled NvSciBufAttrList of the + * peer calling this API via NvSciBufGeneralAttrKey_NeedCpuAccess. + * - ::NvSciError_NotSupported if any of the following occurs: + * - @a bufObj represents an image that this API does not understand + * - Panics if any of the following occurs: + * - @a bufObj is invalid. + * - @a NvSciBufAttrList associated with the @a bufObj is invalid. + * + * @pre + * - NvSciBufType requested via NvSciBufGeneralAttrKey_Types by the unreconciled + * NvSciBufAttrList(s) is NvSciBufType_Image. + * - CPU access is requested via NvSciBufGeneralAttrKey_NeedCpuAccess by + * at least one unreconciled NvSciBufAttrList belonging to the SoC on which + * below API will be called. + * - Valid NvSciBufObj is obtained such that the reconciled NvSciBufAttrList + * associated with the NvSciBufObj is reconciled from the + * unreconciled NvSciBufAttrList(s) satisfying the conditions stated above. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciBufObjPutPixels( + NvSciBufObj bufObj, + const NvSciBufRect* rect, + const void** srcPtrs, + const uint32_t* srcPtrSizes, + const uint32_t* srcPitches); + +/** + * @} + */ + +/** + * @defgroup nvscibuf_transport_api NvSciBuf APIs + * List of APIs to transport NvSciBuf buffers and attribute list objects across + * various communication boundaries that interact using NvSciIpc. + * @{ + */ + + +/** + * @brief Exports NvSciBufAttrList and NvSciBufObj into an + * NvSciIpc-transferable object export descriptor. The blob can be + * transferred to the other processes to create a matching NvSciBufObj. + * + * @param[in] bufObj NvSciBufObj to export. + * @param[in] permissions Flag indicating the expected access permission + * (see @ref NvSciBufAttrValAccessPerm). The valid value is either + * of NvSciBufAccessPerm_Readonly or NvSciBufAccessPerm_ReadWrite + * such that the value of NvSciBufGeneralAttrKey_ActualPerm set in + * the reconciled NvSciBufAttrList exported to the peer to which + * NvSciBufObj is being exported is less than or equal to + * @a permissions and @a permissions is less than or equal to + * underlying NvSciBufObj permission. Additionally, + * NvSciBufAccessPerm_Auto value is unconditionally valid. + * @param[in] ipcEndpoint NvSciIpcEndpoint to identify the peer process. + * \param[out] attrListAndObjDesc NvSciBuf allocates and fills in the + * exportable form of NvSciBufObj and its corresponding + * NvSciBufAttrList to be shared across an NvSciIpc channel. + * \param[out] attrListAndObjDescSize Size of the exported blob. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a attrListAndObjDesc is NULL + * - @a attrListAndObjDescSize is NULL + * - @a bufObj is NULL + * - @a ipcEndpoint is invalid + * - @a permissions takes value other than NvSciBufAccessPerm_Readonly, + * NvSciBufAccessPerm_ReadWrite or NvSciBufAccessPerm_Auto. + * - ::NvSciError_InsufficientMemory if memory allocation failed + * - ::NvSciError_InvalidOperation if reconciled NvSciBufAttrList of @a bufObj + * has greater permissions for the @a ipcEndpoint peer than the + * @a permissions + * - ::NvSciError_Overflow if an arithmetic overflow occurs due to an invalid + * export descriptor + * - ::NvSciError_NotPermitted if NvSciBufObj and NvSciBufAttrList associated + * with it are not being exported in the reverse direction of IPC path in + * which unreconciled NvSciBufAttrLists involved in reconciliation of + * NvSciBufAttrList associated with the input NvScibufObj were exported. + * - ::NvSciError_ResourceError if the NVIDIA driver stack failed. + * - ::NvSciError_TryItAgain if current operation needs to be retried by the + * user. This error is returned only when communication boundary is chip to + * chip (C2c). + * - Panic if @a bufObj is invalid + * + * @pre + * - Valid NvSciIpcEndpoint is obtained. + * - Valid NvSciBufObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufIpcExportAttrListAndObj( + NvSciBufObj bufObj, + NvSciBufAttrValAccessPerm permissions, + NvSciIpcEndpoint ipcEndpoint, + void** attrListAndObjDesc, + size_t* attrListAndObjDescSize); + +/** + * @brief This API is invoked by the importing process after it receives the + * object export descriptor sent by the other process who has created + * descriptor. + * The importing process will create its own NvSciBufObj and return as + * output. + * + * @param[in] module NvSciBufModule to be used for importing NvSciBufObj. + * @param[in] ipcEndpoint NvSciIpcEndpoint to identify the peer process. + * @param[in] attrListAndObjDesc The exported form of NvSciBufAttrList and + * NvSciBufObj. The valid value must be non NULL. + * @param[in] attrListAndObjDescSize Size of the imported blob. This value must + * be non-zero. + * @param[in] attrList[] Receiver side array of NvSciBufAttrList(s) against + * which the imported NvSciBufAttrList has to be validated. NULL is + * valid value here if the validation of the received + * NvSciBufAttrList needs to be skipped. + * @param[in] count Number of NvSciBufAttrList objects in the array. This value + * must be non-zero, provided @a attrList is non-NULL. + * @param[in] minPermissions Minimum permissions of the NvSciBufObj that the + * process is expecting to import it with (see @ref + * NvSciBufAttrValAccessPerm). The valid value is either of + * NvSciBufAccessPerm_Readonly or NvSciBufAccessPerm_ReadWrite such + * that the value is less than or equal to NvSciBufAttrValAccessPerm + * with which NvSciBufObj was exported. Additionally, + * NvSciBufAccessPerm_Auto value is unconditionally valid. + * @param[in] timeoutUs Maximum delay (in microseconds) before an NvSciBufObj + * times out. The value of the variable is ignored currently. + * \param[out] bufObj NvSciBufObj duplicated and exported during the + * importing process. This NvSciBufObj is associated with the + * reconciled NvSciBufAttrList imported from the attrListAndObjDesc. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a module is NULL + * - @a ipcEndpoint is invalid + * - @a attrListAndObjDesc is NULL + * - @a attrListAndObjDesc represents an NvSciBufAttrList with invalid + * attribute key values set + * - @a attrListAndObjDesc represents an NvSciBufAttrList which is + * unreconciled. + * - @a attrListAndObjDesc is invalid + * - @a attrListAndObjDescSize is 0 + * - @a count is 0, provided @a attrList is non-NULL + * - @a minPermissions are invalid. + * - @a bufObj is NULL + * - ::NvSciError_NotSupported if any of the following occurs: + * - @a attrListAndObjDesc is incompatible + * - Internal attribute of the imported NvSciBufAttrList represents + * memory domain which is not supported. + * - ::NvSciError_AccessDenied if @a minPermissions are greater than permissions + * with which NvSciBufObj was exported + * - ::NvSciError_AttrListValidationFailed if any of the following occurs: + * - input unreconciled NvSciBufAttrList(s)' contraints are not satisfied + * by attributes associated with the imported NvSciBufObj + * - an NvSciBufAttrList appears multiple times in @a attrList + * - ::NvSciError_InsufficientMemory if memory allocation failed + * - ::NvSciError_ResourceError if any of the following occurs: + * - NVIDIA driver stack failed + * - system lacks resource other than memory + * - ::NvSciError_TryItAgain if current operation needs to be retried by the + * user. This error is returned only when communication boundary is chip to + * chip (C2c). + * - ::NvSciError_InvalidState if any of the following occurs: + * - Imported NvSciBufAttrList cannot be associated with @a module. + * - Imported NvSciBufObj cannot be associated with @a module. + * - Panic if: + * - @a any of the unreconciled NvSciBufAttrList(s) are not valid + * - @a module is invalid + * + * @pre + * - Valid NvSciIpcEndpoint is obtained. + * - Valid NvSciBufModule is obtained. + * - Valid (reconciled NvSciBufAttrList + NvSciBufObj) export descriptor is + * obtained. + * - Valid unreconciled NvSciBufAttrList(s) are obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufIpcImportAttrListAndObj( + NvSciBufModule module, + NvSciIpcEndpoint ipcEndpoint, + const void* attrListAndObjDesc, + size_t attrListAndObjDescSize, + const NvSciBufAttrList attrList[], + size_t count, + NvSciBufAttrValAccessPerm minPermissions, + int64_t timeoutUs, + NvSciBufObj* bufObj); + +/** + * @brief Frees the descriptor used for exporting both NvSciBufAttrList and + * NvSciBufObj together. + * + * @param[in] attrListAndObjDescBuf Descriptor to be freed. The valid value is + * the one returned by successful call to + * NvSciBufIpcExportAttrListAndObj(). + * + * @return void + * - Panics if: + * - if Init Mode API is called in Runtime Mode. + * - @a attrListAndObjDescBuf is invalid + * + * @pre + * - Valid (NvSciBufAttrList + NvSciBufObj) export descriptor is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the + * @a attrListAndObjDescBuf to be freed + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +void NvSciBufAttrListAndObjFreeDesc( + void* attrListAndObjDescBuf); + +/** + * @brief Exports the NvSciBufObj into an NvSciIpc-transferable object + * export descriptor. + * Descriptor can be transferred to other end of IPC where matching + * NvSciBufObj can be created from the descriptor. + * + * @param[in] bufObj NvSciBufObj to export. + * @param[in] accPerm Flag indicating the expected access permission + * (see @ref NvSciBufAttrValAccessPerm). The valid value is either + * of NvSciBufAccessPerm_Readonly or NvSciBufAccessPerm_ReadWrite + * such that the value of NvSciBufGeneralAttrKey_ActualPerm set in + * the reconciled NvSciBufAttrList exported to the peer to which + * NvSciBufObj is being exported is less than or equal to @a accPerm + * and @a accPerm is less than or equal to underlying NvSciBufObj + * permission. Additionally, NvSciBufAccessPerm_Auto value is + * unconditionally valid. + * @param[in] ipcEndpoint NvSciIpcEndpoint. + * \param[out] exportData NvSciBuf populates the return value with exportable + * form of NvSciBufObj shared across an NvSciIpc channel. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a bufObj is NULL + * - @a accPerm takes value other than NvSciBufAccessPerm_Readonly, + * NvSciBufAccessPerm_ReadWrite or NvSciBufAccessPerm_Auto. + * - @a ipcEndpoint is invalid + * - @a exportData is NULL + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_InvalidOperation if reconciled NvSciBufAttrList of @a bufObj + * has greater permissions for the @a ipcEndpoint peer than the + * @a accPerm + * - ::NvSciError_NotPermitted if NvSciBufObj is not being exported in the + * reverse direction of IPC path in which unreconciled NvSciBufAttrLists + * involved in reconciliation of NvSciBufAttrList associated with the input + * NvScibufObj were exported. + * - ::NvSciError_ResourceError if the NVIDIA driver stack failed. + * - ::NvSciError_TryItAgain if current operation needs to be retried by the + * user. This error is returned only when communication boundary is chip to + * chip (C2c). + * - Panic if @a bufObj is invalid + * + * @pre + * - Valid NvSciIpcEndpoint is obtained. + * - Valid NvSciBufObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufObjIpcExport( + NvSciBufObj bufObj, + NvSciBufAttrValAccessPerm accPerm, + NvSciIpcEndpoint ipcEndpoint, + NvSciBufObjIpcExportDescriptor* exportData); + +/** + * @brief Creates the NvSciBufObj based on supplied object export descriptor + * and returns the NvSciBufObj bound to the reconciled NvSciBufAttrList. + * + * @note It is not guaranteed that the input reconciled NvSciBufAttrList in + * this API is the same NvSciBufAttrList that is ultimately associated with the + * allocated NvSciBufObj. If the user needs to query attributes from an + * NvSciBufAttrList associated with an NvSciBufObj after allocation, they must + * first obtain the reconciled NvSciBufAttrList from the NvSciBufObj using + * NvSciBufObjGetAttrList(). + * + * @param[in] ipcEndpoint NvSciIpcEndpoint. + * @param[in] desc A pointer to an NvSciBufObjIpcExportDescriptor. The valid + * value is non-NULL that points to descriptor received on NvSciIpc + * channel. + * @param[in] reconciledAttrList Reconciled NvSciBufAttrList returned by + * NvSciBufAttrListIpcImportReconciled(). + * @param[in] minPermissions Minimum permissions of the NvSciBufObj that the + * process is expecting to import it with (see @ref + * NvSciBufAttrValAccessPerm). The valid value is either of + * NvSciBufAccessPerm_Readonly or NvSciBufAccessPerm_ReadWrite such + * that the value is less than or equal to NvSciBufAttrValAccessPerm + * with which NvSciBufObj was exported. Additionally, + * NvSciBufAccessPerm_Auto value is unconditionally valid. + * @param[in] timeoutUs Maximum delay (in microseconds) before an NvSciBufObj + times out. The value of the variable is ignored currently. + * @param[out] bufObj Imported NvSciBufObj created from the descriptor. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API is called in Runtime Mode. + * - ::NvSciError_AccessDenied if minPermissions are greater than permissions + * with which object was exported + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a ipcEndpoint is invalid + * - @a desc is NULL or invalid + * - @a reconciledAttrList is NULL + * - @a reconciledAttrList is unreconciled. + * - @a minPermissions are invalid. + * - @a bufObj is NULL + * - ::NvSciError_InsufficientMemory if there is insufficient system memory. + * - ::NvSciError_Overflow if an arithmetic overflow occurs due to an invalid + * export descriptor + * - ::NvSciError_ResourceError if any of the following occurs: + * - NVIDIA driver stack failed + * - system lacks resource other than memory + * - ::NvSciError_TryItAgain if current operation needs to be retried by the + * user. This error is returned only when communication boundary is chip to + * chip (C2c). + */ +#if defined (BACKEND_RESMAN) +#if (BACKEND_RESMAN) +/** + * - ::NvSciError_InvalidOperation if the NvSciBufObj has already been freed in + * the exporting peer + */ +#endif +#endif +/** + * - ::NvSciError_InvalidState if imported NvSciBufObj cannot be associated with + * NvSciBufModule with which @a reconciledAttrList is associated. + * - ::NvSciError_NotSupported if the internal attribute of + * @a reconciledAttrList represents memory domain which is not supported. + * - Panic if @a reconciledAttrList is invalid + * + * @pre + * - Valid NvSciIpcEndpoint is obtained. + * - Valid reconciled NvSciBufAttrList is obtained. + * - Valid NvSciBufObjIpcExportDescriptor is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufObjIpcImport( + NvSciIpcEndpoint ipcEndpoint, + const NvSciBufObjIpcExportDescriptor* desc, + NvSciBufAttrList reconciledAttrList, + NvSciBufAttrValAccessPerm minPermissions, + int64_t timeoutUs, + NvSciBufObj* bufObj); + +/** + * @brief Allows remote peer NvSciIpcEndpoint to gain access to already allocated NvSciBufObj. + * Provided that the allocated NvSciBufObj is according to buffer requirements provided by the + * input unreconciled attribute list of remote peer interested in gaining access to input NvSciBufObj. + * On success, the NvSciBufObj is exportable to remote peer + * NvSciIpcEndpoints whose unreconciled NvSciBufAttrList was provided + * as input to this function. + * + * @param[in] bufObj The NvSciBufObj whose access needs to be granted + * @param[in] inputArray list of unreconciled NvSciBufAttrList imported + * from remote peers who wants access to the input NvSciBufObj + * @param[in] inputCount Count of unreconciled NvSciBufAttrList provided in + * input @a inputArray + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a inputArray is NULL + * - @a inputCount is 0 + * - @a bufObj is NULL + * - not all the NvSciBufAttrList(s) in @a inputArray and the reconciled + * NvSciBufAttrList bound to @a bufObj are bound to same NvSciBufModule + * instance. + * - an NvSciBufAttrList appears multiple times in @a inputArray + * - if any of the NvSciBufAttrList is reconciled in @a inputArray + * - the NvSciBufGeneralAttrKey_Types key is not set on any of the + * NvSciBufAttrList(s) in @a inputArray + * - ::NvSciError_InsufficientMemory if internal memory allocation failed. + * - ::NvSciError_ResourceError if system lacks resource other than memory. + * - ::NvSciError_ReconciliationFailed if validation of reconciled + * NvSciBufAttrList associated with input @a bufObj failed against input + * unreconciled NvSciBufAttrList(s) in @a inputArray. + * - ::NvSciError_Overflow if internal integer overflow occurs. + * - ::panics if @a any NvSciBufAttrList in the @a + * inputArray is invalid + + * + * @pre + * - Valid NvSciBufObj is allocated. + * - Reconciled NvSciBufAttrList bound to input NvSciBufObj contains + * list of all remote peer location set using + * NvSciBufGeneralAttrKey_PeerLocationInfo attribute. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the input + * NvSciBufAttrList @a attrList + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufObjAttachPeer( + NvSciBufObj bufObj, + const NvSciBufAttrList inputArray[], + size_t inputCount); + +/** + * @brief Transforms the input unreconciled NvSciBufAttrList(s) to an exportable + * unreconciled NvSciBufAttrList descriptor that can be transported by the + * application to any remote process as a serialized set of bytes over an + * NvSciIpc channel. + * + * @param[in] unreconciledAttrListArray The unreconciled NvSciBufAttrList(s) to + * be exported. The valid value is non NULL. + * @param[in] unreconciledAttrListCount Number of unreconciled + * NvSciBufAttrList(s) in @a unreconciledAttrListArray. This value + * must be non-zero. For a single list, the count must be set 1. + * @param[in] ipcEndpoint The NvSciIpcEndpoint. + * @param[out] descBuf A pointer to the new unreconciled NvSciBufAttrList + * descriptor, which the caller can deallocate later using + * NvSciBufAttrListFreeDesc(). + * @param[out] descLen The size of the new unreconciled NvSciBufAttrList + * descriptor. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a unreconciledAttrListArray is NULL + * - any of the NvSciBufAttrLists in the @a unreconciledAttrListArray is + * reconciled. + * - not all the NvSciBufAttrLists in the @a unreconciledAttrListArray are + * bound to the same NvSciBufModule. + * - an NvSciBufAttrList appears multiple times in @a unreconciledAttrListArray + * - @a unreconciledAttrListCount is 0 + * - @a ipcEndpoint is invalid + * - @a descBuf is NULL + * - @a descLen is NULL + * - ::NvSciError_InsufficientResource if any of the following occurs: + * - the API is unable to implicitly append an additional attribute key + * when needed + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - Panic if @a any of the NvSciBufAttrList(s) in @a unreconciledAttrListArray + * is invalid. + * + * @pre + * - Valid NvSciIpcEndpoint is obtained. + * - Valid unreconciled NvSciBufAttrList(s) are obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufAttrListIpcExportUnreconciled( + const NvSciBufAttrList unreconciledAttrListArray[], + size_t unreconciledAttrListCount, + NvSciIpcEndpoint ipcEndpoint, + void** descBuf, + size_t* descLen); + +/** + * @brief Transforms the reconciled NvSciBufAttrList to an exportable reconciled + * NvSciBufAttrList descriptor that can be transported by the application to any + * remote process as a serialized set of bytes over an NvSciIpc channel. + * + * @param[in] reconciledAttrList The reconciled NvSciBufAttrList to be exported. + * @param[in] ipcEndpoint NvSciIpcEndpoint. + * @param[out] descBuf A pointer to the new reconciled NvSciBufAttrList + * descriptor, which the caller can deallocate later using + * NvSciBufAttrListFreeDesc(). + * @param[out] descLen The size of the new reconciled NvSciBufAttrList + * descriptor. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a reconciledAttrList is NULL + * - @a reconciledAttrList is unreconciled. + * - @a ipcEndpoint is invalid + * - @a descBuf is NULL + * - @a descLen is NULL + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_NotPermitted if reconciled NvSciBufAttrList is not being + * exported in the reverse direction of IPC path in which unreconciled + * NvSciBufAttrLists involved in reconciliation of input NvSciBufAttrList were + * exported. + * - Panic if @a reconciledAttrList is invalid. + * + * @pre + * - Valid NvSciIpcEndpoint is obtained. + * - Valid reconciled NvSciBufAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufAttrListIpcExportReconciled( + NvSciBufAttrList reconciledAttrList, + NvSciIpcEndpoint ipcEndpoint, + void** descBuf, + size_t* descLen); + +/** + * @brief Translates an exported unreconciled NvSciBufAttrList descriptor + * (potentially received from any process) into an unreconciled NvSciBufAttrList. + * + * @param[in] module NvScibufModule with which to associate the + * imported NvSciBufAttrList. + * @param[in] ipcEndpoint NvSciIpcEndpoint. + * @param[in] descBuf The unreconciled NvSciBufAttrList descriptor to be + * translated into an unreconciled NvSciBufAttrList. The valid value + * is non-NULL that points to descriptor received on NvSciIpc + * channel. + * @param[in] descLen The size of the unreconciled NvSciBufAttrList descriptor. + * This value must be non-zero. + * @param[out] importedUnreconciledAttrList The imported unreconciled + * NvSciBufAttrList. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a module is NULL + * - @a ipcEndpoint is invalid + * - @a descBuf is NULL + * - @a descBuf represents an NvSciBufAttrList with invalid attribute key + * values set + * - @a descBuf represents an NvSciBufAttrList which is reconciled. + * - @a descBuf is invalid + * - @a descLen is 0 + * - @a importedUnreconciledAttrList is NULL + * - ::NvSciError_NotSupported if @a descBuf represents an NvSciBufAttrList with + * same key multiple times. + * - ::NvSciError_InsufficientMemory if insufficient system memory. + * - ::NvSciError_InvalidState if imported NvSciBufAttrList cannot be + * associated with @a module. + * - ::NvSciError_ResourceError if system lacks resource other than memory. + * - Panic if @a module is invalid + * + * @pre + * - Valid NvSciIpcEndpoint is obtained. + * - Valid NvSciBufModule is obtained. + * - Valid unreconciled NvSciBufAttrList export descriptor is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufAttrListIpcImportUnreconciled( + NvSciBufModule module, + NvSciIpcEndpoint ipcEndpoint, + const void* descBuf, + size_t descLen, + NvSciBufAttrList* importedUnreconciledAttrList); + +/** + * @brief Translates an exported reconciled NvSciBufAttrList descriptor + * (potentially received from any process) into a reconciled NvSciBufAttrList. + * + * It also validates that the reconciled NvSciBufAttrList to be imported will + * be a reconciled NvSciBufAttrList that is consistent with the constraints in + * an array of input unreconciled NvSciBufAttrList(s). This is recommended + * while importing what is expected to be a reconciled NvSciBufAttrList to + * cause NvSciBuf to validate the reconciled NvSciBufAttrList against the input + * un-reconciled NvSciBufAttrList(s), so that the importing process can be sure + * that an NvSciBufObj will satisfy the input constraints. + * + * @param[in] module NvScibufModule with which to associate the + * imported NvSciBufAttrList. + * @param[in] ipcEndpoint NvSciIpcEndpoint. + * @param[in] descBuf The reconciled NvSciBufAttrList descriptor to be + * translated into a reconciled NvSciBufAttrList. The valid value is + * non-NULL that points to descriptor received on NvSciIpc channel. + * @param[in] descLen The size of the reconciled NvSciBufAttrList descriptor. + * This value must be non-zero. + * @param[in] inputUnreconciledAttrListArray The array of unreconciled + * NvSciBufAttrList against which the new reconciled + * NvSciBufAttrList is to be validated. NULL pointer is acceptable + * as a parameter if the validation needs to be skipped. + * @param[in] inputUnreconciledAttrListCount The number of unreconciled + * NvSciBufAttrList(s) in @a inputUnreconciledAttrListArray. If + * @a inputUnreconciledAttrListCount is non-zero, then this operation + * will fail with an error unless all the constraints of all the + * unreconciled NvSciBufAttrList(s) in inputUnreconciledAttrListArray + * are met by the imported reconciled NvSciBufAttrList. + * @param[out] importedReconciledAttrList Imported reconciled NvSciBufAttrList. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a module is NULL + * - @a ipcEndpoint is invalid + * - @a descBuf is NULL + * - @a descBuf represents an NvSciBufAttrList with invalid attribute key + * values set + * - @a descBuf represents an NvSciBufAttrList which is unreconciled. + * - @a descBuf is invalid + * - @a descLen is 0 + * - @a importedReconciledAttrList is NULL + * - @a inputUnreconciledAttrListCount is 0 provided + * @a inputUnreconciledAttrListArray is non-NULL + * - ::NvSciError_NotSupported if any of the following occurs: + * - @a descBuf is incompatible + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_AttrListValidationFailed if any of the following occurs: + * - input unreconciled NvSciBufAttrList(s)' attribute constraints are not + * satisfied by attributes associated with the imported importedReconciledAttrList. + * - an NvSciBufAttrList appears multiple times in @a inputUnreconciledAttrListArray + * - ::NvSciError_InvalidState if imported NvSciBufAttrList cannot be + * associated with @a module. + * - ::NvSciError_ResourceError if system lacks resource other than memory. + * - Panic if: + * - @a any of the NvSciBufAttrList in + * inputUnreconciledAttrListArray is invalid + * - @a module is invalid + * + * @pre + * - Valid NvSciIpcEndpoint is obtained. + * - Valid NvSciBufModule is obtained. + * - Valid reconciled NvSciBufAttrList export descriptor is obtained. + * - Valid unreconciled NvSciBufAttrList(s) are obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufAttrListIpcImportReconciled( + NvSciBufModule module, + NvSciIpcEndpoint ipcEndpoint, + const void* descBuf, + size_t descLen, + const NvSciBufAttrList inputUnreconciledAttrListArray[], + size_t inputUnreconciledAttrListCount, + NvSciBufAttrList* importedReconciledAttrList); + + +/** + * @brief Frees the NvSciBuf exported NvSciBufAttrList descriptor. + * + * @param[in] descBuf NvSciBufAttrList descriptor to be freed. The valid value + * is non-NULL. + * + * @return void + * - Panics if: + * - if Init Mode API is called in Runtime Mode. + * - @a descBuf is invalid + * + * @pre + * - Valid NvSciBufAttrList export descriptor is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the @a descBuf to be + * freed + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +void NvSciBufAttrListFreeDesc( + void* descBuf); + +/** + * @} + */ + +/** + * @defgroup nvscibuf_init_api NvSciBuf Initialization APIs + * List of APIs to initialize/de-initialize NvSciBuf module. + * @{ + */ + +/** + * @brief Initializes and returns a new NvSciBufModule with no + * NvSciBufAttrLists, buffers, or NvSciBufObjs bound to it. + * @note A process may call this function multiple times. + * Each successful invocation will yield a new NvSciBufModule. + * + * @param[out] newModule The new NvSciBufModule. + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if @a newModule is NULL. + * - ::NvSciError_InsufficientMemory if memory is not available. + * - ::NvSciError_ResourceError if any of the following occurs: + * - NVIDIA driver stack failed + * - system lacks resource other than memory + * + * @pre + * - None + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufModuleOpen( + NvSciBufModule* newModule); + +/** + * @brief Releases the NvSciBufModule obtained through + * an earlier call to NvSciBufModuleOpen(). Once the NvSciBufModule is closed + * and all NvSciBufAttrLists and NvSciBufObjs bound to it + * are freed, the NvSciBufModule will be de-initialized in + * the calling process. + * + * @note Every owner of the NvSciBufModule shall call NvSciBufModuleClose() + * only after all the functions invoked by the owner with NvSciBufModule as + * an input are completed. + * + * @param[in] module The NvSciBufModule to close. + * + * @return void + * - Panic if: + * - if Init Mode API is called in Runtime Mode. + * - @a module is invalid + * + * @pre + * - Valid NvSciBufModule is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the input + * NvSciBufModule @a module + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +void NvSciBufModuleClose( + NvSciBufModule module); + +/** + * @brief Checks if loaded NvSciBuf library version is compatible with + * NvSciBuf library version with which elements dependent on NvSciBuf + * were built. + * This function checks loaded NvSciBuf library version with input NvSciBuf + * library version and sets output variable true provided major version of the + * loaded library is same as @a majorVer and minor version of the + * loaded library is not less than @a minorVer. + */ +#if (NV_IS_SAFETY == 0) +/** + * Additionally, this function also checks the versions of libraries that + * NvSciBuf depends on and sets the output variable to true if all libraries are + * compatible, else sets output to false. + */ +#endif +/** + * + * @param[in] majorVer build major version. + * @param[in] minorVer build minor version. + * @param[out] isCompatible boolean value stating if loaded NvSciBuf library is + * compatible or not. + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a isCompatible is NULL + */ +#if (NV_IS_SAFETY == 0) +/** + * - failed to check dependent library versions. + */ +#endif +/** + * + * @pre + * - None + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufCheckVersionCompatibility( + uint32_t majorVer, + uint32_t minorVer, + bool* isCompatible); + +/** + * @brief Validates the NvSciBufObj satisfies the constraints of the + * NvSciBufAttrList that it is associated with. + */ +#if (NV_IS_SAFETY == 0) +/** + * @param[in] bufObj Unused + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success + * + * @note This is a no-op. + */ +#else +/** + * @param[in] bufObj The NvSciBufObj to validate + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a bufObj is NULL + * - @a bufObj is invalid + * - @a bufObj does not satisfy the constraints of the NvSciBufAttrList + * that it is associated with + * - ::NvSciError_Revalidation_Success if any of the following occurs: + * - the API is called after the provided @a bufObj has already been + * validated + * - ::NvSciError_ObjValidationFailed NvSciBufObj doesn't satisfy the reconciled + * NvSciBufAttrList or not holding a valid underlying buffer. + */ +#endif +/** + * @pre + * - None + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufObjValidate( + NvSciBufObj bufObj); + +/** + * @brief + * Validate the reconciled NvSciBufAttrList against the set of all attributes that the + * user has set in the unreconciled NvSciBufAttrList(s). This API provides the safety mechanism + * to detect and report any reconciliation errors. + * + * @param[in] reconciledAttrList reconciled NvSciBufAttrList that need to be validated + * @param[in] pairArray Array of NvSciBufAttrKeyValuePair structures that the user has used + * to set in the unreconciled NvSciBufAttrList. + * Valid value: pairArray is valid input if it is not NULL and + * key member of every NvSciBufAttrKeyValuePair in the array is a valid enumeration + * value defined by the NvSciBufAttrKey enum and value member of every + * NvSciBufAttrKeyValuePair in the array is not NULL. + * @param[in] pairCount Number of elements/entries in @a pairArray. + * Valid value: pairCount is valid input if it is non-zero. + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a reconciledAttrList is NULL + * - @a pairArray is NULL + * - NvSciBufAttrKey specified in @a pairArray is invalid. + * - @a pairCount is 0. + * - ::NvSciError_AttrListValidationFailed indicates that reconciled + * NvSciBufAttrList is not valid against the user provided key value pair(s). + * - panics if @a reconciledAttrList is invalid. + * + * @pre + * - Valid reconciled NvSciBufAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciBufAttrListValidateReconciledAgainstAttrs( + const NvSciBufAttrList reconciledAttrList, + const NvSciBufAttrKeyValuePair* pairArray, + const size_t pairCount); + +/** + * @brief + * Retrieve the NvSciBufAttrValAccessPerm of an NvSciBufObj for given + * NvSciIpcEndpoint. Application can use this API to ensure that when + * an NvSciBufObj is exported with NvSciBufAccessPerm_Auto, the + * NvSciBufObj will be exported with appropriate NvSciBufAttrValAccessPerm + * expected by the application. + * + * @param[in] bufObj object for which access permissions need to be retrieved. + * @param[in] ipcEndpoint NvSciIpcEndpoint of the peer for which the permissions + * need to retrieved. + * Valid value: valid NvSciIpcEndpoint returned by NvSciIpc to identify the peer. + * @param[out] accPerm address at which the retrieved access permissions + * need to be stored. + * Valid Value: non NULL Pointer. + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState If the Init Mode API is called in Runtime Mode. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a bufObj is NULL + * - @a ipcEndpoint is invalid + * - @a accPerm is NULL. + * - panics if @a bufObj is invalid. + * + * @pre + * - Valid bufObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: Yes + * - De-Init: No + */ + +NvSciError NvSciBufObjGetMaxPerm( + const NvSciBufObj bufObj, + const NvSciIpcEndpoint ipcEndpoint, + NvSciBufAttrValAccessPerm* accPerm); + +/** + * @} + */ + +/** @} */ + +#if defined(__cplusplus) +} +#endif // __cplusplus + +#endif /* INCLUDED_NVSCIBUF_H */ diff --git a/nvscierror.h b/nvscierror.h new file mode 100644 index 0000000..a1f5c6e --- /dev/null +++ b/nvscierror.h @@ -0,0 +1,286 @@ +/* + * Copyright (c) 2019-2023, NVIDIA CORPORATION. All rights reserved. + * + * 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. + */ + +/** + * @file + * + * NVIDIA Software Communications Interface (SCI): Error Handling + * + * @b Description: This file declares error codes for NvSci APIs. + */ + +#ifndef INCLUDED_NVSCI_ERROR_H +#define INCLUDED_NVSCI_ERROR_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @defgroup NvSciError SCI Error Handling + * + * Contains error code enumeration and helper macros. + * + * @ingroup nvsci_top + * @{ + */ + +/** + * @brief Return/error codes for all NvSci functions. + * + * This enumeration contains unique return/error codes to identify the + * source of a failure. Some errors have direct correspondence to standard + * errno.h codes, indicated [IN BRACKETS], and may result from failures in + * lower level system calls. Others indicate failures specific to misuse + * of NvSci library function. + * + */ +typedef enum { + /* Range 0x00000000 - 0x00FFFFFF : Common errors + * This range is used for errors common to all NvSci libraries. */ + + /** [EOK] No error */ + NvSciError_Success = 0x00000000, + + /** Unidentified error with no additional info */ + NvSciError_Unknown = 0x00000001, + + /* Generic errors */ + /** [ENOSYS] Feature is not implemented */ + NvSciError_NotImplemented = 0x00000010, + /** [ENOTSUP] Feature is not supported */ + NvSciError_NotSupported = 0x00000011, + /** [EACCES] Access to resource denied */ + NvSciError_AccessDenied = 0x00000020, + /** [EPERM] No permission to perform operation */ + NvSciError_NotPermitted = 0x00000021, + /** Resource is in wrong state to perform operation */ + NvSciError_InvalidState = 0x00000022, + /** Requested operation is not legal */ + NvSciError_InvalidOperation = 0x00000023, + /** Required resource is not initialized */ + NvSciError_NotInitialized = 0x00000024, + /** Requested resource is already in use */ + NvSciError_AlreadyInUse = 0x00000025, + /** Operation has already been performed */ + NvSciError_AlreadyDone = 0x00000026, + /** Resource/information not yet available */ + NvSciError_NotYetAvailable = 0x00000027, + /** Resource/information no longer available */ + NvSciError_NoLongerAvailable = 0x00000028, + /** [ENOMEM] Not enough memory */ + NvSciError_InsufficientMemory = 0x00000030, + /** Not enough (non-memory) resources */ + NvSciError_InsufficientResource = 0x00000031, + /** Resource failed */ + NvSciError_ResourceError = 0x00000032, + + /* Function parameter errors */ + /** [EINVAL] Invalid parameter value */ + NvSciError_BadParameter = 0x00000100, + /** [EFAULT] Invalid address */ + NvSciError_BadAddress = 0x00000101, + /** [E2BIG] Parameter list too long */ + NvSciError_TooBig = 0x00000102, + /** [EOVERFLOW] Value too large for data type */ + NvSciError_Overflow = 0x00000103, + /** Parameters are inconsistent with each other or prior settings */ + NvSciError_InconsistentData = 0x00000104, + /** Parameters or prior settings are insufficient */ + NvSciError_InsufficientData = 0x00000105, + /** An index is not in the allowed range */ + NvSciError_IndexOutOfRange = 0x00000106, + /** A value is not in the allowed range */ + NvSciError_ValueOutOfRange = 0x00000107, + /** An object is successfully revalidated */ + NvSciError_Revalidation_Success = 0x00000108, + + /* Timing/temporary errors */ + /** [ETIMEDOUT] Operation timed out*/ + NvSciError_Timeout = 0x00000200, + /** [EAGAIN] Resource unavailable. Try again. */ + NvSciError_TryItAgain = 0x00000201, + /** [EBUSY] Resource is busy */ + NvSciError_Busy = 0x00000202, + /** [EINTR] An interrupt ocurred */ + NvSciError_InterruptedCall = 0x00000203, + + /* Device errors */ + /** [ENODEV] No such device */ + NvSciError_NoSuchDevice = 0x00001000, + /** [ENOSPC] No space left on device */ + NvSciError_NoSpace = 0x00001001, + /** [ENXIO] No such device or address */ + NvSciError_NoSuchDevAddr = 0x00001002, + /** [EIO] Input/output error */ + NvSciError_IO = 0x00001003, + /** [ENOTTY] Inappropriate I/O control operation */ + NvSciError_InvalidIoctlNum = 0x00001004, + + /* File system errors */ + /** [ENOENT] No such file or directory*/ + NvSciError_NoSuchEntry = 0x00001100, + /** [EBADF] Bad file descriptor */ + NvSciError_BadFileDesc = 0x00001101, + /** [EBADFSYS] Corrupted file system detected */ + NvSciError_CorruptedFileSys = 0x00001102, + /** [EEXIST] File already exists */ + NvSciError_FileExists = 0x00001103, + /** [EISDIR] File is a directory */ + NvSciError_IsDirectory = 0x00001104, + /** [EROFS] Read-only file system */ + NvSciError_ReadOnlyFileSys = 0x00001105, + /** [ETXTBSY] Text file is busy */ + NvSciError_TextFileBusy = 0x00001106, + /** [ENAMETOOLONG] File name is too long */ + NvSciError_FileNameTooLong = 0x00001107, + /** [EFBIG] File is too large */ + NvSciError_FileTooBig = 0x00001108, + /** [ELOOP] Too many levels of symbolic links */ + NvSciError_TooManySymbolLinks = 0x00001109, + /** [EMFILE] Too many open files in process*/ + NvSciError_TooManyOpenFiles = 0x0000110A, + /** [ENFILE] Too many open files in system */ + NvSciError_FileTableOverflow = 0x0000110B, + /** End of file reached */ + NvSciError_EndOfFile = 0x0000110C, + + + /* Communication errors */ + /** [ECONNRESET] Connection was closed or lost */ + NvSciError_ConnectionReset = 0x00001200, + /** [EALREADY] Pending connection is already in progress */ + NvSciError_AlreadyInProgress = 0x00001201, + /** [ENODATA] No message data available */ + NvSciError_NoData = 0x00001202, + /** [ENOMSG] No message of the desired type available*/ + NvSciError_NoDesiredMessage = 0x00001203, + /** [EMSGSIZE] Message is too large */ + NvSciError_MessageSize = 0x00001204, + /** [ENOREMOTE] Remote node doesn't exist */ + NvSciError_NoRemote = 0x00001205, + + /* Process/thread errors */ + /** [ESRCH] No such process */ + NvSciError_NoSuchProcess = 0x00002000, + + /* Mutex errors */ + /** [ENOTRECOVERABLE] Mutex damaged by previous owner's death */ + NvSciError_MutexNotRecoverable = 0x00002100, + /** [EOWNERDEAD] Previous owner died while holding mutex */ + NvSciError_LockOwnerDead = 0x00002101, + /** [EDEADLK] Taking ownership would cause deadlock */ + NvSciError_ResourceDeadlock = 0x00002102, + + /* NvSci attribute list errors */ + /** Could not reconcile attributes */ + NvSciError_ReconciliationFailed = 0x00010100, + /** Could not validate attributes */ + NvSciError_AttrListValidationFailed = 0x00010101, + /** Object validation has errors */ + NvSciError_ObjValidationFailed = 0x00010102, + + + + /** End of range for common error codes */ + NvSciError_CommonEnd = 0x00FFFFFF, + + + /* Range 0x01000000 - 0x01FFFFFF : NvSciBuf errors */ + /** Unidentified NvSciBuf error with no additional info */ + NvSciError_NvSciBufUnknown = 0x01000000, + /** End of range for NvSciBuf errors */ + NvSciError_NvSciBufEnd = 0x01FFFFFF, + + + /* Range 0x02000000 - 0x02FFFFFF : NvSciSync errors */ + /** Unidentified NvSciSync error with no additional info */ + NvSciError_NvSciSyncUnknown = 0x02000000, + /** Unsupported configuration */ + NvSciError_UnsupportedConfig = 0x02000001, + /** Provided fence is cleared */ + NvSciError_ClearedFence = 0x02000002, + /* End of range for NvScSync errors */ + NvSciError_NvSciSyncEnd = 0x02FFFFFF, + + + /* Range 0x03000000 - 0x03FFFFFF : NvSciStream errors */ + + /** Unidentified NvSciStream error with no additional info */ + NvSciError_NvSciStreamUnknown = 0x03000000, + /** Internal stream resource failure occurred */ + NvSciError_StreamInternalError = 0x03000001, + /** Unrecognized block handle */ + NvSciError_StreamBadBlock = 0x03000100, + /** Unrecognized packet handle */ + NvSciError_StreamBadPacket = 0x03000101, + /** Invalid packet cookie value */ + NvSciError_StreamBadCookie = 0x03000102, + /** Operation requires stream be fully connected */ + NvSciError_StreamNotConnected = 0x03000200, + /** Operation can only be performed in setup phase */ + NvSciError_StreamNotSetupPhase = 0x03000201, + /** Operation can only be performed in safety phase */ + NvSciError_StreamNotSafetyPhase = 0x03000202, + /** No stream packet available */ + NvSciError_NoStreamPacket = 0x03001000, + /** Referenced packet's current location does not allow this operation */ + NvSciError_StreamPacketInaccessible = 0x03001001, + /** Internal error due to operation on deleted packet */ + NvSciError_StreamPacketDeleted = 0x03001002, + /** Queried info not exist */ + NvSciError_StreamInfoNotProvided = 0x03003000, + + /** + * These stream errors represent failures detected from lower level + * system components. They generally are not due to any user error, + * but might be caused by the system running out of resources. + */ + /** Failed to acquire lock on mutex used to ensure thread safety */ + NvSciError_StreamLockFailed = 0x03400000, + + /** + * These stream errors represent internal failures which should never + * be possible in a production system. They exist only for internal + * unit testing. + */ + /** Invalid input index was passed to a block. */ + NvSciError_StreamBadSrcIndex = 0x03800000, + /** Invalid output index was passed to a block. */ + NvSciError_StreamBadDstIndex = 0x03800001, + + /** End of range for NvSciStream errors */ + NvSciError_NvSciStreamEnd = 0x03FFFFFF, + + + /* Range 0x04000000 - 0x04FFFFFF : NvSciIpc errors */ + /** Unidentified NvSciIpc error with no additional info */ + NvSciError_NvSciIpcUnknown = 0x04000000, + /** End of range for NvSciIpc errors */ + NvSciError_NvSciIpcEnd = 0x04FFFFFF, + + + /* Range 0x05000000 - 0x05FFFFFF : NvSciEvent errors */ + /** Unidentified NvSciEvent error with no additional info */ + NvSciError_NvSciEventUnknown = 0x05000000, + /** End of range for NvSciEvent errors */ + NvSciError_NvSciEventEnd = 0x05FFFFFF, + +} NvSciError; + +/** + * @} +*/ + +#ifdef __cplusplus +} +#endif + +#endif /* INCLUDED_NVSCI_ERROR_H */ diff --git a/nvscievent.h b/nvscievent.h new file mode 100644 index 0000000..6593731 --- /dev/null +++ b/nvscievent.h @@ -0,0 +1,928 @@ +/* + * Copyright (c) 2019-2023, NVIDIA CORPORATION. All rights reserved. + * + * 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 +#include +#include +#include +#include + +/** + * @file + * + * @brief NVIDIA Software Communications Interface (SCI) : NvSci Event Service + * + * @version 1.3 + * + * @section 1.3 May/18/2023 + * - Set NvSciLocalEvent object to public + * --------------------------------------------------------------------------- + * @section 1.2 Mar/07/2023 + * - Deprecate NvSciEventLoopServiceCreate in safety build + * --------------------------------------------------------------------------- + * @section 1.1 Dec/15/2022 + * - Add NvSciError_NotPermitted error for incorrect API group usage + * in QNX safety only (NvDVMS). + * NvSciEventNotifier::SetHandler() + * NvSciEventLoopServiceCreateSafe() + * --------------------------------------------------------------------------- + * @section 1.0 Jun/23/2022 + * - Add NvSciEventLoopServiceCreateSafe() + * - Add NvSciEventInspect() + * - Add NvSciEventCheckVersionCompatibility() + * - Add NvSciEventMajorVersion, NvSciEventMinorVersion const var + */ + +/* use constant global version variable instead of macro for consistency with + * version check API of existing NvSci family + */ + +/** @brief NvSciEvent API Major version number */ +static const uint32_t NvSciEventMajorVersion = 1U; + +/** @brief NvSciEvent API Minor version number */ +static const uint32_t NvSciEventMinorVersion = 2U; + +/** + * @defgroup nvsci_ipc_event Event Service APIs + * + * @ingroup nvsci_group_ipc + * @{ + * + * 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 TYPES */ +/*****************************************************************************/ + +/** + * \brief Infinite timeout for NvSciEventLoopService::WaitForEvent() or + * NvSciEventLoopService::WaitForMultipleEvents(). + */ +#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; + +/// @cond (SWDOCS_NVSCIIPC_INTERNAL) +typedef struct NvSciTimerEvent NvSciTimerEvent; +typedef struct NvSciEventLoop NvSciEventLoop; +/// @endcond + +/** + * \struct NvSciLocalEvent + * \brief An OS-agnostic object that sends signal to another thread + * in the same process. + * @note This is for internal use only. + */ +struct NvSciLocalEvent { + /** \brief Event notifier associated with this local event. */ + NvSciEventNotifier* eventNotifier; + + /** + * \brief Sends an intra-process local event signal. + * + * @note This is for internal use only. + * + * Any thread which is blocked by local event notifier associated with + * local event will be unblocked by this signal. + * + * @param[in] thisLocalEvent NvSciLocalEvent object pointer created by + * NvSciEventService::CreateLocalEvent() + * + * @return ::NvSciError, the completion code of operations: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_BadParameter Indicates an invalid input parameter. + * - ::NvSciError_TryItAgain Indicates an kernel pulse queue shortage. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * + * @pre NvSciEventService::CreateLocalEvent() must be called. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges: None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ + NvSciError (*Signal)(NvSciLocalEvent* thisLocalEvent); + + /** + * \brief Releases any resources associated with this local event. + * + * @note This is for internal use only. + * + * This function must be called after releasing notifier and when + * NvSciLocalEvent is no longer required. + * + * @note This API can be called in Init mode to release resources + * in error handling or to test functionality. + * + * @param[in] thisLocalEvent NvSciLocalEvent object pointer created by + * NvSciEventService::CreateLocalEvent(). + * + * @pre NvSciEventService::CreateLocalEvent() must be called. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges: None + * - API Group + * - Init: Yes + * - Runtime: No + * - De-Init: Yes + */ + void (*Delete)(NvSciLocalEvent* thisLocalEvent); +}; + +/** + * \struct NvSciEventService + * \brief An abstract interface for a program's event handling infrastructure. + * + * An NvSciEventService is an abstraction that a library can use to interact + * with the event handling infrastructure of the containing program. + * + * If a library needs to handle asynchronous events or report asynchronous + * events to its users, but the library does not wish to impose a threading + * model on its users, the library can require each user to provide an + * NvSciEventService when the user initializes the library (or a portion + * thereof). + * + * An NvSciEventService provides two categories of services related to event + * handling: + * + * (1) The ability to define "event notifiers", which are objects that can + * notify event handling infrastructure each time an event has occurred. + * Note that event notifications carry no payload; it is expected that any + * event payload information is conveyed separately. + * + * (2) The ability to bind an "event handler" to each event notifier. An event + * handler is essentially a callback that is invoked each time the bound + * event notifier reports the occurrence of an event. + */ +struct NvSciEventService { + /** + * @if (SWDOCS_NVSCIIPC_INTERNAL) + * \brief Defines an event notifier for a native notifier. + * + * @note This API is for internal use only. + * + * The new NvSciEventNotifier will report the occurrence of an event to + * the event service each time the provided native notifier reports an + * event from the OS environment. + * + * This function creates event notifier which reports the occurrence of + * an event from the OS environment to the event service. + * To configure the event bound to OS environment, it calls the function + * in @a nativeEvent with the notifier pointer, which is a supported function + * in the NvSciIpc library. + * + * @param[in] thisEventService NvSciEventService object pointer created by + * NvSciEventLoopServiceCreateSafe(). + * @param[in] nativeEvent NvSciNativeEvent object pointer. + * @param[out] newEventNotifier NvSciEventNotifier object pointer on + * success. + * + * @return ::NvSciError, the completion code of operations: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_InsufficientMemory Indicates memory is not sufficient. + * - ::NvSciError_BadParameter Indicates an invalid input parameters. + * - ::NvSciError_ResourceError Indicates not enough system resources. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * + * @pre NvSciEventLoopServiceCreateSafe() must be called. + * + * @usage + * - 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: No + * - De-Init: No + * @endif + */ + /// @cond (SWDOCS_NVSCIIPC_INTERNAL) + NvSciError (*CreateNativeEventNotifier)( + NvSciEventService* thisEventService, + NvSciNativeEvent* nativeEvent, + NvSciEventNotifier** newEventNotifier); + /// @endcond + + /** + * \brief Creates an intra-process local event with an event notifier + * that reports each event signaled through it. + * + * @note This API is for internal use only. + * + * @param[in] thisEventService NvSciEventService object pointer created by + * NvSciEventLoopServiceCreateSafe(). + * @param[out] newLocalEvent NvSciLocalEvent object pointer on + * success. + * + * @return ::NvSciError, the completion code of operations: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_InsufficientMemory Indicates memory is not sufficient. + * - ::NvSciError_BadParameter Indicates an invalid input parameter. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * - ::NvSciError_NotPermitted Indicates incorrect API group usage. + * + * @pre NvSciEventLoopServiceCreateSafe() must be called. + * + * @usage + * - 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: No + * - De-Init: No + */ + NvSciError (*CreateLocalEvent)( + NvSciEventService* thisEventService, + NvSciLocalEvent** newLocalEvent); + + /** + * @if (SWDOCS_NVSCIIPC_INTERNAL) + * \brief Creates a timer event with an event notifier that reports each + * event signaled through it. + * + * @note This is for internal use only in Linux. + * + * @endif + */ + /// @cond (SWDOCS_NVSCIIPC_INTERNAL) + NvSciError (*CreateTimerEvent)( + NvSciEventService* thisEventService, + NvSciTimerEvent** newTimerEvent); + /// @endcond + + /** + * \brief Releases any resources associated with this event service. + * + * Before this member function is called, the caller must ensure that all + * other member function calls on @a thisEventService have completed and the + * caller must never again invoke any member functions on + * @a thisEventService. + * + * If there any NvSciEventNotifier objects created from this event service that + * have not been deleted yet, the resources allocated for this event + * service will not necessarily be released until all those + * NvSciEventNotifier objects are first deleted. + * + * There may also be implementation-specific conditions that result in a + * delay in the release of resources. + * + * Release resources associated with NvSciEventService and NvSciEventService + * which is created by NvSciEventLoopServiceCreateSafe(). + * + * @note This API must be called after releasing notifier and + * NvSciEventService is no longer required. + * + * @note This API can be called in Init mode to release resources + * in error handling or to test functionality. + * + * @param[in] thisEventService NvSciEventService object pointer created by + * NvSciEventLoopServiceCreateSafe(). + * + * @pre NvSciEventLoopServiceCreateSafe() must be called. + * + * @usage + * - 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: No + * - De-Init: Yes + */ + void (*Delete)(NvSciEventService* thisEventService); +}; + +/** + * \struct NvSciEventNotifier + * + * \brief An abstract interface to notify event to event consumer and + * to register event handler of the event consumer client process. + */ +struct NvSciEventNotifier { + /** + * \brief Registers or unregisters a handler for a particular event notifier. + * + * In general, handlers for distinct event notifiers may run + * concurrently with one another. The NvSciEventService promises however + * that no single event notifier will have its handler invoked concurrently. + * + * Handlers for both NvSciNativeEvent and NvSciLocalEvent can be registered. + * + * \param[in] eventNotifier The event notifier that reports each event. Must + * not already be in use by another event loop. + * + * \param[in] callback The function to call to handle the event. If NULL, + * handler will be unregistered. + * + * \param[in] cookie The parameter to pass to the callback. + * + * \param[in] priority The priority of the handler relative to other + * handlers registered with eventLoop. Must be less + * than @ref NV_SCI_EVENT_PRIORITIES. + * @return ::NvSciError, the completion code of operations: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_BadParameter Indicates an invalid or NULL argument. + * - ::NvSciError_NotPermitted Indicates incorrect API group usage. + * + * @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: Yes + * - Signal handler: Yes + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ + NvSciError (*SetHandler)(NvSciEventNotifier* thisEventNotifier, + void (*callback)(void* cookie), + void* cookie, + uint32_t priority); + + /** + * \brief Unregisters any previously-registered event handler and delete + * this event notifier. + * + * If the event handler's callback is concurrently executing in another + * thread, then this function will still return immediately, but the event + * handler will not be deleted until after the callback returns. + * + * This function releases the NvSciEventNotifier and unregisters the event handler. + * It should be called when the NvSciEventNotifier is no longer required. + * + * @note This API can be called in Init mode to release resources + * in error handling or to test functionality. + * + * @param[in] thisEventNotifier The event handler to unregister and delete. + * + * @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: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: Yes + * - Runtime: No + * - De-Init: Yes + */ + void (*Delete)(NvSciEventNotifier* thisEventNotifier); +}; + +/** + * \brief 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 + * @a 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 @a newEventLoopService which is + * a primary instance of event service. An application must call event service + * functions along with @a newEventLoopService. + * The number of event loops that can be created in the new event loop service + * will be limited to at most @a maxEventLoops. + * + * @param[in] maxEventLoops The number of event loops, it must be 1. + * @param[out] newEventLoopService NvSciEventNotifier object double pointer. + * + * @return ::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. + * + * @pre None. + * + * @usage + * - 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 + */ +NvSciError NvSciEventLoopServiceCreate( + size_t maxEventLoops, + NvSciEventLoopService** newEventLoopService); + +/** + * \brief 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 + * @a maxEventLoops. + * + * This function creates a new event loop service @a newEventLoopService which + * is a primary instance of event service. An application must call event + * service functions along with @a newEventLoopService. + * The number of event loops that can be created in the new event loop service + * will be limited to at most @a maxEventLoops. + * + * @note The following information is specific to QNX and about @a 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 @a 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. + * + * @param[in] maxEventLoops The number of event loops, it must be 1. + * @param[in] config OS-specific configuration parameter. + * It should NULL in Linux. + * @param[out] newEventLoopService NvSciEventNotifier object double pointer. + * + * @return ::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. + * - ::NvSciError_NotPermitted Indicates incorrect API group usage. + * + * @pre None. + * + * @usage + * - 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 + */ +NvSciError NvSciEventLoopServiceCreateSafe( + size_t maxEventLoops, + void* config, + NvSciEventLoopService** newEventLoopService); + +/** + * \struct NvSciEventLoopService + + * \brief An abstract interface that event consumer can wait for + * events using event notifier in event loop. + */ +struct NvSciEventLoopService { + NvSciEventService EventService; + + /** + * @if (SWDOCS_NVSCIIPC_NOTSUPPORT) + * \brief Creates an event loop that can handle events for NvSciEventLoopService. + * + * @note This API is not yet supported. + * + * The user is responsible for running the event loop from a thread by + * calling the new event loop's Run() function. + * @endif + */ + /// @cond (SWDOCS_NVSCIIPC_NOTSUPPORT) + NvSciError (*CreateEventLoop)(NvSciEventLoopService* eventLoopService, + NvSciEventLoop** eventLoop); + /// @endcond + + /** + * \brief Waits up to a configurable timeout for a particular event + * notification, servicing events with configured callbacks in the interim. + * + * Any asynchronous event notifiers that are pending before calling + * this function will be claimed by some thread for handling before + * this function returns. + * + * @a eventNotifier must have been created through EventService. + * + * @note This function must not be called from an event notifier + * callback. + * + * This function waits up to a configurable timeout to receive a pulse event + * which is configured on NvSciQnxEventService_CreateNativeEventNotifier(). + * @a eventNotifier must have been created through EventService before calling. + * + * @param[in] eventNotifier NvSciEventNotifier object pointer. + * @param[in] microseconds A 64-bit integer timeout in microsecond. + * Set to -1 for an infinite timeout, for example, + * the value @ref NV_SCI_EVENT_INFINITE_WAIT. + * + * @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 a condition is unsupported. + * - ::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: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ + NvSciError (*WaitForEvent)( + NvSciEventNotifier* eventNotifier, + int64_t microseconds); + + /** + * \brief Waits up to a configurable timeout for any of a set of + * particular event notifications, servicing events with configured + * callbacks in the interim. + * + * Any asynchronous event notifiers that are pending before calling + * this function will be claimed by some thread for handling before + * this function returns. + * + * Each event notifier in @a eventNotifierArray must have been created + * through EventService. + * + * On a successful return, for each integer `i` in the range + * `[0, eventNotifierCount-1]`, `newEventArray[i]` will be true only if + * `eventNotifierArray[i]` had a new event. + * + * @note This function must not be called from an event notifier + * callback. + * @note This function will be deprecated in furture and user must use + * the newer version of the API which is + * NvSciEventWaitForMultipleEventsExt + * + * @param[in] eventNotifierArray Array of NvSciEventNotifier object + * pointers. It should not be NULL. + * @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. + * @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 a condition is not supported. + * - ::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: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ + NvSciError (*WaitForMultipleEvents)( + NvSciEventNotifier* const * eventNotifierArray, + size_t eventNotifierCount, + int64_t microseconds, + bool* newEventArray); + + /** + * \brief Waits up to a configurable timeout for any of a set of + * particular event notifications, servicing events with configured + * callbacks in the interim. + * + * Any asynchronous event notifiers that are pending before calling + * this function will be claimed by some thread for handling before + * this function returns. + * + * Each event notifier in @a eventNotifierArray must have been created + * through EventService. + * + * On a successful return, for each integer `i` in the range + * `[0, eventNotifierCount-1]`, `newEventArray[i]` will be true only if + * `eventNotifierArray[i]` had a new event. + * + * @a eventNotifierArray can be NULL then this function will not update + * @a newEventArray but still service events with configured callbacks, + * which are created with @a eventService until the specified timeout period. + * For this NULL case, timeout in @a microseconds works in this way. + * 1. @a microseconds > 0 + * Callbacks will continue to be served until the timeout happens. If + * any callback takes long more than timeout, other callbacks associated + * with events which arrives before timeout will be served even after + * timeout. + * 2. @a microseconds = -1 (NV_SCI_EVENT_INFINITE_WAIT) + * Callbacks will continue to be served and this API will never + * returns. + * + * @note This function must not be called from an event notifier + * callback. + * + * @param[in] eventService Pointer to the event service object + * @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. + * @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 a condition is not supported. + * - ::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: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ + NvSciError (*WaitForMultipleEventsExt)( + NvSciEventService *eventService, + NvSciEventNotifier* const * eventNotifierArray, + size_t eventNotifierCount, + int64_t microseconds, + bool* newEventArray); +}; + +#ifdef __QNX__ +/** + * \brief Inspect events + * + * This API is specific to QNX OS. + * + * If event storm happens in specific event notifiers, + * this API unregisters relevant events and returns the event notifiers + * bound to the events. This API is used in a thread receiving semaphore + * event when event can't be obtained from the pool any more due to + * event storm. In order to prevent unwanted breakage on handling event, + * Do not call this API when semaphore event is not triggered. + * + * @param[in] thisEventService NvSciEventService object pointer created + * by NvSciEventLoopServiceCreateSafe(). + * @param[in] numEvents A threshold value to unregister events. + * This shall be less than num_pulses which + * is configured in . + * @param[in] eventNotifierCount Notifier count in @eventNotifierArray. + * @param[out] eventNotifierArray Array of NvSciNotifier which has + * excessive event signalling + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_BadParameter Indicates an invalid or NULL argument. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * + * @pre NvSciEventLoopServiceCreateSafe() must be called. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: No + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciEventInspect( + NvSciEventService *thisEventSerivce, + uint32_t numEvents, + uint32_t eventNotifierCount, + NvSciEventNotifier** eventNotifierArray); +#endif /* __QNX__ */ + +/* + * \brief 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 @a majorVer and minor version of the + * loaded library is not less than @a minorVer, else sets output to false + * + * @param[in] majorVer build major version. + * @param[in] minorVer build minor version. + * @param[out] isCompatible boolean value stating if loaded NvSciEvent library + * is compatible or not. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a isCompatible is NULL + * + * @pre None + * + * @usage + * - 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 + */ +NvSciError NvSciEventCheckVersionCompatibility( + uint32_t majorVer, + uint32_t minorVer, + bool* isCompatible); + +/** @} */ + +#ifdef __cplusplus +} +#endif +#endif /* INCLUDED_NVSCIEVENT_H */ diff --git a/nvsciipc.cfg b/nvsciipc.cfg new file mode 100644 index 0000000..9b421ef --- /dev/null +++ b/nvsciipc.cfg @@ -0,0 +1,82 @@ +# +# Copyright (c) 2019-2022, NVIDIA CORPORATION. All rights reserved. +# +# Format of NvSciIpc Config file +# +# First column should specify the backend. All possible backend types +# are listed below: +# INTER_THREAD, INTER_PROCESS, INTER_VM, INTER_CHIP +# +# For INTER_THREAD/PROCESS backend type, format will be: +# +# +# For INTER_THREAD and INTER_PROCESS, two endpoints name should be different. +# You can use different suffix with basename for them. denotes +# "number of frames" and denotes "frame size" +# +# For INTER_VM/CHIP backend type, format will be: +# +# +# For INTER_CHIP optional backend info is derive with below rule: +# +# Both should be written as two digit decimal number. +# eg: device_id = 5, xfer_role = producer +# backend info: 0105 +# +# For INTER_VM backend type, BACKEND_INFO1 denotes ivc queue number +# +# This is NvSciIpc CFG file for x86 machine, so only 3 backends are supported +# as of now : INTER_PROCESS, INTER_THREAD and INTER_CHIP +INTER_PROCESS ipc_test_0 ipc_test_1 64 1536 +INTER_PROCESS ipc_test_a_0 ipc_test_a_1 64 1536 +INTER_PROCESS ipc_test_b_0 ipc_test_b_1 64 1536 +INTER_PROCESS ipc_test_c_0 ipc_test_c_1 64 1536 +INTER_THREAD itc_test_0 itc_test_1 64 1536 +INTER_THREAD nvscistream_itc_0 nvscistream_itc_1 64 1536 +INTER_THREAD nvscibuf_itc_0 nvscibuf_itc_1 64 1536 +INTER_PROCESS nvscistream_0 nvscistream_1 16 24576 +INTER_PROCESS nvscistream_2 nvscistream_3 16 24576 +INTER_PROCESS nvscistream_4 nvscistream_5 16 24576 +INTER_PROCESS nvscistream_6 nvscistream_7 16 24576 +INTER_PROCESS nvscisync_a_0 nvscisync_a_1 16 24576 +INTER_PROCESS nvscisync_b_0 nvscisync_b_1 16 24576 +INTER_PROCESS nvscisync_c_0 nvscisync_c_1 16 24576 +INTER_PROCESS nvscisync_d_0 nvscisync_d_1 16 24576 +INTER_PROCESS nvscibuf_ipc_A_B nvscibuf_ipc_B_A 16 24576 +INTER_PROCESS nvscibuf_ipc_B_C nvscibuf_ipc_C_B 16 24576 +INTER_PROCESS nvscibuf_ipc_A_D nvscibuf_ipc_D_A 16 24576 +INTER_PROCESS nvscibuf_ipc_B_E nvscibuf_ipc_E_B 16 24576 +INTER_PROCESS nvmap_sciipc_1 nvmap_sciipc_2 16 24576 +INTER_PROCESS nvmap_sciipc_3 nvmap_sciipc_4 16 24576 +INTER_CHIP nvscic2c_pcie_s0_c5_1 0000 +INTER_CHIP nvscic2c_pcie_s0_c5_2 0000 +INTER_CHIP nvscic2c_pcie_s0_c5_3 0000 +INTER_CHIP nvscic2c_pcie_s0_c5_4 0000 +INTER_CHIP nvscic2c_pcie_s0_c5_5 0000 +INTER_CHIP nvscic2c_pcie_s0_c5_6 0000 +INTER_CHIP nvscic2c_pcie_s0_c5_7 0000 +INTER_CHIP nvscic2c_pcie_s0_c5_8 0000 +INTER_CHIP nvscic2c_pcie_s0_c5_9 0000 +INTER_CHIP nvscic2c_pcie_s0_c5_10 0000 +INTER_CHIP nvscic2c_pcie_s0_c5_11 0000 +INTER_CHIP nvscic2c_pcie_s0_c6_1 0000 +INTER_CHIP nvscic2c_pcie_s0_c6_2 0000 +INTER_CHIP nvscic2c_pcie_s0_c6_3 0000 +INTER_CHIP nvscic2c_pcie_s0_c6_4 0000 +INTER_CHIP nvscic2c_pcie_s0_c6_5 0000 +INTER_CHIP nvscic2c_pcie_s0_c6_6 0000 +INTER_CHIP nvscic2c_pcie_s0_c6_7 0000 +INTER_CHIP nvscic2c_pcie_s0_c6_8 0000 +INTER_CHIP nvscic2c_pcie_s0_c6_9 0000 +INTER_CHIP nvscic2c_pcie_s0_c6_10 0000 +INTER_CHIP nvscic2c_pcie_s0_c6_11 0000 +INTER_CHIP egl_nvscic2c_5_prod 0105 +INTER_CHIP egl_nvscic2c_5_cons 1005 +INTER_CHIP egl_nvscic2c_6_prod 0106 +INTER_CHIP egl_nvscic2c_6_cons 1006 +INTER_CHIP egl_nvscic2c_7_prod 0107 +INTER_CHIP egl_nvscic2c_7_cons 1007 +INTER_CHIP egl_nvscic2c_8_prod 0108 +INTER_CHIP egl_nvscic2c_8_cons 1008 +INTER_CHIP egl_nvscic2c_9_prod 0109 +INTER_CHIP egl_nvscic2c_9_cons 1009 diff --git a/nvsciipc.h b/nvsciipc.h new file mode 100644 index 0000000..420af94 --- /dev/null +++ b/nvsciipc.h @@ -0,0 +1,1713 @@ +/* + * Copyright (c) 2018-2023, NVIDIA CORPORATION. All rights reserved. + * + * 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_NVSCIIPC_H +#define INCLUDED_NVSCIIPC_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include +#include +#include +#include + +/** + * @file + * + * @brief NVIDIA Software Communications Interface (SCI) : NvSci Inter-Process Communication + * + * @version 1.2 + * + * @section 1.2 Mar/07/2023 + * - Deprecate non-safe APIs in safety build + * NvSciIpcCloseEndpoint + * NvSciIpcResetEndpoint + * NvSciIpcRead + * NvSciIpcWrite + * NvSciIpcGetEvent + * NvSciIpcSetQnxPulseParam + * --------------------------------------------------------------------------- + * @section 1.1 Dec/15/2022 + * - Add NvSciError_NotPermitted error for incorrect API group usage + * in QNX safety only (NvDVMS). + * NvSciIpcInit() + * NvSciIpcOpenEndpoint() + * NvSciIpcOpenEndpointWithEventService() + * NvSciIpcGetEventNotifier() + * NvSciIpcCloseEndpointSafe() + * NvSciIpcSetQnxPulseParamSafe() + * --------------------------------------------------------------------------- + * @section 1.0 Jun/23/2022 + * - Add NvSciIpcGetEventSafe() + * - Add NvSciIpcWaitEventQnx() : QNX only + * - Add NvSciIpcSetQnxPulseParamSafe() : QNX only + * - Add NvSciIpcInspectEventQnx() : QNX only + * - Add NvSciIpcCheckVersionCompatibility() + * - Add NvSciIpcMajorVersion, NvSciIpcMinorVersion constant + */ + +/* use constant global version variable instead of macro for consistency with + * version check API of existing NvSci family + */ + +/** @brief NvSciIpc API Major version number */ +static const uint32_t NvSciIpcMajorVersion = 1U; + +/** @brief NvSciIpc API Minor version number */ +static const uint32_t NvSciIpcMinorVersion = 2U; + +/** + * @defgroup nvsci_group_ipc Inter-Process Communication + * IPC and Event Service APIs + * + * @ingroup nvsci_top + * @{ + */ +/** + * @defgroup nvsci_ipc_api IPC APIs + * + * + * @ingroup nvsci_group_ipc + * @{ + * + * The NvSciIpc library provides interfaces for any two entities in a system to + * communicate with each other irrespective of where they are placed. Entities + * can be in: + * - Different threads in the same process + * - The same process + * - Different processes in the same VM + * - Different VMs on the same SoC + * @if (SWDOCS_NVSCIIPC_STANDARD) + * - Different SoCs + * @endif + * + * Each of these different boundaries will be abstracted by a library providing + * unified communication (Read/Write) APIs to entities. The communication + * consists of two bi-directional send/receive queues. + * + * When Init operation group APIs are used, the user should call them in the + * following order, with or without NvSciEventService. + * + * Typical call flow with NvSciIpc library + * + * 1) Init mode + * - NvSciIpcInit() + * - NvSciIpcOpenEndpoint() + * - Set event reporting path + * NvSciIpcSetQnxPulseParam() (QNX OS-specific) or + * NvSciIpcGetLinuxEventFd() (Linux OS-specific) + * - NvSciIpcGetEndpointInfo() + * - NvSciIpcResetEndpointSafe() + * - Ensure a channel is established + * ~~~~~~~~~~~~~~~~~~~~~ + * loop { + * NvSciIpcGetEvent() + * if (event & NV_SCI_IPC_EVENT_CONN_EST_ALL) break + * else { + * NvSciIpcWaitEventQnx() (QNX OS-specific) or + * select(), poll() (Linux OS-specific) + * } + * } + * ~~~~~~~~~~~~~~~~~~~~~ + * + * 2) Runtime mode (loop) + * - NvSciIpcGetEvent() + * - If an event is not desired, + * call OS-blocking API + * NvSciIpcWaitEventQnx() (QNX OS-specific) or + * select(), poll() (Linux OS-specific) + * - NvSciIpcReadSafe() or NvSciIpcWriteSafe() + * + * 3) De-Init mode + * - NvSciIpcCloseEndpointSafe() + * - NvSciIpcDeinit() + * + * Typical call flow with NvSciIpc and NvSciEventService library + * + * NvSciEventService provides APIs that replace OS-specific event-blocking API. + * They are only compatible with an endpoint which is opened with + * NvSciOpenEndpointWithEventService(). + * + * 1) Init mode + * - NvSciEventLoopServiceCreateSafe() to get eventLoopService + * - NvSciIpcInit() + * - NvSciIpcOpenEndpointWithEventService() + * - NvSciIpcGetEventNotifier() to get eventNotifier + * - NvSciIpcGetEndpointInfo() + * - NvSciIpcResetEndpointSafe() + * - Ensure a channel is established + * ~~~~~~~~~~~~~~~~~~~~~ + * loop { + * NvSciIpcGetEvent() + * if (event & NV_SCI_IPC_EVENT_CONN_EST_ALL) break + * else { + * eventLoopService->WaitForEvent(eventNotifier) + * } + * } + * ~~~~~~~~~~~~~~~~~~~~~ + * + * 2) Runtime mode (loop) + * - NvSciIpcGetEvent() + * - If an event is not desired, + * - eventLoopService->WaitForEvent() + * - NvSciIpcReadSafe() or NvSciIpcWriteSafe() + * + * 3) De-Init mode + * - eventNotifier->Delete() + * - NvSciIpcCloseEndpointSafe() + * - NvSciIpcDeinit() + * - eventLoopService->EventService.Delete() + * + * Using multi-threading in NvSciIpc - QNX OS + * + * For Inter-VM and Inter-Process backend applications on QNX OS, + * only a single event-blocking OS API (i.e. NvSciIpcWaitEventQnx(), + * NvSciEventLoopService::WaitForEvent()) is allowed per endpoint + * in the same process boundary. + * If a client application tries to use receiving and sending thread separately + * for the same endpoint handle, the event-blocking OS APIs must be used in a + * single thread in order to receive remote notification. + * Once a remote notification arrives in the thread, the notification should be + * forwarded to the other thread using the same endpoint handle through any OS + * synchronization method (e.g. sem_post, pthread_cond_signal or + * MsgSendPulse etc.) + * Single thread usage is recommended to handle both TX and RX data. + * + * Configuring thread pool of resource manager - QNX OS + * + * NvSciIpc resource manager (io-nvsciipc) uses thread pool to manage + * concurrent request from multiple NvSciIpc client processes using NvSciIpc + * library. + * io-nvsciipc is used during opening endpoint. + * Drive OS users should evaluate thread pool capacity of io-nvsciipc then + * configure them with -t option in startup script. + * Thread pool capacity for NvSciIPC can be evaluated based on number of + * parallel outstanding NvSciIPC requests, at any point of time, that are + * expected in the system. Default value of thread pool capacity is 10. + * + * Getting events before using Read/Write NvSciIpc API + * + * Before using any Read/Write APIs, the user must check if + * @ref NV_SCI_IPC_EVENT_READ or @ref NV_SCI_IPC_EVENT_WRITE event is available + * through NvSciIpcGetEvent(). + * NvSciIpcGetEvent() has additional support to establish connection between + * two endpoint software entities. + * + * When to use blocking API + * + * Users of NvSciIpc must call OS event-blocking API to wait for an event when + * NvSciIpcGetEvent() does not return desired events. + * The following are OS event-blocking API examples: + * - QNX : NvSciIpcWaitEventQnx() + * - LINUX: select(), poll() etc. + * - NvSciEventService: NvSciEventLoopService::WaitForEvent(),
+ * NvSciEventLoopService::WaitForMultipleEvents() + * + * If user process needs to wait for events from multiple remote NvSciIpc + * endpoint processes, use single blocking call from single thread instead of + * using blocking call per endpoint thread. This is recommended to improve + * performance by avoiding thread creation per endpoint. + * NvSciEventLoopService::WaitForMultipleEvents() blocking call is suitable for + * this use case. + * + * How to check if peer endpoint entity receives a message + * + * NvSciIpc library does not provide information about whether a peer endpoint + * entity receives all sent messages from a local endpoint entity. + * If such a mechanism is required, the client user should implement separate + * message acknowledgment in the application layer. + * + * Checksum for data integrity + * + * NvSciIpc does not provide checksum for data to be transferred or check for + * data integrity error. + * If such a mechanism is required, the client user should implement checksum + * processing routine for data. + * + * Recommended Read/Write APIs + * + * Using NvSciIpcReadSafe() and NvSciIpcWriteSafe() is recommended rather than following + * Read/Write APIs. See detail constraints of API in each function description. + * - NvSciIpcReadGetNextFrame() + * - NvSciIpcWriteGetNextFrame() + * - NvSciIpcReadAdvance() + * - NvSciIpcWriteAdvance() + * However, above functions are better to avoid extra memory copy. + * + * Provide valid buffer pointers + * + * The user of NvSciIpc must provide valid buffer pointers to NvSciIpcReadSafe(), + * NvSciIpcWriteSafe() and other Read/Write NvSciIpc APIs as NvSciIpc library + * validation to these parameters is limited to a NULL pointer check. + * + * Maximum number of endpoints + * + * One NvSciIpc client process is allowed to open up to 500 endpoints. + * QNX NvSciIpc opens two device nodes in opening endpoint. + * QNX OS kernel supports 1024 + * 100 open channels without disabling kernel preemption. User client needs + * one channel/connection pair to receive an endpoint notification. + * + * Concurrent read/write + * Client processes who want concurrent read and write operation on endpoints + * need to open two endpoints, one for read and the other for write operation. + * Read and write operation on different endpoint work exclusively without any + * external locking mechanism in multiple threads. Channel memory consumption + * will be doubled in using two endpoints. + * + * Use ChannelCreatePulsePool() - QNX OS + * + * In using legacy event handling (without NvSciEventService) on NvSciIpc, + * user has to create chid and coid using ChannelCreate_r() and + * ConnectAttach_r() before calling NvSciIpcSetQnxPulseParamSafe(). + * This ChannelCreate() uses global pulse message pool. If privileged and + * non-privileged processes use the same global pool, unprivileged processes + * can potentially interfere with privileged processes by receiving and not + * handling large numbers of pulses (thereby causing denial of service attack). + * So, ChannelCreatePulsePool() API is recommended to use fixed private pool of + * pulses instead of using ChannelCreate_r(). + * + * 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 IVC signalling storm, user needs to create separate thread + * to receive semaphore event which is set in nto_channel_config structure and + * call sem_wait() in that thread. + * NvSciIpcInspectEventQnx() API returns NvSciIpcEndpoint handle in which IVC + * signalling storm happens. + * User can decide post action (i.e. close endpoint, restart process, deinit + * NvSciIpc etc.) per system usecase scenario after detecting issue. + * + * Regarding fork() - QNX OS safety build + * + * NvSciIpc library depends on QNX_BSP::NvDVMS to check VM state restriction. + * Hence parent process should not use fork(). Instead, posix_spawn() + * should be used to spawn child process. + */ + +/*******************************************************************/ +/************************ DATA TYPES *******************************/ +/*******************************************************************/ + +/** + * @brief Handle to the NvSciIpc endpoint. + */ +typedef uint64_t NvSciIpcEndpoint; + +typedef struct NvSciIpcEndpointInfo NvSciIpcEndpointInfo; + +/** + * @brief Defines information about the NvSciIpc endpoint. + */ +struct NvSciIpcEndpointInfo { + /** Holds the number of frames. */ + uint32_t nframes; + /** Holds the frame size in bytes. */ + uint32_t frame_size; +}; + +/** + * Specifies maximum Endpoint name length + * including null terminator + */ +#define NVSCIIPC_MAX_ENDPOINT_NAME 64U + +/* NvSciIPC Event type */ +/** Specifies the IPC read event. */ +#define NV_SCI_IPC_EVENT_READ 0x01U +/** Specifies the IPC write event. */ +#define NV_SCI_IPC_EVENT_WRITE 0x02U +/** Specifies the IPC connection established event. */ +#define NV_SCI_IPC_EVENT_CONN_EST 0x04U +/** Specifies the IPC connection reset event. */ +#define NV_SCI_IPC_EVENT_CONN_RESET 0x08U +/** Specifies the IPC write fifo empty event. */ +#define NV_SCI_IPC_EVENT_WRITE_EMPTY 0x10U +/** Specifies single event mask to check IPC connection establishment */ +#define NV_SCI_IPC_EVENT_CONN_EST_ALL (NV_SCI_IPC_EVENT_CONN_EST | \ + NV_SCI_IPC_EVENT_WRITE | NV_SCI_IPC_EVENT_WRITE_EMPTY | \ + NV_SCI_IPC_EVENT_READ) + +/** infinite timeout for NvSciIpcWaitEventQnx() */ +#define NVSCIIPC_INFINITE_WAIT -1LL + +/*******************************************************************/ +/********************* FUNCTION TYPES ******************************/ +/*******************************************************************/ + +/** + * @brief Initializes the NvSciIpc library. + * + * This function parses the NvSciIpc configuration file and creates + * an internal database of NvSciIpc endpoints that exist in a system. + * + * @return ::NvSciError, the completion code of the operation. + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_NotPermitted Indicates initialization has failed. + * Indicates incorrect API group usage. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * + * @usage + * - 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: No + * - De-Init: No + */ +NvSciError NvSciIpcInit(void); + +/** + * @brief De-initializes the NvSciIpc library. + * + * This function cleans up the NvSciIpc endpoint internal database + * created by NvSciIpcInit(). + * Before calling this API, all existing opened endpoints must be closed + * by NvSciIpcCloseEndpointSafe(). + * + * @note This API can be called in Init mode to release resources + * in error handling or to test functionality. + * + * @return @c void + * + * @pre Invocation of NvSciIpcInit() must be successful. + * + * @usage + * - 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: No + * - De-Init: Yes + */ +void NvSciIpcDeinit(void); + +/** + * @brief Opens an endpoint with the given name. + * + * The function locates the NvSciIpc endpoint with the given name in the + * NvSciIpc configuration table in the internal database, and returns a handle + * to the endpoint if found. When the operation is successful, endpoint can + * utilize the allocated shared data area and the corresponding signaling + * mechanism setup. If the operation fails, the state of the NvSciIpc endpoint + * is undefined. + * In case of QNX OS, in order to authenticate user client process, NvSciIpc + * uses custom ability "NvSciIpcEndpoint". Use procmgr_ability_lookup() + * QNX OS API to get ability ID. + * + * @param[in] endpoint The name of the NvSciIpc endpoint to open. + * @param[out] handle A handle to the endpoint on success. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_BadParameter Indicates any argument was NULL or invalid. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_NoSuchEntry Indicates the @a endpoint was not found. + * - ::NvSciError_Busy Indicates the @a endpoint is already in + * use. + * - ::NvSciError_InsufficientMemory Indicates memory allocation failed for + * the operation. + * - ::NvSciError_NotSupported Indicates API is not supported on provided + * endpoint backend type. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * - ::NvSciError_NotPermitted Indicates process doesn't have the required + * privilege. + * Indicates incorrect API group usage. + * + * @pre Invocation of NvSciIpcInit() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): + * - "NvSciIpcEndpoint" + * - "NvSciC2cPcieEndpoint" (Inter-Chip only) + * - PROCMGR_AID_PROT_EXEC (Inter-Chip only) + * - PROCMGR_AID_MAP_FIXED (Inter-Chip only) + * - API Group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciIpcOpenEndpoint(const char *endpoint, NvSciIpcEndpoint *handle); + +/** + * @brief Opens an endpoint with the given name and event service. + * + * This API provides same functionality as NvSciIpcOpenEndpoint(). + * But, it requires additional event service abstract object as an input + * parameter to utilize NvSciEventService infrastructure. + * NvSciEventService can be created through NvSciEventLoopServiceCreateSafe(). + * NvSciIpcGetEventNotifier() can be used only when this API is invoked + * successfully. + * In case of QNX OS, in order to authenticate user client process, NvSciIpc + * uses custom ability "NvSciIpcEndpoint". Use procmgr_ability_lookup() + * QNX OS API to get ability ID. + * + * @param[in] endpoint The name of the NvSciIpc endpoint to open. + * @param[out] handle A handle to the endpoint on success. + * @param[in] eventService An abstract object to use NvSciEventService + * infrastructure. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_BadParameter Indicates any argument was NULL or invalid. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_NoSuchEntry Indicates the @a endpoint was not found. + * - ::NvSciError_Busy Indicates the @a endpoint is already in + * use. + * - ::NvSciError_InsufficientMemory Indicates memory allocation failed for + * the operation. + * - ::NvSciError_NotSupported Indicates API is not supported on provided + * endpoint backend type. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * - ::NvSciError_NotPermitted Indicates process doesn't have the required + * privilege. + * Indicates incorrect API group usage. + * + * @pre Invocation of NvSciEventLoopServiceCreateSafe() must be successful. + * Invocation of NvSciIpcInit() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): + * - "NvSciIpcEndpoint" + * - "NvSciC2cPcieEndpoint" (Inter-Chip only) + * - PROCMGR_AID_PROT_EXEC (Inter-Chip only) + * - PROCMGR_AID_MAP_FIXED (Inter-Chip only) + * - API Group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciIpcOpenEndpointWithEventService(const char *endpoint, + NvSciIpcEndpoint *handle, NvSciEventService *eventService); + +/** + * @brief Get NvSciIpc event notifier. + * + * This API is used to connect NvSciIpc event handling with OS-provided + * event interface. + * It also utilizes NvSciEventService infrastructure. + * Before calling NvSciIpcCloseEndpointSafe(), event notifier should be deleted + * through Delete callback of NvSciEventNotifier. + * + * @note This API is only compatible with an endpoint that is opened with + * NvSciIpcOpenEndpointWithEventService() + * + * @param[in] handle NvSciIpc endpoint handle. + * @param[out] eventNotifier A pointer to NvSciEventNotifier object on success. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_BadParameter Indicates an invalid or NULL argument. + * - ::NvSciError_NotSupported Indicates API is not supported on provided + * endpoint backend type. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * - ::NvSciError_InsufficientMemory Indicates memory allocation failed for the + * operation. + * - ::NvSciError_ResourceError Indicates not enough system resources. + * - ::NvSciError_NotPermitted Indicates incorrect API group usage. + * + * @pre Invocation of NvSciIpcOpenEndpointWithEventService() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): + * - PROCMGR_AID_INTERRUPTEVENT (Inter-VM only) + * - PROCMGR_AID_PUBLIC_CHANNEL + * - API Group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciIpcGetEventNotifier(NvSciIpcEndpoint handle, + NvSciEventNotifier **eventNotifier); + +/** + * @brief Closes an endpoint with the given handle. + * + * @warning This API is deprecated and returns without doing anything in safety + * build. + * Use NvSciIpcCloseEndpointSafe() instead of this. + * + * The function frees the NvSciIpc endpoint associated with the given @a handle. + * + * @param[in] handle A handle to the endpoint to close. + * + * @return @c void + * + * @pre Invocation of NvSciIpcOpenEndpoint() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: No + * - Runtime: No + * - De-Init: Yes + */ +void NvSciIpcCloseEndpoint(NvSciIpcEndpoint handle); + +/** + * @brief Closes an endpoint with the given handle (safety version) + * + * The function frees the NvSciIpc endpoint associated with the given @a handle. + * + * @note This API can be called in Init mode to release resources + * in error handling or to test functionality. + * + * @param[in] handle A handle to the endpoint to close. + * @param[in] clear Reserved for future use and any value has no change to the + * function behavior. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_BadParameter Indicates an invalid @a handle. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_NotPermitted Indicates incorrect API group usage. + * + * @pre Invocation of NvSciIpcOpenEndpoint() must be successful. + * + * @usage + * - 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: No + * - De-Init: Yes + */ +NvSciError NvSciIpcCloseEndpointSafe(NvSciIpcEndpoint handle, bool clear); + +/** + * @brief Resets an endpoint. + * + * @warning This API is deprecated and returns without doing anything in safety + * build. + * Use NvSciIpcResetEndpointSafe() instead of this. + * @warning This API won't support Runtime in future release since existing + * data communications are not guaranteed. + * + * Initiates a reset on the endpoint and notifies the remote endpoint. + * Applications must call this function at most once per endpoint handle during + * Init mode and complete the reset operation before using the endpoint for + * communication. + * Once this API is called, all existing data in channel will be discarded. + * After invoking this function, client user shall call NvSciIpcGetEvent() + * to get specific event type (READ, WRITE etc.). if desired event is not + * returned from GetEvent API, OS-specific blocking call (select/poll + * or NvSciIpcWaitEventQnx) should be called to wait remote notification. + * This sequence must be done repeatedly to get event type that + * endpoint wants. + * + * @note This API must be called at most once per endpoint handle during Init + * mode, and at most once during De-init mode (i.e. synchronization for + * closing channel). In case of De-Init mode, NvSciIpcGetEvent() must NOT + * be called after NvSciIpcResetEndpoint() is called. + * + * @param[in] handle A handle to the endpoint to reset. + * + * @return @c void + * + * @pre Invocation of NvSciIpcOpenEndpoint() must be successful. + * + * @usage + * - 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 + */ +void NvSciIpcResetEndpoint(NvSciIpcEndpoint handle); + +/** + * @brief Resets an endpoint. (safety version) + * + * @warning This API won't support Runtime in future release since existing + * data communications are not guaranteed. + * + * Initiates a reset on the endpoint and notifies the remote endpoint. + * Applications must call this function at most once per endpoint handle during + * Init mode and complete the reset operation before using the endpoint for + * communication. + * Once this API is called, all existing data in channel will be discarded. + * After invoking this function, client user shall call NvSciIpcGetEvent() + * to get specific event type (READ, WRITE etc.). if desired event is not + * returned from GetEvent API, OS-specific blocking call (select/poll + * or NvSciIpcWaitEventQnx) should be called to wait remote notification. + * This sequence must be done repeatedly to get event type that + * endpoint wants. + * + * @note This API must be called at most once per endpoint handle during Init + * mode, and at most once during De-init mode (i.e. synchronization for + * closing channel). In case of De-Init mode, NvSciIpcGetEventSafe() must NOT + * be called after NvSciIpcResetEndpointSafe() is called. + * + * @param[in] handle A handle to the endpoint to reset. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_BadParameter Indicates an invalid @a handle. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * - ::NvSciError_NotSupported Indicates API is not supported on provided + * endpoint backend type. + * + * @pre Invocation of NvSciIpcOpenEndpoint() must be successful. + * + * @usage + * - 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: No + * - De-Init: Yes + */ +NvSciError NvSciIpcResetEndpointSafe(NvSciIpcEndpoint handle); + +/** + * @brief Reads a frame from the endpoint. + * + * @warning This API is deprecated and returns NvSciError_NotSupported without + * doing anything in safety build. + * Use NvSciIpcReadSafe() instead of this. + * + * This function copies a new frame contents into a buffer and advances to the + * next frame. If the destination buffer is smaller than the configured + * frame size of the endpoint, the trailing bytes are discarded. + * + * This is a non-blocking call. Read channel of the endpoint must not be empty. + * If read channel of the endpoint was previously full, then the function + * notifies the remote endpoint. + * + * This operation cannot proceed if the endpoint is being reset. However, + * if the remote endpoint has called NvSciIpcResetEndpointSafe(), calls to this + * function can still succeed until the next event notification on the local + * endpoint. + * + * The user shall make sure if actual input buffer size is equal or bigger than + * requested size before using this API. + * + * @param[in] handle The handle to the endpoint to read from. + * @param[out] buf A pointer to a destination buffer to receive the contents + * of the next frame. + * @param[in] size The number of bytes to copy from the frame, + * not to exceed the length of the destination buffer and + * configured frame size of the endpoint. + * @param[out] bytes The number of bytes read on success. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_BadParameter Indicates an invalid @a handle or @a size. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_InsufficientMemory Indicates read channel is empty and + * the read operation aborted. + * - ::NvSciError_ConnectionReset Indicates the endpoint is being reset. + * - ::NvSciError_NotSupported Indicates API is not supported on provided + * endpoint backend type. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * + * @pre NvSciIpcResetEndpointSafe() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciIpcRead(NvSciIpcEndpoint handle, void *buf, size_t size, + int32_t *bytes); + +/** + * @brief Reads a frame from the endpoint (safety version) + * + * This function copies a new frame contents into a buffer and advances to the + * next frame. If the destination buffer is smaller than the configured + * frame size of the endpoint, the trailing bytes are discarded. + * + * This is a non-blocking call. Read channel of the endpoint must not be empty. + * If read channel of the endpoint was previously full, then the function + * notifies the remote endpoint. + * + * This operation cannot proceed if the endpoint is being reset. However, + * if the remote endpoint has called NvSciIpcResetEndpointSafe(), calls to this + * function can still succeed until the next event notification on the local + * endpoint. + * + * The user shall make sure if actual input buffer size is equal or bigger than + * requested size before using this API. + * + * @param[in] handle The handle to the endpoint to read from. + * @param[out] buf A pointer to a destination buffer to receive the contents + * of the next frame. + * @param[in] size The number of bytes to copy from the frame, + * not to exceed the length of the destination buffer and + * configured frame size of the endpoint. + * @param[out] bytes The number of bytes read on success. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_BadParameter Indicates an invalid @a handle or @a size. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_InsufficientMemory Indicates read channel is empty and + * the read operation aborted. + * - ::NvSciError_ConnectionReset Indicates the endpoint is being reset. + * - ::NvSciError_NotSupported Indicates API is not supported on provided + * endpoint backend type. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * + * @pre NvSciIpcResetEndpointSafe() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciIpcReadSafe(NvSciIpcEndpoint handle, void *buf, uint32_t size, + uint32_t *bytes); + +/** + * @brief Get a pointer to the read frame from the endpoint. + * + * This is a non-blocking call. + * This operation cannot proceed if the endpoint is being reset. However, + * if the remote endpoint has called NvSciIpcResetEndpointSafe(), calls to this + * function can still succeed until the next event notification on the local + * endpoint. + * Between NvSciIpcReadGetNextFrame() and NvSciIpcReadAdvance(), do not perform + * any other NvSciIpc read operations with the same endpoint handle. + * Once a read frame is released by NvSciIpcReadAdvance(), do not use previously + * returned pointer of NvSciIpcReadGetNextFrame() since it is already invalid. + * Do not write through a returned pointer of NvSciIpcReadGetNextFrame(). + * This is protected by a const volatile pointer return type. + * Do not read the same memory location multiple times. If required, copy + * specific memory location to a local buffer before using it. + * + * @param[in] handle The handle to the endpoint to read from. + * @param[out] buf A pointer to a destination buffer to receive + * the contents of the next frame on success. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_BadParameter Indicates an invalid @a handle. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_InsufficientMemory Indicates read channel is empty and + * the read operation aborted. + * - ::NvSciError_ConnectionReset Indicates the endpoint is being reset. + * - ::NvSciError_NotSupported Indicates API is not supported in provided + * endpoint backend type. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * + * @pre NvSciIpcResetEndpointSafe() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciIpcReadGetNextFrame(NvSciIpcEndpoint handle, + const volatile void **buf); + +/** + * @brief Advance to the next read frame of the endpoint. + * + * This is a non-blocking call. Read channel of the endpoint must not be empty. + * If a read channel of the endpoint was previously full, then this function + * notifies the remote endpoint. + * + * This operation cannot proceed if the endpoint is being reset. However, + * if the remote endpoint has called NvSciIpcResetEndpointSafe(), calls to this + * function can still succeed until the next event notification on the local + * endpoint. + * + * Between NvSciIpcReadGetNextFrame() and NvSciIpcReadAdvance(), do not perform + * any other NvSciIpc read operations with the same endpoint handle. + * Once a read frame is released by NvSciIpcReadAdvance(), do not use previously + * returned pointer of NvSciIpcReadGetNextFrame() since it is already invalid. + * + * @param[in] handle The handle to the endpoint to read from. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates successful operation. + * - ::NvSciError_BadParameter Indicates an invalid @a handle. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_InsufficientMemory Indicates read channel is empty and + * the read operation aborted. + * - ::NvSciError_ConnectionReset Indicates the endpoint is being reset. + * - ::NvSciError_NotSupported Indicates API is not supported in provided + * endpoint backend type. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * + * @pre NvSciIpcResetEndpointSafe() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciIpcReadAdvance(NvSciIpcEndpoint handle); + +/** + * @brief Writes a frame to the endpoint. + * + * @warning This API is deprecated and returns NvSciError_NotSupported without + * doing anything in safety build. + * Use NvSciIpcWriteSafe() instead of this. + * + * If space is available in the endpoint, this function posts a new frame, + * copying the contents from the provided data buffer. + * If @a size is less than the frame size, then the remaining bytes of the frame + * are undefined. + * + * This is a non-blocking call. + * If write channel of the endpoint was previously empty, then the function + * notifies the remote endpoint. + * + * This operation cannot proceed if the endpoint is being reset. + * + * The user shall make sure if actual input buffer size is equal or bigger than + * requested size before using this API. + * + * @param[in] handle The handle to the endpoint to write to. + * @param[in] buf A pointer to a source buffer for the contents of + * the next frame. + * @param[in] size The number of bytes to be copied to the frame, + * not to exceed the length of the destination buffer and + * configured frame size of the endpoint. + * @param[out] bytes The number of bytes written on success. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_BadParameter Indicates an invalid @a handle or @a size. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_InsufficientMemory Indicates write channel is full and + * the write operation aborted. + * - ::NvSciError_ConnectionReset Indicates the endpoint is being reset. + * - ::NvSciError_NotSupported Indicates API is not supported in provided + * endpoint backend type. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * + * @pre NvSciIpcResetEndpointSafe() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciIpcWrite(NvSciIpcEndpoint handle, const void *buf, size_t size, + int32_t *bytes); + +/** + * @brief Writes a frame to the endpoint. (safety version) + * + * If space is available in the endpoint, this function posts a new frame, + * copying the contents from the provided data buffer. + * If @a size is less than the frame size, then the remaining bytes of the frame + * are undefined. + * + * This is a non-blocking call. + * If write channel of the endpoint was previously empty, then the function + * notifies the remote endpoint. + * + * This operation cannot proceed if the endpoint is being reset. + * + * The user shall make sure if actual input buffer size is equal or bigger than + * requested size before using this API. + * + * @param[in] handle The handle to the endpoint to write to. + * @param[in] buf A pointer to a source buffer for the contents of + * the next frame. + * @param[in] size The number of bytes to be copied to the frame, + * not to exceed the length of the destination buffer and + * configured frame size of the endpoint. + * @param[out] bytes The number of bytes written on success. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_BadParameter Indicates an invalid @a handle or @a size. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_InsufficientMemory Indicates write channel is full and + * the write operation aborted. + * - ::NvSciError_ConnectionReset Indicates the endpoint is being reset. + * - ::NvSciError_NotSupported Indicates API is not supported in provided + * endpoint backend type. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * + * @pre NvSciIpcResetEndpointSafe() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciIpcWriteSafe(NvSciIpcEndpoint handle, const void *buf, + uint32_t size, uint32_t *bytes); + +/** + * @brief Get a pointer to the write frame from the endpoint. + * + * This is a non-blocking call. write channel of the endpoint must not be full. + * + * This operation cannot proceed if the endpoint is being reset. However, + * if the remote endpoint has called NvSciIpcResetEndpointSafe(), calls to this + * function can still succeed until the next event notification on the local + * endpoint. + * Between NvSciIpcWriteGetNextFrame() and NvSciIpcWriteAdvance(), do not + * perform any other NvSciIpc write operations with the same endpoint handle. + * Once a transmit message is committed by NvSciIpcWriteAdvance(), do not use + * previously returned pointer of NvSciIpcWriteGetNextFrame() since it is + * already invalid. + * Do not read through a returned pointer of NvSciIpcWriteGetNextFrame(). + * + * @param[in] handle The handle to the endpoint to write to. + * @param[out] buf A pointer to a destination buffer to hold the contents of + * the next frame on success. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates successful operation. + * - ::NvSciError_BadParameter Indicates an invalid @a handle. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_InsufficientMemory Indicates write channel is full and + * the write operation aborted. + * - ::NvSciError_ConnectionReset Indicates the endpoint is being reset. + * - ::NvSciError_NotSupported Indicates API is not supported in provided + * endpoint backend type. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * + * @pre NvSciIpcResetEndpointSafe() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciIpcWriteGetNextFrame(NvSciIpcEndpoint handle, + volatile void **buf); + +/** + * @brief Advance to the next write frame of the endpoint. + * + * This is a non-blocking call. + * If write channel of the endpoint is not full, then post the next frame. + * If write channel of the endpoint was previously empty, then this function + * notifies the remote endpoint. + * + * This operation cannot proceed if the endpoint is being reset. However, + * if the remote endpoint has called NvSciIpcResetEndpointSafe(), calls to this + * function can still succeed until the next event notification on the local + * endpoint. + * + * Between NvSciIpcWriteGetNextFrame() and NvSciIpcWriteAdvance(), do not + * perform any other NvSciIpc write operations with the same endpoint handle. + * Once transmit message is committed by NvSciIpcWriteAdvance(), do not use + * previously returned pointer of NvSciIpcWriteGetNextFrame() since it is + * already invalid. + * + * @param[in] handle The handle to the endpoint to write to. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates successful operation. + * - ::NvSciError_BadParameter Indicates an invalid @a handle. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_InsufficientMemory Indicates write channel is full and + * the write operation aborted. + * - ::NvSciError_ConnectionReset Indicates the endpoint is being reset. + * - ::NvSciError_NotSupported Indicates API is not supported in provided + * endpoint backend type. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * + * @pre NvSciIpcResetEndpointSafe() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciIpcWriteAdvance(NvSciIpcEndpoint handle); + +/** + * @brief Returns endpoint information. + * + * + * @param[in] handle NvSciIpc endpoint handle. + * @param[out] info A pointer to NvSciIpcEndpointInfo object that + * this function copies the info to on success. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_BadParameter Indicates an invalid or NULL argument. + * - ::NvSciError_NotSupported Indicates API is not supported in provided + * endpoint backend type. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * + * @pre Invocation of NvSciIpcOpenEndpoint() must be successful. + * + * @usage + * - 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: No + */ +NvSciError NvSciIpcGetEndpointInfo(NvSciIpcEndpoint handle, + NvSciIpcEndpointInfo *info); + +#ifndef __QNX__ +/** + * Returns the NvSciIpc file descriptor for a given endpoint. + * + * This API is specific to Linux OS. + * Event handle will be used to plug OS event notification + * (can be read, can be written, established, reset etc.) + * + * @param handle NvSciIpc endpoint handle + * @param fd A pointer to the endpoint file descriptor. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_BadParameter Indicates an invalid or NULL argument. + * - ::NvSciError_NotSupported Indicates API is not supported in provided + * endpoint backend type or OS environment. + */ +NvSciError NvSciIpcGetLinuxEventFd(NvSciIpcEndpoint handle, int32_t *fd); +#endif /* !__QNX__ */ + +/** + * @brief Get Events + * + * @warning This API is deprecated and returns NvSciError_NotSupported without + * doing anything in safety build. + * Use NvSciIpcGetEventSafe() instead of this. + * + * Returns a bitwise OR operation on new events that occurred since the + * last call to this function. + * + * This function sets @a events to the result of a bitwise OR operation of zero + * or more @c NV_SCI_IPC_EVENT_* constants corresponding to all new events that + * have occurred on the endpoint since: + * - the preceding call to this function on the endpoint or + * - opening the endpoint, if this is the first call to this function on the + * endpoint since it was opened. + * + * The parameter @a events is set to zero if no new events have + * occurred. + * + * There are 5 types of events: + * - @c NV_SCI_IPC_EVENT_CONN_EST : IPC connection established + * - @c NV_SCI_IPC_EVENT_WRITE : IPC write + * - @c NV_SCI_IPC_EVENT_READ : IPC read + * - @c NV_SCI_IPC_EVENT_CONN_RESET : IPC connection reset + * - @c NV_SCI_IPC_EVENT_WRITE_EMPTY : IPC write FIFO empty + * + * @c NV_SCI_IPC_EVENT_CONN_EST and @c NV_SCI_IPC_EVENT_CONN_RESET events are + * connection event. They're edge-triggered events and once they're read by + * user, events are cleared. + * + * @c NV_SCI_IPC_EVENT_WRITE, @c NV_SCI_IPC_EVENT_READ and + * @c NV_SCI_IPC_EVENT_WRITE_EMPTY events are FIFO status event. + * As long as free buffer is available on write FIFO or data are available in + * read FIFO, API keeps reporting same events. All these events mean that + * connection is still alive. + * + * An @c NV_SCI_IPC_EVENT_CONN_EST event occurs on an endpoint each time a + * connection is established through the endpoint (between the endpoint and + * the other end of the corresponding channel). + * + * An @c NV_SCI_IPC_EVENT_WRITE event occurs on an endpoint: + * -# In conjunction with the delivery of each @c NV_SCI_IPC_CONN_EST event. + * -# Each time the endpoint ceases to be full after a prior @c NvSciIpcWrite* + * call returned @c NvSciError_InsufficientMemory. Note however that an + * implementation is permitted to delay the delivery of this type of + * @c NV_SCI_IPC_EVENT_WRITE event, e.g., for purposes of improving throughput. + * + * An @c NV_SCI_IPC_EVENT_READ event occurs on an endpoint: + * -# In conjunction with the delivery of each @c NV_SCI_IPC_EVENT_CONN_EST + * event, if frames can already be read as of delivery. + * -# Each time the endpoint ceases to be empty after a prior @c NvSciRead* + * call returned @c NvSciError_InsufficientMemory. Note however that an + * implementation is permitted to delay the delivery of this type of + * @c NV_SCI_IPC_EVENT_READ event, e.g., for purposes of improving throughput. + * + * An @c NV_SCI_IPC_EVENT_CONN_RESET event occurs on an endpoint when the user + * calls NvSciIpcResetEndpoint. + * + * An @c NV_SCI_IPC_EVENT_WRITE_EMPTY event occurs on an endpoint when write + * FIFO is empty. user can utilize this event to check if remote endpoint reads + * all data which local endpoint sent. + * + * If this function doesn't return desired events, user must call + * OS-provided blocking API to wait for notification from remote endpoint. + * + * The following are blocking API examples: + * - QNX : NvSciIpcWaitEventQnx() + * - LINUX: select(), poll() etc. + * - NvSciEventService: NvSciEventLoopService::WaitForEvent(),
+ * NvSciEventLoopService::WaitForMultipleEvents() + * + * In case of QNX OS, in order to authenticate user client process, NvSciIpc + * uses custom ability "NvSciIpcEndpoint". Use procmgr_ability_lookup() + * QNX OS API to get ability ID. + * + * @note Before using any read and write NvSciIpc API, user should call this + * API to make sure if connection is established. + * + * @param[in] handle NvSciIpc endpoint handle. + * @param[out] events A pointer to the variable into which to store + * the bitwise OR result of new events on success. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_BadParameter Indicates an invalid or NULL argument. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * - ::NvSciError_NotSupported Indicates API is not supported in provided + * endpoint backend type. + * + * @pre NvSciIpcResetEndpointSafe() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): "NvSciIpcEndpoint" + * - API Group + * - Init: Yes + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciIpcGetEvent(NvSciIpcEndpoint handle, uint32_t *events); + +/** + * @brief Get Events + * (safety version) + * + * Returns a bitwise OR operation on new events that occurred since the + * last call to this function. + * + * This function sets @a events to the result of a bitwise OR operation of zero + * or more @c NV_SCI_IPC_EVENT_* constants corresponding to all new events that + * have occurred on the endpoint since: + * - the preceding call to this function on the endpoint or + * - opening the endpoint, if this is the first call to this function on the + * endpoint since it was opened. + * + * The parameter @a events is set to zero if no new events have + * occurred. + * + * There are four types of events: + * - @c NV_SCI_IPC_EVENT_CONN_EST : IPC connection established + * - @c NV_SCI_IPC_EVENT_WRITE : IPC write + * - @c NV_SCI_IPC_EVENT_READ : IPC read + * - @c NV_SCI_IPC_EVENT_CONN_RESET : IPC connection reset + * - @c NV_SCI_IPC_EVENT_WRITE_EMPTY : IPC write FIFO empty + * + * @c NV_SCI_IPC_EVENT_CONN_EST and @c NV_SCI_IPC_EVENT_CONN_RESET events are + * connection event. They're edge-triggered events and once they're read by + * user, events are cleared. + * + * @c NV_SCI_IPC_EVENT_WRITE, @c NV_SCI_IPC_EVENT_READ and + * @c NV_SCI_IPC_EVENT_WRITE_EMPTY events are FIFO status event. + * As long as free buffer is available on write FIFO or data are available in + * read FIFO, API keeps reporting same events. All these events mean that + * connection is still alive. + * + * An @c NV_SCI_IPC_EVENT_CONN_EST event occurs on an endpoint each time a + * connection is established through the endpoint (between the endpoint and + * the other end of the corresponding channel). + * + * An @c NV_SCI_IPC_EVENT_WRITE event occurs on an endpoint: + * -# In conjunction with the delivery of each @c NV_SCI_IPC_CONN_EST event. + * -# Each time the endpoint ceases to be full after a prior @c NvSciIpcWrite* + * call returned @c NvSciError_InsufficientMemory. Note however that an + * implementation is permitted to delay the delivery of this type of + * @c NV_SCI_IPC_EVENT_WRITE event, e.g., for purposes of improving throughput. + * + * An @c NV_SCI_IPC_EVENT_READ event occurs on an endpoint: + * -# In conjunction with the delivery of each @c NV_SCI_IPC_EVENT_CONN_EST + * event, if frames can already be read as of delivery. + * -# Each time the endpoint ceases to be empty after a prior @c NvSciRead* + * call returned @c NvSciError_InsufficientMemory. Note however that an + * implementation is permitted to delay the delivery of this type of + * @c NV_SCI_IPC_EVENT_READ event, e.g., for purposes of improving throughput. + * + * An @c NV_SCI_IPC_EVENT_CONN_RESET event occurs on an endpoint when the user + * calls NvSciIpcResetEndpoint. + * + * An @c NV_SCI_IPC_EVENT_WRITE_EMPTY event occurs on an endpoint when write + * FIFO is empty. user can utilize this event to check if remote endpoint reads + * all data which local endpoint sent. + * + * If this function doesn't return desired events, user must call + * OS-provided blocking API to wait for notification from remote endpoint. + * + * The following are blocking API examples: + * - QNX : NvSciIpcWaitEventQnx() + * - LINUX: select(), poll() etc. + * - NvSciEventService: NvSciEventLoopService::WaitForEvent(),
+ * NvSciEventLoopService::WaitForMultipleEvents() + * + * In case of QNX OS, in order to authenticate user client process, NvSciIpc + * uses custom ability "NvSciIpcEndpoint". Use procmgr_ability_lookup() + * QNX OS API to get ability ID. + * + * @note Before using any read and write NvSciIpc API, user should call this + * API to make sure if connection is established. + * + * @param[in] handle NvSciIpc endpoint handle. + * @param[out] events A pointer to the variable into which to store + * the bitwise OR result of new events on success. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_BadParameter Indicates an invalid or NULL argument. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * - ::NvSciError_NotSupported Indicates API is not supported in provided + * endpoint backend type. + * + * @pre NvSciIpcResetEndpointSafe() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): "NvSciIpcEndpoint" + * - API Group + * - Init: Yes + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciIpcGetEventSafe(NvSciIpcEndpoint handle, uint32_t *events); + +#if defined(__QNX__) +/** + * @brief Wait for an event with timeout + * + * This API is specific to QNX OS. + * Users of NvSciIpc must call this API to wait for an event when + * NvSciIpcGetEventSafe() does not return desired events. + * This API is a blocking call. + * + * In using NvSciEventService, call other blocking APIs instead of this API. + * - NvSciEventLoopService::WaitForEvent() + * - NvSciEventLoopService::WaitForMultipleEvents() + * - NvSciEventLoopService::WaitForMultipleEventsExt() + * + * If user process needs to wait for events from multiple remote NvSciIpc + * endpoint processes, use single blocking call from single thread instead of + * using blocking call per endpoint thread. + * NvSciEventLoopService::WaitForMultipleEvents() blocking call is suitable for + * this use case. + * + * If you're using same chid between this API and NvSciIpcInspectEventQnx(), + * you have to suspend a thread which calls this API before calling + * NvSciIpcInspectEventQnx() in other monitor thread. + * You can suspend thread using delay() or other method. + * + * @note It is only compatible with an endpoint that is opened with + * NvSciIpcOpenEndpoint(). + * + * @param[in] chid The ID of a channel that you established by calling + * ChannelCreate_r() or ChannelCreatePulsePool(). + * @param[in] microseconds A 64-bit integer timeout in microsecond. + * Set to NVSCIIPC_INFINITE_WAIT for an infinite + * timeout. + * @param[in] bytes The size of @pulse buffer + * @param[out] pulse A void * pointer to struct _pulse structure where the + * fuction can store the received data. + * + * @return ::NvSciError, the completion code of the operation: + * - ::EOK Indicates a successful operation. + * - ::EFAULT Indicates A fault occurred when the kernel tried to access + * the buffer provided, or the size of the receive buffer is + * less than the size of @a pulse. The pulse is lost in this + * case. + * - ::EPERM Indicates NvSciIpc is uninitialized. + * - ::EINTR Indicates API was interrupted by a signal. + * - ::ESRCH Indicates The channel indicated by chid doesn't exist. + * - ::ETIMEDOUT Indicates A kernel timeout unblocked the call. + * See TimerTimeout(). + * - ::EINVAL Indicates a invalid parameter + * + * @pre ChannelCreate_r() or ChannelCreatePulsePool() must be successful. + * NvSciIpcSetQnxPulseParamSafe() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: No + * - Async/Sync: Sync + * - Required Privileges(QNX): None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +int32_t NvSciIpcWaitEventQnx(int chid, int64_t microseconds, uint32_t bytes, + void *pulse); + +/** + * @brief Sets the event pulse parameters for QNX. + * + * This API is specific to QNX OS. + * @warning This API is deprecated and just returns NvSciError_NotSupported without + * doing anything in safety build. + * Use NvSciIpcSetQnxPulseParamSafe() instead of this. + * + * When a notification from a peer endpoint is available, the NvSciIpc library + * sends a pulse message to the application. + * This API is to connect @a coid to the endpoint, plug OS event notification + * and set pulse parameters (@a pulsePriority and @a pulseCode), + * thereby enabling the application to receive peer notifications from the + * NvSciIpc library. + * An application can receive notifications from a peer endpoint using + * @c NvSciIpcWaitEventQnx() which is blocking call. + * + * Prior to calling this function, both @c ChannelCreate_r() / + * @c ChannelCreatePulsePool() and @c ConnectAttach_r() must be called in the + * application to obtain the value for @a coid to pass to this function. + * + * To use the priority of the calling thread, set @a pulsePriority to + * @c SIGEV_PULSE_PRIO_INHERIT(-1). The priority must fall within the valid + * range, which can be determined by calling @c sched_get_priority_min() and + * @c sched_get_priority_max(). + * + * Applications can define any value per endpoint for @a pulseCode. + * @a pulseCode will be used by NvSciIpc to signal IPC events and should be + * reserved for this purpose by the application. + * + * @note It is only compatible with an endpoint that is opened with + * NvSciIpcOpenEndpoint(). + * + * @param[in] handle NvSciIpc endpoint handle. + * @param[in] coid The connection ID created from calling + * @c ConnectAttach_r(). + * @param[in] pulsePriority The value for pulse priority. + * @param[in] pulseCode The 8-bit positive pulse code specified by the user. + * The values must be between @c _PULSE_CODE_MINAVAIL + * and @c _PULSE_CODE_MAXAVAIL. + * @param[in] pulseValue Pass NULL for this argument. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_BadParameter Indicates an invalid @a handle. + * - ::NvSciError_NotSupported Indicates API is not supported in provided + * endpoint backend type or OS environment. + * - ::NvSciError_ResourceError Indicates not enough system resources. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * - ::NvSciError_NotPermitted Indicates incorrect API group usage. + * + * @pre Invocation of NvSciIpcOpenEndpoint() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): + * - PROCMGR_AID_INTERRUPTEVENT (Inter-VM only) + * - PROCMGR_AID_PUBLIC_CHANNEL + * - API Group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciIpcSetQnxPulseParam(NvSciIpcEndpoint handle, + int32_t coid, int16_t pulsePriority, int16_t pulseCode, + void *pulseValue); + +/** + * @brief Sets the event pulse parameters for QNX. + * (safety version) + * + * This API is specific to QNX OS. + * When a notification from a peer endpoint is available, the NvSciIpc library + * sends a pulse message to the application. + * This API is to connect @a coid to the endpoint, plug OS event notification + * and set pulse parameters (@a pulsePriority and @a pulseCode), + * thereby enabling the application to receive peer notifications from the + * NvSciIpc library. + * An application can receive notifications from a peer endpoint using + * @c NvSciIpcWaitEventQnx() which is blocking call. + * + * Prior to calling this function, both @c ChannelCreate_r() / + * @c ChannelCreatePulsePool() and @c ConnectAttach_r() must be called in + * the application to obtain the value for @a coid to pass to this function. + * + * To use the priority of the calling thread, set @a pulsePriority to + * @c SIGEV_PULSE_PRIO_INHERIT(-1). The priority must fall within the valid + * range, which can be determined by calling @c sched_get_priority_min() and + * @c sched_get_priority_max(). + * + * Applications can define any value per endpoint for @a pulseCode. + * @a pulseCode will be used by NvSciIpc to signal IPC events and should be + * reserved for this purpose by the application. + * + * @note It is only compatible with an endpoint that is opened with + * NvSciIpcOpenEndpoint(). + * + * @param[in] handle NvSciIpc endpoint handle. + * @param[in] coid The connection ID created from calling + * @c ConnectAttach_r(). + * @param[in] pulsePriority The value for pulse priority. + * @param[in] pulseCode The 8-bit positive pulse code specified by the user. + * The values must be between @c _PULSE_CODE_MINAVAIL + * and @c _PULSE_CODE_MAXAVAIL. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_BadParameter Indicates an invalid @a handle. + * - ::NvSciError_NotSupported Indicates API is not supported in provided + * endpoint backend type or OS environment. + * - ::NvSciError_ResourceError Indicates not enough system resources. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * - ::NvSciError_NotPermitted Indicates incorrect API group usage. + * + * @pre Invocation of NvSciIpcOpenEndpoint() must be successful. + * Invocation of ConnectAttach_r() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: Yes + * - Async/Sync: Sync + * - Required Privileges(QNX): + * - PROCMGR_AID_INTERRUPTEVENT (Inter-VM only) + * - PROCMGR_AID_PUBLIC_CHANNEL + * - API Group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciIpcSetQnxPulseParamSafe(NvSciIpcEndpoint handle, + int32_t coid, int16_t pulsePriority, int16_t pulseCode); + + +/** + * @brief Inspect Event for QNX. + * + * This API is specific to QNX OS. + * When legacy event handling is used, if IVC signalling storm happens in + * specific Intra-VM endpoint which is not bound to NvSciEventService object, + * this API returns that endpoint handle and unregisters relavant events. + * This API is used in a thread to receive semaphore event of + * ChannelCreatePulsePool() when pulse can't be obtained from the fixed pool + * any more. + * In order to prevent unwanted IVC signaling path breakage, Do not call this + * API when semaphore event is not triggered by ChannelCreatePulsePool(). + * + * If you're using same chid between this API and NvSciIpcWaitEventQnx(), + * you have to suspend a thread which calls NvSciIpcWaitEventQnx() before + * calling this API in monitor thread. You can suspend thread using delay() or + * other method. + * + * @note It is only compatible with endpoints that are opened with + * NvSciIpcOpenEndpoint(). + * + * @param[in] chid A chid which is created by ChannelCreatePulsePool() + * @param[in] numEvents A threshold value to unregister Intra-VM IVC + * signalling events. This shall be less than + * num_pulses which is configured in + * ChannelCreatePulsePool(). + * @param[in] epCount endpoint handle count in @epHandleArray. + * @param[out] epHandleArray Array of NvSciIpc endpoint handle which has + * excessive IVC signalling. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success Indicates a successful operation. + * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. + * - ::NvSciError_NoSuchEntry Indicates unknown endpoint. + * - ::NvSciError_InvalidState Indicates an invalid operation state. + * + * @pre Invocation of ChannelCreatePulsePool() must be successful. + * Invocation of ConnectAttach_r() must be successful. + * Invocation of NvSciIpcSetQnxPulseParamSafe() must be successful. + * + * @usage + * - Allowed context for the API call + * - Interrupt: No + * - Signal handler: No + * - Thread-safe: No + * - Async/Sync: Sync + * - Required Privileges: None + * - API Group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciIpcInspectEventQnx(int32_t chid, uint16_t numEvents, + uint32_t epCount, NvSciIpcEndpoint **epHandleArray); +#endif /* __QNX__ */ + +/* + * \brief Checks if loaded NvSciIpc library version is compatible with + * the version the application was compiled against. + * + * This function checks loaded NvSciIpc library version with input NvSciIpc + * library version and sets output variable true provided major version of the + * loaded library is same as @a majorVer and minor version of the + * loaded library is not less than @a minorVer, else sets output to false + * + * @param[in] majorVer build major version. + * @param[in] minorVer build minor version. + * @param[out] isCompatible boolean value stating if loaded NvSciIpc library + * is compatible or not. + * + * @return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a isCompatible is NULL + * + * @pre None + * + * @usage + * - 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 + */ +NvSciError NvSciIpcCheckVersionCompatibility( + uint32_t majorVer, + uint32_t minorVer, + bool* isCompatible); + +/** @} */ +/** @} */ + +#ifdef __cplusplus +} +#endif +#endif /* INCLUDED_NVSCIIPC_H */ diff --git a/nvscistream.h b/nvscistream.h new file mode 100644 index 0000000..c9e7d55 --- /dev/null +++ b/nvscistream.h @@ -0,0 +1,31 @@ +/* + * Copyright (c) 2018-2020 NVIDIA Corporation. All rights reserved. + * + * 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. + */ +/** + * @file + * + * @brief NVIDIA Software Communications Interface (SCI) : NvSciStream + * + * The NvSciStream library is a layer on top of NvSciBuf and NvSciSync libraries + * to provide utilities for streaming sequences of data packets between + * multiple application modules to support a wide variety of use cases. + */ +#ifndef NVSCISTREAM_H +#define NVSCISTREAM_H + +#ifdef __cplusplus +#include +#else +#include +#endif + +#include "nvscistream_api.h" +#include "nvscistream_types.h" + +#endif /* NVSCISTREAM_H */ diff --git a/nvscistream_api.h b/nvscistream_api.h new file mode 100644 index 0000000..b29e6d4 --- /dev/null +++ b/nvscistream_api.h @@ -0,0 +1,3663 @@ +/* + * Copyright (c) 2020-2023 NVIDIA Corporation. All rights reserved. + * + * 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. + */ +/** + * @file + * + * @brief NVIDIA Software Communications Interface (SCI) : NvSciStream + * + * The NvSciStream library is a layer on top of NvSciBuf and NvSciSync libraries + * to provide utilities for streaming sequences of data packets between + * multiple application modules to support a wide variety of use cases. + */ +#ifndef NVSCISTREAM_API_H +#define NVSCISTREAM_API_H + +#ifdef __cplusplus +#include +#else +#include +#endif +#if defined(NV_QNX) +#include "nvdvms_client.h" +#include "nvdvms_types.h" +#endif +#include "nvscierror.h" +#include "nvscibuf.h" +#include "nvscisync.h" +#include "nvsciipc.h" +#include "nvscievent.h" +#include "nvscistream_types.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @defgroup nvscistream_blanket_statements NvSciStream Blanket Statements + * Generic statements applicable for NvSciStream interfaces. + * @ingroup nvsci_stream + * @{ + */ + +/** + * \page nvscistream_page_blanket_statements NvSciStream blanket statements + * \section nvscistream_input_parameters Input parameters + * - NvSciStreamPacket passed as input parameter to NvSciStreamPoolPacketInsertBuffer() + * or NvSciStreamPoolPacketDelete() API is valid if it is returned from a successful call to + * NvSciStreamPoolPacketCreate() API and has not been deleted using + * NvSciStreamPoolPacketDelete(). + * - NvSciStreamPacket passed as input parameter to NvSciStreamBlockPacketAccept() or + * NvSciStreamBlockElementAccept() or NvSciStreamProducerPacketPresent() or + * NvSciStreamConsumerPacketRelease() API is valid if it was received earlier through a + * NvSciStreamEventType_PacketCreate event and NvSciStreamEventType_PacketDelete + * event for the same NvSciStreamPacket is not yet received. + * - NvSciStreamBlock passed as input parameter to an API is valid if it is returned from + * a successful call to any one of the block create APIs and has not yet been destroyed + * using NvSciStreamBlockDelete() unless otherwise stated explicitly. + * - An array of NvSciSyncFence(s) passed as an input parameter to an API is valid if it is not + * NULL and each entry in the array holds a valid NvSciSyncFence. The NvSciSyncFence(s) + * in the array should be in the order according to the indices specified for the NvSciSyncObj(s) + * during NvSciStreamBlockSyncObject() API. That is, if the NvSciSyncObj is set with index == 1, + * its NvSciSyncFence should be the 2nd element in the array. The array should be empty + * if the synchronousOnly flag received through NvSciStreamEventType_SyncAttr from + * other endpoint is true. + * - NvSciIpcEndpoint passed as input parameter to an API is valid if it is obtained + * from successful call to NvSciIpcOpenEndpoint() and has not yet been freed using + * NvSciIpcCloseEndpointSafe(). + * - Pointer to NvSciEventService passed as input parameter to an API is valid if the + * NvSciEventService instance is obtained from successful call to + * NvSciEventLoopServiceCreateSafe() and has not yet been freed using NvSciEventService::Delete(). + * - The input parameter for which the valid value is not stated in the interface specification and not + * covered by any of the blanket statements, it is considered that the entire range of the parameter + * type is valid. + * + * \section nvscistream_out_params Output parameters + * - Output parameters are passed by reference through pointers. Also, since a + * null pointer cannot be used to convey an output parameter, API functions return + * an error code if a null pointer is supplied for a required output parameter unless + * otherwise stated explicitly. Output parameter is valid only if error code returned + * by an API function is NvSciError_Success unless otherwise stated explicitly. + * + * \section nvscistream_return_values Return values + * - Any initialization API will return NvSciError_InvalidState if it cannot be legally + * called in the current VM state. + * - Any initialization API that allocates memory (for example, Block creation + * APIs) to store information provided by the caller, will return + * NvSciError_InsufficientMemory if the allocation fails unless otherwise + * stated explicitly. + * - Any API which takes an NvSciStreamBlock as input parameter returns + * NvSciError_StreamBadBlock error if the NvSciStreamBlock is invalid. + * (Note: Currently in transition from BadParameter) + * - Any API which is only allowed for specific block types returns + * NvSciError_NotSupported if the NvSciStreamBlock input parameter + * does not support the operation. + * - Any API which takes an NvSciStreamPacket as input parameter returns + * NvSciError_StreamBadPacket error if the NvSciStreamPacket is invalid. + * (Note: Currently in transition from BadParameter) + * - All block creation interfaces returns NvSciError_StreamInternalError error if the + * block registration fails. + * - Any element level interface which operates on a block other than the interfaces for + * block creation, NvSciStreamBlockConnect(), NvSciStreamBlockEventQuery(), and + * NvSciStreamBlockEventServiceSetup() will return NvSciError_StreamNotConnected error + * code if the producer block in the stream is not connected to every consumer block in + * the stream or the NvSciStreamEventType_Connected event from the block is not yet queried + * by the application by calling NvSciStreamBlockEventQuery() interface. + * - If any API detects an inconsistency in internal data structures, + * it will return an NvSciError_StreamInternalError error code. + * - If an API function is invoked with parameters such that two or more failure modes are + * possible, it is guaranteed that one of those failure modes will occur, but it is not + * guaranteed which. + * + * \section nvscistream_concurrency Concurrency + * - Unless otherwise stated explicitly in the interface specifications, + * any two or more NvSciStream functions can be called concurrently + * without any side effects. The effect will be as if the functions were + * executed sequentially. The order of execution is not guaranteed. + */ + +/** + * @} + */ + +/** + * @defgroup nvsci_stream Streaming APIs + * + * The NvSciStream library is a layer on top of NvSciBuf and NvSciSync libraries + * that provides utilities for streaming sequences of data packets between + * multiple application modules to support a wide variety of use cases. + * + * @ingroup nvsci_group_stream + * @{ + */ + + /** + * @defgroup nvsci_stream_apis NvSciStream APIs + * + * Methods to setup and stream sequences of data packets. + * + * @ingroup nvsci_stream + * @{ + */ + +/*! + * \brief Establishes connection between two blocks referenced + * by the given NvSciStreamBlock(s). + * + * - Connects an available output of one block with an available + * input of another block. + * + * - Each input and output can only have one connection. A stream is operational + * when all inputs and outputs of all blocks in the stream have a connection. + * + * @pre + * - The upstream block has an available output connection. + * - The downstream block has an available input connection. + * + * Actions + * - Establish a connection between the two blocks. + * + * Postconditions + * - When a block has a connection to producer as well as connection to + * every consumer(s) in the stream, it will receive a NvSciStreamEventType_Connected + * event. + * + * \param[in] upstream NvSciStreamBlock which references an upstream block. + * Valid value: A valid NvSciStreamBlock which does not reference + * a Pool or Queue block. + * \param[in] downstream NvSciStreamBlock which references a downstream block. + * Valid value: A valid NvSciStreamBlock which does not reference + * a Pool or Queue block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success The connection was made successfully. + * - ::NvSciError_InsufficientResource block referenced by @a upstream argument has + * no available outputs or block referenced by @a downstream argument has + * no available inputs. + * - ::NvSciError_AccessDenied: block referenced by @a upstream argument + * or block referenced by @a downstream argument(for example, Pool or Queue) + * does not allow explicit connection via NvSciStreamBlockConnect(). + */ +/*! - ::NvSciError_InvalidState: Multicast block referenced by @a upstream argument + * is not ready for late consumer connections. + */ +/*! + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Async + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamBlockConnect( + NvSciStreamBlock const upstream, + NvSciStreamBlock const downstream +); + +/*! \brief Creates an instance of producer block, associates + * the given pool referenced by the given NvSciStreamBlock + * with it and returns a NvSciStreamBlock referencing the + * created producer block. + * + * - Creates a block for the producer end of a stream. All streams + * require one producer block. A producer block must have a pool + * associated with it for managing available packets. Producer blocks have one + * output connection and no input connections. + * + * - Once the stream is operational, this block can be used to exchange + * NvSciSync information with the consumer and NvSciBuf information with the pool. + * + * @pre + * - None. + * + * Actions + * - Creates a new instance of producer block. + * - Associates the given pool block with the producer block. + * + * Postconditions + * - The block is ready to be connected to other stream blocks. + * - The block can be queried for events. + * + * \param [in] pool NvSciStreamBlock which references a pool block + * to be associated with the producer block. + * \param [out] producer NvSciStreamBlock which references a + * new producer block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success A new producer block was set up successfully. + * - ::NvSciError_BadParameter If the output parameter @a producer + * is a null pointer or the @a pool parameter does not reference a + * pool block. + * - ::NvSciError_InsufficientResource If the pool block is already + * associated with another producer. + * - ::NvSciError_StreamInternalError The producer block cannot be + * initialized properly. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamProducerCreate( + NvSciStreamBlock const pool, + NvSciStreamBlock *const producer +); + + +/*! \brief Creates an instance of producer block, associates + * the given pool referenced by the given NvSciStreamBlock + * with it and returns a NvSciStreamBlock referencing the + * created producer block. + * + * - Creates a block for the producer end of a stream. All streams + * require one producer block. A producer block must have a pool + * associated with it for managing available packets. Producer blocks have one + * output connection and no input connections. + * + * - Waits for the CRC validation done by applications before switching to runtime + * if @a crcValidate is set to true. + * + * - Once the stream is operational, this block can be used to exchange + * NvSciSync information with the consumer and NvSciBuf information with the pool. + * + * @pre + * - None. + * + * Actions + * - Creates a new instance of producer block. + * - Associates the given pool block with the producer block. + * + * Postconditions + * - The block is ready to be connected to other stream blocks. + * - The block can be queried for events. + * + * \param [in] pool NvSciStreamBlock which references a pool block + * to be associated with the producer block. + * \param [in] crcValidate Indicates whether validation step is required + * before switching to runtime. + * \param [out] producer NvSciStreamBlock which references a + * new producer block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success A new producer block was set up successfully. + * - ::NvSciError_BadParameter If the output parameter @a producer + * is a null pointer or the @a pool parameter does not reference a + * pool block. + * - ::NvSciError_InsufficientResource If the pool block is already + * associated with another producer. + * - ::NvSciError_StreamInternalError The producer block cannot be + * initialized properly. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamProducerCreate2( + NvSciStreamBlock const pool, + bool const crcValidate, + NvSciStreamBlock *const producer +); + +/*! \brief Creates an instance of consumer block, associates + * the given queue block referenced by the given NvSciStreamBlock + * with it and returns a NvSciStreamBlock referencing the created + * consumer block. + * + * - Creates a block for the consumer end of a stream. All streams + * require at least one consumer block. A consumer block must have + * a queue associated with it for managing pending packets. Consumer blocks have + * one input connection and no output connections. + * + * - Once the stream is operational, this block can be used to exchange + * NvSciSync information with the producer and NvSciBuf information with the pool. + * + * @pre + * - None. + * + * Actions + * - Creates a new instance of consumer block. + * - Associates the given queue block with the consumer block. + * + * Postconditions + * - The block is ready to be connected to other stream blocks. + * - The block can be queried for events. + * + * \param [in] queue NvSciStreamBlock which references a queue + * block to be associated with the consumer block. + * \param [out] consumer NvSciStreamBlock which references a + * new consumer block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success A new consumer block was set up successfully. + * - ::NvSciError_BadParameter If the output parameter @a consumer + * is a null pointer or the @a queue parameter does not reference a + * queue block. + * - ::NvSciError_InsufficientResource If the queue block is already bound to + * another consumer. + * - ::NvSciError_StreamInternalError The consumer block cannot be + * initialized properly. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamConsumerCreate( + NvSciStreamBlock const queue, + NvSciStreamBlock *const consumer +); + + +/*! \brief Creates an instance of consumer block, associates + * the given queue block referenced by the given NvSciStreamBlock + * with it and returns a NvSciStreamBlock referencing the created + * consumer block. + * + * - Enables the exporting the CRC data for validation with producer + * to switch to runtime if @a crcValidate is true. + * + * - Creates a block for the consumer end of a stream. All streams + * require at least one consumer block. A consumer block must have + * a queue associated with it for managing pending packets. Consumer blocks have + * one input connection and no output connections. + * + * - Waits for CRC data provided by the application before switching to + * runtime if @a crcValidate is true. + * + * - Once the stream is operational, this block can be used to exchange + * NvSciSync information with the producer and NvSciBuf information with the pool. + * + * @pre + * - None. + * + * Actions + * - Creates a new instance of consumer block. + * - Associates the given queue block with the consumer block. + * + * Postconditions + * - The block is ready to be connected to other stream blocks. + * - The block can be queried for events. + * + * \param [in] queue NvSciStreamBlock which references a queue + * block to be associated with the consumer block. + * \param [in] crcValidate Indicates whether validation step is required + * before switching to runtime. + * \param [out] consumer NvSciStreamBlock which references a + * new consumer block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success A new consumer block was set up successfully. + * - ::NvSciError_BadParameter If the output parameter @a consumer + * is a null pointer or the @a queue parameter does not reference a + * queue block. + * - ::NvSciError_InsufficientResource If the queue block is already bound to + * another consumer. + * - ::NvSciError_StreamInternalError The consumer block cannot be + * initialized properly. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamConsumerCreate2( + NvSciStreamBlock const queue, + bool const crcValidate, + NvSciStreamBlock *const consumer +); + + +/*! + * \brief Creates an instance of static pool block and returns a + * NvSciStreamBlock referencing the created pool block. + * + * - Creates a block for management of a stream's packet pool. Every producer + * must be associated with a pool block, provided at the producer's creation. + * + * - A static pool has a fixed number of packets which must be created and accepted + * before the first free packet is acquired by the producer block. + * + * - Once the stream is operational and the application has determined + * the packet requirements(packet element count and packet element buffer attributes), + * this block can be used to register NvSciBufObj(s) to each packet. + * + * @pre + * - None. + * + * Actions + * - Allocates data structures to describe packets. + * - Initializes queue of available packets. + * + * Postconditions + * - The block is ready to be connected to other stream blocks. + * - The block can be queried for events. + * + * \param[in] numPackets Number of packets. + * \param[out] pool NvSciStreamBlock which references a + * new pool block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success A new pool block was set up successfully. + * - ::NvSciError_BadParameter The output parameter @a pool is a null pointer. + * - ::NvSciError_StreamInternalError The pool block cannot be initialized properly. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamStaticPoolCreate( + uint32_t const numPackets, + NvSciStreamBlock *const pool +); + +/*! + * \brief Creates an instance of mailbox queue block and returns a + * NvSciStreamBlock referencing the created mailbox queue block. + * + * - Creates a block for managing the packets that are ready to be + * acquired by the consumer. This is one of the two available types of queue + * block. Every consumer must be associated with a queue block, provided at + * the time the consumer is created. + * + * - A mailbox queue holds a single packet. If a new packet arrives, the packet + * currently being held is replaced and returned to the pool for reuse. + * + * - This type of queue is intended for consumer applications + * which don't need to process every packet and always wish to have the + * latest input available. + * + * - Once connected, the application does not directly interact with this block. + * The consumer block will communicate with the queue block to obtain new packets. + * + * @pre + * - None. + * + * Actions + * - Initialize a queue to hold a single packet for acquire. + * + * Postconditions + * - The block is ready to be connected to other stream blocks. + * + * \param[out] queue NvSciStreamBlock which references a + * new mailbox queue block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success A new mailbox queue block was set up successfully. + * - ::NvSciError_BadParameter The output parameter @a queue is a null pointer. + * - ::NvSciError_StreamInternalError The mailbox queue block cannot be initialized properly. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamMailboxQueueCreate( + NvSciStreamBlock *const queue +); + +/*! + * \brief Creates an instance of FIFO queue block and returns a + * NvSciStreamBlock referencing the created FIFO queue block. + * + * - Creates a block for tracking the list of packets available to be + * acquired by the consumer. This is one of the two available types of queue block. + * Every consumer must be associated with a queue block, provided at the time the + * consumer is created. + * + * - A FIFO queue can hold up to the complete set of packets created, + * which will be acquired in the order they were presented. + * + * - This type of queue is intended for consumer applications which require + * processing of every packet that is presented. + * + * - Once connected, the application does not directly interact with this block. + * The consumer block will communicate with it to obtain new packets. + * + * @pre + * - None. + * + * Actions + * - Initialize a queue to manage waiting packets. + * + * Postconditions + * - The block is ready to be connected to other stream blocks. + * + * \param[out] queue NvSciStreamBlock which references a + * new FIFO queue block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success A new FIFO queue block was set up successfully. + * - ::NvSciError_BadParameter The output parameter @a queue is a null pointer. + * - ::NvSciError_StreamInternalError The FIFO queue block cannot be initialized properly. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamFifoQueueCreate( + NvSciStreamBlock *const queue +); + +/*! + * \brief Creates an instance of multicast block and returns a + * NvSciStreamBlock referencing the created multicast block. + * + * - Creates a block allowing for one input and one or more outputs. + * + * - Multicast block broadcasts messages sent from upstream to all of the + * downstream blocks. + * + * - Mulitcast block aggregates messages of the same type from downstream into + * a single message before sending it upstream. + * + * @pre + * - None. + * + * Actions + * - Initializes a block that takes one input and one or more outputs. + * + * Postconditions + * - The block is ready to be connected to other stream blocks. + * + * \param[in] outputCount Number of output blocks that will be connected. + * Valid value: 1 to NvSciStreamQueryableAttrib_MaxMulticastOutputs + * attribute value queried by successful call to NvSciStreamAttributeQuery() + * API. + * \param[out] multicast NvSciStreamBlock which references a + * new multicast block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success A new multicast block was set up successfully. + * - ::NvSciError_BadParameter The output parameter @a multicast is a null + * pointer or @a outputCount is larger than the number allowed. + * - ::NvSciError_StreamInternalError The multicast block cannot be + * initialized properly. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamMulticastCreate( + uint32_t const outputCount, + NvSciStreamBlock *const multicast +); + +/*! + * \brief Creates an instance of IpcSrc block and returns a + * NvSciStreamBlock referencing the created IpcSrc block. + * + * - Creates the upstream half of an IPC block pair which allows + * stream information to be transmitted between processes. If producer and + * consumer(s) present in the same process, then there is no need for + * IPC block pair. + * + * - IpcSrc block has one input connection and no output connection. + * + * - An IpcSrc block connects to downstream through the NvSciIpcEndpoint + * used to create the block. + * + * @pre + * - None. + * + * Actions + * - Establishes connection through NvSciIpcEndpoint. + * + * Postconditions + * - The block is ready to be connected to other stream blocks. + * + * \param[in] ipcEndpoint NvSciIpcEndpoint handle. + * \param[in] syncModule NvSciSyncModule that is used to import a + * NvSciSyncAttrList across an IPC boundary. This must be the + * module associated with the NvSciSyncAttrList that is used in + * specifying the NvSciSyncObj waiter requirements. + * \param[in] bufModule NvSciBufModule that is used to import a + * NvSciBufAttrList across an IPC boundary. This must be the + * module associated with the NvSciBufAttrList that is used in + * specifying the packet element information. + * \param[out] ipc NvSciStreamBlock which references a + * new IpcSrc block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success A new IpcSrc block was set up successfully. + * - ::NvSciError_StreamInternalError: If connection establishment through + * @a ipcEndpoint fails or IpcSrc block cannot be initialized properly. + * - ::NvSciError_BadParameter The output parameter @a ipc is a null pointer. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamIpcSrcCreate( + NvSciIpcEndpoint const ipcEndpoint, + NvSciSyncModule const syncModule, + NvSciBufModule const bufModule, + NvSciStreamBlock *const ipc +); + +/*! + * \brief Creates an instance of IpcSrc or C2CSrc block and returns a + * NvSciStreamBlock referencing the created block. + * + * - If input NvSciIpcEndpoint is of type IPC, then this API Creates + * the upstream half of an IPC block pair which allows stream information + * to be transmitted between processes. + * + * - If input NvSciIpcEndpoint is of type C2C, then this API Creates + * the upstream half of an C2C block pair which allows stream information + * to be transmitted between chips. + * + * - If input NvSciIpcEndpoint is of type C2C and queue is not provided by + * application, driver creates and binds a default FIFO queue with C2CSrc block. + * Note that this default queue block is not visible to application. + * + * If producer and consumer(s) are present in the same process, then there is + * no need for IPC or C2C block pairs. + * + * - IpcSrc/C2CSrc block has one input connection and no output connection. + * + * - An IpcSrc/C2CSrc block connects to downstream through the NvSciIpcEndpoint + * used to create the block. + * + * @pre + * - None. + * + * Actions + * - Establishes connection through NvSciIpcEndpoint. + * + * Postconditions + * - The block is ready to be connected to other stream blocks. + * + * \param[in] ipcEndpoint NvSciIpcEndpoint handle. + * \param[in] syncModule NvSciSyncModule that is used to import a + * NvSciSyncAttrList across an IPC boundary. This must be the + * module associated with the NvSciSyncAttrList that is used in + * specifying the NvSciSyncObj waiter requirements. + * \param[in] bufModule NvSciBufModule that is used to import a + * NvSciBufAttrList across an IPC boundary. This must be the + * module associated with the NvSciBufAttrList that is used in + * specifying the packet element information. + * \param[in] queue NvSciStreamBlock that is used to enqueue the Packets + * from the Producer and send those packets downstream to C2CDst + * block. + * \param[out] ipc NvSciStreamBlock which references a + * new IpcSrc or C2CSrc block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success A new IpcSrc or C2CSrc block was set up successfully. + * - ::NvSciError_StreamInternalError: If connection establishment through + * @a ipcEndpoint fails or IpcSrc or C2CSrc block cannot be initialized properly + * or default FIFO queue cannot be initialized properly when queue is not + * provided by user if the @a ipcEndpoint is C2C type. + * - ::NvSciError_BadParameter The output parameter @a ipc is a null pointer. + * - ::NvSciError_BadParameter The input parameter @a queue is a invalid and the + * @a ipcEndpoint is C2C type. + * - ::NvSciError_BadParameter The input parameter @a queue is a valid and the + * @a ipcEndpoint is IPC type. + * - ::NvSciError_InsufficientResource If the queue block is already + * associated with any other consumer or C2CSrc block. + * - ::NvSciError_NotInitialized @a ipcEndpoint is uninitialized. + * - ::NvSciError_NotSupported Not supported in provided endpoint backend type + * - ::NvSciError_NotSupported C2CSrc block not supported in this safety build. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamIpcSrcCreate2( + NvSciIpcEndpoint const ipcEndpoint, + NvSciSyncModule const syncModule, + NvSciBufModule const bufModule, + NvSciStreamBlock const queue, + NvSciStreamBlock *const ipc +); + +/*! + * \brief Creates an instance of IpcDst block and returns a + * NvSciStreamBlock referencing the created IpcDst block. + * + * - Creates the downstream half of an IPC block pair which allows + * stream information to be transmitted between processes.If producer and + * consumer(s) present in the same process, then there is no need for + * IPC block pair. + * + * - IpcDst block has one output connection and no input connection. + * + * - An IpcDst block connects to upstream through the NvSciIpcEndpoint used + * to create the block. + * + * @pre + * - None. + * + * Actions + * - Establishes connection through NvSciIpcEndpoint. + * + * Postconditions + * - The block is ready to be connected to other stream blocks. + * + * \param[in] ipcEndpoint NvSciIpcEndpoint handle. + * \param[in] syncModule NvSciSyncModule that is used to import a + * NvSciSyncAttrList across an IPC boundary. This must be the + * module associated with the NvSciSyncAttrList that is used in + * specifying the NvSciSyncObj waiter requirements. + * \param[in] bufModule NvSciBufModule that is used to import a + * NvSciBufAttrList across an IPC boundary. This must be the + * module associated with the NvSciBufAttrList that is used in + * specifying the packet element information. + * \param[out] ipc NvSciStreamBlock which references a + * new IpcDst block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success A new IpcDst block was set up successfully. + * - ::NvSciError_StreamInternalError: If connection establishment through + * @a ipcEndpoint fails or IpcDst block can't be initialized properly. + * - ::NvSciError_BadParameter The output parameter @a ipc is a null pointer. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamIpcDstCreate( + NvSciIpcEndpoint const ipcEndpoint, + NvSciSyncModule const syncModule, + NvSciBufModule const bufModule, + NvSciStreamBlock *const ipc +); + +/*! + * \brief Creates an instance of IpcDst or C2CDst block and returns a + * NvSciStreamBlock referencing the created block. + * + * - If input NvSciIpcEndpoint is of type IPC, then this API Creates + * the downstream half of an IPC block pair which allows stream information + * to be transmitted between processes. + * + * - If input NvSciIpcEndpoint is of type C2C, then this API Creates + * the downstream half of an C2C block pair which allows stream information + * to be transmitted between chips. + * + * If producer and consumer(s) are present in the same process, then there is + * no need for IPC or C2C block pairs. + * + * - IpcDst/C2CDst block has one output connection and no input connection. + * + * - An IpcDst/C2CDst block connects to downstream through the NvSciIpcEndpoint + * used to create the block. + * + * @pre + * - None. + * + * Actions + * - Establishes connection through NvSciIpcEndpoint. + * + * Postconditions + * - The block is ready to be connected to other stream blocks. + * + * \param[in] ipcEndpoint NvSciIpcEndpoint handle. + * \param[in] syncModule NvSciSyncModule that is used to import a + * NvSciSyncAttrList across an IPC boundary. This must be the + * module associated with the NvSciSyncAttrList that is used in + * specifying the NvSciSyncObj waiter requirements. + * \param[in] bufModule NvSciBufModule that is used to import a + * NvSciBufAttrList across an IPC boundary. This must be the + * module associated with the NvSciBufAttrList that is used in + * specifying the packet element information. + * \param[in] pool NvSciStreamBlock that is used to enqueue the Packets + * received from C2CSrc block and send those packets downstream to + * . consumer block. + * \param[out] ipc NvSciStreamBlock which references a + * new IpcDst or C2CDst block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success A new IpcDst or C2CDst block was set up successfully. + * - ::NvSciError_StreamInternalError: If connection establishment through + * @a ipcEndpoint fails or IpcDst or C2CDst block cannot be initialized properly. + * - ::NvSciError_BadParameter The output parameter @a ipc is a null pointer. + * - ::NvSciError_BadParameter The input parameter @a pool is a invalid and the + * @a ipcEndpoint is C2C type. + * - ::NvSciError_BadParameter The input parameter @a pool is a valid and the + * @a ipcEndpoint is IPC type. + * - ::NvSciError_InsufficientResource If the pool block is already + * associated with any other producer or C2CDst block. + * - ::NvSciError_NotInitialized @a ipcEndpoint is uninitialized. + * - ::NvSciError_NotSupported Not supported in provided endpoint backend type + * - ::NvSciError_NotSupported C2CSrc block not supported in this safety build. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamIpcDstCreate2( + NvSciIpcEndpoint const ipcEndpoint, + NvSciSyncModule const syncModule, + NvSciBufModule const bufModule, + NvSciStreamBlock const pool, + NvSciStreamBlock *const ipc +); + +/*! +* \brief Creates an instance of Limiter block and returns a +* NvSciStreamBlock referencing the created Limiter block. +* +* - Creates a block to limit the number of packets allowed to be sent +* downstream to a consumer block. +* +* - A limiter block can be inserted anywhere in the stream between the +* Producer and Consumer Blocks, but its primary intent is to be inserted +* between a Multicast block and a Consumer. +* + * @pre +* - None. +* +* Actions +* - Creates a new instance of Limiter block. +* +* Postconditions +* - The block is ready to be connected to other stream blocks. +* +* \param[in] maxPackets Number of packets allowed to be sent downstream +* to a consumer block. +* \param[out] limiter NvSciStreamBlock which references a +* new limiter block. +* +* \return ::NvSciError, the completion code of this operation. +* - ::NvSciError_Success A new Limiter block was set up successfully. +* - ::NvSciError_BadParameter The output parameter @a limiter is a null +* pointer. +* - ::NvSciError_StreamInternalError The Limiter block can't be initialized +* properly. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No +*/ +NvSciError NvSciStreamLimiterCreate( + uint32_t const maxPackets, + NvSciStreamBlock *const limiter +); + + +/*! +* \brief Creates an instance of ReturnSync block and returns a +* NvSciStreamBlock referencing the created ReturnSync block. +* +* - Creates a block to wait for the fences for the packets received +* from consumer before sending them upstream. +* +* - A ReturnSync block can be inserted anywhere in the stream between the +* Producer and Consumer Blocks, but its primary intent is to be inserted +* between a limiter block and a Consumer. +* + * @pre +* - None. +* +* Actions +* - Creates a new instance of ReturnSync block. +* +* Postconditions +* - The block is ready to be connected to other stream blocks. +* +* \param[in] syncModule NvSciSyncModule that will be used +* during fence wait operations. +* \param[out] returnSync NvSciStreamBlock which references a +* new ReturnSync block. +* +* \return ::NvSciError, the completion code of this operation. +* - ::NvSciError_Success A new ReturnSync block was set up successfully. +* - ::NvSciError_BadParameter The output parameter @a returnSync is a null +* pointer. +* - ::NvSciError_StreamInternalError The ReturnSync block can't be initialized +* properly. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No +*/ +NvSciError NvSciStreamReturnSyncCreate( + NvSciSyncModule const syncModule, + NvSciStreamBlock *const returnSync +); + +/*! +* \brief Creates an instance of PresentSync block and returns a +* NvSciStreamBlock referencing the created PresentSync block. +* +* - Creates a block to wait for the fences for the packets received +* from producer before sending them downstream. +* +* - The primary usecase is to insert PresentSync block between producer +* and C2CSrc block. +* + * @pre +* - None. +* +* Actions +* - Creates a new instance of PresentSync block. +* +* Postconditions +* - The block is ready to be connected to other stream blocks. +* +* \param[in] syncModule NvSciSyncModule that will be used +* during fence wait operations. +* \param[out] presentSync NvSciStreamBlock which references a +* new PresentSync block. +* +* \return ::NvSciError, the completion code of this operation. +* - ::NvSciError_Success A new PresentSync block was set up successfully. +* - ::NvSciError_BadParameter The output parameter @a presentSync is a null +* pointer. +* - ::NvSciError_StreamInternalError The PresentSync block can't be initialized +* properly. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No +*/ +NvSciError NvSciStreamPresentSyncCreate( + NvSciSyncModule const syncModule, + NvSciStreamBlock *const presentSync +); + +/*! + * \brief Queries for the next event from block referenced by the given + * NvSciStreamBlock, optionally waiting when the an event is not yet + * available, then removes the event from the priority queue and returns + * the event type to the caller. Additional information about the event + * can be queried through the appropriate block functions. + * + * If the block is set up to use NvSciEventService, applications should call + * this API with zero timeout after waking up from waiting on the + * NvSciEventNotifier obtained from NvSciStreamBlockEventServiceSetup() + * interface, and applications should query all the events in the block + * after waking up. Wake up due to spurious events is possible, and in + * that case calling this function will return no event. + * + * @pre + * - The block to query has been created. + * + * Actions + * - If the block is not set up to use NvSciEventService, wait until + * an event is pending on the block or the specified timeout period + * is reached, whichever comes first. + * - Retrieves the next event (if any) from the block, returning the + * NvSciStreamEventType. + * + * Postconditions + * - As defined for each NvSciStreamEventType, dequeuing an event + * may allow other operations on the block to proceed. + * + * \param[in] block NvSciStreamBlock which references a block. + * \param[in] timeoutUsec Timeout in microseconds (-1 to wait forever). + * \param[out] event Location in which to return the NvSciStreamEventType. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success The output argument @a event is filled with the + * queried event data. + * - ::NvSciError_Timeout The @a timeoutUsec period was reached before an + * event became available. + * - ::NvSciError_BadParameter The output argument @a event is null, or + * @a timeoutUsec is not zero if the block has been set up to use + * NvSciEventService. + * - ::NvSciError_InvalidState If no more references can be taken on + * the NvSciSyncObj or NvSciBufObj while duping the objects. + * - Any error/panic behavior that NvSciSyncAttrListClone() and NvSciBufAttrListClone() + * can generate. + * - Panics if NvSciSyncObj or NvSciBufObj is invalid while duping the objects. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciStreamBlockEventQuery( + NvSciStreamBlock const block, + int64_t const timeoutUsec, + NvSciStreamEventType *const eventType +); + +/*! + * \brief Queries the error code for an error event. + * + * If multiple errors occur before this query, only return the first error + * code. All subsequent errors are ignored until the error code is queried, + * with the assumption that they are side effects of the first one. + * + * @pre + * None + * + * Actions + * None + * + * Postconditions + * None + * + * \param[in] block NvSciStreamBlock which references a block. + * \param[out] status Pointer to location in which to store the error code. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a status is NULL. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: Yes + * - De-Init: No + */ +NvSciError +NvSciStreamBlockErrorGet( + NvSciStreamBlock const block, + NvSciError* const status +); + +/*! + * \brief Queries the number of consumers downstream of the block referenced + * by the given NvSciStreamBlock (or 1 if the block itself is a consumer). + * + * Used primarily by producer to determine the number of signaller sync + * objects and corresponding fences that must be waited for before + * reusing packet buffers. + * + * @pre + * - Block must have received NvSciStreamEventType_Connected event indicating + * that the stream is fully connected. + * + * Actions + * - None. + * + * Postconditions + * - None. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[out] numConsumers: Pointer to location in which to store the count. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Count successfully retrieved. + * - ::NvSciError_BadAddress: @a numConsumers is NULL. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockConsumerCountGet( + NvSciStreamBlock const block, + uint32_t* const numConsumers +); + +/*! + * \brief Indicates a group of setup operations identified by @a setupType + * on @a block are complete. The relevant information will be transmitted + * to the rest of the stream, triggering events and becoming available + * for query where appropriate. + * + * @pre + * - See descriptions for specific NvSciStreamSetup enum values. + * + * Actions + * - See descriptions for specific NvSciStreamSetup enum values. + * + * Postconditions + * - See descriptions for specific NvSciStreamSetup enum values. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[in] setupType: Identifies the group of setup operations whose status + * is to be updated. + * \param[in] completed: Provided for future support of dynamically + * reconfigurable streams. Currently must always be true. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_NotYetAvailable: Prerequisites for marking the group + * identified by @a setupType as complete have not been met. + * - ::NvSciError_InsufficientData: Not all data associated with the group + * identified by @a setupType has been provided. + * - ::NvSciError_AlreadyDone: The group identified by @a setupType has + * already been marked complete. + * - ::NvSciError_BadParameter: @a completed is not true. + * - ::NvSciError_Busy: An NvSciStream interface in another thread is + * currently interacting with the group identified by @a setupType on + * this @a block. The call can be tried again, but this typically + * indicates a flaw in application design. + * - ::NvSciError_InsufficientMemory: Failed to allocate memory needed to + * process the data. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Async + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockSetupStatusSet( + NvSciStreamBlock const block, + NvSciStreamSetup const setupType, + bool const completed +); + +/*! + * \brief Adds an element with the specified @a userType and @a bufAttrList + * to the list of elements defined by @a block. + * + * When called on a producer or consumer block, it adds to the list of + * elements which that endpoint is capable of supporting. + * When called on a pool block, it adds to the list of elements which will + * be used for the final packet layout. This interface is not supported on + * the secondary pools. + * + * @pre + * - The block must be in the phase where element export is available. + * For producer and consumer blocks, this begins after receiving the + * NvSciStreamEventType_Connected event. For pool blocks, this begins + * after receiving the NvSciStreamEventType_Elements event. In all cases, + * this phase ends after a call to NvSciStreamBlockSetupStatusSet() with + * NvSciStreamSetup_ElementExport. + * + * Actions + * - Appends the specified element to the current list. + * + * Postconditions + * - None. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[in] userType: User-defined type to identify the element. + * \param[in] bufAttrList: Buffer attribute list for element. NvSciStream + * will clone the attribute list, so the caller can safely free it once + * the function returns. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_NotYetAvailable: The prerequisite event has not yet arrived. + * - ::NvSciError_NoLongerAvailable: The element export phase was completed. + * - ::NvSciError_Busy: An NvSciStream interface in another thread is + * currently interacting with the block's exported element information. + * The call can be retried, but this typically indicates a flaw in + * application design. + * - ::NvSciError_Overflow: The number of elements in the list has reached + * the maximum allowed value. + * - ::NvSciError_AlreadyInUse: An element with the specified @a userType + * already exists in the list. + * - ::NvSciError_InsufficientMemory: Unable to allocate storage for the new + * element. + * - Any error that NvSciBufAttrListClone() can generate. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockElementAttrSet( + NvSciStreamBlock const block, + uint32_t const userType, + NvSciBufAttrList const bufAttrList +); + +/*! + * \brief Queries the number of elements received at the @a block from the + * source identified by @a queryBlockType. + * + * When called on a producer or consumer block, @a queryBlockType must be + * NvSciStreamBlockType_Pool, and the query is for the list of allocated + * elements sent from the pool. + * When called on a primary pool block, @a queryBlockType may be either + * NvSciStreamBlockType_Producer or NvSciStreamBlockType_Consumer, and + * the query is for the list of supported elements sent from the referenced + * endpoint(s). + * When called on a secondary pool block, @a queryBlockType may be either + * NvSciStreamBlockType_Producer or NvSciStreamBlockType_Consumer. + * If @a queryBlockType is NvSciStreamBlockType_Producer, the query is for + * the list of allocated elements sent from the primary pool. + * If @a queryBlockType is NvSciStreamBlockType_Consumer, the query is for + * referenced the list of supported elements sent from consumer(s). + * + * @pre + * - Block must be in the phase where element import is available, after + * receiving an NvSciStreamEventType_Elements event and before a call to + * NvSciStreamBlockSetupStatusSet() with NvSciStreamSetup_ElementImport. + * + * Actions + * - None. + * + * Postconditions + * - None. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[in] queryBlockType: Identifies the source of the element list. + * \param[out] numElements: Pointer to location in which to store the count. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a numElements is NULL. + * - ::NvSciError_BadParameter: The @a queryBlockType is not valid for + * the @a block. + * - ::NvSciError_NotYetAvailable: The requested element information has + * not yet arrived. + * - ::NvSciError_NoLongerAvailable: The element import phase was completed. + * - ::NvSciError_Busy: An NvSciStream interface in another thread is + * currently interacting with the block's imported element information. + * The call can be retried. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockElementCountGet( + NvSciStreamBlock const block, + NvSciStreamBlockType const queryBlockType, + uint32_t* const numElements +); + +/*! + * \brief Queries the user-defined type and/or buffer attribute list for + * an entry, referenced by @a elemIndex, in list of elements received at + * the @a block from the source identified by @a queryBlockType. + * At least one of @a userType or @a bufAttrList must be non-NULL, but + * if the caller is only interested in one of the values, the other + * can be NULL. + * + * When called on a producer or consumer block, @a queryBlockType must be + * NvSciStreamBlockType_Pool, and the query is for the list of allocated + * elements sent from the pool. + * When called on a primary pool block, @a queryBlockType may be either + * NvSciStreamBlockType_Producer or NvSciStreamBlockType_Consumer, and + * the query is for the list of supported elements sent from the referenced + * endpoint(s). + * When called on a secondary pool block, @a queryBlockType may be either + * NvSciStreamBlockType_Producer or NvSciStreamBlockType_Consumer. + * If @a queryBlockType is NvSciStreamBlockType_Producer, the query is for + * the list of allocated elements sent from the primary pool. If the element + * is unused by the consumer, an NULL NvSciBufAttrList is returned. + * If @a queryBlockType is NvSciStreamBlockType_Consumer, the query is for + * referenced the list of supported elements sent from consumer(s). + * + * @pre + * - Block must be in the phase where element import is available, after + * receiving an NvSciStreamEventType_Elements event and before a call to + * NvSciStreamBlockSetupStatusSet() with NvSciStreamSetup_ElementImport. + * + * Actions + * - None. + * + * Postconditions + * - None. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[in] queryBlockType: Identifies the source of the element list. + * \param[in] elemIndex: Index of the entry in the element list to query. + * \param[out] userType: Pointer to location in which to store the type. + * \param[out] bufAttrList: Pointer to location in which to store the + * attribute list. The caller owns the attribute list handle received + * and should free it when it is no longer needed. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a userType and @a bufAttrList are both NULL. + * - ::NvSciError_BadParameter: The @a queryBlockType is not valid for + * the @a block or the @a elemIndex is out of range. + * - ::NvSciError_NotYetAvailable: The requested element information has + * not yet arrived. + * - ::NvSciError_NoLongerAvailable: The element import phase was completed. + * - ::NvSciError_Busy: An NvSciStream interface in another thread is + * currently interacting with the block's imported element information. + * The call can be retried. + * - Any error that NvSciBufAttrListClone() can generate. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockElementAttrGet( + NvSciStreamBlock const block, + NvSciStreamBlockType const queryBlockType, + uint32_t const elemIndex, + uint32_t* const userType, + NvSciBufAttrList* const bufAttrList +); + +/*! + * \brief Indicates the entry with @a userType in the list of allocated + * elements will be visible to the consumer block at @consumerIndex. + * By default, all entries are visible, so this is only necessary if an + * element will not be visible to indexed consumer. + * + * This is only supported for pool blocks. + * + * For any elements that not visible to the consumer, any waiter + * NvSciSyncAttrLists that it provides (or fails to provide) will be + * ignored when consolidating with other attribute lists and passing to + * the producer. Additionally, NvSciStream may optimize buffer resources + * and not share the element buffers with the consumer. + * + * @pre + * - Block must be in the phase where element export is available, after + * receiving an NvSciStreamEventType_Elements event and before a call to + * NvSciStreamBlockSetupStatusSet() with NvSciStreamSetup_ElementExport. + * + * Actions + * - Marks the element not visible by the consumer. + * + * Postconditions + * - None. + * + * \param[in] pool: NvSciStreamBlock which references a pool. + * \param[in] userType: User-defined type to identify the element. + * \param[in] consumerIndex: Index of the consumer block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_NotYetAvailable: The requested element information has + * not yet arrived. + * - ::NvSciError_NoLongerAvailable: The element export phase was completed. + * - ::NvSciError_BadParameter: The @a consumerIndex is out of range or + * entry with @userType not found in the allocated element list. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockElementNotVisible( + NvSciStreamBlock const pool, + uint32_t const userType, + uint32_t const consumerIndex +); + +/*! + * \brief Indicates whether the entry at @a elemIndex in the list of allocated + * elements will be used by the @a block. By default, all entries are + * are assumed to be used, so this is only necessary if an entry will not + * be used. + * + * This is only supported for consumer blocks. Producers are expected to + * provide all elements defined by the pool. + * + * For any elements that a consumer indicates it will not use, any waiter + * NvSciSyncAttrLists that it provides (or fails to provide) will be + * ignored when consolidating with other attribute lists and passing to + * the producer. Additionally, NvSciStream may optimize buffer resources + * and not share the element buffers with the consumer. + * + * @pre + * - Block must be in the phase where element import is available, after + * receiving an NvSciStreamEventType_Elements event and before a call to + * NvSciStreamBlockSetupStatusSet() with NvSciStreamSetup_ElementImport. + * + * Actions + * - Marks the element as unused by the consumer. + * + * Postconditions + * - None. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[in] elemIndex: Index of the entry in the element list to set. + * \param[in] used: Flag indicating whether the element is used. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_NotYetAvailable: The requested element information has + * not yet arrived. + * - ::NvSciError_NoLongerAvailable: The element import phase was completed. + * - ::NvSciError_BadParameter: The @a elemIndex is out of range. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockElementUsageSet( + NvSciStreamBlock const block, + uint32_t const elemIndex, + bool const used +); + +/*! + * \brief Creates a new packet and adds it to the pool block + * referenced by the given NvSciStreamBlock, associates the + * given NvSciStreamCookie with the packet and returns a + * NvSciStreamPacket which references the created packet. + * + * @pre + * - Pool must have successfully completed NvSciStreamSetup_ElementExport + * phase. + * - For static pool, the number of packets already created has not reached the + * number of packets which was set when the static pool was created. + * + * Actions + * - A new NvSciStreamPacket is assigned to the created packet + * and returned to the caller. + * + * Postconditions + * - The application can register NvSciBufObj(s) to the created packet. + * + * \param[in] pool: NvSciStreamBlock which references a pool block. + * \param[in] cookie: Pool's NvSciStreamCookie for the packet. + * Valid value: cookie != NvSciStreamCookie_Invalid. + * \param[out] handle: NvSciStreamPacket which references the + * created packet. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: The operation completed successfully. + * - ::NvSciError_BadAddress: @a handle is NULL. + * - ::NvSciError_NotYetAvailable: Completion of element export has not + * yet been signaled on the pool. + * - ::NvSciError_StreamBadCookie: @a cookie is invalid. + * - ::NvSciError_AlreadyInUse: @a cookie is already assigned to a packet. + * - ::NvSciError_Overflow: Pool already has maximum number of packets. + * - ::NvSciError_InsufficientMemory: Unable to allocate memory for the new + * packet. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamPoolPacketCreate( + NvSciStreamBlock const pool, + NvSciStreamCookie const cookie, + NvSciStreamPacket *const handle +); + +/*! + * \brief Registers an NvSciBufObj as the indexed element of the referenced + * NvSciStreamPacket owned by the pool block. + * + * @pre + * - The packet has not yet been marked as completed. + * + * Actions + * - The NvSciBufObj is registered to the given packet element. + * + * Postconditions + * None + * + * \param[in] pool NvSciStreamBlock which references a pool block. + * \param[in] handle NvSciStreamPacket which references the packet. + * \param[in] index Index of element within packet. + * Valid value: 0 to number of elements specifed - 1. + * \param[in] bufObj NvSciBufObj to be registered. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: The operation completed successfully. + * - ::NvSciError_BadParameter: @a bufObj is NULL. + * - ::NvSciError_IndexOutOfRange: @a index is out of range. + * - ::NvSciError_NoLongerAvailable: The packet has been marked complete. + * - ::NvSciError_InconsistentData: The element at @a index is unused by + * the consumer. + * - Any error or panic behavior returned by NvSciBufObjRef(). + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamPoolPacketInsertBuffer( + NvSciStreamBlock const pool, + NvSciStreamPacket const handle, + uint32_t const index, + NvSciBufObj const bufObj +); + +/*! + * \brief Marks a packet as complete and sends it to the rest of the stream. + * + * @pre + * - The packet has not yet been marked as completed. + * + * Actions + * - The packet is complete. + * + * Postconditions + * - Status for the packet can be received. + * + * \param[in] pool NvSciStreamBlock which references a pool block. + * \param[in] handle NvSciStreamPacket which references the packet. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: The operation completed successfully. + * - ::NvSciError_AlreadyDone: The packet has already been marked complete. + * - ::NvSciError_InsufficientData: Buffers were not provided for all of the + * packet's elements. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Async + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamPoolPacketComplete( + NvSciStreamBlock const pool, + NvSciStreamPacket const handle +); + +/*! + * \brief Removes a packet referenced by the given NvSciStreamPacket from + * the pool block referenced by the given NvSciStreamBlock. + * + * If the packet is currently in the pool, it is removed right away. Otherwise + * this is deferred until the packet returns to the pool. + * + * @pre + * - Specified packet must exist. + * + * Actions + * - If the pool holds the specified packet or when it is returned to the + * pool, the pool releases resources associated with it and sends a + * NvSciStreamEventType_PacketDelete event to the producer and + * consumer endpoint(s). + * + * Postconditions + * - The packet may no longer be used for pool operations. + * + * \param[in] pool NvSciStreamBlock which references a pool block. + * \param[in] handle NvSciStreamPacket which references the packet. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success Packet successfully removed. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Async + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamPoolPacketDelete( + NvSciStreamBlock const pool, + NvSciStreamPacket const handle +); + +/*! + * \brief In producer and consumer blocks, queries the handle of a newly + * defined packet. + * + * @pre + * - Must follow receipt of a NvSciStreamEventType_PacketCreate event for + * which the handle has not yet been retrieved. + * + * Actions + * - Dequeues the pending handle. + * + * Postconditions + * - The packet can now be queried and accepted or rejected. + * + * \param[in] block NvSciStreamBlock which references a producer or + * consumer block. + * \param[out] handle Location in which to return the packet handle. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a handle is NULL. + * - ::NvSciError_NotYetAvailable: The block has not yet indicated it is + * done importing element information. + * - ::NvSciError_NoLongerAvailable: The block has completed importing packets. + * - ::NvSciError_NoStreamPacket:: There is no pending new packet handle. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockPacketNewHandleGet( + NvSciStreamBlock const block, + NvSciStreamPacket* const handle +); + +/*! + * \brief In producer and consumer blocks, queries an indexed buffer from + * a packet. The resulting NvSciBufObj is owned by the caller and should + * be freed when it is no longer needed. + * + * @pre + * - Block must not have rejected the packet, and must still be in packet + * import phase. + * + * Actions + * - Returns an NvSciBufObj owned by the caller. + * + * Postconditions + * None + * + * \param[in] block NvSciStreamBlock which references a producer or + * consumer block. + * \param[in] handle NvSciStreamPacket which references the packet. + * \param[in] elemIndex Index of the element to query. + * \param[out] bufObj Location in which to store the buffer object handle. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a bufObj is NULL. + * - ::NvSciError_NotYetAvailable: The block has not yet indicated it is + * done importing element information. + * - ::NvSciError_NoLongerAvailable: The block has completed importing packets. + * - ::NvSciError_IndexOutOfRange: @a elemIndex is out of range. + * - Any error or panic behavior returned by NvSciBufObjRef(). + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockPacketBufferGet( + NvSciStreamBlock const block, + NvSciStreamPacket const handle, + uint32_t const elemIndex, + NvSciBufObj* const bufObj +); + +/*! + * \brief In producer and consumer blocks, queries the cookie of a recently + * deleted packet. + * + * @pre + * - Must follow receipt of a NvSciStreamEventType_PacketDelete event for + * which the cookie has not yet been retrieved. + * + * Actions + * - Dequeues the pending cookie and frees packet resources. + * + * Postconditions + * - The packet's handle can no longer be used for any operations on the block. + * + * \param[in] block NvSciStreamBlock which references a producer or + * consumer block. + * \param[out] cookie Location in which to return the packet cookie. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a cookie is NULL. + * - ::NvSciError_NotYetAvailable: The block has not yet indicated it is + * done importing element information. + * - ::NvSciError_NoStreamPacket:: There is no pending deleted packet cookie. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockPacketOldCookieGet( + NvSciStreamBlock const block, + NvSciStreamCookie* const cookie +); + +/*! + * \brief In producer and consumer blocks, either accepts a packet, providing + * a cookie to be used in subsequent operations, or rejects it, providing + * an error value to be reported to the pool. + * + * @pre + * - The packet has not yet been accepted or rejected. + * + * Actions + * - Binds the cookie, if any, to the packet, and informs the pool of + * the status. + * + * Postconditions + * - If rejected, the packet handle can no longer be used for any operations. + * + * \param[in] block NvSciStreamBlock which references a producer or + * consumer block. + * \param[in] handle NvSciStreamPacket which references the packet. + * \param[in] cookie Cookie to assign to the packet if it is accepted. + * \param[in] status Status value which is either NvSciError_Success to + * indicate acceptance, or any other value to indicate rejection. + * (But NvSciError_StreamInternalError is not allowed.) + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadParameter: @a status is invalid. + * - ::NvSciError_StreamBadCookie: The packet was accepted but @a cookie is + * invalid. + * - ::NvSciError_AlreadyInUse: The packet was accepted but @a cookie was + * already assigned to another packet. + * - ::NvSciError_AlreadyDone: The packet's status was already set. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Async + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockPacketStatusSet( + NvSciStreamBlock const block, + NvSciStreamPacket const handle, + NvSciStreamCookie const cookie, + NvSciError const status +); + +/*! + * \brief In pool, queries whether or not a packet has been accepted. + * + * @pre + * None + * + * Actions + * None + * + * Postconditions + * None + * + * \param[in] block NvSciStreamBlock which references a pool block. + * \param[in] handle NvSciStreamPacket which references the packet. + * \param[out] accepted Location in which to return the acceptance. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a accepted is NULL. + * - ::NvSciError_NotYetAvailable: Packet status has not yet arrived. + * - ::NvSciError_NoLongerAvailable: Packet export phase has completed. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamPoolPacketStatusAcceptGet( + NvSciStreamBlock const pool, + NvSciStreamPacket const handle, + bool* const accepted +); + +/*! + * \brief In pool, queries the status value for a given packet returned + * by a specified endpoint. Used when a packet is rejected to learn + * more about which endpoint(s) rejected it and why. + * + * @pre + * None + * + * Actions + * None + * + * Postconditions + * None + * + * \param[in] block NvSciStreamBlock which references a pool block. + * \param[in] handle NvSciStreamPacket which references the packet. + * \param[in] queryBlockType Indicates whether to query status from + * producer or consumer endpoint. + * \param[in] queryBlockIndex Index of the endpoint from which to query status. + * \param[out] status Location in which to return the status value. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a status is NULL. + * - ::NvSciError_NotYetAvailable: Packet status has not yet arrived. + * - ::NvSciError_NoLongerAvailable: Packet export phase has completed. + * - ::NvSciError_IndexOutOfRange: @a queryBlockIndex is out of range. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamPoolPacketStatusValueGet( + NvSciStreamBlock const pool, + NvSciStreamPacket const handle, + NvSciStreamBlockType const queryBlockType, + uint32_t const queryBlockIndex, + NvSciError* const status +); + +/*! + * \brief Specifies @a block's NvSciSync requirements to be able to wait + * for sync objects provided by the opposing endpoint(s) for the element + * referenced by @a elemIndex. By default, the value is NULL, indicating + * the opposing endpoint(s) must write or read the element synchronously, + * unless this endpoint marked it as unused. + * + * This is only supported for producer and consumer blocks. + * + * @pre + * - Block must be in the phase where waiter attr export is available, after + * receiving an NvSciStreamEventType_Elements event and before a call to + * NvSciStreamBlockSetupStatusSet() with NvSciStreamSetup_WaiterAttrExport. + * + * Actions + * - Saves the attribute list for the element. + * + * Postconditions + * - None. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[in] elemIndex: Index of the entry in the attribute list to set. + * \param[in] waitSyncAtttList: Attribute list with waiter requirments. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_NotYetAvailable: Element information has not yet arrived. + * - ::NvSciError_NoLongerAvailable: The waiter info export phase was + * completed. + * - ::NvSciError_IndexOutOfRange: The @a elemIndex is out of range. + * - Any error or panic behavior that NvSciSyncAttrListClone() can generate. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockElementWaiterAttrSet( + NvSciStreamBlock const block, + uint32_t const elemIndex, + NvSciSyncAttrList const waitSyncAttrList +); + +/*! + * \brief Retrieves the opposing endpoints' NvSciSync requirements to be + * be able to wait for sync objects signalled by @a block for the element + * referenced by @a elemIndex. If the value is NULL, the opposing endpoint + * expects this block to write or read the element synchronously, and not + * provide any sync object. The received attribute list is owned by the + * caller, and should be freed when it is no longer needed. + * + * This is only supported for producer and consumer blocks. + * + * @pre + * - Block must be in the phase where waiter attr import is available, after + * receiving an NvSciStreamEventType_WaiterAttr event and before a call to + * NvSciStreamBlockSetupStatusSet() with NvSciStreamSetup_WaiterAttrImport. + * + * Actions + * None + * + * Postconditions + * None + * + * \param[in] block NvSciStreamBlock which references a block. + * \param[in] elemIndex: Index of the entry in the attribute list to get. + * \param[in] waitSyncAtttList: Location in which to return the requirements. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a waitSyncAttrList is NULL. + * - ::NvSciError_NotYetAvailable: Waiter information has not yet arrived. + * - ::NvSciError_NoLongerAvailable: The waiter info import phase was + * completed. + * - ::NvSciError_IndexOutOfRange: The @a elemIndex is out of range. + * - Any error or panic behavior that NvSciSyncAttrListClone() can generate. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockElementWaiterAttrGet( + NvSciStreamBlock const block, + uint32_t const elemIndex, + NvSciSyncAttrList* const waitSyncAttrList +); + +/*! + * \brief Specifies @a block's NvSciSync object used to signal when it is + * done writing or reading a buffer referenced by @a elemIndex. By default, + * the value is NULL, indicating that the buffer is either unused or is + * used synchronously and all operations will have completed by the time + * the endpoint returns the packet to the stream. + * + * This is only supported for producer and consumer blocks. + * + * @pre + * - Block must be in the phase where signal object export is available, after + * receiving an NvSciStreamEventType_WaiterAttr event and before a call to + * NvSciStreamBlockSetupStatusSet() with NvSciStreamSetup_SignalObjExport. + * + * Actions + * - Saves the sync object for the element. + * + * Postconditions + * - None. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[in] elemIndex: Index of the entry in the sync object list to set. + * \param[in] signalSyncObj: Signalling sync object. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_NotYetAvailable: Waiter requirements have not yet arrived. + * - ::NvSciError_NoLongerAvailable: The signal info export phase was + * completed. + * - ::NvSciError_IndexOutOfRange: The @a elemIndex is out of range. + * - ::NvSciError_InconsistentData: The element at @a elemIndex is unused by + * @a block. + * - Any error or panic behavior that NvSciSyncObjRef() can generate. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockElementSignalObjSet( + NvSciStreamBlock const block, + uint32_t const elemIndex, + NvSciSyncObj const signalSyncObj +); + +/*! + * \brief Retrieves an opposing endpoint's NvSciSync object which it uses + * to signal when it is done writing or readying a buffer referenced by + * @a elemIndex. If the value is NULL, the opposing endpoint either does + * not use the buffer or uses it synchronously, and all operations on + * the buffer will be completed by the time the packet is received. + * The received sync object is owned by the caller, and should be freed + * when it is no longer needed. + * + * Note: In the late-/re-attach usecase, when the producer retrieves + * consumer's NvSciSync object, this returns NULL to indicate no change + * for the early consumers. It only returns NvSciSync object for the + * new late-/re-attach consumers. + * + * This is only supported for producer and consumer blocks. + * + * @pre + * - Block must be in the phase where signal object import is available, after + * receiving an NvSciStreamEventType_SignalObj event and before a call to + * NvSciStreamBlockSetupStatusSet() with NvSciStreamSetup_SignalObjImport. + * + * Actions + * None + * + * Postconditions + * None + * + * \param[in] block NvSciStreamBlock which references a block. + * \param[in] queryBlockIndex: The index of the opposing block to query. + * When querying producer sync objects from the consumer, this is always 0. + * When querying consumer sync objects from the producer, this is the + * index of the consumer. + * \param[in] elemIndex: Index of the entry in the sync object list to get. + * \param[in] signalSyncObj: Location in which to return the sync object. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a signalSyncObj is NULL. + * - ::NvSciError_NotYetAvailable: Signal information has not yet arrived. + * - ::NvSciError_NoLongerAvailable: The signal info import phase was + * completed. + * - ::NvSciError_IndexOutOfRange: The @a queryBlockIndex or @a elemIndex + * is out of range. + * - Any error or panic behavior that NvSciSyncObjRef() can generate. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockElementSignalObjGet( + NvSciStreamBlock const block, + uint32_t const queryBlockIndex, + uint32_t const elemIndex, + NvSciSyncObj* const signalSyncObj +); + +/*! + * \brief Instructs the producer referenced by @a producer to retrieve + * a packet from the pool. + * + * If a packet is available for producer processing, its producer fences + * will be cleared, ownership will be moved to the application, and its + * cookie will be returned. + * + * The producer may hold multiple packets and is not required to present + * them in the order they were obtained. + * + * @pre + * - All packets have been accepted by the producer and the consumer(s). + * - The producer block must have received the NvSciStreamEventType_PacketReady + * event from pool for processing the next available packet. + * + * Actions + * - Retrieves an available packet for producer processing and returns + * it to the caller. + * + * Postconditions + * - Packet is held by the producer application. + * + * \param[in] producer NvSciStreamBlock which references a producer block. + * \param[out] cookie Location in which to return the packet's cookie. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success Packet successfully retrieved. + * - ::NvSciError_BadAddress: @a cookie is NULL. + * - ::NvSciError_NoStreamPacket: No packet is available. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciStreamProducerPacketGet( + NvSciStreamBlock const producer, + NvSciStreamCookie *const cookie +); + +/*! + * \brief Instructs the producer referenced by @a producer to insert the + * packet referenced by @a handle into the stream for consumer processing. + * + * @pre + * - The packet must be held by the producer application. + * + * Actions + * - The packet is sent downstream, where it will be processed according + * to the stream's configuration. + * + * Postconditions + * - The packet is no longer held by the producer application. + * + * \param[in] producer NvSciStreamBlock which references a producer block. + * \param[in] handle NvSciStreamPacket which references the packet. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success Packet successfully presented. + * - ::NvSciError_StreamBadPacket @a handle is not recognized. + * - ::NvSciError_StreamPacketInaccessible @a handle is not currently + * held by the application. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Async + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciStreamProducerPacketPresent( + NvSciStreamBlock const producer, + NvSciStreamPacket const handle +); + +/*! + * \brief Instructs the consumer referenced by @a consumer to retrieve + * a packet from the queue. + * + * If a packet is available for consumer processing, its consumer fences + * will be cleared, ownership will be moved to the application, and its + * cookie will be returned. + * + * The consumer may hold multiple packets and is not required to return + * them in the order they were obtained. + * + * @pre + * - All packets have been accepted by the producer and the consumer(s). + * - The consumer block must have received the NvSciStreamEventType_PacketReady + * event from queue for processing the next available packet. + * + * Actions + * - Retrieves an available packet for consumer processing and returns + * it to the caller. + * + * Postconditions + * - Packet is held by the consumer application. + * + * \param[in] consumer NvSciStreamBlock which references a consumer block. + * \param[out] cookie NvSciStreamCookie identifying the packet. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success Packet was successfully acquired. + * - ::NvSciError_BadAddress: @a cookie is NULL. + * - ::NvSciError_NoStreamPacket: No packet is available. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciStreamConsumerPacketAcquire( + NvSciStreamBlock const consumer, + NvSciStreamCookie *const cookie +); + +/*! + * \brief Instructs the consumer referenced by @a consumer to release the + * packet referenced by @a handle into the stream for producer reuse. + * + * @pre + * - The packet must be held by the consumer application. + * + * Actions + * - The packet is sent upstream, where it will be processed according + * to the stream's configuration. + + * Postconditions + * - The packet is no longer held by the consumer application. + * + * \param[in] consumer NvSciStreamBlock which references a consumer block. + * \param[in] handle NvSciStreamPacket which references the packet. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success Packet was successfully released. + * - ::NvSciError_StreamBadPacket @a handle is not recognized. + * - ::NvSciError_StreamPacketInaccessible @a handle is not currently + * held by the application. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Async + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciStreamConsumerPacketRelease( + NvSciStreamBlock const consumer, + NvSciStreamPacket const handle +); + +/*! + * \brief Sets the postfence which indicates when the application + * controlling will be done operating on the indexed buffer of + * a packet. + * + * @pre + * - The packet must be held by the application. + * + * Actions + * - The fence is saved in the packet until it is returned to the stream. + + * Postconditions + * None + * + * \param[in] block NvSciStreamBlock which references a producer or + * consumer block. + * \param[in] handle NvSciStreamPacket which references the packet. + * \param[in] elemIndex Index of the buffer for the fence. + * \param[in] postfence The fence to save. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success The operation was completed successfully. + * - ::NvSciError_BadAddress: @a postfence is NULL. + * - ::NvSciError_StreamBadPacket @a handle is not recognized. + * - ::NvSciError_StreamPacketInaccessible @a handle is not currently + * held by the application. + * - ::NvSciError_IndexOutOfRange @a elemIndex is not valid. + * - ::NvSciError_InconsistentData: The element at @a elemIndex is unused by + * @a block. + * - Any error returned by NvSciSyncFenceDup(). + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError +NvSciStreamBlockPacketFenceSet( + NvSciStreamBlock const block, + NvSciStreamPacket const handle, + uint32_t const elemIndex, + NvSciSyncFence const *const postfence +); + +/*! + * \brief Retrieves the prefence which indicates when the the indexed + * opposing endpoint will be done operating on the indexed buffer + * of a packet. + * + * @pre + * - The packet must be held by the application. + * + * Actions + * - The fence is copied from the packet. + + * Postconditions + * None + * + * \param[in] block NvSciStreamBlock which references a producer or + * consumer block. + * \param[in] handle NvSciStreamPacket which references the packet. + * \param[in] queryBlockIndex Index of the opposing block to query. + * When querying producer fences from the consumer, this is always 0. + * When querying consumer fences from the producer, this is the + * index of the consumer. + * \param[in] elemIndex Index of the buffer for the fence. + * \param[out] prefence Location in which to return the fence. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success The operation was completed successfully. + * - ::NvSciError_BadAddress: @a prefence is NULL. + * - ::NvSciError_StreamBadPacket @a handle is not recognized. + * - ::NvSciError_StreamPacketInaccessible @a handle is not currently + * held by the application. + * - ::NvSciError_IndexOutOfRange @a queryBlockIndex or @a elemIndex is + * not valid. + * - Any error returned by NvSciSyncFenceDup() or NvSciSyncIpcImportFence(). + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError +NvSciStreamBlockPacketFenceGet( + NvSciStreamBlock const block, + NvSciStreamPacket const handle, + uint32_t const queryBlockIndex, + uint32_t const elemIndex, + NvSciSyncFence* const prefence +); + +/*! + * \brief Queries whether the indexed consumer is a newly connected consumer. + * + * This API can only be used when application uses late-attach/re-attach consumer + * feature. + * + * @pre + * - The application must have received the NvSciStreamEventType_Connected + * event corresponding to the new consumer attach. + * + * Actions + * - None + + * Postconditions + * None + * + * \param[in] producer NvSciStreamBlock which references a producer block. + * \param[in] consumerIndex The index of the queried consumer block. + * \param[out] newConnected true if the @a consumerIndex corresponds to + * newly connected consumer else false. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success The operation was completed successfully. + * - ::NvSciError_BadAddress: @a newConnected is NULL. + * - ::NvSciError_IndexOutOfRange @a queryConnIndex is not valid + * - ::NvSciError_NotYetAvailable If NvSciStreamEventType_Connected is not + * yet received for the newly connected consumers. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamNewConsumerGet( + NvSciStreamBlock const producer, + uint32_t const consumerIndex, + bool* const newConnected ); + +/*! + * \brief Schedules a block referenced by the given NvSciStreamBlock + * for destruction, disconnecting the block if this + * hasn't already occurred. + * + * - The block's handle may no longer be used for any function calls. + * + * - Resources associated with the block may not be freed immediately. + * + * - Any pending packets downstream of the destroyed block will + * still be available for the consumer to acquire. + * + * - No new packets upstream of the destroyed block can be presented. Once packets + * are released, they will be freed. + * + * @pre + * - None. + * + * Actions + * - The block is scheduled for destruction. + * - A NvSciStreamEventType_Disconnected event is sent to all upstream + * and downstream blocks, if they haven't received one already. + * + * Postconditions + * - The referenced NvSciStreamBlock is no longer valid. + * - If there is an NvSciEventNotifier bound to the referenced + * NvSciStreamBlock, it is unbound. + * + * \param[in] block NvSciStreamBlock which references a block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success Block successfully destroyed. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Async + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamBlockDelete( + NvSciStreamBlock const block +); + + +/*! + * \brief Disconnects an IpcSrc block referenced by the given NvSciStreamBlock. + * + * - This API can be used to disconnect any dead consumer process during normal + * operational state. + * + * @pre + * - Block must be in the normal operational state after receiving an + * NvSciStreamEventType_SetupComplete event. + * + * Actions + * - A NvSciStreamEventType_Disconnected event is sent to all upstream + * and downstream blocks, if they haven't received one already. + * + * Postconditions + * - None + * + * \param[in] block NvSciStreamBlock which references an IpcSrc block. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success Block successfully disconnected. + * - ::NvSciError_InvalidState If not during normal operational state. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Async + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciStreamBlockDisconnect( + NvSciStreamBlock const block +); + +/*! + * \brief Queries the value of one of the NvSciStreamQueryableAttrib. + * + * @pre + * - None. + * + * Actions + * - NvSciStream looks up the value for the given NvSciStreamQueryableAttrib + * and returns it. + * + * Postconditions + * - None. + * + * \param[in] attr NvSciStreamQueryableAttrib to query. + * \param[out] value The value queried. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success Query is successful. + * - ::NvSciError_BadParameter @a attr is invalid or @a value is null. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamAttributeQuery( + NvSciStreamQueryableAttrib const attr, + int32_t *const value +); + +/*! + * Sets up the NvSciEventService on a block referenced by the given + * NvSciStreamBlock by creating an NvSciEventNotifier to report the occurrence + * of any events on that block. The NvSciEventNotifier is bound to the input + * NvSciEventService and NvSciStreamBlock. Users can wait for events on the + * block using the NvSciEventService API and then retrieve event details + * using NvSciStreamBlockEventQuery(). Binding one or more blocks in a stream + * to an NvSciEventService is optional. If not bound to an NvSciEventService, + * users may instead wait for events on a block by specifying a non-zero + * timeout in NvSciStreamBlockEventQuery(). If blocks in the same stream within + * the same process are bound to different NvSciEventService, behavior is + * undefined. The user is responsible for destroying the NvSciEventNotifier when + * it's no longer needed. + * + * @pre + * - After the input block is created, before calling this API, no NvSciStream + * API shall be called on the block. + * + * Actions + * - Sets up the input block to use the input NvSciEventService for event + * signaling. + * - Creates an NvSciEventNotifier object and returns the pointer to the object + * via @a eventNotifier. + * + * Postconditions + * - NvSciStreamBlockEventQuery() calls with non-zero timeout on the block will + * return error. + * + * \param[in] block NvSciStreamBlock which references a block. + * \param[in] eventService Pointer to a NvSciEventService object. + * \param[out] eventNotifier To be filled with the pointer to the created + * NvSciEventNotifier object. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success The setup is successful. + * - ::NvSciError_BadParameter @a eventService is null or @a eventNotifier + * is null. + * - ::NvSciError_InvalidState An NvSciStream API has already been called on the + * block referenced by @a block. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciStreamBlockEventServiceSetup( + NvSciStreamBlock const block, + NvSciEventService *const eventService, + NvSciEventNotifier **const eventNotifier +); + +/*! + * \brief Provides user-defined information at the producer and consumer with + * the specified @a userType, which can be queried by other blocks after the + * stream is fully connected. + * + * When called on a producer or consumer block, it adds to its list of + * user-defined information. + * + * @pre + * - The block is created but not connected to any other block. + * + * Actions + * - Appends the specified user-defined information to the information list. + * + * Postconditions + * - None. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[in] userType: User-defined type to identify the endpoint information. + * \param[in] dataSize: Size of the provided @a data. + * \param[in] data: Pointer to user-defined information. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadParameter: @a data is a NULL pointer. + * - ::NvSciError_AlreadyInUse: An endpoint information with the specified + * @a userType already exists in the list. + * - ::NvSciError_InsufficientMemory: Unable to allocate storage for the new + * endpoint information. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockUserInfoSet( + NvSciStreamBlock const block, + uint32_t const userType, + uint32_t const dataSize, + void const* const data); + +/*! + * \brief Queries the user-defined information with @a userType in list of + * endpoint information at the @a block from the source identified by + * @a queryBlockType and @a queryBlockIndex. + * + * The @a dataSize contains the size of the input @a data. If @a data is NULL, + * store the total size of the queried information in @a dataSize. If not, + * copy the queried information into @a data and store the size of the data + * copied into @a data. + * + * @pre + * - Block must have received NvSciStreamEventType_Connected event indicating + * that the stream is fully connected and before receiving + * NvSciStreamEventType_SetupComplete event indicating setup of the stream + * is complete. + * + * Actions + * - None. + * + * Postconditions + * - None. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[in] queryBlockType: Indicates whether to query information from + * producer or consumer endpoint. + * \param[in] queryBlockIndex: Index of the endpoint block to query. + * \param[in] userType: User-defined type to query. + * \param[in,out] dataSize: On input, contains the size of the memory + * referenced by @a data. On output, contains the + * amount of data copied into @a data, or the total + * size of the queried information if @a data is NULL. + * \param[out] data: Pointer to location in which to store the information. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a dataSize is NULL or @a data is NULL when + * @a dataSize is non-zero. + * - ::NvSciError_NoLongerAvailable: Setup of the stream is completed. + * - ::NvSciError_BadParameter: The @a queryBlockType is not valid. + * - ::NvSciError_IndexOutOfRange: The @a queryBlockIndex is invalid for the + * @a queryBlockType. + * - ::NvSciError_StreamInfoNotProvided: The queried endpoint info not exist. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockUserInfoGet( + NvSciStreamBlock const block, + NvSciStreamBlockType const queryBlockType, + uint32_t const queryBlockIndex, + uint32_t const userType, + uint32_t* const dataSize, + void* const data); + +/*! + * \brief Provides user-defined information at the producer and consumer with + * the specified @a userType, which can be queried by other blocks after the + * stream is fully connected. + * + * When called on a producer or consumer block, it adds to its list of + * user-defined information. + * + * A wrapper function which calls the NvSciStreamBlockUserInfoSet() API and + * updates the @a crc value. + * + * @pre + * - The block is created but not connected to any other block. + * + * Actions + * - Appends the specified user-defined information to the information list. + * + * Postconditions + * - None. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[in] userType: User-defined type to identify the endpoint information. + * \param[in] dataSize: Size of the provided @a data. + * \param[in] data: Pointer to user-defined information. + * \param[in,out] crc: Pointer to the location in which to store the CRC value. + * On input, contains the initial CRC value. + * On output, contains the updated CRC value. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadParameter: @a data is a NULL pointer. + * - ::NvSciError_AlreadyInUse: An endpoint information with the specified + * @a userType already exists in the list. + * - ::NvSciError_InsufficientMemory: Unable to allocate storage for the new + * endpoint information. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockUserInfoSetWithCrc( + NvSciStreamBlock const block, + uint32_t const userType, + uint32_t const dataSize, + void const* const data, + uint32_t* const crc); + +/*! + * \brief Queries the user-defined information with @a userType in list of + * endpoint information at the @a block from the source identified by + * @a queryBlockType and @a queryBlockIndex. + * + * The @a dataSize contains the size of the input @a data. If @a data is NULL, + * store the total size of the queried information in @a dataSize. If not, + * copy the queried information into @a data and store the size of the data + * copied into @a data. + * + * A wrapper function which calls the NvSciStreamBlockUserInfoGet() API and + * updates the @a crc value. + * + * @pre + * - Block must have received NvSciStreamEventType_Connected event indicating + * that the stream is fully connected and before receiving + * NvSciStreamEventType_SetupComplete event indicating setup of the stream + * is complete. + * + * Actions + * - None. + * + * Postconditions + * - None. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[in] queryBlockType: Indicates whether to query information from + * producer or consumer endpoint. + * \param[in] queryBlockIndex: Index of the endpoint block to query. + * \param[in] userType: User-defined type to query. + * \param[in,out] dataSize: On input, contains the size of the memory + * referenced by @a data. On output, contains the + * amount of data copied into @a data, or the total + * size of the queried information if @a data is NULL. + * \param[out] data: Pointer to location in which to store the information. + * \param[in,out] crc: Pointer to the location in which to store the CRC value. + * On input, contains the initial CRC value. + * On output, contains the updated CRC value. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a dataSize is NULL or @a data is NULL when + * @a dataSize is non-zero. + * - ::NvSciError_NoLongerAvailable: Setup of the stream is completed. + * - ::NvSciError_BadParameter: The @a queryBlockType is not valid. + * - ::NvSciError_IndexOutOfRange: The @a queryBlockIndex is invalid for the + * @a queryBlockType. + * - ::NvSciError_StreamInfoNotProvided: The queried endpoint info not exist. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockUserInfoGetWithCrc( + NvSciStreamBlock const block, + NvSciStreamBlockType const queryBlockType, + uint32_t const queryBlockIndex, + uint32_t const userType, + uint32_t* const dataSize, + void* const data, + uint32_t* const crc); + +/*! + * \brief Adds an element with the specified @a userType and @a bufAttrList + * to the list of elements defined by @a block. + * + * When called on a producer or consumer block, it adds to the list of + * elements which that endpoint is capable of supporting. + * When called on a pool block, it adds to the list of elements which will + * be used for the final packet layout. This interface is not supported on + * the secondary pools. + * + * A wrapper function which calls the NvSciStreamBlockElementAttrSet() API and + * updates the @a crc value. + * + * @pre + * - The block must be in the phase where element export is available. + * For producer and consumer blocks, this begins after receiving the + * NvSciStreamEventType_Connected event. For pool blocks, this begins + * after receiving the NvSciStreamEventType_Elements event. In all cases, + * this phase ends after a call to NvSciStreamBlockSetupStatusSet() with + * NvSciStreamSetup_ElementExport. + * + * Actions + * - Appends the specified element to the current list. + * + * Postconditions + * - None. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[in] userType: User-defined type to identify the element. + * \param[in] bufAttrList: Buffer attribute list for element. NvSciStream + * will clone the attribute list, so the caller can safely free it once + * the function returns. + * \param[in,out] crc: Pointer to the location in which to store the CRC value. + * On input, contains the initial CRC value. + * On output, contains the updated CRC value. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_NotYetAvailable: The prerequisite event has not yet arrived. + * - ::NvSciError_NoLongerAvailable: The element export phase was completed. + * - ::NvSciError_Busy: An NvSciStream interface in another thread is + * currently interacting with the block's exported element information. + * The call can be retried, but this typically indicates a flaw in + * application design. + * - ::NvSciError_Overflow: The number of elements in the list has reached + * the maximum allowed value. + * - ::NvSciError_AlreadyInUse: An element with the specified @a userType + * already exists in the list. + * - ::NvSciError_InsufficientMemory: Unable to allocate storage for the new + * element. + * - Any error that NvSciBufAttrListClone() can generate. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockElementAttrSetWithCrc( + NvSciStreamBlock const block, + uint32_t const userType, + NvSciBufAttrList const bufAttrList, + uint32_t* const crc); + +/*! + * \brief Queries the user-defined type and/or buffer attribute list for + * an entry, referenced by @a elemIndex, in list of elements received at + * the @a block from the source identified by @a queryBlockType. + * At least one of @a userType or @a bufAttrList must be non-NULL, but + * if the caller is only interested in one of the values, the other + * can be NULL. + * + * When called on a producer or consumer block, @a queryBlockType must be + * NvSciStreamBlockType_Pool, and the query is for the list of allocated + * elements sent from the pool. + * When called on a primary pool block, @a queryBlockType may be either + * NvSciStreamBlockType_Producer or NvSciStreamBlockType_Consumer, and + * the query is for the list of supported elements sent from the referenced + * endpoint(s). + * When called on a secondary pool block, @a queryBlockType may be either + * NvSciStreamBlockType_Producer or NvSciStreamBlockType_Consumer. + * If @a queryBlockType is NvSciStreamBlockType_Producer, the query is for + * the list of allocated elements sent from the primary pool. If the element + * is unused by the consumer, an NULL NvSciBufAttrList is returned. + * If @a queryBlockType is NvSciStreamBlockType_Consumer, the query is for + * referenced the list of supported elements sent from consumer(s). + * + * A wrapper function which calls the NvSciStreamBlockElementAttrGet() API and + * updates the @a crc value. + * + * @pre + * - Block must be in the phase where element import is available, after + * receiving an NvSciStreamEventType_Elements event and before a call to + * NvSciStreamBlockSetupStatusSet() with NvSciStreamSetup_ElementImport. + * + * Actions + * - None. + * + * Postconditions + * - None. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[in] queryBlockType: Identifies the source of the element list. + * \param[in] elemIndex: Index of the entry in the element list to query. + * \param[out] userType: Pointer to location in which to store the type. + * \param[out] bufAttrList: Pointer to location in which to store the + * attribute list. The caller owns the attribute list handle received + * and should free it when it is no longer needed. + * \param[in,out] crc: Pointer to the location in which to store the CRC value. + * On input, contains the initial CRC value. + * On output, contains the updated CRC value. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a userType and @a bufAttrList are both NULL. + * - ::NvSciError_BadParameter: The @a queryBlockType is not valid for + * the @a block or the @a elemIndex is out of range. + * - ::NvSciError_NotYetAvailable: The requested element information has + * not yet arrived. + * - ::NvSciError_NoLongerAvailable: The element import phase was completed. + * - ::NvSciError_Busy: An NvSciStream interface in another thread is + * currently interacting with the block's imported element information. + * The call can be retried. + * - Any error that NvSciBufAttrListClone() can generate. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockElementAttrGetWithCrc( + NvSciStreamBlock const block, + NvSciStreamBlockType const queryBlockType, + uint32_t const elemIndex, + uint32_t* const userType, + NvSciBufAttrList* const bufAttrList, + uint32_t* const crc); + +/*! + * \brief Registers an NvSciBufObj as the indexed element of the referenced + * NvSciStreamPacket owned by the pool block. + * + * A wrapper function which calls the NvSciStreamPoolPacketInsertBuffer() API + * and updates the @a crc value. + * + * @pre + * - The packet has not yet been marked as completed. + * + * Actions + * - The NvSciBufObj is registered to the given packet element. + * + * Postconditions + * None + * + * \param[in] pool NvSciStreamBlock which references a pool block. + * \param[in] handle NvSciStreamPacket which references the packet. + * \param[in] index Index of element within packet. + * Valid value: 0 to number of elements specifed - 1. + * \param[in] bufObj NvSciBufObj to be registered. + * \param[in,out] crc: Pointer to the location in which to store the CRC value. + * On input, contains the initial CRC value. + * On output, contains the updated CRC value. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: The operation completed successfully. + * - ::NvSciError_BadParameter: @a bufObj is NULL. + * - ::NvSciError_IndexOutOfRange: @a index is out of range. + * - ::NvSciError_NoLongerAvailable: The packet has been marked complete. + * - ::NvSciError_InconsistentData: The element at @a index is unused by + * the consumer. + * - Any error or panic behavior returned by NvSciBufObjRef(). + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamPoolPacketInsertBufferWithCrc( + NvSciStreamBlock const pool, + NvSciStreamPacket const handle, + uint32_t const index, + NvSciBufObj const bufObj, + uint32_t* const crc); + +/*! + * \brief In producer and consumer blocks, queries an indexed buffer from + * a packet. The resulting NvSciBufObj is owned by the caller and should + * be freed when it is no longer needed. + * + * A wrapper function which calls the NvSciStreamBlockPacketBufferGet() API and + * updates the @a crc value. + * + * @pre + * - Block must not have rejected the packet, and must still be in packet + * import phase. + * + * Actions + * - Returns an NvSciBufObj owned by the caller. + * + * Postconditions + * None + * + * \param[in] block NvSciStreamBlock which references a producer or + * consumer block. + * \param[in] handle NvSciStreamPacket which references the packet. + * \param[in] elemIndex Index of the element to query. + * \param[out] bufObj Location in which to store the buffer object handle. + * \param[in] crcCount: Number of CRC values to be updated by this API. + * \param[in,out] crc: Pointer to the location in which to store the CRC value. + * On input, contains the initial CRC value. + * On output, contains the updated CRC value. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a bufObj is NULL. + * - ::NvSciError_NotYetAvailable: The block has not yet indicated it is + * done importing element information. + * - ::NvSciError_NoLongerAvailable: The block has completed importing packets. + * - ::NvSciError_IndexOutOfRange: @a elemIndex is out of range. + * - Any error or panic behavior returned by NvSciBufObjRef(). + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockPacketBufferGetWithCrc( + NvSciStreamBlock const block, + NvSciStreamPacket const handle, + uint32_t const elemIndex, + NvSciBufObj* const bufObj, + size_t const crcCount, + uint32_t* const crc); + +/*! + * \brief Specifies @a block's NvSciSync object used to signal when it is + * done writing or reading a buffer referenced by @a elemIndex. By default, + * the value is NULL, indicating that the buffer is either unused or is + * used synchronously and all operations will have completed by the time + * the endpoint returns the packet to the stream. + * + * This is only supported for producer and consumer blocks. + * + * A wrapper function which calls the NvSciStreamBlockElementSignalObjSet() API + * and updates the @a crc value. + * + * @pre + * - Block must be in the phase where signal object export is available, after + * receiving an NvSciStreamEventType_WaiterAttr event and before a call to + * NvSciStreamBlockSetupStatusSet() with NvSciStreamSetup_SignalObjExport. + * + * Actions + * - Saves the sync object for the element. + * + * Postconditions + * - None. + * + * \param[in] block: NvSciStreamBlock which references a block. + * \param[in] elemIndex: Index of the entry in the sync object list to set. + * \param[in] signalSyncObj: Signalling sync object. + * \param[in,out] crc: Pointer to the location in which to store the CRC value. + * On input, contains the initial CRC value. + * On output, contains the updated CRC value. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_NotYetAvailable: Waiter requirements have not yet arrived. + * - ::NvSciError_NoLongerAvailable: The signal info export phase was + * completed. + * - ::NvSciError_IndexOutOfRange: The @a elemIndex is out of range. + * - ::NvSciError_InconsistentData: The element at @a elemIndex is unused by + * @a block. + * - Any error or panic behavior that NvSciSyncObjRef() can generate. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockElementSignalObjSetWithCrc( + NvSciStreamBlock const block, + uint32_t const elemIndex, + NvSciSyncObj const signalSyncObj, + uint32_t* const crc); + +/*! + * \brief Retrieves an opposing endpoint's NvSciSync object which it uses + * to signal when it is done writing or readying a buffer referenced by + * @a elemIndex. If the value is NULL, the opposing endpoint either does + * not use the buffer or uses it synchronously, and all operations on + * the buffer will be completed by the time the packet is received. + * The received sync object is owned by the caller, and should be freed + * when it is no longer needed. + * + * Note: In the late-/re-attach usecase, when the producer retrieves + * consumer's NvSciSync object, this returns NULL to indicate no change + * for the early consumers. It only returns NvSciSync object for the + * new late-/re-attach consumers. + * + * This is only supported for producer and consumer blocks. + * + * A wrapper function which calls the NvSciStreamBlockElementSignalObjGet() API + * and updates the @a crc value. + * + * @pre + * - Block must be in the phase where signal object import is available, after + * receiving an NvSciStreamEventType_SignalObj event and before a call to + * NvSciStreamBlockSetupStatusSet() with NvSciStreamSetup_SignalObjImport. + * + * Actions + * None + * + * Postconditions + * None + * + * \param[in] block NvSciStreamBlock which references a block. + * \param[in] queryBlockIndex: The index of the opposing block to query. + * When querying producer sync objects from the consumer, this is always 0. + * When querying consumer sync objects from the producer, this is the + * index of the consumer. + * \param[in] elemIndex: Index of the entry in the sync object list to get. + * \param[in] signalSyncObj: Location in which to return the sync object. + * \param[in,out] crc: Pointer to the location in which to store the CRC value. + * On input, contains the initial CRC value. + * On output, contains the updated CRC value. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a signalSyncObj is NULL. + * - ::NvSciError_NotYetAvailable: Signal information has not yet arrived. + * - ::NvSciError_NoLongerAvailable: The signal info import phase was + * completed. + * - ::NvSciError_IndexOutOfRange: The @a queryBlockIndex or @a elemIndex + * is out of range. + * - Any error or panic behavior that NvSciSyncObjRef() can generate. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamBlockElementSignalObjGetWithCrc( + NvSciStreamBlock const block, + uint32_t const queryBlockIndex, + uint32_t const elemIndex, + NvSciSyncObj* const signalSyncObj, + uint32_t* const crc); + +/*! + * \brief Sets the postfence which indicates when the application + * controlling will be done operating on the indexed buffer of + * a packet. + * + * A wrapper function which calls the NvSciStreamBlockPacketFenceSet() API and + * updates the @a crc value. + * + * @pre + * - The packet must be held by the application. + * + * Actions + * - The fence is saved in the packet until it is returned to the stream. + + * Postconditions + * None + * + * \param[in] block NvSciStreamBlock which references a producer or + * consumer block. + * \param[in] handle NvSciStreamPacket which references the packet. + * \param[in] elemIndex Index of the buffer for the fence. + * \param[in] postfence The fence to save. + * \param[in,out] crc: Pointer to the location in which to store the CRC value. + * On input, contains the initial CRC value. + * On output, contains the updated CRC value. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success The operation was completed successfully. + * - ::NvSciError_BadAddress: @a postfence is NULL. + * - ::NvSciError_StreamBadPacket @a handle is not recognized. + * - ::NvSciError_StreamPacketInaccessible @a handle is not currently + * held by the application. + * - ::NvSciError_IndexOutOfRange @a elemIndex is not valid. + * - ::NvSciError_InconsistentData: The element at @a elemIndex is unused by + * @a block. + * - Any error returned by NvSciSyncFenceDup(). + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError +NvSciStreamBlockPacketFenceSetWithCrc( + NvSciStreamBlock const block, + NvSciStreamPacket const handle, + uint32_t const elemIndex, + NvSciSyncFence const *const postfence, + uint32_t* const crc); + +/*! + * \brief Retrieves the prefence which indicates when the the indexed + * opposing endpoint will be done operating on the indexed buffer + * of a packet. + * + * A wrapper function which calls the NvSciStreamBlockPacketFenceGet() API and + * updates the @a crc value. + * + * @pre + * - The packet must be held by the application. + * + * Actions + * - The fence is copied from the packet. + + * Postconditions + * None + * + * \param[in] block NvSciStreamBlock which references a producer or + * consumer block. + * \param[in] handle NvSciStreamPacket which references the packet. + * \param[in] queryBlockIndex Index of the opposing block to query. + * When querying producer fences from the consumer, this is always 0. + * When querying consumer fences from the producer, this is the + * index of the consumer. + * \param[in] elemIndex Index of the buffer for the fence. + * \param[out] prefence Location in which to return the fence. + * \param[in,out] crc: Pointer to the location in which to store the CRC value. + * On input, contains the initial CRC value. + * On output, contains the updated CRC value. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success The operation was completed successfully. + * - ::NvSciError_BadAddress: @a prefence is NULL. + * - ::NvSciError_StreamBadPacket @a handle is not recognized. + * - ::NvSciError_StreamPacketInaccessible @a handle is not currently + * held by the application. + * - ::NvSciError_IndexOutOfRange @a queryBlockIndex or @a elemIndex is + * not valid. + * - Any error returned by NvSciSyncFenceDup() or NvSciSyncIpcImportFence(). + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError +NvSciStreamBlockPacketFenceGetWithCrc( + NvSciStreamBlock const block, + NvSciStreamPacket const handle, + uint32_t const queryBlockIndex, + uint32_t const elemIndex, + NvSciSyncFence* const prefence, + uint32_t* const crc); + +/*! + * \brief Queries the index of the consumer block referenced + * by the given NvSciStreamBlock. + * + * @pre + * - Block must have received NvSciStreamEventType_Connected event indicating + * that the stream is fully connected. + * + * Actions + * - None. + * + * Postconditions + * - None. + * + * \param[in] consumer: NvSciStreamBlock which references a consumer block. + * \param[out] index: Location in which to return the consumer's index. + * + * \return ::NvSciError, the completion code of this operation. + * - ::NvSciError_Success: Operation completed successfully. + * - ::NvSciError_BadAddress: @a index is NULL. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError +NvSciStreamConsumerIndexGet( + NvSciStreamBlock const consumer, + uint32_t* const index); + +#ifdef __cplusplus +} +#endif +/** @} */ +/** @} */ +#endif /* NVSCISTREAM_API_H */ diff --git a/nvscistream_types.h b/nvscistream_types.h new file mode 100644 index 0000000..6ef4192 --- /dev/null +++ b/nvscistream_types.h @@ -0,0 +1,545 @@ +/* + * Copyright (c) 2020-2023 NVIDIA Corporation. All rights reserved. + * + * 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. + */ +/** + * @file + * + * @brief NVIDIA Software Communications Interface (SCI) : NvSciStream + * + * The NvSciStream library is a layer on top of NvSciBuf and NvSciSync libraries + * to provide utilities for streaming sequences of data packets between + * multiple application modules to support a wide variety of use cases. + */ +#ifndef NVSCISTREAM_TYPES_H +#define NVSCISTREAM_TYPES_H + +#ifdef __cplusplus +#include +#else +#include +#endif + +#include "nvscierror.h" +#include "nvscibuf.h" +#include "nvscisync.h" +#include "nvsciipc.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* Temporary comment out some c2c code, which can be re-enable after + * swtiching the C2C block to use NvSciEvent model + */ +#define C2C_EVENT_SERVICE 0 + +/** + * @defgroup nvsci_stream_data_types NvSciStream Data Types + * + * Contains a list of NvSciStream datatypes. + * + * @ingroup nvsci_stream + * @{ + * + * NvSciStream version: + * It is expected that, when the NvSciStream library is being developed, it + * might potentially be incompatible with previous versions. An application + * built for a given major and minor version of NvSciStream will be compatible + * with any NvSciStream library with the same major version and equal or + * greater minor version. + * + * Different processes using different minor versions of NvSciStream libraries + * with the same major version may share a stream as long as the stream does + * not make use of any features not supported in the lower minor version. + * + * NvSciStream version numbers are incremented in the following circumstances: + * - Major version: + * - A public interface is modified or removed, so as to make the library + * incompatible with applications built for a previous version. + * - A data structure used by the public interfaces is modified. + * - Existing message formats used by IPC blocks to communicate between + * processes are modified, or new messages are added for existing features. + * - Minor version: + * - A new public interface or feature is added which does not affect + * applications using old features. + * - Additional values are added to existing enums which do not affect + * applications using old features. + * + */ + + +/*! \brief NvSciStream major version number.*/ +static const uint32_t NvSciStreamMajorVersion = 4U; + +/*! \brief NvSciStream minor version number.*/ +static const uint32_t NvSciStreamMinorVersion = 1U; + +/*! \brief Handle to a block.*/ +typedef uintptr_t NvSciStreamBlock; + +/*! \brief NvSciStream assigned handle for a packet.*/ +typedef uintptr_t NvSciStreamPacket; + +/*! \brief Application assigned cookie for a + * NvSciStreamPacket. + */ +typedef uintptr_t NvSciStreamCookie; + +/*! \brief Constant variable denoting an invalid + * NvSciStreamPacket. + * + * \implements{19620996} + */ +static const NvSciStreamPacket NvSciStreamPacket_Invalid = 0U; + +/*! \brief Constant variable denoting an invalid + * NvSciStreamCookie. + * + * \implements{19620999} + */ +static const NvSciStreamCookie NvSciStreamCookie_Invalid = 0U; + +/** + * \cond Non-doxygen comment + * page nvsci_stream_logical_data_types NvSciStream logical data types + * section NvSciStream logical data types + * Block: A block is a modular portion of a stream which resides + * in a single process and manages one aspect of the stream's + * behavior. Blocks are connected together in a tree to form + * arbitrary streams. + * + * NvSciStream supports the following types of blocks: + * - Producer: Producer is a type of block responsible for + * generating stream data. Each stream begins with a producer + * block, it is also referred to as the upstream endpoint of the + * stream. + * + * - Consumer: Consumer is a type of block responsible for + * processing stream data. Each stream ends with one or + * more consumer blocks, it is also referred to as the + * downstream endpoint of the stream. + * + * - Pool: Pool is a type of block containing the set of + * packets available for use by @a Producer. NvSciStream + * supports only a static pool in which the number of + * packets managed by the pool is fixed when the pool + * is created. + * + * - Queue: Queue is a type of block containing set of + * packets available for use by @a Consumer. + * NvSciStream supports two types of queue blocks: + * - Fifo: A Fifo Queue block is used when all + * packets must be acquired by the consumer in + * the order received. Packets will wait in the FIFO + * until the consumer acquires them. + * - Mailbox: Mailbox Queue block is used when the consumer + * should acquire the most recent data. If a new + * packet is inserted in the mailbox when one + * is already waiting, the previous one will be skipped + * and its buffers will immediately be returned to the + * Producer for reuse. + * + * - Multicast: Multicast is a type of block which is responsible + * for connecting separate pipelines when a stream has more than + * one Consumer. + * + * - IpcSrc - IpcSrc is a type of block which is the upstream + * half of an IPC block pair which allows NvSciSyncObj waiter + * requirements, NvSciSyncObj(s), packet element + * information and packets to be transmitted to or received from + * the downstream half of the stream which resides in another + * process. + * + * - IpcDst - IpcDst is a type of block which is the downstream + * half of an IPC block pair which allows NvSciSyncObj waiter + * requirements, NvSciSyncObj(s), packet element + * information and packets to be transmitted to or received from + * the upstream half of the stream which resides in another process. + * + * Packet: A packet represents a set of NvSciBufObjs containing stream + * data, each NvSciBufObj it contains is also referred to as an element + * of the packet. + * \endcond + */ + +/*! \brief Defines NvSciStream attributes that are queryable. + * + * \implements{19621074} + */ +typedef enum { + /*! \brief Maximum number of elements allowed per packet. */ + NvSciStreamQueryableAttrib_MaxElements = 0x000000, + /*! \brief Maximum number of NvSciSyncObjs allowed. */ + NvSciStreamQueryableAttrib_MaxSyncObj = 0x000001, + /*! \brief Maximum number of multicast outputs allowed. */ + NvSciStreamQueryableAttrib_MaxMulticastOutputs = 0x000002 +} NvSciStreamQueryableAttrib; + +/*! \brief Most queries on one block request information received from + *! another block. Where there is ambiguity in the kind of block the + *! information originated from, this type is used to specify it. + */ +typedef enum { + /*! \brief Query information received from the producer */ + NvSciStreamBlockType_Producer, + /*! \brief Query information received from a consumer */ + NvSciStreamBlockType_Consumer, + /*! \brief Query information received from the pool */ + NvSciStreamBlockType_Pool +} NvSciStreamBlockType; + +/*! \brief Setup information will be broken into several distinct groups, + *! with restrictions on when they can be specified and queried. The + *! application will indicate when each group has been fully specified + *! and is ready to send (for *Export groups) or when it has finished + *! querying the group and the driver can reclaim space and allow dependent + *! operations to proceed (for *Import groups). + */ +typedef enum { + /*! \brief Specification of element-related support. + * + * In the producer and consumer(s), this group contains the list of + * elements supported by the endpoint. Marking this complete causes + * the list to be sent to the pool. + * + * In the pool, this group contains the list of elements which will + * be used for the final packet layout. Marking this complete causes + * the list to be sent to the producer and consumer(s). This group of + * operations are not supported on the secondary pool. + * + * When element export is complete, the following functions are no longer + * available on the block: + * - NvSciStreamBlockElementAttrSet() + * + * When element export is complete, the following functions become + * available on the pool: + * - NvSciStreamPoolPacketCreate() + * - NvSciStreamPoolPacketInsertBuffer() + * - NvSciStreamPoolPacketComplete() + * - NvSciStreamPoolPacketStatusAcceptGet() + * - NvSciStreamPoolPacketStatusValueGet() + */ + NvSciStreamSetup_ElementExport = 0x0001, + + /*! \brief Processing of element-related support + * + * In the pool, this group contains the lists of supported elements sent by + * the producer and consumer(s). Marking this complete releases resources + * associated with these lists. This must be completed before element + * export can complete. + * + * In the producer and consumer(s), this group contains the list of + * elements sent by the pool for use in the final packet layout, as + * well as the flags tracking whether the block uses each element (for + * consumers only). Marking this complete releases resources associated + * with the element list, sends the usage list through the stream for + * use in optimization, and unblocks any pending + * NvSciStreamEventType_PacketCreate events waiting at the block. + * + * When element import is complete, the following functions are no longer + * available on the block: + * - NvSciStreamBlockElementCountGet() + * - NvSciStreamBlockElementAttrGet() + * - NvSciStreamBlockElementUsageSet() + */ + NvSciStreamSetup_ElementImport = 0x0002, + + /*! \brief Specification of all packets + * + * In the pool, this group contains the lists of all packet definitions. + * Marking this complete releases resources associated with the packet + * setup, and indicates no more packets will be created. The producer + * and consumer will receive an NvSciStreamEventType_PacketsComplete + * event after receiving all of the individual packets. + * + * When packet export is completed, the following functions are no longer + * available on the pool: + * - NvSciStreamPoolPacketCreate() + * - NvSciStreamPoolPacketInsertBuffer() + * - NvSciStreamPoolPacketComplete() + */ + NvSciStreamSetup_PacketExport = 0x0011, + + /*! \brief Mapping of all packets + * + * In the producer and consumer, this group contains the lists of all + * packet definitions and their status. This cannot be completed + * until the NvSciStreamEventType_PacketsComplete event arrives from + * the pool and status has been returned for all received packets. + * + * In the pool, this group contains the packet status returned by + * the producer and consumers. This cannot be completed until + * packet export has finished and NvSciStreamEventType_PacketStatus + * events have arrived for all packets. + * + * Marking this complete releases resources associated with the packet + * setup. + * + * When packet import is completed, the following functions are no longer + * available on the relevant blocks: + * - NvSciStreamBlockPacketNewHandleGet() + * - NvSciStreamBlockPacketBufferGet() + * - NvSciStreamBlockPacketStatusSet() + * - NvSciStreamPoolPacketStatusAcceptGet() + * - NvSciStreamPoolPacketStatusValueGet() + */ + NvSciStreamSetup_PacketImport = 0x0012, + + /*! \brief Specification of waiter sync attributes + * + * In the producer and consumer, this group contains the per-element + * NvSciSync attribute lists containing the requirements to wait for + * sync objects signalled by the opposing endpoints. This cannot be + * completed until NvSciStreamSetup_ElementImport is completed, so + * the list of used elements is known. + * + * When waiter information export is completed, the following functions + * are no longer available: + * - NvSciStreamBlockElementWaiterAttrSet() + */ + NvSciStreamSetup_WaiterAttrExport = 0x0021, + + /*! \brief Processing of waiter sync attributes + * + * In the producer and consumer, this group contains the per-element + * NvSciSync attribute lists containing the requirements provided + * by the opposing endpoints so that they can wait for sync objects + * signalled by this endpoint. This cannot be completed until + * NvSciStreamSetup_ElementImport is completed and the + * NvSciStreamEventType_WaiterAttr event has arrived. + * + * When waiter information import is completed, the following functions + * are no longer available: + * - NvSciStreamBlockElementWaiterAttrGet() + */ + NvSciStreamSetup_WaiterAttrImport = 0x0022, + + /*! \brief Specification of signaling sync objects + * + * In the producer and consumer, this group contains the per-element + * NvSciSync objects used to signal when writing and reading, + * respectively, of each element has completed. This cannot be + * completed until NvSciStreamSetup_WaiterAttrImport is completed. + * + * When signal information export is completed, the following functions + * are no longer available: + * - NvSciStreamBlockElementSignalObjSet() + */ + NvSciStreamSetup_SignalObjExport = 0x0031, + + /*! \brief Mapping of signaling sync objects + * + * In the producer and consumer, this group contains the per-element + * NvSciSync objects that are signalled when the opposing endpoint(s) + * are done reading and writing, respectively, each element. This cannot + * be completed until the NvSciStreamEventType_SignalObj event has + * arrived. + * + * When waiter information import is completed, the following functions + * are no longer available: + * - NvSciStreamBlockElementSignalObjGet() + */ + NvSciStreamSetup_SignalObjImport = 0x0032, + + /*! \brief Continue initialization with the new connected consumers. + * + * In the multicast, even though not all consumers are connected, marking + * this complete allows the application to continue the initialization + * and streaming with the existing consumers. This is applicable to both + * early-attach and late-attach consumers. This cannot be completed until + * there's a new connection to the multicast. + * + * When the existing consumer(s) finish initialization and enter the + * streaming phase, the multicast can start another connection with the + * new late-attach consumer(s), after receiving the + * NvSciStreamEventType_SetupComplete event. + */ + NvSciStreamSetup_Connect = 0x0041, + + /*! \brief Indication for successful CRC validation. + * + * In the producer, marking this complete means the producer finishes + * all validation and validation is successful, which unblocks the + * pending NvSciStreamEventType_SetupComplete event. + * + * This must be used by producer after receiving the + * NvSciStreamEventType_Validate event. + */ + NvSciStreamSetup_CrcImport = 0x0051, + + /*! \brief Specification CRC validation data + * + * In the consumer, marking this complete means that CRC data is set and is + * ready for validation. This triggers the validation event + * NvSciStreamEventType_Validate at producer. + */ + NvSciStreamSetup_CrcExport = 0x0052 + +} NvSciStreamSetup; + +/*! \brief Defines event types for the blocks. + * + * \implements{19621083} + */ +typedef enum { + + /*! \brief + * Indicates the stream containing the block is fully connected. + * + * At all blocks, the following functions become available: + * - NvSciStreamBlockConsumerCountGet() + * + * At the producer and consumer blocks, the element export phase may + * begin, and the following functions become available: + * - NvSciStreamBlockElementAttrSet() + */ + NvSciStreamEventType_Connected = 0x004004, + + /*! \brief + * Indicates portions of the stream have disconnected such that no + * more useful work can be done with the block. Note that this + * event is not always triggered immediately when any disconnect + * occurs. For instance: + * - If a consumer still has packets waiting in its queue when + * a producer is destroyed, it will not be informed of the + * disconnection until all packets are acquired + * by calling NvSciStreamConsumerPacketAcquire(). + * + * Received by all blocks. + */ + NvSciStreamEventType_Disconnected = 0x004005, + + /*! \brief + * Signals the arrival of NvSciSync waiter information from the + * opposing endpoint(s). + * + * Received by producer and consumer blocks. + * + * The following function becomes available: + * - NvSciStreamBlockElementWaiterAttrGet() + * - NvSciStreamBlockElementSignalObjSet() + */ + NvSciStreamEventType_WaiterAttr = 0x004013, + + /*! \brief + * Signals the arrival of NvSciSync signal information from the + * opposing endpoint(s). + * + * Received by producer and consumer blocks. + * + * The following function becomes available: + * - NvSciStreamBlockElementSignalObjGet() + */ + NvSciStreamEventType_SignalObj = 0x004014, + + /*! \brief + * Signals the arrival of all element-related information. + * + * At the pool, both the element import and export phases may begin, + * and the following functions become available: + * - NvSciStreamBlockElementCountGet() + * - NvSciStreamBlockElementAttrGet() + * - NvSciStreamBlockElementAttrSet() + * + * At the producer and consumer(s), the element import and waiter + * information export phases may begin, and the following functions + * become available: + * - NvSciStreamBlockElementCountGet() + * - NvSciStreamBlockElementAttrGet() + * - NvSciStreamBlockElementUsageSet() (consumer only) + * - NvSciStreamBlockElementWaiterAttrSet() + * + * Not received by any other block types. + */ + NvSciStreamEventType_Elements = 0x004026, + + /*! \brief + * Signals the arrival of a new packet definition from the pool. + * + * Received by producer and consumer blocks. + * + * These events become available to the producer and consumer after + * they have indicated that they are done importing element + * information by calling NvSciStreamBlockSetupStatusSet() + * with NvSciStreamSetup_ElementImport. The following functions + * become available to query and accept or reject packet information: + * - NvSciStreamBlockPacketNewHandleGet() + * - NvSciStreamBlockPacketBufferGet() + * - NvSciStreamBlockPacketStatusSet() + */ + NvSciStreamEventType_PacketCreate = 0x004030, + + /*! \brief + * Signals that the pool has finished defining all of its packets. + * + * Received by producer and consumer blocks. + * + * This event becomes available to the producer and consumer after + * the pool indicates it has sent all the packets. + */ + NvSciStreamEventType_PacketsComplete = 0x004038, + + /*! \brief + * Signals that the pool has deleted a packet and no further paylaods + * using the packet will arrive. + * + * Received by producer and consumer blocks. + * + * The following function becomes available to query the deleted packet: + * - NvSciStreamBlockPacketOldCookieGet() + */ + NvSciStreamEventType_PacketDelete = 0x004032, + + /*! \brief + * Signals the arrival of status for a packet from producer and all + * consumers. + * + * Received by pool blocks. + * + * The following functions become available to query the packet status: + * - NvSciStreamPoolPacketStatusAcceptGet() + * - NvSciStreamPoolPacketStatusValueGet() + */ + NvSciStreamEventType_PacketStatus = 0x004037, + + /*! \brief + * Specifies a packet is available for reuse or acquire. + * + * Received by producer and consumer blocks. + */ + NvSciStreamEventType_PacketReady = 0x004040, + + /*! \brief + * Specifies all setup operations have completed and streaming may begin. + * + * Received by all blocks. + */ + NvSciStreamEventType_SetupComplete = 0x004050, + + /*! \brief + * Signals the validation data provided by all consumers. + * + * Received by producer block only. + */ + NvSciStreamEventType_Validate = 0x004060, + + /*! \brief + * Indicates a failure not directly triggered by user action. + * + * Received by any block. + */ + NvSciStreamEventType_Error = 0x0040FF + +} NvSciStreamEventType; + +#ifdef __cplusplus +} +#endif +/** @} */ +#endif /* NVSCISTREAM_TYPES_H */ diff --git a/nvscisync.h b/nvscisync.h new file mode 100644 index 0000000..1cec789 --- /dev/null +++ b/nvscisync.h @@ -0,0 +1,3230 @@ +/* + * Copyright (c) 2019-2023, NVIDIA CORPORATION. All rights reserved. + * + * 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. + */ +/** + * @file + * + * @brief NVIDIA Software Communications Interface (SCI) : NvSciSync + * + * The NvSciSync library allows applications to manage synchronization + * objects which coordinate when sequences of operations begin and end. + */ +#ifndef INCLUDED_NVSCISYNC_H +#define INCLUDED_NVSCISYNC_H + +/** + * @defgroup nvsci_sync Synchronization APIs + * + * @ingroup nvsci_group_stream + * @{ + * + * The NvSciSync library allows applications to manage synchronization + * objects which coordinate when sequences of operations begin and end. + * + * The following constants are defined and have type @c unsigned @c int: + * * @c NvSciSyncMajorVersion + * * @c NvSciSyncMinorVersion + * + * In C and C++ these constants are guaranteed to be defined as global + * const variables. + + * Upon each new release of NvSciSync: + * * If the new release changes behavior of NvSciSync that could in any way + * prevent an application compliant with previous versions of this + * specification from functioning correctly, or that could prevent + * interoperability with earlier versions of NvSciSync, the major version is + * increased and the minor version is reset to zero. + * @note This is typically done only after a deprecation period. + * * Otherwise, if the new release changes NvSciSync in any application + * observable manner (e.g., new features, or bug fixes), the major version is + * kept the same and the minor version is increased. + * * Otherwise, the major and minor version are both kept the same. + * + * This version of this specification corresponds to NvSciSync version 1.0 + * (major version 1, minor version 0). + * + * Different processes using the NvSciSync inter-process APIs may use different + * minor versions of NvSciSync within the same major version, provided that if + * a process uses a feature newer than another processor's NvSciSync version, + * the latter process does not import an unreconciled NvSciSyncAttrList (directly + * or indirectly) from the former process. + * + * In general, an NvSciSync API call will not return an error code if it has + * caused any side effects other than allocating resources and subsequently + * freeing those resources. + * + * In general, unless specified otherwise, if a NULL pointer is passed to an + * NvSciSync API call, the API call will either return ::NvSciError_BadParameter + * or (if there are other applicable error conditions as well) an error code + * corresponding to another error. + * + * Each NvSciSyncAttrList is either unreconciled or reconciled. + * It is unreconciled if it was: + * - Created by NvSciSyncAttrListCreate(), + * - Created by a failed NvSciSyncAttrListReconcile() call, + * - Created by a failed NvSciSyncAttrListReconcileAndObjAlloc() call, or + * - An import of an export of one or more unreconciled NvSciSyncAttrLists. + * + * It is reconciled if it was: + * - Created by a successful NvSciSyncAttrListReconcile() call, + * - Provided by NvSciSyncObjGetAttrList(), or + * - An import of an export of another reconciled NvSciSyncAttrList. + */ + +/** + * \page nvscisync_page_blanket_statements NvSciSync blanket statements + * \section nvscisync_in_out_params Input/Output parameters + * - NvSciSyncFence passed as input parameter to an API is valid input if + * it was first initialized to all zeroes + * or modified by any successful NvSciSync API accepting NvSciSyncFence. + * - NvSciSyncObj passed as an input parameter to an API is valid input if it + * is returned from a successful call to NvSciSyncObjAlloc(), NvSciSyncObjDup(), + * NvSciSyncObjIpcImport(), NvSciSyncIpcImportAttrListAndObj(), + * NvSciSyncAttrListReconcileAndObjAlloc(), or NvSciSyncFenceGetSyncObj() and + * has not yet been deallocated using NvSciSyncObjFree(). + * - NvSciSyncCpuWaitContext passed as an input parameter to an API is valid + * input if it is returned from a successful call to + * NvSciSyncCpuWaitContextAlloc() and has not been deallocated using + * NvSciSyncCpuWaitContextFree(). + * - NvSciSyncModule passed as input parameter to an API is valid input if it is + * returned from a successful call to NvSciSyncModuleOpen() and has not yet + * been deallocated using NvSciSyncModuleClose(). + * - NvSciIpcEndpoint passed as input parameter to an API is valid if it is + * obtained from successful call to NvSciIpcOpenEndpoint() and has not yet been + * freed using NvSciIpcCloseEndpointSafe(). + * - Unreconciled NvSciSyncAttrList is valid if it is obtained from successful + * call to NvSciSyncAttrListCreate() or if it is obtained from successful call to + * NvSciSyncAttrListClone() where input to NvSciSyncAttrListClone() is valid + * unreconciled NvSciSyncAttrList or if it is obtained from successful call to + * NvSciSyncAttrListIpcImportUnreconciled() and has not been deallocated using + * NvSciSyncAttrListFree(). + * - Reconciled NvSciSyncAttrList is valid if it is obtained from successful call + * to NvSciSyncAttrListReconcile() or if it is obtained from successful call to + * NvSciSyncAttrListClone() where input to NvSciSyncAttrListClone() is valid + * reconciled NvSciSyncAttrList or if it is obtained from successful call to + * NvSciSyncAttrListIpcImportReconciled() and has not been deallocated using + * NvSciSyncAttrListFree() or has been obtained from a successful call to + * NvSciSyncObjGetAttrList() and the input NvSciSyncObj to this call has not + * yet been deallocated using NvSciSyncObjFree(). + * - If the valid range for the input parameter is not explicitly mentioned in + * the API specification or in the blanket statements then it is considered that + * the input parameter takes any value from the entire range corresponding to + * its datatype as the valid value. Please note that this also applies to the + * members of a structure if the structure is taken as an input parameter. + * - NvSciSyncModule is not sharable accross processes. User must create a new + * NvSciSyncModule using NvSciSyncModuleOpen() in every process. + * + * \section nvscisync_out_params Output parameters + * - In general, output parameters are passed by reference through pointers. + * Also, since a null pointer cannot be used to convey an output parameter, API + * functions typically return an error code if a null pointer is supplied for a + * required output parameter unless otherwise stated explicitly. Output + * parameter is valid only if error code returned by an API is + * NvSciError_Success unless otherwise stated explicitly. + * + * \section nvscisync_concurrency Concurrency + * - Every individual function can be called concurrently with itself + * without any side-effects unless otherwise stated explicitly in + * the interface specifications. + * - The conditions for combinations of functions that cannot be called + * concurrently or calling them concurrently leads to side effects are + * explicitly stated in the interface specifications. + * + * \section nvscisync_fence_states Fence states + * - A zero initialized NvSciSyncFence or one fed to NvSciSyncFenceClear() + * becomes cleared. + * - NvSciSyncFence becomes not cleared if it is modified by a successful + * NvSciSyncObjGenerateFence() or NvSciSyncFenceDup(). + * - NvSciSyncFence filled by successful NvSciSyncIpcImportFence() is cleared + * if and only if the input fence descriptor was created from a cleared + * NvSciSyncFence. + * + * \implements{18839709} + */ + +#if !defined (__cplusplus) +#include +#include +#include +#endif + +#include +#include +#include + +#if defined (__cplusplus) +extern "C" +{ +#endif + +#if defined __GNUC__ + #define PACK_SYNC( __Declaration__, ... ) __Declaration__,##__VA_ARGS__ __attribute__((packed)) +#else + #define PACK_SYNC( __Declaration__, ... ) __pragma(pack(push, 1)) __Declaration__,##__VA_ARGS__ __pragma(pack(pop)) +#endif + +/** + * \brief NvSciSync major version number. + * + * \implements{18840177} + */ +static const uint32_t NvSciSyncMajorVersion = 2U; + +/** + * \brief NvSciSync minor version number. + * + * \implements{18840180} + */ +static const uint32_t NvSciSyncMinorVersion = 6U; + +/** + * Maximum supported timeout value. + * NvSciSyncFenceWait() can wait for at most this many microseconds. + * This value also corresponds to infinite timeout. + */ +static const int64_t NvSciSyncFenceMaxTimeout = (0x7fffffffffffffff / 1000); + +/** + * \brief Represents an instance of the NvSciSyncModule. Any NvSciSyncAttrList + * created or imported using a particular NvSciSyncModule is bound to that + * module instance, along with any NvSciSyncObjs created or imported using those + * NvSciSyncAttrLists and any NvSciSyncFences created or imported using those + * NvSciSyncObjs. + * + * @note For any NvSciSync API call that has more than one input of type + * NvSciSyncModule, NvSciSyncAttrList, NvSciSyncObj, and/or NvSciSyncFence, all + * such inputs must agree on the NvSciSyncModule instance. + */ +typedef struct NvSciSyncModuleRec* NvSciSyncModule; + +/** + * \brief Represents the right to perform a CPU wait on an NvSciSyncFence. It + * holds resources necessary to perform a CPU wait using NvSciSyncFenceWait(). + * It can be used to wait on NvSciSyncFence(s) associated with the same + * NvSciSyncModule that this NvSciSyncCpuWaitContext is associated with. + * An NvSciSyncCpuWaitContext can be used to wait on only one + * NvSciSyncFence at a time. However, a single NvSciSyncCpuWaitContext + * can be used to wait on different NvSciSyncFences at different + * instants of time. + */ +typedef struct NvSciSyncCpuWaitContextRec* NvSciSyncCpuWaitContext; + +/** + * \brief Defines the opaque NvSciSyncFence. + * + * This structure describes a synchronization primitive snapshot + * that must be reached to release the waiters. + * + * Unlike NvSciSyncAttrList and NvSciSyncObj objects, applications are + * responsible for the memory management of NvSciSyncFences. + * + * Every NvSciSyncFence must be initialized to all zeros after its storage + * is allocated before the first time it is passed to any NvSciSync API + * calls. NvSciSyncFenceInitializer can be used for this, or + * memset(), or any other mechanism for zeroing memory. + * + * Every NvSciSyncFence not in a cleared state holds a reference to + * the NvSciSyncObj it is related to, preventing that NvSciSyncObj + * from being deleted. It also contains + * id and value of the synchronization primitive corresponding + * to the desired snapshot. + * + * In case if the corresponding NvSciSyncObj supports timestamps, + * this structure also contains information about the memory location + * of the timestamp of the event unblocking the NvSciSyncFence. + * + * This structure also contains information about the memory location + * of the status of the task triggering the event unblocking + * the NvSciSyncFence. + */ +/** + * \implements{18840156} + */ +typedef struct NvSciSyncFence { + uint64_t payload[6]; +} NvSciSyncFence; + +/** + * \brief Defines the value used to zero-initialize the NvSciSyncFence object. + * An NvSciSyncFence that is all zeroes is in a cleared state. + * + * \implements{18840183} + */ +static const NvSciSyncFence NvSciSyncFenceInitializer = {{0U}}; + +/** + * \brief Defines the exported form of NvSciSyncFence intended to be shared + * across an NvSciIpc channel. + * + * \implements{18840195} + */ +typedef struct { + uint64_t payload[7]; +} NvSciSyncFenceIpcExportDescriptor; + +/** + * \brief Defines the exported form of NvSciSyncObj intended to be shared + * across an NvSciIpc channel. + * + * \implements{18840198} + */ +typedef struct { + /** Exported data (blob) for NvSciSyncObj */ + uint64_t payload[128]; +} NvSciSyncObjIpcExportDescriptor; + +/** + * A Synchronization Object is a container holding the reconciled + * NvSciSyncAttrList defining constraints of the Fence and the handle of the + * actual Primitive, with access permissions being enforced by the + * NvSciSyncAttrKey_RequiredPerm and NvSciSyncAttrKey_NeedCpuAccess Attribute + * Keys. + * + * If Timestamps have been requested prior to Reconciliation via the + * NvSciSyncAttrKey_WaiterRequireTimestamps key, this will also hold the + * Timestamp Buffer allocated by NvSciBuf. + * + * The object will also hold a buffer containing the task statuses + * of the tasks signaling this Object. + */ + +/** + * \brief A reference to a particular Synchronization Object. + * + * @note Every NvSciSyncObj that has been created but not freed + * holds a reference to the NvSciSyncModule, preventing the module + * from being de-initialized. + */ +typedef struct NvSciSyncObjRec* NvSciSyncObj; + +/** + * \brief A reference, that is not modifiable, + * to a particular Synchronization Object. + */ +typedef const struct NvSciSyncObjRec* NvSciSyncObjConst; + +/** + * \brief A container constituting an NvSciSyncAttrList which contains: + * - set of NvSciSyncAttrKey attributes defining synchronization object + * constraints + * - slot count defining number of slots in an NvSciSyncAttrList + * - flag specifying if NvSciSyncAttrList is reconciled or unreconciled. + * + * @note Every NvSciSyncAttrList that has been created but not freed + * holds a reference to the NvSciSyncModule, preventing the module + * from being de-initialized. + */ +typedef struct NvSciSyncAttrListRec* NvSciSyncAttrList; + +/** + * \brief Describes NvSciSyncObj access permissions. + * + * \implements{18840171} + */ +typedef uint64_t NvSciSyncAccessPerm; + +/** + * This represents the capability to wait on an NvSciSyncObj as it + * progresses through points on its sync timeline. + */ +#if defined(__cplusplus) + #define NvSciSyncAccessPerm_WaitOnly (static_cast(1U) << 0U) +#else + #define NvSciSyncAccessPerm_WaitOnly ((uint64_t)1U << 0U) +#endif + +/** + * This represents the capability to advance an NvSciSyncObj to its + * next point on its sync timeline. + */ +#if defined(__cplusplus) + #define NvSciSyncAccessPerm_SignalOnly (static_cast(1U) << 1U) +#else + #define NvSciSyncAccessPerm_SignalOnly ((uint64_t)1U << 1U) +#endif + +/** + * This represents the capability to advance an NvSciSyncObj to its + * next point on its sync timeline and also wait until that next point is + * reached. + */ +#define NvSciSyncAccessPerm_WaitSignal (NvSciSyncAccessPerm_WaitOnly | NvSciSyncAccessPerm_SignalOnly) +/** + * Usage of Auto permissions is restricted only for export/import APIs and + * shouldn't be used as valid value for NvSciSyncAttrKey_RequiredPerm + * Attribute. + */ +#if defined(__cplusplus) + #define NvSciSyncAccessPerm_Auto (static_cast(1U) << 63U) +#else + #define NvSciSyncAccessPerm_Auto ((uint64_t)1U << 63U) +#endif + +/** + * \brief Status of the signaler's task that signals a particular + * NvSciSyncFence. + * + * This is defined as an enum but will be kept in a 16-bit field + * of a slot in the shared task status buffer. + * + * A value outside of range defined here is an engine specific failure. + * + * \implements{TBD} + */ +typedef enum { + /** The task has completed successfully */ + NvSciSyncTaskStatus_Success = 0U, + /** The task has failed */ + NvSciSyncTaskStatus_Failure = 1U, + /** The signaler did not report any task status. + The default value set by NvSciSync when a new slot is requested. */ + NvSciSyncTaskStatus_Invalid = UINT16_MAX, +} NvSciSyncTaskStatusVal; + +/** + * \brief A single slot in the task status buffer. + * + * \implements{TBD} + */ +PACK_SYNC(typedef struct { + /** Used to get timestamp of Task Status */ + uint64_t timestamp; + /** unused */ + uint32_t statusEngine; + /** unused */ + uint16_t subframe; + /** A status word filled with NvSciSyncTaskStatusVal values. + * A value from beyond NvSciSyncTaskStatusVal's range signifies + * an engine specific error */ + uint16_t status; +}) NvSciSyncTaskStatus; + +/** + * \brief Types of synchronization primitives. + * + * \implements{} + */ +enum NvSciSyncAttrValPrimitiveTypeRec { + /** For NvSciSync internal use only */ + NvSciSyncAttrValPrimitiveType_LowerBound, + /** + * Syncpoint. + * Supported only on Tegra platforms. + */ + NvSciSyncAttrValPrimitiveType_Syncpoint, + /** + * 16 bytes semaphore backed by system memory. + * Contains space for 8-byte timestamp and 4-byte payload. + * Supported on Tegra and x86_64 platforms. + */ + NvSciSyncAttrValPrimitiveType_SysmemSemaphore, + /** + * 16 bytes semaphore backed by video memory. + * Contains space for 8-byte timestamp and 4-byte payload. + * Currently not supported. + */ + NvSciSyncAttrValPrimitiveType_VidmemSemaphore, + /** + * 16 bytes semaphore backed by system memory. + * Contains space for 8-byte timestamp and 8-byte payload. + * Supported on Tegra and x86_64 platforms. + */ + NvSciSyncAttrValPrimitiveType_SysmemSemaphorePayload64b, + /** + * 16 bytes semaphore backed by video memory. + * Contains space for 8-byte timestamp and 8-byte payload. + * Currently not supported. + */ + NvSciSyncAttrValPrimitiveType_VidmemSemaphorePayload64b, + /** For NvSciSync internal use only */ + NvSciSyncAttrValPrimitiveType_UpperBound, +}; + +/** + * \brief Alias for enum NvSciSyncAttrValPrimitiveTypeRec + * + * \implements{} + */ +typedef enum NvSciSyncAttrValPrimitiveTypeRec NvSciSyncAttrValPrimitiveType; + +/** + * \brief Describes the NvSciSync public attribute keys holding the + * corresponding values specifying synchronization object constraints. Input + * attribute keys specify desired synchronization object constraints and can be + * set/retrieved from the unreconciled NvSciSyncAttrList using + * NvSciSyncAttrListSetAttrs()/NvSciSyncAttrListGetAttrs() respectively. Output + * attribute keys specify actual constraints computed by NvSciSync if + * reconciliation succeeds. Output attribute keys can be retrieved from a + * reconciled NvSciSyncAttrList using NvSciSyncAttrListGetAttrs(). + * + * \implements{18840165} + */ +typedef enum { + /** Specifies the lower bound - for NvSciSync internal use only. */ + NvSciSyncAttrKey_LowerBound, + /** (bool, inout) Specifies if CPU access is required. + * + * During reconciliation, reconciler sets value of this key to true in the + * reconciled NvSciSyncAttrList if any of the unreconciled + * NvSciSyncAttrList(s) involved in reconciliation that is owned by the + * reconciler has this key set to true, otherwise it is set to false in + * reconciled NvSciSyncAttrList. + * If the user sets it to true in the unreconciled list but does not set + * NvSciSyncAttrKey_PrimitiveInfo, then NvSciSync will add the following values + * to NvSciSyncAttrKey_PrimitiveInfo attribute just before reconciliation or + * exporting unreconciled attribute list: + * - NvSciSyncAttrValPrimitiveType_Syncpoint + * - NvSciSyncAttrValPrimitiveType_SysmemSemaphore + * - NvSciSyncAttrValPrimitiveType_SysmemSemaphorePayload64b + * + * When importing the reconciled NvSciSyncAttrList NvSciSync will set the key + * to OR of values of this key in unreconciled NvSciSyncAttrList(s) relayed by + * the peer. + * + * During validation of reconciled NvSciSyncAttrList against input + * unreconciled NvSciSyncAttrList(s), validation succeeds if value of this + * attribute in the reconciled NvSciSyncAttrList is true provided any of the + * input unreconciled NvSciSyncAttrList(s) owned by the peer set it to + * true OR if value of this attribute in the reconciled NvSciSyncAttrList is + * false provided all of the input unreconciled NvSciSyncAttrList(s) owned by + * the peer set it to false. + */ + NvSciSyncAttrKey_NeedCpuAccess, + /** + * (NvSciSyncAccessPerm, inout) Specifies the required access permissions. + * If @ref NvSciSyncAttrKey_NeedCpuAccess is true, the CPU will be offered + * at least these permissions. + * Any hardware accelerators that contribute to this NvSciSyncAttrList will be + * offered at least these permissions. + */ + NvSciSyncAttrKey_RequiredPerm, + /** + * (NvSciSyncAccessPerm, out) Actual permission granted after reconciliation. + * @note This key is read-only. + * + * It represents the cumulative permissions of the + * NvSciSyncAttrKey_RequiredPerm in all NvSciSyncAttrLists being reconciled. + * The reconciliation fails if any of the following conditions are met: + * - no NvSciSyncAttrList with NvSciSyncAttrKey_RequiredPerm being set to + * NvSciSyncAccessPerm_SignalOnly, + * - more than one NvSciSyncAttrList with NvSciSyncAttrKey_RequiredPerm + * being set to NvSciSyncAccessPerm_SignalOnly, + * - no NvSciSyncAttrList with NvSciSyncAttrKey_RequiredPerm + * being set to NvSciSyncAccessPerm_WaitOnly. + * + * If NvSciSyncObj is obtained by calling NvSciSyncObjAlloc(), + * NvSciSyncAttrKey_ActualPerm is set to NvSciSyncAccessPerm_WaitSignal + * in the reconciled NvSciSyncAttrList corresponding to it since allocated + * NvSciSyncObj gets wait-signal permissions by default. + * + * For any peer importing the NvSciSyncObj, this key is set in the reconciled + * NvSciSyncAttrList to the sum of NvSciSyncAttrKey_RequiredPerm requested + * by the peer and all peers relaying their NvSciSyncAttrList export + * descriptors via it. + * + * During validation of reconciled NvSciSyncAttrList against input + * unreconciled NvSciSyncAttrList(s), validation succeeds only if + * NvSciSyncAttrKey_ActualPerm in reconciled is bigger or equal than + * NvSciSyncAttrKey_RequiredPerm of all the input unreconciled + * NvSciSyncAttrLists. + */ + NvSciSyncAttrKey_ActualPerm, + /** + * (bool, inout) Importing and then exporting an + * NvSciSyncFenceIpcExportDescriptor has no side effects and yields an + * identical NvSciSyncFenceIpcExportDescriptor even if the + * NvSciIpcEndpoint(s) used for import and export are different from ones + * used for exporting/importing NvSciSyncAttrList(s). + * + * If this attribute key is set to false, this indicates that the + * NvSciSyncFenceIpcExportDescriptor must be exported through the same IPC + * path as the NvSciSyncObj. Otherwise if set to true, this indicates that + * the NvSciSyncFenceIpcExportDescriptor must be exported via NvSciIpc + * through the first peer that was part of the IPC path travelled through + * by the NvSciSyncObj (but not necessarily an identical path). + * + * During reconciliation, this key is set to true in reconciled + * NvSciSyncAttrList if any one of the input NvSciSyncAttrList has this set + * to true. + */ + NvSciSyncAttrKey_WaiterContextInsensitiveFenceExports, + /** (bool, inout) Specifies if timestamps are required. If the waiter + * wishes to read timestamps then the NvSciSyncAttrKey_NeedCpuAccess key + * should be set to true. + * + * Only valid for CPU waiters. */ + NvSciSyncAttrKey_WaiterRequireTimestamps, + /** + * (bool, inout) Specifies if deterministic primitives are required. + * This allows for the possibility of generating fences on the waiter's + * side without needing to import them. This means that the Signaler will + * increment the instance 0 of the primitive in NvSciSyncObj by 1 at each + * submission. + * + * During reconciliation, this key is set to true in the reconciled + * NvSciSyncAttrList if any one of the input NvSciSyncAttrList(s) has this + * set to true. + */ + NvSciSyncAttrKey_RequireDeterministicFences, + /** + * (uint32_t, out) Specifies the total number of slots in the timestamps buffer. + * This allows the user to iterate over the slots by incrementing + * the current slot index modulo _NumTimestampsSlots. + * + * During reconciliation, the value of this key is set to the number of + * slots in the timestamps buffer. If timestamps are not required by this + * attribute list, then the value of this key is undefined. + */ + NvSciSyncAttrKey_NumTimestampSlots, + /** + * (uint32_t, out) Specifies the total number of slots in the task status buffer. + * This allows the user to iterate over the slots by incrementing + * the current slot index modulo _NumTaskStatusSlots. + * + * During reconciliation, the value of this key is set to the number of + * slots in the task status buffer. If task status is not required by this + * attribute list, then the value of this key will be 0. + */ + NvSciSyncAttrKey_NumTaskStatusSlots, + /** + * (uint64_t, out) Specifies the maximum value of the reconciled primitive. + * + * During reconciliation, value of this key is set to UINT64_MAX if the + * reconciled primitive type is 64bit-SysmemSemaphore, otherwise value of + * the key is set to UINT32_MAX + */ + NvSciSyncAttrKey_MaxPrimitiveValue, + /** + * (NvSciSyncAttrValPrimitiveType[], inout) supported primitive + * types. + * + * If set, the value of this key is used in reconciliation and determines + * the primitive type backing the NvSciSyncObj. + * If this key is not set, then it has no impact on reconciliation. + * During reconciliation, the reconciler sets the value of this key to the + * reconciled primitive type. + * + * The reconciliation will fail if this key is set to value which does not + * intersect with values of primitive type set internally by user mode drivers + * or NvSciSync. + * + * During validation of a reconciled NvSciSyncAttrList against input + * unreconciled NvSciSyncAttrList(s), validation succeeds if the + * NvSciSyncAttrValPrimitiveType in + * NvSciSyncAttrKey_PrimitiveInfo of the reconciled + * NvSciSyncAttrList is present in NvSciSyncAttrKey_PrimitiveInfo or any of + * the internal attributes related to NvSciSyncAttrValPrimitiveType + * of the input unreconciled NvSciSyncAttrLists. + */ + NvSciSyncAttrKey_PrimitiveInfo, + + /** (NvSciBufPeerLocationInfo[], inout) An attribute indicating location + * information of late peer which are going to gain access to the allocated + * NvSciSyncObj using NvSciSyncObjAttachPeer() API. + */ + NvSciSyncAttrKey_PeerLocationInfo, +#if (NV_IS_SAFETY == 0) + /** + * (NvSciRmGpuId[], inout) + * GpuID of the GPU in the system that will access the semaphore + * buffer. + */ +#else + /** + * (NvSciRmGpuId, inout) Unused + */ +#endif + NvSciSyncAttrKey_GpuId, + /** + * (NvSciBufPeerHwEngine[], inout) An attribute indicating engine + * information of late peer which are going to gain access to the allocated + * NvSciSyncObj using NvSciSyncObjAttachPeer() API. + */ + NvSciSyncAttrKey_PeerHwEngineArray, + /** Specifies the upper bound - for NvSciSync internal use only. */ + NvSciSyncAttrKey_UpperBound, +} NvSciSyncAttrKey; + +/** + * \brief This structure defines a key/value pair used to get or set + * the NvSciSyncAttrKey(s) and their corresponding values from or to + * NvSciSyncAttrList. + * + * \implements{18840168} + */ +typedef struct { + /** NvSciSyncAttrKey for which value needs to be set/retrieved. This member + * is initialized to any defined value of the NvSciSyncAttrKey other than + * NvSciSyncAttrKey_LowerBound and NvSciSyncAttrKey_UpperBound */ + NvSciSyncAttrKey attrKey; + /** Memory which contains the value corresponding to the key */ + const void* value; + /** Length of the value in bytes */ + size_t len; +} NvSciSyncAttrKeyValuePair; + +/** + * \brief Initializes and returns a new NvSciSyncModule with no + * NvSciSyncAttrLists, NvSciSyncCpuWaitContexts, NvSciSyncObjs or + * NvSciSyncFences bound to it. + * + * @note A process may call this function multiple times. Each successful + * invocation will yield a new NvSciSyncModule instance. + * + * \param[out] newModule The new NvSciSyncModule. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if @a newModule is NULL. + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_ResourceError if system drivers are not available or + * resources other then memory are unavailable. + * + * @pre + * - None + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncModuleOpen( + NvSciSyncModule* newModule); + +/** + * \brief Closes an instance of the NvSciSyncModule that was + * obtained through an earlier call to NvSciSyncModuleOpen(). Once an + * NvSciSyncModule is closed and all NvSciSyncAttrLists, NvSciSyncObjs, + * NvSciSyncCpuWaitContexts, NvSciSyncFences bound to that module instance are + * freed, the NvSciSyncModule instance will be de-initialized in the calling + * process. Until then the NvSciSyncModule will still be accessible from those + * objects still referencing it. + * + * \note Every owner of the NvSciSyncModule must call NvSciSyncModuleClose() + * only after all the functions invoked by the owner with NvSciSyncModule as an + * input are completed. + * + * \param[in] module The NvSciSyncModule instance to close. The calling process + * must not pass this module to another NvSciSync API call. + * + * \return void + * - Panics if: + * - Init Mode API is called in Runtime Mode. + * - @a module is invalid + * + * @pre + * - Valid NvSciSyncModule is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the input + * NvSciSyncModule @a module + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +void NvSciSyncModuleClose( + NvSciSyncModule module); + +/** + * \brief Allocates a new NvSciSyncCpuWaitContext. + * + * \param[in] module NvSciSyncModule instance with which to associate + * the new NvSciSyncCpuWaitContext. + * \param[out] newContext The new NvSciSyncCpuWaitContext. + * + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if @a module is NULL or @a newContext is NULL. + * - ::NvSciError_InvalidState if failed to associate @a module with @a + * newContext. + * - ::NvSciError_InsufficientMemory if not enough system memory to create a + * new context. + * - ::NvSciError_ResourceError if not enough system resources. + * - Panics if @a module is not valid. + * + * @pre + * - Valid NvSciSyncModule is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No +*/ +NvSciError NvSciSyncCpuWaitContextAlloc( + NvSciSyncModule module, + NvSciSyncCpuWaitContext* newContext); + +/** + * \brief Releases the NvSciSyncCpuWaitContext. + * + * \param[in] context NvSciSyncCpuWaitContext to be freed. + * + * \return void + * - Panics if: + * - Init Mode API is called in Runtime Mode. + * - NvSciSyncModule associated with @a context is not valid. + * + * @pre + * - Valid NvSciSyncCpuWaitContext is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the input + * NvSciSyncCpuWaitContext @a context + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No +*/ +void NvSciSyncCpuWaitContextFree( + NvSciSyncCpuWaitContext context); + +/** + * \brief Creates a new, single-slot unreconciled NvSciSyncAttrList + * associated with the input NvSciSyncModule with empty NvSciSyncAttrKeys. + * + * \param[in] module The NvSciSyncModule instance with which to associate the + * new NvSciSyncAttrList. + * \param[out] attrList The new NvSciSyncAttrList. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any argument is NULL. + * - ::NvSciError_InsufficientMemory if there is insufficient system memory + * - ::NvSciError_ResourceError if system lacks resource other than memory + * to create a NvSciSyncAttrList. + * - ::NvSciError_InvalidState if no more references can be taken for + * input NvSciSyncModule to create the new NvSciSyncAttrList. + * - Panics if @a module is not valid. + * + * @pre + * - Valid NvSciSyncModule is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncAttrListCreate( + NvSciSyncModule module, + NvSciSyncAttrList* attrList); + +/** + * \brief Frees the NvSciSyncAttrList and removes its association with the + * NvSciSyncModule with which it was created. + * + * \param[in] attrList The NvSciSyncAttrList to be freed. + * \return void + * - Panics if: + * - Init Mode API is called in Runtime Mode. + * - @a attrList is not valid. + * + * @pre + * - Valid NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the input + * NvSciSyncAttrList @a attrList + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +void NvSciSyncAttrListFree( + NvSciSyncAttrList attrList); + +/** + * \brief Checks whether the NvSciSyncAttrList is reconciled + * + * \param[in] attrList NvSciSyncAttrList to check. + * \param[out] isReconciled A pointer to a boolean to store whether the + * @a attrList is reconciled or not. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any argument is NULL. + * - Panics if @a attrList is not valid. + * + * @pre + * - Valid NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncAttrListIsReconciled( + NvSciSyncAttrList attrList, + bool* isReconciled); + +/** + * \brief Validates a reconciled NvSciSyncAttrList against a set of input + * unreconciled NvSciSyncAttrLists. + * + * \param[in] reconciledAttrList Reconciled NvSciSyncAttrList to be validated. + * \param[in] inputUnreconciledAttrListArray Array containing the unreconciled + * NvSciSyncAttrLists used for validation. + * Valid value: Array of valid unreconciled NvSciSyncAttrLists + * \param[in] inputUnreconciledAttrListCount number of elements/indices in + * @a inputUnreconciledAttrListArray + * Valid value: [1, SIZE_MAX] + * \param[out] isReconciledListValid A pointer to a boolean to store whether + * the reconciled NvSciSyncAttrList satisfies the parameters of set of + * unreconciled NvSciSyncAttrList(s) or not. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a inputUnreconciledAttrListArray is NULL + * - @a inputUnreconciledAttrListCount is 0 + * - an NvSciSyncAttrList appears multiple times in + * @a inputUnreconciledAttrListArray + * - @a isReconciledListValid is NULL + * - any of the input NvSciSyncAttrLists in + * inputUnreconciledAttrListArray are not unreconciled + * - @a reconciledAttrList is NULL or not reconciled + * - not all the NvSciSyncAttrLists in @a inputUnreconciledAttrListArray + * and the @a reconciledAttrList are bound to the same NvSciSyncModule + * instance. + * - reconciled NvSciSyncAttrList does not satisfy the unreconciled + * NvSciSyncAttrLists requirements. + * - ::NvSciError_InsufficientMemory if there is insufficient system memory + * to create temporary data structures + * - ::NvSciError_Overflow if internal integer overflow occurs. + * - Panics if @a reconciledAttrList or any of the input unreconciled + * NvSciSyncAttrList are not valid. + * + * @pre + * - Valid reconciled NvSciSyncAttrList is obtained. + * - Valid unreconciled NvSciSyncAttrList(s) are obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncAttrListValidateReconciled( + NvSciSyncAttrList reconciledAttrList, + const NvSciSyncAttrList inputUnreconciledAttrListArray[], + size_t inputUnreconciledAttrListCount, + bool* isReconciledListValid); + +/** + * \brief Sets the values for NvSciSyncAttrKey(s) in slot 0 of the + * input NvSciSyncAttrList. + * + * Reads values only during the call, saving copies. Only allows writing + * attributes once, making them non writable in the NvSciSyncAttrList. + * + * \param[in] attrList An unreconciled NvSciSyncAttrList containing the attribute + * key and value to set. + * \param[in] pairArray Array of NvSciSyncAttrKeyValuePair. + * Valid value: pairArray is valid input if it is not NULL and + * key member of every NvSciSyncAttrKeyValuePair in the array is an input or + * input/output attribute and it is > NvSciSyncAttrKey_LowerBound and < + * NvSciSyncAttrKey_UpperBound and value member of every NvSciSyncAttrKeyValuePair + * in the array is not NULL. + * \param[in] pairCount The number of elements/entries in @a pairArray. + * Valid value: pairCount is valid input if it is non-zero. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a pairArray is NULL + * - @a attrList is NULL + * - @a attrList is not unreconciled and/or not writable, + * - @a pairCount is 0 + * - @a pairArray has duplicate keys + * - any of the keys in @a pairArray is not a supported public key + * - any of the values in @a pairArray is NULL + * - any of the len(s) in @a pairArray is invalid for a given attribute + * - any of the attributes to be written is non-writable in attrList + * - Panics if @a attrList is not valid + * + * @pre + * - Valid unreconciled NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncAttrListSetAttrs( + NvSciSyncAttrList attrList, + const NvSciSyncAttrKeyValuePair* pairArray, + size_t pairCount); + +/** + * \brief Gets the value of NvSciSyncAttrKey from slot 0 of the input + * NvSciSyncAttrList. + * + * The return values, stored in NvSciSyncAttrKeyValuePair, consist of + * const void* pointers to the attribute values from NvSciSyncAttrList. + * The application must not write to this data. If an attribute was never set, + * the corresponding value will be set to NULL and length to 0. + * + * \param[in] attrList NvSciSyncAttrList to retrieve the value for given + * NvSciSyncAttrKey(s) from + * \param[in,out] pairArray A pointer to the array of NvSciSyncAttrKeyValuePair. + * Valid value: pairArray is valid input if it is not NULL and key member + * of every NvSciSyncAttrKeyValuePair in the array > NvSciSyncAttrKey_LowerBound + * and < NvSciSyncAttrKey_UpperBound. + * \param[in] pairCount The number of elements/entries in @a pairArray. + * Valid value: pairCount is valid input if it is non-zero. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - any argument is NULL + * - @a pairCount is 0 + * - any of the keys in @a pairArray is not a supported NvSciSyncAttrKey + * - Panics if @a attrList is not valid + * + * @pre + * - Valid NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncAttrListGetAttrs( + NvSciSyncAttrList attrList, + NvSciSyncAttrKeyValuePair* pairArray, + size_t pairCount); + +/** + * \brief Gets the slot count of the given NvSciSyncAttrList. + * + * \param[in] attrList NvSciSyncAttrList to get the slot count from. + * \return Number of slots or 0 if attrList is NULL or panic if attrList + * is not valid + * + * @pre + * - Valid NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +size_t NvSciSyncAttrListGetSlotCount( + NvSciSyncAttrList attrList); + +/** + * \brief Appends multiple unreconciled NvSciSyncAttrLists together, forming a + * single new unreconciled NvSciSyncAttrList with a slot count equal to the sum + * of all the slot counts of NvSciSyncAttrList(s) in the input array which is + * no longer writable. + * + * \param[in] inputUnreconciledAttrListArray Array containing the unreconciled + * NvSciSyncAttrList(s) to be appended together. + * Valid value: Array of unreconciled NvSciSyncAttrList(s) where the array + * size is at least 1. + * \param[in] inputUnreconciledAttrListCount Number of unreconciled + * NvSciSyncAttrList(s) in @a inputUnreconciledAttrListArray. + * Valid value: inputUnreconciledAttrListCount is valid input if it + * is non-zero. + * \param[out] newUnreconciledAttrList Appended NvSciSyncAttrList created out of + * the input unreconciled NvSciSyncAttrList(s). The output NvSciSyncAttrList is + * non-writable. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a inputUnreconciledAttrListArray is NULL + * - @a inputUnreconciledAttrListCount is 0 + * - an NvSciSyncAttrList appears multiple times in + * @a inputUnreconciledAttrListArray + * - @a newUnreconciledAttrList is NULL + * - any of the input NvSciSyncAttrLists in + * inputUnreconciledAttrListArray are not unreconciled + * - not all the NvSciSyncAttrLists in @a inputUnreconciledAttrListArray + * are bound to the same NvSciSyncModule instance. + * - ::NvSciError_InsufficientMemory if there is insufficient system memory to + * create the new unreconciled NvSciSyncAttrList. + * - ::NvSciError_Overflow if the combined slot counts of all the input + * NvSciSyncAttrLists exceeds UINT64_MAX + * - ::NvSciError_InvalidState if no more references can be taken for + * NvSciSyncModule associated with the NvSciSyncAttrList in @a + * inputUnreconciledAttrListArray to create the new NvSciSyncAttrList. + * - Panics if any of the input NvSciSyncAttrLists are not valid + * + * @pre + * - Valid unreconciled NvSciSyncAttrList(s) are obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncAttrListAppendUnreconciled( + const NvSciSyncAttrList inputUnreconciledAttrListArray[], + size_t inputUnreconciledAttrListCount, + NvSciSyncAttrList* newUnreconciledAttrList); + +/** + * \brief Clones an NvSciSyncAttrList. The cloned NvSciSyncAttrList will + * contain slot count, reconciliation type and all the attribute values of the + * original NvSciSyncAttrList. + * If the original NvSciSyncAttrList is unreconciled, then modification will be + * allowed on the cloned NvSciSyncAttrList using set attributes APIs even if the + * attributes had been set in the original NvSciSyncAttrList, but the calls to + * set attributes in either NvSciSyncAttrList will not affect the other. + * + * \param[in] origAttrList NvSciSyncAttrList to be cloned. + * \param[out] newAttrList The new NvSciSyncAttrList. + * + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if @a origAttrList or @a newAttrList is NULL. + * - ::NvSciError_InsufficientMemory if there is insufficient system memory + * - ::NvSciError_InvalidState if no more references can be taken for + * NvSciSyncModule associated with @a origAttrList to create the new + * NvSciSyncAttrList. + * - ::NvSciError_ResourceError if system lacks resource other than memory + * to create a NvSciSyncAttrList. + * - Panic if @a origAttrList is not valid + * + * @pre + * - Valid NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncAttrListClone( + NvSciSyncAttrList origAttrList, + NvSciSyncAttrList* newAttrList); + +/** + * \brief Gets the value(s) of NvSciSyncAttrKey(s) from an NvSciSyncAttrList at + * given slot index in a multi-slot unreconciled NvSciSyncAttrList. + * + * The returned pairArray consist of const void* pointers to the actual attribute + * values from NvSciSyncAttrList. The application must not overwrite this data. + * If an attribute was never set, the corresponding value will be set to NULL + * and length to 0. + * + * \param[in] attrList NvSciSyncAttrList to retrieve the NvSciSyncAttrKey and value + * from. + * \param[in] slotIndex Index in the NvSciSyncAttrList. + * Valid value: 0 to slot count of NvSciSyncAttrList - 1. + * \param[in,out] pairArray Array of NvSciSyncAttrKeyValuePair. Holds the + * NvSciSyncAttrKey(s) passed into the function and returns an array of + * NvSciSyncAttrKeyValuePair structures. + * Valid value: pairArray is valid input if it is not NULL and key member + * of every NvSciSyncAttrKeyValuePair in the array > NvSciSyncAttrKey_LowerBound + * and < NvSciSyncAttrKey_UpperBound. + * \param[in] pairCount Indicates the number of elements/entries in @a pairArray. + * Valid value: pairCount is valid input if it is non-zero. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a slotIndex is not a valid slot in @a attrList + * - @a attrList is NULL + * - @a pairArray is NULL + * - @a pairCount is 0 + * - any of the keys in @a pairArray is not a NvSciSyncAttrKey + * - Panics if @a attrList is not valid + * + * @pre + * - Valid NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncAttrListSlotGetAttrs( + NvSciSyncAttrList attrList, + size_t slotIndex, + NvSciSyncAttrKeyValuePair* pairArray, + size_t pairCount); + +/** + * \brief Reconciles the input unreconciled NvSciSyncAttrLists into a new + * reconciled NvSciSyncAttrList. + * + * On success, this API call allocates memory for the reconciled NvSciSyncAttrList + * which has to be freed by the caller using NvSciSyncAttrListFree(). + * + */ +#if (NV_IS_SAFETY == 0) +/** + * On reconciliation failure, this API call allocates memory for the conflicting + * NvSciSyncAttrList which has to be freed by the caller using + * NvSciSyncAttrListFree(). + * + */ +#endif +/** + * \param[in] inputArray Array containing unreconciled NvSciSyncAttrLists to be + * reconciled. + * Valid value: Array of valid NvSciSyncAttrLists where the array size is at least 1 + * \param[in] inputCount The number of unreconciled NvSciSyncAttrLists in + * @a inputArray. + * Valid value: inputCount is valid input if is non-zero. + * \param[out] newReconciledList Reconciled NvSciSyncAttrList. This field is populated + * only if the reconciliation succeeded. + */ +#if (NV_IS_SAFETY == 0) +/** + * \param[out] newConflictList Unreconciled NvSciSyncAttrList consisting of the + * key/value pairs which caused the reconciliation failure. This field is + * populated only if the reconciliation failed. + */ +#else +/** + * \param[out] newConflictList Unused. + */ +#endif +/** + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - inputCount is 0 + * - any of the input NvSciSyncAttrLists are not unreconciled + * - not all the NvSciSyncAttrLists in inputArray are bound to the same + * NvSciSyncModule instance. + * - any of the attributes in any of the input NvSciSyncAttrLists has + * an invalid value for that attribute + * - inputArray is NULL + * - newReconciledList is NULL + * - an NvSciSyncAttrList appears multiple times in inputArray + */ +#if (NV_IS_SAFETY == 0) +/** - newConflictList is NULL + */ +#endif +/** + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_InvalidState if a new NvSciSyncAttrList cannot be associated + * with the NvSciSyncModule associated with the NvSciSyncAttrList(s) in the + * given @a inputArray to create a new reconciled NvSciSyncAttrList + * - ::NvSciError_Overflow if internal integer overflow is detected. + * - ::NvSciError_ReconciliationFailed if reconciliation failed because + * of conflicting attributes + * - ::NvSciError_UnsupportedConfig if any of the following occurs: + * - there is an attribute mismatch between signaler and waiters + * - an unsuported combination of attributes is requested + * - Panics if any of the input NvSciSyncAttrLists is not valid + * + * @pre + * - Valid unreconciled NvSciSyncAttrList(s) are obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncAttrListReconcile( + const NvSciSyncAttrList inputArray[], + size_t inputCount, + NvSciSyncAttrList* newReconciledList, + NvSciSyncAttrList* newConflictList); + +#if (NV_IS_SAFETY == 0) +/** + * \brief Dumps the NvSciSyncAttrList into a binary descriptor. + * + * @note This API can be used for debugging purpose. + * + * \param[in] attrList NvSciSyncAttrList to create the blob from. + * \param[out] buf A pointer to binary descriptor buffer. + * \param[out] len The length of the binary descriptor buffer created. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - any argument is NULL + * - ::NvSciError_InsufficientMemory if memory allocation failed + * - Panics if attrList is not valid + * + * @note This API is deprecated and will be removed in a future version. This + * prototype is only provided to not break compiliation of older code. Its use + * is not supported. Do not rely on using this API. + * + * @pre + * - Valid NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncAttrListDebugDump( + NvSciSyncAttrList attrList, + void** buf, + size_t* len); +#endif + +/** + * \brief Transforms the input unreconciled NvSciSyncAttrList(s) to an exportable + * unreconciled NvSciSyncAttrList descriptor that can be transported by the + * application to any remote process as a serialized set of bytes over an + * NvSciIpc channel. + * + * @note When exporting an array containing multiple unreconciled + * NvSciSyncAttrLists, the importing endpoint still imports just one unreconciled + * NvSciSyncAttrList. This unreconciled NvSciSyncAttrList is referred to as a + * multi-slot NvSciSyncAttrList. It logically represents an array of + * NvSciSyncAttrLists, where each key has an array of values, one per slot. + * + * \param[in] unreconciledAttrListArray NvSciSyncAttrList(s) to be exported. + * Valid value: Array of valid NvSciSyncAttrList(s) where the array + * size is at least 1. + * \param[in] unreconciledAttrListCount Number of NvSciSyncAttrList(s) in + * @a unreconciledAttrListArray. + * Valid value: unreconciledAttrListCount is valid input if it + * is non-zero. + * \param[in] ipcEndpoint The NvSciIpcEndpoint through which the caller may + * send the exported unreconciled NvSciSyncAttrList descriptor. + * \param[out] descBuf A pointer to the new unreconciled NvSciSyncAttrList + * descriptor, which the caller can deallocate later using + * NvSciSyncAttrListFreeDesc(). + * \param[out] descLen The size of the new unreconciled NvSciSyncAttrList + * descriptor. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a unreconciledAttrListCount is 0 + * - @a unreconciledAttrListArray is NULL + * - @a ipcEndpoint is not a valid NvSciIpcEndpoint + * - @a descBuf is NULL + * - @a descLen is NULL + * - any of the input NvSciSyncAttrLists is not unreconciled + * - Not all of the NvSciSyncAttrLists in @a unreconciledAttrListArray + * are bound to the same NvSciSyncModule instance. + * - an NvSciSyncAttrList appears multiple times in + * @a unreconciledAttrListArray + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_InvalidState if no more references can be taken for the + * NvSciSyncModule associated with @a unreconciledAttrListArray. + * - ::NvSciError_Overflow if the combined slot count of all the unreconciled + * NvSciSyncAttrList exceeds UINT64_MAX + * - ::NvSciError_ResourceError if system lacks resource other than memory + */ +#if (NV_IS_SAFETY == 0) +/** + * or there was a problem with NvSciIpc +*/ +#endif +/** + * - ::NvSciError_NoSpace if no space is left in transport buffer to append the + * key-value pair. + * - Panic if any of the input NvSciSyncAttrLists is not valid. + * + * @pre + * - Valid NvSciIpcEndpoint is obtained. + * - Valid unreconciled NvSciSyncAttrList(s) are obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncAttrListIpcExportUnreconciled( + const NvSciSyncAttrList unreconciledAttrListArray[], + size_t unreconciledAttrListCount, + NvSciIpcEndpoint ipcEndpoint, + void** descBuf, + size_t* descLen); + +/** + * \brief Transforms the reconciled NvSciSyncAttrList to an exportable reconciled + * NvSciSyncAttrList descriptor that can be transported by the application to any + * remote process as a serialized set of bytes over an NvSciIpc channel. + * + * \param[in] reconciledAttrList The NvSciSyncAttrList to be exported. + * \param[in] ipcEndpoint The NvSciIpcEndpoint through which the caller may + * send the exported reconciled NvSciSyncAttrList descriptor. + * \param[out] descBuf A pointer to the new reconciled NvSciSyncAttrList + * descriptor, which the caller can deallocate later using + * NvSciSyncAttrListFreeDesc(). + * \param[out] descLen The size of the new reconciled NvSciSyncAttrList + * descriptor. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - any argument is NULL + * - @a ipcEndpoint is not a valid NvSciIpcEndpoint + * - @a reconciledAttrList does not correspond to a waiter or a signaler + * - @a reconciledAttrList is not a reconciled NvSciSyncAttrList + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_ResourceError if system lacks resource other than memory. + * - ::NvSciError_InvalidState if no more references can be taken for + * NvSciSyncModule associated with @a reconciledAttrList to create the new + * NvSciSyncAttrList. + * - Panic if @a reconciledAttrList is not valid + * + * @pre + * - Valid NvSciIpcEndpoint is obtained. + * - Valid reconciled NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncAttrListIpcExportReconciled( + const NvSciSyncAttrList reconciledAttrList, + NvSciIpcEndpoint ipcEndpoint, + void** descBuf, + size_t* descLen); + +/** + * \brief Transforms an exported unreconciled NvSciSyncAttrList descriptor + * (potentially received from any process) into an unreconciled + * NvSciSyncAttrList which is no longer writable. + * + * \param[in] module The NvSciSyncModule instance with which to associate the + * imported NvSciSyncAttrList. + * \param[in] ipcEndpoint The NvSciIpcEndpoint through which the caller receives + * the exported unreconciled NvSciSyncAttrList descriptor. + * \param[in] descBuf The unreconciled NvSciSyncAttrList descriptor to be + * translated into an unreconciled NvSciSyncAttrList. It should be the result of + * NvSciSyncAttrListIpcExportUnreconciled + * Valid value: descBuf is valid input if it is non-NULL. + * \param[in] descLen The size of the unreconciled NvSciSyncAttrList descriptor. + * Valid value: descLen is valid input if it is not 0. + * \param[out] importedUnreconciledAttrList Imported unreconciled NvSciSyncAttrList. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - any argument is NULL + * - @a descLen is 0 + * - @a ipcEndpoint is not a valid NvSciIpcEndpoint + * - array of bytes indicated by @a descBuf and @a descLen + * do not constitute a valid exported NvSciSyncAttrList descriptor + * for an unreconciled NvSciSyncAttrList + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_Overflow if internal integer overflow is detected. + * - ::NvSciError_ResourceError if system lacks resource other than memory. + * - Panics if @a module is not valid + * + * @pre + * - Valid NvSciIpcEndpoint is obtained. + * - Valid NvSciSyncModule is obtained. + * - Valid unreconciled NvSciSyncAttrList export descriptor is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncAttrListIpcImportUnreconciled( + NvSciSyncModule module, + NvSciIpcEndpoint ipcEndpoint, + const void* descBuf, + size_t descLen, + NvSciSyncAttrList* importedUnreconciledAttrList); + +/** + * \brief Translates an exported reconciled NvSciSyncAttrList descriptor + * (potentially received from any process) into a reconciled NvSciSyncAttrList. + * + * It also validates that the reconciled NvSciSyncAttrList to be imported will + * be a reconciled NvSciSyncAttrList that is consistent with the constraints in + * an array of input unreconciled NvSciSyncAttrList(s). This is recommended + * while importing what is expected to be a reconciled NvSciSyncAttrList to + * cause NvSciSync to validate the reconciled NvSciSyncAttrList against the input + * unreconciled NvSciSyncAttrList(s), so that the importing process can be sure + * that an NvSciSyncObj will satisfy the input constraints. + * + * \param[in] module The NvSciSyncModule instance with which to associate the + * imported NvSciSyncAttrList. + * \param[in] ipcEndpoint The NvSciIpcEndpoint through which the caller + * receives the exported reconciled NvSciSyncAttrList descriptor. + * \param[in] descBuf The reconciled NvSciSyncAttrList descriptor to be + * transformed into a reconciled NvSciSyncAttrList. + * Valid value: descBuf is valid if it is non-NULL. + * \param[in] descLen The size of the reconciled NvSciSyncAttrList descriptor. + * Valid value: descLen is valid if it is not 0. + * \param[in] inputUnreconciledAttrListArray The array of NvSciSyncAttrLists against + * which the new NvSciSyncAttrList is to be validated. + * Valid value: Array of valid NvSciSyncAttrList(s) + * \param[in] inputUnreconciledAttrListCount The number of NvSciSyncAttrLists in + * inputUnreconciledAttrListArray. If inputUnreconciledAttrListCount is + * non-zero, then this operation will fail with an error unless all the + * constraints of all the NvSciSyncAttrLists in inputUnreconciledAttrListArray are + * met by the imported NvSciSyncAttrList. + * Valid value: [0, SIZE_MAX] + * \param[out] importedReconciledAttrList Imported NvSciSyncAttrList. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a module is NULL + * - @a ipcEndpoint is not a valid NvSciIpcEndpoint + * - the array of bytes indicated by @a descBuf and @a descLen do not + * constitute a valid exported NvSciSyncAttrList descriptor for a + * reconciled NvSciSyncAttrList + * - @a inputUnreconciledAttrListArray is NULL but + * @a inputUnreconciledAttrListCount is not 0 + * - any of the NvSciSyncAttrLists in inputUnreconciledAttrListArray are + * not unreconciled + * - any of the NvSciSyncAttrLists in @a inputUnreconciledAttrListArray + * is not bound to @a module. + * - an NvSciSyncAttrList appears multiple times in + * @a inputUnreconciledAttrListArray + * - @a importedReconciledAttrList is NULL + * - ::NvSciError_AttrListValidationFailed if the NvSciSyncAttrList to be + * imported either would not be a reconciled NvSciSyncAttrList or would not meet + * at least one of constraints in one of the input unreconciled + * NvSciSyncAttrLists. + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_InvalidState if no more references can be taken on the + * NvSciSyncModule. + * - ::NvSciError_Overflow if internal integer overflow is detected. + * - ::NvSciError_ResourceError if system lacks resource other than memory. + * - Panics if @a module or any of the input NvSciSyncAttrLists are not valid + * + * @pre + * - Valid NvSciIpcEndpoint is obtained. + * - Valid NvSciSyncModule is obtained. + * - Valid reconciled NvSciSyncAttrList export descriptor is obtained. + * - Valid unreconciled NvSciSyncAttrList(s) are obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncAttrListIpcImportReconciled( + NvSciSyncModule module, + NvSciIpcEndpoint ipcEndpoint, + const void* descBuf, + size_t descLen, + const NvSciSyncAttrList inputUnreconciledAttrListArray[], + size_t inputUnreconciledAttrListCount, + NvSciSyncAttrList* importedReconciledAttrList); + +/** + * \brief Frees an exported NvSciSyncAttrList descriptor previously returned by + * any NvSciSyncAttrList exporting function. + * + * \param[in] descBuf The exported NvSciSyncAttrList descriptor to be freed. + * The valid value is non-NULL. + * \return void + * - Panics if Init Mode API is called in Runtime Mode. + * + * @pre + * - Valid NvSciSyncAttrList export descriptor is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the input @a descBuf + * to be freed + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +void NvSciSyncAttrListFreeDesc( + void* descBuf); + +/** + * \brief Frees any resources allocated for the NvSciSyncFence. + * + * Upon return, the memory pointed to by the NvSciSyncFence is guaranteed to be all + * zeros and thus the NvSciSyncFence is returned to the cleared state. + * + * \param[in,out] syncFence A pointer to NvSciSyncFence. + * \return void + * - Panics if the NvSciSyncObj associated with @a syncFence is not valid + * + * @pre + * - Valid NvSciSyncFence* is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the @a syncFence to + * be cleared + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +void NvSciSyncFenceClear( + NvSciSyncFence* syncFence); + +/** + * \brief Duplicates the given NvSciSyncFence, such that any wait on duplicated + * NvSciSyncFence will complete at the same time as a wait on given + * NvSciSyncFence. If the given NvSciSyncFence is in a cleared state, then so + * also will be the duplicated NvSciSyncFence. The given NvSciSyncFence will be + * cleared before the duplication. If the given NvSciSyncFence holds any + * reference on a NvSciSyncObj, then the duplicated NvSciSyncFence will create + * an additional reference on it. + * + * \param[in] srcSyncFence NvSciSyncFence to duplicate. + * \param[out] dstSyncFence duplicated NvSciSyncFence. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any argument is NULL or both parameters + point to the same NvSciSyncFence. + * - ::NvSciError_InvalidState if no more references can be taken + * for NvSciSyncObj associated with @a srcSyncFence + * - Panics if the NvSciSyncObj associated with @a srcSyncFence + * or @a dstSyncFence are not valid + * + * @pre + * - Both arguments are pointers to valid NvSciSyncFences. + * - Input pointers point to different NvSciSyncFences. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the @a dstSyncFence + * if it had previously been associated with an NvSciSyncObj + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncFenceDup( + const NvSciSyncFence* srcSyncFence, + NvSciSyncFence* dstSyncFence); + +/** + * \brief Extracts the id and value from the input NvSciSyncFence. + * + * \param[in] syncFence NvSciSyncFence from which the id and value should be + * retrieved + * \param[out] id NvSciSyncFence id + * \param[out] value NvSciSyncFence value + * + * \return NvSciError + * - NvSciError_Success if successful + * - NvSciError_BadParameter if syncFence is NULL or invalid or id/value are NULL + * - NvSciError_ClearedFence if syncFence is a valid cleared NvSciSyncFence + * - Panics if the NvSciSyncObj associated with the syncFence is invalid + * + * @pre + * - Valid NvSciSyncFence* is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncFenceExtractFence( + const NvSciSyncFence* syncFence, + uint64_t* id, + uint64_t* value); + +/** + * \brief Populates the input NvSciSyncFence based on the input id and value. + * + * This new NvSciSyncFence is associated with the input NvSciSyncObj. The input + * NvSciSyncFence is cleared before being populated with the new data. + * + * The task status slot associated with this fence will be 0. It is recommended + * to not use this interface when using task status buffer. + * + * \param[in] syncObj valid NvSciSyncObj + * \param[in] id NvSciSyncFence identifier + * Valid value: [0, UINT32_MAX-1] for NvSciSyncAttrValPrimitiveType_Syncpoint. + * [0, value returned by NvSciSyncObjGetNumPrimitives()-1] for + * NvSciSyncAttrValPrimitiveType_SysmemSemaphore and + * NvSciSyncAttrValPrimitiveType_SysmemSemaphorePayload64b. + * \param[in] value NvSciSyncFence value + * Valid value: [0, UINT32_MAX] for NvSciSyncAttrValPrimitiveType_Syncpoint + * and NvSciSyncAttrValPrimitiveType_SysmemSemaphore. + * [0, UINT64_MAX] for + * NvSciSyncAttrValPrimitiveType_SysmemSemaphorePayload64b. + * \param[in,out] syncFence NvSciSyncFence to populate + * + * \return NvSciError + * - NvSciError_Success if successful. + * - NvSciError_BadParameter if syncObj or syncFence is NULL. + * - NvSciError_Overflow if id is invalid. + * - NvSciError_Overflow if value is invalid. + * - NvSciError_InvalidState if no more references can be taken on + * the syncObj + * - Panics if syncObj or NvSciSyncObj initially associated with syncFence + * is invalid + * + * @pre + * - Valid NvSciSyncObj is obtained. + * - Valid NvSciSyncFence* is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the @a syncFence to + * be updated + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncFenceUpdateFence( + NvSciSyncObj syncObj, + uint64_t id, + uint64_t value, + NvSciSyncFence* syncFence); + +/** + * \brief Sets the current timestamp slot index in the NvSciSyncFence + * + * \param[in,out] syncFence object of type NvSciSyncFence + * \param[in] timestampSlot index of the timestamp slot to set in NvSciSyncFence. + * Valid value: [0, number-of-timestamp-slots - 1] + * + * \return ::NvSciError + * - ::NvSciError_Success if successful + * - ::NvSciError_ClearedFence if @a syncFence is cleared + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a syncFence is NULL + * - timestamps are not supported by NvSciSyncObj associated with the @a syncFence + * - @a timestampSlot is invalid slot index + * - Panics if NvSciSyncObj associated with @a syncFence is not valid. + * + * @pre + * - Valid NvSciSyncFence* is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: No + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncFenceAddTimestampSlot( + NvSciSyncFence* syncFence, + uint32_t timestampSlot); + +/** + * \brief Sets the current task status slot index to the NvSciSyncFence + * + * \param[in,out] syncFence object of type NvSciSyncFence + * \param[in] taskStatusSlot index of the task status slot to set in NvSciSyncFence. + * Valid value: [0, number-of-task-status-slots - 1] + * + * \return ::NvSciError + * - ::NvSciError_Success if successful + * - ::NvSciError_ClearedFence if @a syncFence is cleared + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a syncFence is NULL + * - task status is not supported by NvSciSyncObj associated with @a syncFence + * - @a taskStatusSlot is invalid slot index + * - Panics if NvSciSyncObj associated with @a syncFence is not valid. + * + * @pre + * - Valid NvSciSyncFence* is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: No + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncFenceAddTaskStatusSlot( + NvSciSyncFence* syncFence, + uint32_t taskStatusSlot); + +/** + * \brief Reads the current timestamp slot index from the NvSciSyncFence + * + * \param[in] syncFence object of type NvSciSyncFence + * \param[out] timestampSlot index of the timestmp slot in NvSciSyncFence. + * + * \return ::NvSciError + * - ::NvSciError_Success if successful + * - ::NvSciError_ClearedFence if @a syncFence is cleared + * - ::NvSciError_BadParameter if any of the following occurs: + * - any argument is NULL + * - timestamps are not supported by NvSciSyncObj associated with + * - @a syncFence does not support timestamps + * - Panics if NvSciSyncObj associated with @a syncFence is not valid. + * + * @pre + * - Valid NvSciSyncFence* is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: No + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncFenceExtractTimestampSlot( + NvSciSyncFence* syncFence, + uint32_t* timeStampSlot); + +/** + * \brief Allocates and initializes a @ref NvSciSyncObj that meets all the + * constraints specified in the given reconciled NvSciSyncAttrList. + * + * The resulting object will hold a buffer of 1024 slots + * for holding tasks status. + * + * @note This function does not take ownership of the reconciled NvSciSyncAttrList. + * The caller remains responsible for freeing the reconciled NvSciSyncAttrList. + * The caller may free the reconciled NvSciSyncAttrList any time after this + * function is called. + * + * \param[in] reconciledList A reconciled NvSciSyncAttrList. + * \param[out] syncObj The allocated @ref NvSciSyncObj. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_InvalidState if not enough references remain on the + * reconciled NvSciSyncAttrList + * - ::NvSciError_BadParameter if any of the following occurs: + * - any argument is NULL + * - @a reconciledList is not a reconciled NvSciSyncAttrList + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_ResourceError if system lacks resource other than memory. + * - Panics if @a reconciledList is not valid + * + * @pre + * - Valid reconciled NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncObjAlloc( + NvSciSyncAttrList reconciledList, + NvSciSyncObj* syncObj); + +/** + * \brief Creates a new @ref NvSciSyncObj holding a reference to the original + * resources to which the input @ref NvSciSyncObj holds reference to. + * + * The duplicated NvSciSyncObj is not a completely new NvSciSyncObj. Therefore, + * signaling and generating NvSciSyncFences from one affects the state of the + * other, because it is the same underlying NvSciSyncObj. + * + * The resulting NvSciSyncObj must be freed separately by the user. + * + * \param[in] syncObj NvSciSyncObj to duplicate. + * \param[out] dupObj Duplicated NvSciSyncObj. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any argument is NULL. + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_InvalidState if the number of references to the + * synchronization object of the input NvSciSyncObj is INT32_MAX and the + * newly duplicated NvSciSyncObj tries to take one more reference using this + * API. + * - ::NvSciError_ResourceError if system lacks resource other than memory. + * - Panics if @a syncObj is not valid + * + * @pre + * - Valid NvSciSyncObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncObjDup( + NvSciSyncObj syncObj, + NvSciSyncObj* dupObj); + +/** + * \brief Retrieves the reconciled NvSciSyncAttrList associated with an + * input NvSciSyncObj. + * + * The retrieved reconciled NvSciSyncAttrList is always read-only and the + * Attribute Key values in the NvSciSyncAttrList cannot be changed using the + * set attribute APIs. In addition, the returned NvSciSyncAttrList must not be + * freed. + * + * \param[in] syncObj Handle corresponding to NvSciSyncObj from which the + * NvSciSyncAttrList has to be retrieved. + * \param[out] syncAttrList pointer to the retrieved NvSciSyncAttrList. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if @a syncObj or @a syncAttrList is NULL. + * - Panics if @a syncObj is not valid + * + * @pre + * - Valid NvSciSyncObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncObjGetAttrList( + NvSciSyncObj syncObj, + NvSciSyncAttrList* syncAttrList); + +/** + * \brief Destroys a valid @ref NvSciSyncObj and frees any resources that were + * allocated for it. + * + * \param[in] syncObj NvSciSyncObj to be freed. + * + * \return void + * - Panics if: + * - Init Mode API is called in Runtime Mode. + * - @a syncObj is not a valid @ref NvSciSyncObj +#if 0 + * or there was an unexpected freeing error from C2C +#endif + * + * @pre + * - Valid NvSciSyncObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the + * NvSciSyncAttrList obtained from NvSciSyncObjGetAttrList() to be + * freed, since the lifetime of that reconciled NvSciSyncAttrList is + * tied to the associated NvSciSyncObj + * - Provided there is no active operation involving the input + * NvSciSyncObj @a syncObj + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + * + * \implements{11273441} + */ +void NvSciSyncObjFree( + NvSciSyncObj syncObj); + +/** + * \brief Exports an NvSciSyncObj into an NvSciIpc-transferable object + * binary descriptor. + * + * The binary descriptor can be transferred to a Waiter to create a matching + * NvSciSyncObj. + * + * \param[in] syncObj A NvSciSyncObj to export. + * \param[in] permissions Flag indicating the expected NvSciSyncAccessPerm. + * Valid value: any value of NvSciSyncAccessPerm + * \param[in] ipcEndpoint The NvSciIpcEndpoint through which the caller + * intends to transfer the exported NvSciSyncObj descriptor. + * \param[out] desc NvSciSync fills in this caller-supplied descriptor with + * the exported form of NvSciSyncObj that is to be shared across + * an NvSciIpc channel. + * + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_ResourceError if something went wrong with NvSciIpc + * - ::NvSciError_TryItAgain if current operation needs to be retried by the + * user. This error is returned only when communication boundary is chip to + * chip (C2c). + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a desc is NULL + * - @a syncObj is NULL + * - @a permissions is invalid + * - @a permissions contains larger permissions than those set on + * NvSciSyncAttrKey_ActualPerm on the reconciled NvSciSyncAttrList + * associated with the NvSciSyncObj granted to this peer + * - @a permissions contains smaller permissions than the expected + * permissions requested by the receiving peer + * - @a ipcEndpoint is invalid + * - @a ipcEndpoint does not lead to a peer in the topology tree + * of this NvSciSyncObj + * - ::NvSciError_InsufficientMemory if memory allocation failed. + */ +#if (NV_L4T == 1) +/** + * - ::NvSciError_NotSupported if trying to export syncpoint signaling + * over a C2C Ipc channel. + */ +#endif +/** + * - Panics if @a syncObj is not valid + * + * @pre + * - Valid NvSciSyncObj is obtained. + * - Valid NvSciIpcEndpoint is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncObjIpcExport( + NvSciSyncObj syncObj, + NvSciSyncAccessPerm permissions, + NvSciIpcEndpoint ipcEndpoint, + NvSciSyncObjIpcExportDescriptor* desc); + +/** + * \brief Creates and returns an @ref NvSciSyncObj based on the supplied binary + * descriptor describing an exported @ref NvSciSyncObj. + * + * This function is called from the waiter after it receives the binary + * descriptor from the signaler who has created and exported the binary + * descriptor. + * + * @note This function does not take ownership of input NvSciSyncAttrList. The + * caller remains responsible for freeing input NvSciSyncAttrList. The caller + * may free the input NvSciSyncAttrList any time after this function is called. + * + * \param[in] ipcEndpoint The @ref NvSciIpcEndpoint through which the caller + * received the exported NvSciSyncObj descriptor. + * \param[in] desc The exported form of @ref NvSciSyncObj received through the + * NvSciIpc channel. + * Valid value: desc is valid if it is non-NULL + * \param[in] inputAttrList The reconciled NvSciSyncAttrList returned by + * @ref NvSciSyncAttrListIpcImportReconciled. + * \param[in] permissions NvSciSyncAccessPerm indicating the expected access + * permissions. + * Valid value: any value of NvSciSyncAccessPerm + * \param[in] timeoutUs Unused + * \param[out] syncObj The Waiter's NvSciSyncObj. + * + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_ResourceError if something went wrong with NvSciIpc + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a ipcEndpoint is invalid + * - @a desc is invalid + * - @a inputAttrList is NULL + * - @a permissions is invalid + * - @a syncObj is NULL + * - @a permissions is NvSciSyncAccessPerm_Auto but permissions granted + * in @a desc are not enough to satisfy expected permissions stored in + * @a inputAttrList + * - the NvSciSyncObjIpcExportDescriptor export descriptor corresponds to + * a descriptor generated by an incompatible NvSciSync library version + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_InvalidState if the imported NvSciSyncObj cannot be associated + * with the NvSciSyncModule associated with the reconciled input + * NvSciSyncAttrList. + * - ::NvSciError_Overflow if @a desc is too big to be imported. + * - ::NvSciError_ResourceError if system lacks resource other than memory. + * - ::NvSciError_TryItAgain if current operation needs to be retried by the + * user. This error is returned only when communication boundary is chip to + * chip (C2c). + * - Panics if @a inputAttrList is not valid + * + * @pre + * - Valid NvSciSyncObjIpcExportDescriptor is obtained. + * - Valid NvSciIpcEndpoint is obtained. + * - Valid reconciled NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncObjIpcImport( + NvSciIpcEndpoint ipcEndpoint, + const NvSciSyncObjIpcExportDescriptor* desc, + NvSciSyncAttrList inputAttrList, + NvSciSyncAccessPerm permissions, + int64_t timeoutUs, + NvSciSyncObj* syncObj); + +/** + * \brief Exports the input NvSciSyncFence into a binary descriptor shareable + * across the NvSciIpc channel. + * + * The resulting descriptor of a non-cleared NvSciSyncFence is associated with + * NvSciSyncObj associated with the NvSciSyncFence. After transporting + * the descriptor via an Ipc path, NvSciSync will be able to recognize + * that the NvSciSyncFence is associated with this NvSciSyncObj if NvSciSyncObj + * traversed the same Ipc path. + * + * \param[in] syncFence A pointer to NvSciSyncFence object to be exported. + * \param[in] ipcEndpoint The NvSciIpcEndpoint through which the caller may + * send the exported fence descriptor. + * \param[out] desc The exported form of NvSciSyncFence shared across + * an NvSciIpc channel. + * + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - any argument is NULL + * - ipcEndpoint is not a valid NvSciIpcEndpoint + * - Panics if @a syncFence is associated an invalid NvSciSyncObj + * + * @pre + * - Valid NvSciSyncFence* is obtained. + * - Valid NvSciIpcEndpoint is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncIpcExportFence( + const NvSciSyncFence* syncFence, + NvSciIpcEndpoint ipcEndpoint, + NvSciSyncFenceIpcExportDescriptor* desc); + +/** + * \brief Fills in the NvSciSyncFence based on the input + * binary descriptor. If the NvSciSyncFence descriptor does not describe a + * cleared NvSciSyncFence, then NvSciSync will validate if it corresponds to the + * NvSciSyncObj and it will associate the out NvSciSyncFence with the + * NvSciSyncObj. + * + * The NvSciSyncFence will be cleared first, removing any previous + * reference to a NvSciSyncObj. + * + * \param[in] syncObj The NvSciSyncObj. + * \param[in] desc The exported form of NvSciSyncFence. + * Valid value: A binary descriptor produced by NvSciSyncIpcExportFence. + * \param[out] syncFence A pointer to NvSciSyncFence object. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - any argument is NULL + * - fence descriptor does not describe a cleared NvSciSyncFence but + * it is associated with an NvSciSyncObj different from @a syncObj + * - fence descriptor's value exceeds allowed range for syncObj's primitive + * - ::NvSciError_InvalidState if @a syncObj cannot take more references. + * - Panics if @a syncObj is not valid + * + * @pre + * - Valid NvSciSyncFenceIpcExportDescriptor is obtained. + * - Valid NvSciIpcEndpoint is obtained. + * - Valid NvSciSyncObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the @a syncFence if + * it had previously been associated with an NvSciSyncObj + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncIpcImportFence( + NvSciSyncObj syncObj, + const NvSciSyncFenceIpcExportDescriptor* desc, + NvSciSyncFence* syncFence); + +/** + * @brief Validates the NvSciSyncObj satisfies the constraints of the + * NvSciSyncAttrList that it is associated with. + */ +#if (NV_IS_SAFETY == 0) +/** + * \param[in] syncObj Unused + * + * \return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success + * + * @note This is a no-op. + */ +#else +/** + * \param[in] syncObj The NvSciSyncObj to validate + * + * \return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a syncObj is NULL + * - @a syncObj is invalid + * - @a syncObj does not satisfy the constraints of the NvSciSyncAttrList + * that it is associated with + * - ::NvSciError_Revalidation_Success if any of the following occurs: + * - the API is called after the provided @a syncObj has already been + * validated + */ +#endif +/** + * @pre + * - None + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncObjValidate( + NvSciSyncObj syncObj); + +/** + * \brief Generates next point on sync timeline of an NvSciSyncObj and fills + * in the supplied NvSciSyncFence object. + * + * This function can be used when the CPU is the Signaler. + * + * \param[in] syncObj A valid NvSciSyncObj. + * \param[out] syncFence NvSciSyncFence to be filled + * + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - any argument is NULL + * - @a syncObj is not a CPU signaler + */ +#if (NV_IS_SAFETY == 0) +/** + * and not a C2C signaler + */ +#endif +/** - @a syncObj does not own the backing primitive + * - ::NvSciError_InvalidState if the newly created NvSciSyncFence cannot be + * associated with the synchronization object of the given NvSciSyncObj. + * - Panics if @a syncObj is not valid + * + * @pre + * - Valid NvSciSyncObj is obtained. + * - Valid NvSciSyncFence is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions + * - Provided there is no active operation involving the @a syncFence if + * it had previously been associated with an NvSciSyncObj + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncObjGenerateFence( + NvSciSyncObj syncObj, + NvSciSyncFence* syncFence); + +/** + * \brief Signals the @ref NvSciSyncObj using the reconciled primitive that + * was allocated along with the NvSciSyncObj. + */ +#if (NV_IS_SAFETY == 0) +/** + * If the signal operation fails, then the timestamp value is undefined. + */ +#endif +/** + * This function is called when the CPU is the Signaler. + * + * \param[in] syncObj A valid NvSciSyncObj to signal. + * + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a syncObj is NULL + * - @a syncObj is not a CPU Signaler + * - @a syncObj does not own the backing primitive + * - ::NvSciError_ResourceError if the signal operation fails. + * - Panics if @a syncObj is not valid + * + * @pre + * - Valid NvSciSyncObj is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncObjSignal( + NvSciSyncObj syncObj); + +/** + * \brief Performs a synchronous wait on the @ref NvSciSyncFence object until the + * NvSciSyncFence has been signaled or the timeout expires. Any + * NvSciSyncCpuWaitContext may be used for waiting on any NvSciSyncFence provided + * they were created in the same NvSciSyncModule context. + * One NvSciSyncCpuWaitContext can be used to wait on only one NvSciSyncFence at a time + * but it can be used to wait on a different NvSciSyncFence at a different time. + * + * Waiting on a cleared and expired NvSciSyncFence is always not blocking. + * + * \param[in] syncFence The NvSciSyncFence to wait on. + * \param[in] context NvSciSyncCpuWaitContext holding resources needed + * to perform waiting. + * \param[in] timeoutUs Timeout to wait for in micro seconds, -1 for infinite + * wait. + * Valid value: [-1, NvSciSyncFenceMaxTimeout] + * + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if any of the following occurs: + * - @a syncFence is cleared + * - @a syncFence is expired + * - @a syncFence has been signaled within the given timeout + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a syncFence is NULL + * - @a context is NULL + * - @a syncFence and @a context are associated with different + * NvSciSyncModule + * - @a timeoutUs is invalid + * - if caller doesn't have CPU wait permissions in NvSciSyncObj + * associated with @a syncFence + * - the module reference associated with @a context + * is NULL + * - ::NvSciError_ResourceError if wait operation did not complete + * successfully. + * - ::NvSciError_Timeout if wait did not complete in the given timeout. + * - ::NvSciError_Overflow if the NvSciSyncFence's id or value are not in range + * supported by the primitive this NvSciSyncFence corresponds to. + * - Panics if any NvSciSyncObj associated with @a syncFence or @a context + * is not valid + * + * @pre + * - Valid NvSciSyncFence* is obtained. + * - Valid NvSciSyncCpuWaitContext is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncFenceWait( + const NvSciSyncFence* syncFence, + NvSciSyncCpuWaitContext context, + int64_t timeoutUs); + +/** + * \brief Read the timestamp associated with the NvSciSyncFence + * + * This function can be used when the CPU is the waiter. + * + * \param[in] syncFence object of type NvSciSyncFence + * \param[out] timestampUS time (in microseconds) when the NvSciSyncFence expired. + * + * \return ::NvSciError + * - ::NvSciError_Success if successful + * - ::NvSciError_ClearedFence if @a syncFence is cleared + * - ::NvSciError_BadParameter if any of the following occurs: + * - any argument is NULL + * - timestamps are not supported by NvSciSyncObj associated with + * @a syncFence + * - @a syncFence does not support timestamps + * - the NvSciSyncAttrList associated with the @a syncFence has not + * requested CPU access + * - Panics if NvSciSyncObj associated with @a syncFence is not valid. + * + * @pre + * - Valid NvSciSyncFence* is obtained. + * - NvSciSyncFence pointed by syncFence is expired. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncFenceGetTimestamp( + const NvSciSyncFence* syncFence, + uint64_t* timestampUS); + +/** + * \brief Reads the task status associated with the NvSciSyncFence and stores + * it in the user provided out parameter. + * + * \param[in] syncFence object of type NvSciSyncFence + * \param[out] taskStatus user provided struct to store the result + * + * \return ::NvSciError + * - ::NvSciError_Success if successful + * - ::NvSciError_ClearedFence if @a syncFence is cleared + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a syncFence is NULL or has no non NULL NvSciSyncObj associated + * - @a taskStatus is NULL + * - syncFence points to an invalid task status slot + * - Panics if NvSciSyncObj associated with @a syncFence is not valid + * + * @pre + * - Valid NvSciSyncFence* is obtained. + * - NvSciSyncFence pointed by syncFence is expired. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncFenceGetTaskStatus( + const NvSciSyncFence* syncFence, + NvSciSyncTaskStatus* taskStatus); + +/* + * NvSciSync Utility functions + */ + +/** + * \brief Gets the attribute value from the slot 0 of the passed NvSciSyncAttrList + * with the given NvSciSyncAttrKey. + * If an NvSciSyncAttrKey was not set, this function will set *value to NULL + * and *len to 0. + * + * \param[in] attrList NvSciSyncAttrList to retrieve the NvSciSyncAttrKey and + * value from. + * \param[in] key NvSciSyncAttrKey for which value to retrieve. + * Valid value: key is a valid input if it is an input or input/output attribute + * and it is > NvSciSyncAttrKey_LowerBound and < NvSciSyncAttrKey_UpperBound + * \param[out] value A pointer to the location where the attribute value is written. + * \param[out] len Length of the value. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a attrList is NULL + * - @a value is NULL + * - @a len is NULL + * - @a key is not a supported public key + * - Panics if @a attrList is not valid + * + * @pre + * - Valid NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: No + * - Runtime: Yes + * - De-Init: No + */ +NvSciError NvSciSyncAttrListGetAttr( + NvSciSyncAttrList attrList, + NvSciSyncAttrKey key, + const void** value, + size_t* len); + +/** + * \brief Reconciles the input unreconciled NvSciSyncAttrList(s) into a new + * reconciled NvSciSyncAttrList. If successful, a reconciled NvSciSyncAttrList will + * be associated with a newly-allocated @ref NvSciSyncObj that satisfies all + * the constraints specified in the reconciled NvSciSyncAttrList. + * + * Note: This function serves as a convenience function that combines calls to + * NvSciSyncAttrListReconcile and NvSciSyncObjAlloc. + * + * \param[in] inputArray Array containing the unreconciled NvSciSyncAttrList(s) + * to reconcile. + * Valid value: Array of valid NvSciSyncAttrLists where the array size is at least 1 + * \param[in] inputCount Number of unreconciled NvSciSyncAttrLists in + * @a inputArray. + * Valid value: inputCount is valid input if is non-zero. + * \param[out] syncObj The new NvSciSyncObj. + */ +#if (NV_IS_SAFETY == 0) +/** + * \param[out] newConflictList unreconciled NvSciSyncAttrList consisting of the + * key-value pairs which caused the reconciliation failure. + * Valid value: This parameter is a valid output parameter only if the return + * code is ::NvSciError_ReconciliationFailed + */ +#else +/** + * \param[out] newConflictList Unused + */ +#endif +/** + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a inputCount is 0 + * - @a inputArray is NULL + * - @a syncObj is NULL + * - not all the NvSciSyncAttrLists in inputArray are bound to the same + * NvSciSyncModule instance + * - any of the attributes in any of the input NvSciSyncAttrLists has an + * invalid value for that attribute + * - if any of the NvSciSyncAttrList in inputArray are not unreconciled + * - an NvSciSyncAttrList appears multiple times in inputArray + */ +#if (NV_IS_SAFETY == 0) +/** - @a newConflictList is NULL + */ +#endif +/** + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_InvalidState if the newly created NvSciSyncObj cannot be + * associated with the NvSciSyncModule with which the NvSciSyncAttrList(s) in + * @a inputArray are associated. + * - ::NvSciError_ReconciliationFailed if reconciliation failed. + * - ::NvSciError_ResourceError if system lacks resource other than memory. + * - ::NvSciError_UnsupportedConfig if there is an NvSciSyncAttrList mismatch between + * Signaler and Waiters. + * - Panics if any of the input NvSciSyncAttrLists are not valid + * + * @pre + * - Valid unreconciled NvSciSyncAttrList(s) are obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncAttrListReconcileAndObjAlloc( + const NvSciSyncAttrList inputArray[], + size_t inputCount, + NvSciSyncObj* syncObj, + NvSciSyncAttrList* newConflictList); + +/** + * \brief Exports an NvSciSyncAttrList and NvSciSyncObj into an + * NvSciIpc-transferable object binary descriptor pointed to by @a data. + * + * The binary descriptor can subsequently be transferred to Waiters to create + * a matching NvSciSyncObj. + * + * Note: This function serves as a convenience function that combines calls to + * NvSciSyncAttrListIpcExportReconciled and NvSciSyncObjIpcExport. + * + * \param[in] syncObj NvSciSyncObj to export. + * \param[in] permissions Flag indicating the expected NvSciSyncAccessPerm. + * Valid value: permissions is valid if it is set to NvSciSyncAccessPerm_WaitOnly + * or NvSciSyncAccessPerm_Auto. + * \param[in] ipcEndpoint The NvSciIpcEndpoint through which the caller may send + * the exported NvSciSyncAttrList and NvSciSyncObj descriptor. + * \param[out] attrListAndObjDesc Exported form of NvSciSyncAttrList and + * NvSciSyncObj shareable across an NvSciIpc channel. + * \param[out] attrListAndObjDescSize Size of the exported blob. + * + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a attrListAndObjDesc is NULL + * - @a attrListAndObjDescSize is NULL + * - @a syncObj is NULL + * - @a permissions flag contains signaling rights + * - @a ipcEndpoint is invalid. + * - @a ipcEndpoint does not lead to a peer in the topology tree + * of this NvSciSyncObj + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_ResourceError if system lacks resource other than memory + * or something went wrong with NvSciIpc + * - ::NvSciError_TryItAgain if current operation needs to be retried by the + * user. This error is returned only when communication boundary is chip to + * chip (C2c). + * - Panic if @a syncObj is not valid + * + * @pre + * - Valid NvSciSyncObj obtained. + * - Valid NvSciIpcEndpoint is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncIpcExportAttrListAndObj( + NvSciSyncObj syncObj, + NvSciSyncAccessPerm permissions, + NvSciIpcEndpoint ipcEndpoint, + void** attrListAndObjDesc, + size_t* attrListAndObjDescSize); + +/** + * \brief Frees an @ref NvSciSyncIpcExportAttrListAndObj descriptor + * returned by a successful call to @ref NvSciSyncIpcExportAttrListAndObj. + * + * Does nothing for NULL. + * + * \param[in] attrListAndObjDescBuf Exported @ref NvSciSyncIpcExportAttrListAndObj + * descriptor to be freed. + * \return void + * - Panics if Init Mode API is called in Runtime Mode. + * + * @pre + * - Valid NvSciSyncAttrListAndObj export descriptor is obtained + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes, with the following conditions: + * - Provided there is no active operation involving the input + * @a attrListAndObjDescBuf to be freed + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +void NvSciSyncAttrListAndObjFreeDesc( + void* attrListAndObjDescBuf); + +/** + * \brief Creates an NvSciSyncObj based on the supplied binary descriptor + * returned from a successful call to @ref NvSciSyncIpcExportAttrListAndObj + * that has not yet been freed via @ref NvSciSyncAttrListAndObjFreeDesc. It + * also validates reconciled NvSciSyncAttrList against input + * unreconciled NvSciSyncAttrLists to ensure that the reconciled + * NvSciSyncAttrList satisfies the constraints of all the given unreconciled + * NvSciSyncAttrLists. + * + * This function is called from the Waiter after it receives the binary + * descriptor from the Signaler who has created the binary descriptor. + * Waiter will create its own NvSciSyncObj and return as output. + * + * Note: This function serves as a convenience function that combines calls to + * NvSciSyncAttrListIpcImportReconciled and NvSciSyncObjIpcImport. + * + * \param[in] module A @ref NvSciSyncModule to associate the imported + * @ref NvSciSyncAttrList with. + * \param[in] ipcEndpoint The @ref NvSciIpcEndpoint through which the caller + * receives the exported NvSciSyncAttrList and NvSciSyncObj descriptor. + * \param[in] attrListAndObjDesc Exported form of NvSciSyncAttrList and + * NvSciSyncObj received through NvSciIpc channel. + * Valid value: attrListAndObjDesc is valid if it is non-NULL. + * \param[in] attrListAndObjDescSize Size of the exported blob. + * Valid value: attrListAndObjDescSize is valid if it is bigger or equal + * sizeof(NvSciSyncObjIpcExportDescriptor). + * \param[in] attrList The array of unreconciled NvSciSyncAttrLists + * against which the new NvSciSyncAttrList is to be validated. + * Valid value: Array of valid NvSciSyncAttrList(s) + * \param[in] attrListCount Number of unreconciled NvSciSyncAttrLists in the + * @a attrList array. + * Valid value: [0, SIZE_MAX] + * \param[in] minPermissions Flag indicating the expected NvSciSyncAccessPerm. + * Valid value: NvSciSyncAccessPerm_WaitOnly and NvSciSyncAccessPerm_Auto + * \param[in] timeoutUs Unused + * \param[out] syncObj Waiter's NvSciSyncObj. + * + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a ipcEndpoint is invalid + * - @a attrListAndObjDesc is invalid + * - @a attrListAndObjDescSize is invalid + * - @a minPermissions is invalid + * - @a syncObj is NULL + * - input unreconciled NvSciSyncAttrLists' constraints + * are not satisfied by attributes of imported NvSciSyncObj. + * - @a attrList is NULL but @a attrListCount is not 0 + * - if any of the NvSciSyncAttrList in attrList are not unreconciled + * - an NvSciSyncAttrList appears multiple times in @a attrList + * - @a minPermissions is NvSciSyncAccessPerm_Auto but permissions granted + * in the object part of @a attrListAndObjDesc are not enough to satisfy + * expected permissions stored in the attribute list part + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - ::NvSciError_ResourceError if system lacks resource other than memory + * or something went wrong with NvSciIpc + * - ::NvSciError_TryItAgain if current operation needs to be retried by the + * user. This error is returned only when communication boundary is chip to + * chip (C2c). + * - Panics if any of the following occurs: + * - @a module is not valid + * - any of the input unreconciled NvSciSyncAttrLists are not valid + * + * @pre + * - Valid NvSciSyncModule is obtained. + * - Valid NvSciIpcEndpoint is obtained. + * - Valid unreconciled NvSciSyncAttrList(s) are obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncIpcImportAttrListAndObj( + NvSciSyncModule module, + NvSciIpcEndpoint ipcEndpoint, + const void* attrListAndObjDesc, + size_t attrListAndObjDescSize, + NvSciSyncAttrList const attrList[], + size_t attrListCount, + NvSciSyncAccessPerm minPermissions, + int64_t timeoutUs, + NvSciSyncObj* syncObj); + +/** + * \brief Checks if the loaded library version is compatible with the version + * the application was compiled against. + * + * This function checks the version of all dependent libraries and sets the + * output variable to true if all libraries are compatible and all in parameters + * valid, else sets output to false. + * + * \param[in] majorVer build major version. + * Valid value: valid if set to NvSciSyncMajorVersion + * \param[in] minorVer build minor version. + * Valid value: valid if set to <= NvSciSyncMinorVersion + * \param[out] isCompatible pointer to the bool holding the result. + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a isCompatible is NULL + * + * @pre + * - None + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +#if (NV_IS_SAFETY == 0) +/** + * - @a failed to check dependent library versions. + */ +#endif +NvSciError NvSciSyncCheckVersionCompatibility( + uint32_t majorVer, + uint32_t minorVer, + bool* isCompatible); + +/** + * \brief Allows remote peer NvSciIpcEndpoint to gain access to already + * allocated NvSciSyncObj. Provided that the allocated NvSciSyncObj + * meets the requirements provided by the input unreconciled attribute + * list of remote peer interested in gaining access to input NvSciSyncObj. + * On success, the NvSciSyncObj is exportable to remote peer + * NvSciIpcEndpoints whose unreconciled NvSciSyncAttrList was provided + * as input to this function. + * + * \param[in] syncObj The NvSciSyncObj whose access needs to be granted + * \param[in] inputArray list of unreconciled NvSciSyncAttrList imported + * from remote peers who wants access to the input NvSciSyncObj + * \param[in] inputCount Count of unreconciled NvSciSyncAttrList provided in + * input unreconciledLists + * + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a syncObj is NULL + * - @a inputArray is NULL + * - any of NvSciSyncAttrLists in @a inputArray are NULL + * - any of NvSciSyncAttrLists in @a inputArray are not unreconciled + * - not all the NvSciSyncAttrLists in @a inputArray are bound to the same + * NvSciSyncModule instance as that of @a syncObj. + * - @a inputCount is 0 + * - ::NvSciError_InsufficientMemory if memory allocation failed. + * - Panic if @a syncObj or NvSciSyncAttrLists inside @a inputArray are not valid + * + * @pre + * - Valid NvSciSyncObj is allocated. + * - Valid unreconciled NvSciSyncAttrLists inside @a inputArray. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncObjAttachPeer( + NvSciSyncObj syncObj, + const NvSciSyncAttrList inputArray[], + size_t inputCount); + +/** + * \brief Fills appropriate attributes for C2C copy in the + * input NvSciSyncAttrList + * + * \param[in] unrecAttrList attribute list to be filled + * \param[in] permissions Permissions to be set in the attribute list + * + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a unrecAttrList is NULL, + * - @a unrecAttrList is not unreconciled and/or not writable, + * - any of NvSciSyncAttrKey_RequiredPerm, + * and equivalent of NvSciSyncAttrKey_PrimitiveInfo, + * is already set in @a unrecAttrList. + * - Panics if @a unrecAttrList is not valid. + * + * @pre + * - Valid unreconciled NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncFillC2cAttrs( + NvSciSyncAttrList unrecAttrList, + NvSciSyncAccessPerm permissions); + +/** + * \brief Validates @a reconciledAttrList against the set of input attributes + * that the user has set in the unreconciled NvSciSyncAttrList(s). + * This API provides the safety mechanism to detect and report + * any reconciliation errors + */ +#if (NV_IS_SAFETY == 0) +/** + * \param[in] reconciledAttrList Unused + * \param[in] pairArray Unused + * \param[in] pairCount Unused + * \param[in] permissions Unused + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success + * + * @note This is a no-op. + */ +#else +/** + * \param[in] reconciledAttrList reconciled NvSciSyncAttrList to be validated + * \param[in] pairArray Array of NvSciSyncAttrKeyValuePair structures that user + * has used to set in the unreconciled NvSciSyncAttrList. + * \param[in] pairCount Number of elements/entries in @a pairArray + * \param[in] permissions Permissions to be used for @a reconciledAttrList validation + * + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a reconciledAttrList is null + * - @a reconciledAttrList is not reconciled + * - any of the input attributes in @a pairArray is not a valid attribute + * - @a reconciledAttrList is not internally consistent + * - @a reconciledAttrList does not satisfy at least one of + * the attributes in @a pairArray + * - ::NvSciError_AttrListValidationFailed indicates that reconciled + * NvSciSyncAttrList is not valid against the user provided key value pair(s). + * - Panics if @a reconciledAttrList is not valid + */ +#endif +/** + * @pre + * - Valid reconciled NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncAttrListValidateReconciledAgainstAttrs( + NvSciSyncAttrList reconciledAttrList, + const NvSciSyncAttrKeyValuePair* pairArray, + size_t pairCount, + NvSciSyncAccessPerm permissions); + +/** + * \brief Validate @a context. + */ +#if (NV_IS_SAFETY == 0) +/** + * \param[in] context Unused + * + * @return ::NvSciError, the completion code of this operation: + * - ::NvSciError_Success + * + * @note This is a no-op. + */ +#else +/** + * \param[in] context input NvSciSyncCpuWaitContext to validate + * + * \return ::NvSciError, the completion code of the operation: + * - ::NvSciError_Success if successful + * - ::NvSciError_InvalidState if the Init Mode API check fails. + * - ::NvSciError_BadParameter if any of the following occurs: + * - @a context is null + * - @a context is not internally consistent + * - ::NvSciError_Revalidation_Success if any of the following occurs: + * - the API is called after the provided @a context has already been + * validated + * - Panics if @a context is not valid + */ +#endif +/** + * @pre + * - Valid reconciled NvSciSyncAttrList is obtained. + * + * @usage + * - Allowed context for the API call + * - Interrupt handler: No + * - Signal handler: No + * - Thread-safe: Yes + * - Re-entrant: No + * - Async/Sync: Sync + * - Required privileges: None + * - API group + * - Init: Yes + * - Runtime: No + * - De-Init: No + */ +NvSciError NvSciSyncCpuWaitContextValidate( + NvSciSyncCpuWaitContext context); + +#if defined(__cplusplus) +} +#endif // __cplusplus + /** @} */ +#endif // INCLUDED_NVSCISYNC_H diff --git a/push_info.txt b/push_info.txt new file mode 100644 index 0000000..9c21818 --- /dev/null +++ b/push_info.txt @@ -0,0 +1 @@ +jetson_36.2