/*
* SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef __NVSANDBOXUTILS_H__
#define __NVSANDBOXUTILS_H__
#ifdef __cplusplus
extern "C" {
#endif
#define INPUT_LENGTH 256
#define MAX_FILE_PATH 256
#define MAX_NAME_LENGTH 256
/***************************************************************************************************/
/** @defgroup enums Enumerations
* @{
*/
/***************************************************************************************************/
/**
* Return types
*/
typedef enum
{
NVSANDBOXUTILS_SUCCESS = 0, //!< The operation was successful
NVSANDBOXUTILS_ERROR_UNINITIALIZED = 1, //!< The library wasn't successfully initialized
NVSANDBOXUTILS_ERROR_NOT_SUPPORTED = 2, //!< The requested operation is not supported on target device
NVSANDBOXUTILS_ERROR_INVALID_ARG = 3, //!< A supplied argument is invalid
NVSANDBOXUTILS_ERROR_INSUFFICIENT_SIZE = 4, //!< A supplied argument is not large enough
NVSANDBOXUTILS_ERROR_VERSION_NOT_SUPPORTED = 5, //!< Requested library version is not supported
NVSANDBOXUTILS_ERROR_LIBRARY_LOAD = 6, //!< The library load failed
NVSANDBOXUTILS_ERROR_FUNCTION_NOT_FOUND = 7, //!< Called function was not found
NVSANDBOXUTILS_ERROR_DEVICE_NOT_FOUND = 8, //!< Target device was not found
NVSANDBOXUTILS_ERROR_NVML_LIB_CALL = 9, //!< NVML library call failed
NVSANDBOXUTILS_ERROR_OUT_OF_MEMORY = 10, //!< There is insufficient memory
NVSANDBOXUTILS_ERROR_FILEPATH_NOT_FOUND = 11, //!< A supplied file path was not found
NVSANDBOXUTILS_ERROR_UNKNOWN = 0xFFFF, //!< Unknown error occurred
} nvSandboxUtilsRet_t;
/**
* Return if there is an error
*/
#define RETURN_ON_SANDBOX_ERROR(result) \
if ((result) != NVSANDBOXUTILS_SUCCESS) { \
NVSANDBOXUTILS_ERROR_MSG("%s %d result=%d", __func__, __LINE__, result); \
return result; \
}
/**
* Log levels
*/
typedef enum
{
NVSANDBOXUTILS_LOG_LEVEL_FATAL = 0, //!< Log fatal errors
NVSANDBOXUTILS_LOG_LEVEL_ERROR = 1, //!< Log all errors
NVSANDBOXUTILS_LOG_LEVEL_WARN = 2, //!< Log all warnings
NVSANDBOXUTILS_LOG_LEVEL_DEBUG = 3, //!< Log all debug messages
NVSANDBOXUTILS_LOG_LEVEL_INFO = 4, //!< Log all info messages
NVSANDBOXUTILS_LOG_LEVEL_NONE = 0xFFFF, //!< Log none
} nvSandboxUtilsLogLevel_t;
/**
* Input rootfs to help access files inside the driver container
*/
typedef enum
{
NV_ROOTFS_DEFAULT, //!< Default no rootfs
NV_ROOTFS_PATH, //!< /run/nvidia/driver
NV_ROOTFS_PID, //!< /proc/PID/mountinfo
} nvSandboxUtilsRootfsInputType_t;
/**
* File type
*/
typedef enum
{
NV_DEV, //!< /dev file system
NV_PROC, //!< /proc file system
NV_SYS, //!< /sys file system
} nvSandboxUtilsFileType_t;
/**
* File subtype
*/
typedef enum
{
NV_DEV_NVIDIA, //!< /dev/nvidia0
NV_DEV_DRI_CARD, //!< /dev/dri/card1
NV_DEV_DRI_RENDERD, //!< /dev/dri/renderD128
NV_DEV_DRI_CARD_SYMLINK, //!< /dev/dri/by-path/pci-0000:41:00.0-card
NV_DEV_DRI_RENDERD_SYMLINK, //!< /dev/dri/by-path/pci-0000:41:00.0-render
NV_DEV_NVIDIA_UVM, //!< /dev/nvidia-uvm
NV_DEV_NVIDIA_UVM_TOOLS, //!< /dev/nvidia-uvm-tools
NV_DEV_NVIDIA_MODESET, //!< /dev/nvidia-uvm-modeset
NV_DEV_NVIDIA_CTL, //!< /dev/nvidiactl
NV_DEV_GDRDRV, //!< /dev/gdrdrv
NV_DEV_NVIDIA_CAPS_NVIDIA_CAP, //!< /dev/nvidia-caps/nvidia-cap22
NV_PROC_DRIVER_NVIDIA_GPUS_PCIBUSID, //!< /proc/driver/nvidia/gpus/0000:2d:00.0
NV_PROC_DRIVER_NVIDIA_GPUS, //!< /proc/driver/nvidia/gpus (for mask out)
NV_PROC_NVIDIA_PARAMS, //!< /proc/driver/nvidia/params
NV_PROC_NVIDIA_CAPS_MIG_MINORS, //!< /proc/driver/nvidia-caps/mig-minors
NV_PROC_DRIVER_NVIDIA_CAPABILITIES_GPU, //!< /proc/driver/nvidia/capabilities/gpu0
NV_PROC_DRIVER_NVIDIA_CAPABILITIES, //!< /proc/driver/nvidia/capabilities (for mask out)
NV_PROC_DRIVER_NVIDIA_CAPABILITIIES_GPU_MIG_CI_ACCESS, //!< proc/driver/nvidia/capabilities/gpu0/mig/gi2/ci0/access
NV_SYS_MODULE_NVIDIA_DRIVER_PCIBUSID, //!< /sys/module/nvidia/drivers/pci:nvidia/0000:2d:00.0
NV_SYS_MODULE_NVIDIA_DRIVER, //!< /sys/module/nvidia/drivers/pci:nvidia (for mask out)
NV_NUM_SUBTYPE, // always at the end.
} nvSandboxUtilsFileSystemSubType_t;
/**
* File module
*/
typedef enum
{
NV_GPU, //!< Target device
NV_MIG, //!< Target device- MIG
NV_DRIVER_NVIDIA, //!< NVIDIA kernel driver
NV_DRIVER_NVIDIA_UVM, //!< NVIDIA kernel driver-UVM
NV_DRIVER_NVIDIA_MODESET, //!< NVIDIA kernel driver-modeset
NV_DRIVER_GDRDRV, //!< GDRDRV driver
NV_SYSTEM, //!< System module
} nvSandboxUtilsFileModule_t;
/**
* Flag to provide additional details about the file
*/
typedef enum
{
NV_FILE_FLAG_HINT = (1 << 0), //!< Default no hint
NV_FILE_FLAG_MASKOUT = (1 << 1), //!< For /proc/driver/nvidia/gpus
NV_FILE_FLAG_CONTENT = (1 << 2), //!< For /proc/driver/nvidia/params
//!< For SYMLINK
//!< Use \p nvSandboxUtilsGetFileContent to get name of the linked file
NV_FILE_FLAG_DEPRECTATED = (1 << 3), //!< For all the FIRMWARE GSP file
NV_FILE_FLAG_CANDIDATES = (1 << 4), //!< For libcuda.so
} nvSandboxUtilsFileFlag_t;
/**
* Input type of the target device
*/
typedef enum
{
NV_GPU_INPUT_GPU_UUID, //!< GPU UUID
NV_GPU_INPUT_MIG_UUID, //!< MIG UUID
NV_GPU_INPUT_PCI_ID, //!< PCIe DBDF ID
NV_GPU_INPUT_PCI_INDEX, //!< PCIe bus order (0 points to the GPU that has lowest PCIe BDF)
} nvSandboxUtilsGpuInputType_t;
/** @} */
/***************************************************************************************************/
/** @defgroup dataTypes Structures and Unions
* @{
*/
/***************************************************************************************************/
/**
* Initalization input v1
*/
typedef struct
{
unsigned int version; //!< Version for the structure
nvSandboxUtilsRootfsInputType_t type; //!< One of \p nvSandboxUtilsRootfsInputType_t
char value[INPUT_LENGTH]; //!< String representation of input
} nvSandboxUtilsInitInput_v1_t;
typedef nvSandboxUtilsInitInput_v1_t nvSandboxUtilsInitInput_t;
/**
* File system information
*/
typedef struct nvSandboxUtilsGpuFileInfo_v1_t
{
struct nvSandboxUtilsGpuFileInfo_v1_t *next; //!< Pointer to the next node in the linked list
nvSandboxUtilsFileType_t fileType; //!< One of \p nvSandboxUtilsFileType_t
nvSandboxUtilsFileSystemSubType_t fileSubType; //!< One of \p nvSandboxUtilsFileSystemSubType_t
nvSandboxUtilsFileModule_t module; //!< One of \p nvSandboxUtilsFileModule_t
nvSandboxUtilsFileFlag_t flags; //!< One of \p nvSandboxUtilsFileFlag_t
char *filePath; //!< Relative file path to rootfs
}nvSandboxUtilsGpuFileInfo_v1_t;
/**
* GPU resource request v1
*/
typedef struct
{
unsigned int version; //!< Version for the structure
nvSandboxUtilsGpuInputType_t inputType; //!< One of \p nvSandboxUtilsGpuInputType_t
char input[INPUT_LENGTH]; //!< String representation of input
nvSandboxUtilsGpuFileInfo_v1_t *files; //!< Linked list of \ref nvSandboxUtilsGpuFileInfo_v1_t
} nvSandboxUtilsGpuRes_v1_t;
typedef nvSandboxUtilsGpuRes_v1_t nvSandboxUtilsGpuRes_t;
/** @} */
/***************************************************************************************************/
/** @defgroup funcs Functions
* @{
*/
/***************************************************************************************************/
/* *************************************************
* Initialize library
* *************************************************
*/
/**
* Prepare library resources before library API can be used.
* This initialization will not fail if one of the initialization prerequisites fails.
* @param input Reference to the called-supplied input struct that has initialization fields
*
* @returns @ref NVSANDBOXUTILS_SUCCESS on success
* @returns @ref NVSANDBOXUTILS_ERROR_INVALID_ARG if \p input->value isn't a valid rootfs path
* @returns @ref NVSANDBOXUTILS_ERROR_VERSION_NOT_SUPPORTED if \p input->version isn't supported by the library
* @returns @ref NVSANDBOXUTILS_ERROR_FILEPATH_NOT_FOUND if any of the required file paths are not found during initialization
* @returns @ref NVSANDBOXUTILS_ERROR_OUT_OF_MEMORY if there is insufficient system memory during initialization
* @returns @ref NVSANDBOXUTILS_ERROR_LIBRARY_LOAD on any error during loading the library
*/
nvSandboxUtilsRet_t nvSandboxUtilsInit(nvSandboxUtilsInitInput_t *input);
/* *************************************************
* Shutdown library
* *************************************************
*/
/**
* Clean up library resources created by init call
*
* @returns @ref NVSANDBOXUTILS_SUCCESS on success
*/
nvSandboxUtilsRet_t nvSandboxUtilsShutdown(void);
/* *************************************************
* Get NVIDIA RM driver version
* *************************************************
*/
/**
* Get NVIDIA RM driver version
* @param version Reference to caller-supplied buffer to return driver version string
* @param length The maximum allowed length of the string returned in \p version
*
* @returns @ref NVSANDBOXUTILS_SUCCESS on success
* @returns @ref NVSANDBOXUTILS_ERROR_INVALID_ARG if \p version is NULL
* @returns @ref NVSANDBOXUTILS_ERROR_NVML_LIB_CALL on any error during driver version query from NVML
*/
nvSandboxUtilsRet_t nvSandboxUtilsGetDriverVersion(char *version, unsigned int length);
/* *************************************************
* Get /dev, /proc, /sys file system information
* *************************************************
*/
/**
* Get /dev, /proc, /sys file system information
* @param request Reference to caller-supplied request struct to return the file system information
*
* @returns @ref NVSANDBOXUTILS_SUCCESS on success
* @returns @ref NVSANDBOXUTILS_ERROR_INVALID_ARG if \p request->input doesn't match any device
* @returns @ref NVSANDBOXUTILS_ERROR_VERSION_NOT_SUPPORTED if \p request->version isn't supported by the library
*/
nvSandboxUtilsRet_t nvSandboxUtilsGetGpuResource(nvSandboxUtilsGpuRes_t *request);
/* *************************************************
* Get content of given file path
* *************************************************
*/
/**
* Get file content of input file path
* @param filePath Reference to the file path
* @param content Reference to the caller-supplied buffer to return the file content
* @param contentSize Reference to the maximum allowed size of content. It is updated to the actual size of the content on return
*
* @returns @ref NVSANDBOXUTILS_SUCCESS on success
* @returns @ref NVSANDBOXUTILS_ERROR_INVALID_ARG if \p filePath or \p content is NULL
* @returns @ref NVSANDBOXUTILS_ERROR_INSUFFICIENT_SIZE if \p contentSize is too small
* @returns @ref NVSANDBOXUTILS_ERROR_FILEPATH_NOT_FOUND on an error while obtaining the content for the file path
*/
nvSandboxUtilsRet_t nvSandboxUtilsGetFileContent(char *filePath, char *content, unsigned int *contentSize);
/** @} */
#ifdef __cplusplus
}
#endif
#endif // __NVSANDBOXUTILS_H__