| /* |
| * 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__ |
