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