video_in_hal/nv_hal/hal_api/nv_hal.h

   1 /*
   2  * @copyright Copyright(c) 2018-2020 TOYOTA MOTOR CORPORATION.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef HAL_API_NV_HAL_H_
  18 #define HAL_API_NV_HAL_H_
  19
  20 #include <stdint.h>
  21 #include <native_service/frameworkunified_types.h>
  22
  23 /**
  24  * @file nv_hal.h
  25  * @brief This file provides API for accessing storage device.
  26  */
  27
  28 /** @addtogroup backup_manager
  29  *  @{
  30  */
  31 /** @addtogroup nv_hal
  32  *  @ingroup backup_manager
  33  *  @{
  34  */
  35
  36 /**
  37  * \~english NvHalMedia
  38  */
  39 enum NvHalMedia {
  40   /**
  41    * \~english CacheDram
  42    */
  43   NVHALMEDIA_CACHEDRAM = 0,
  44   /**
  45    * \~english BackupDram
  46    */
  47   NVHALMEDIA_BACKUPDRAM,
  48   /**
  49    * \~english nand
  50    */
  51   NVHALMEDIA_NAND,
  52   /**
  53    * \~english Max
  54    */
  55   NVHALMEDIA_MAX
  56 };
  57
  58 /**\ingroup InitNv
  59  * \~english @par Brief
  60  *      Initialize Nv hal library.
  61  * \~english @retval eFrameworkunifiedStatusOK   : succsess initialize.
  62  * \~english @retval eFrameworkunifiedStatusFail : fail initialize
  63  * \~english @par Preconditions
  64  *      - There is no preconditions for this API.
  65  * \~english @par Change of internal state
  66  *      - Change of internal state according to the API does not occur.
  67  * \~english @par Conditions of processing failure
  68  *      - Initialization processing failure.[eFrameworkunifiedStatusFail]
  69  * \~english @par Detail
  70  *      - Perform Nv_hal library initialization.
  71  *      - This process also performs deletion of temporary files accompanying system reset\n
  72  *        during write processing.
  73  *      - The API can only be used by 1 process.
  74  * \~english @par Classification
  75  *      Public
  76  * \~english @par Type
  77  *      Sync
  78  * \~english @see
  79  *      - None
  80  */
  81 EFrameworkunifiedStatus InitNv(void);
  82
  83 /**\ingroup GetSizeNv
  84  * \~english @par Brief
  85  *      This API get data size which is stored in storage device.
  86  * \~english @param [in] media
  87  *      enum NvHalMedia           - Media type
  88  * \~english @param [in] filename
  89  *      const char*               - file name(Concatenated[category name/item name])
  90  * \~english @param [out] size
  91  *      uint32_t                  - Data size
  92  * \~english @par
  93  *      - Get decrypted data size as encryption data when item name in the argument of filename (file name) is added Prefix "ENC_".
  94  *       - Non encryption data : D_BK_CA_GID_D/D_BK_ID_GID_D
  95  *       - Encryption data     : D_BK_CA_GID_D/ENC_D_BK_ID_GID_D
  96  * \~english @retval eFrameworkunifiedStatusOK OK
  97  * \~english @retval eFrameworkunifiedStatusFileLoadError File not exists
  98  * \~english @retval eFrameworkunifiedStatusInvldParam Parameter error
  99  * \~english @par Preconditions
 100  *      - There is no preconditions for this API.
 101  * \~english @par Change of internal state
 102  *      - Change of internal state according to the API does not occur.
 103  * \~english @par Conditions of processing failure
 104  *      - If the parameter media is less than NVHALMEDIA_CACHEDRAM or greater than\n
 105  *      NVHALMEDIA_NAND. [eFrameworkunifiedStatusInvldParam]
 106  *      - Parameter id is NULL. [eFrameworkunifiedStatusInvldParam]
 107  *      - Value of parameter size is 0. [eFrameworkunifiedStatusInvldParam]
 108  *      - Internal IO error(lstat).[eFrameworkunifiedStatusFileLoadError]
 109  * \~english @par Detail
 110  *      - This API get the data size according to specified media and ID.
 111  *      - The API can only be used by 1 process.
 112  * \~english @par Classification
 113  *      Public
 114  * \~english @par Type
 115  *      Sync
 116  * \~english @see WriteNv ReadNv
 117  */
 118 EFrameworkunifiedStatus GetSizeNv(enum NvHalMedia media, const char *filename, uint32_t* size);
 119
 120
 121
 122 /**\ingroup ReadNv
 123  * \~english @par Brief
 124  *      Read data from storage device.
 125  * \~english @param [in] media
 126  *      enum NvHalMedia           - Media type
 127  * \~english @param [in] filename
 128  *      const char*               - file name(Concatenated[category name/item name])
 129  * \~english @param [out] buffer
 130  *      uint8_t*                  - Buffer for storing read data
 131  * \~english @param [in] size
 132  *      uint32_t                  - Data size
 133  * \~english @par
 134  *      - Decrypt and read data as encryption data when item name in the argument of filename (file name) is added Prefix "ENC_".
 135  *       - Non encryption data : D_BK_CA_GID_D/D_BK_ID_GID_D
 136  *       - Encryption data     : D_BK_CA_GID_D/ENC_D_BK_ID_GID_D
 137  * \~english @retval eFrameworkunifiedStatusOK OK
 138  * \~english @retval eFrameworkunifiedStatusInvldParam Parameter error
 139  * \~english @retval eFrameworkunifiedStatusFail Read data failed
 140  * \~english @par Preconditions
 141  *      - There is no preconditions for this API.
 142  * \~english @par Change of internal state
 143  *      - Change of internal state according to the API does not occur.
 144  * \~english @par Conditions of processing failure
 145  *      - If the parameter media is less than NVHALMEDIA_CACHEDRAM or greater than\n
 146  *      NVHALMEDIA_NAND. [eFrameworkunifiedStatusInvldParam]
 147  *      - Parameter id is NULL. [eFrameworkunifiedStatusInvldParam]
 148  *      - Parameter buffer is NULL. [eFrameworkunifiedStatusInvldParam]
 149  *      - Value of parameter size is 0. [eFrameworkunifiedStatusInvldParam]
 150  *      - Internal IO error(open, pread, lstat, close).[eFrameworkunifiedStatusFail]
 151  *      - The value of parameter size is not equal to the file size specified by id.
 152  *      [eFrameworkunifiedStatusFail]
 153  * \~english @par Detail
 154  *      - This API reads data according to specified media and ID.
 155  *      - ID is managed by backup_manager.For details, refer to "Details about XML file" in external specification of backup_manager.
 156  *      - The API can only be used by 1 process.
 157  * \~english @par Classification
 158  *      Public
 159  * \~english @par Type
 160  *      Sync
 161  * \~english @see CheckNv WriteNv
 162  */
 163 EFrameworkunifiedStatus ReadNv(enum NvHalMedia media, const char *filename, uint8_t *buffer, uint32_t size);
 164
 165 /**\ingroup WriteNv
 166  * \~english @par Brief
 167  *      Write data to storage device.
 168  * \~english @param [in] media
 169  *      enum NvHalMedia           - Media type
 170  * \~english @param [in] filename
 171  *      const char*               - filename(Concatenated[category name/item name])
 172  * \~english @param [in] buffer
 173  *      uint8_t*                  - Buffer for storing written data
 174  * \~english @param [in] size
 175  *      uint32_t                  - Data size
 176  * \~english @par
 177  *      - Encrypt and write data as encryption data when item name in the argument of filename (file name) is added Prefix "ENC_".
 178  *       - Non encryption data : D_BK_CA_GID_D/D_BK_ID_GID_D
 179  *       - Encryption data     : D_BK_CA_GID_D/ENC_D_BK_ID_GID_D
 180  * \~english @retval eFrameworkunifiedStatusOK OK
 181  * \~english @retval eFrameworkunifiedStatusInvldParam Parameter error
 182  * \~english @retval eFrameworkunifiedStatusFail Write data failed
 183  * \~english @par Preconditions
 184  *      - There is no preconditions for this API.
 185  * \~english @par Change of internal state
 186  *      - Change of internal state according to the API does not occur.
 187  * \~english @par Conditions of processing failure
 188  *      - If the parameter media is less than NVHALMEDIA_CACHEDRAM or greater than\n
 189  *      NVHALMEDIA_NAND. [eFrameworkunifiedStatusInvldParam]
 190  *      - Parameter id is NULL. [eFrameworkunifiedStatusInvldParam]
 191  *      - Parameter buffer is NULL. [eFrameworkunifiedStatusInvldParam]
 192  *      - Value of parameter size is 0. [eFrameworkunifiedStatusInvldParam]
 193  *      - Internal IO error(open, pwrite, close, mkdir).[eFrameworkunifiedStatusFail]
 194  * \~english @par Detail
 195  *      - This API writes data according to specified media and ID.
 196  *      - filename is managed by backup_manager.For details, refer to "Details about XML file" in external specification of backup_manager.
 197  *      - The API can only be used by 1 process.
 198  * \~english @par Classification
 199  *      Public
 200  * \~english @par Type
 201  *      Sync
 202  * \~english @see CheckNv ReadNv
 203  */
 204 EFrameworkunifiedStatus WriteNv(enum NvHalMedia media, const char *filename, uint8_t *buffer, uint32_t size);
 205
 206 /**\ingroup DeleteNv
 207  * \~english @par Brief
 208  *      Delete data which is stored in storage device.
 209  * \~english @param [in] media
 210  *      enum \ref NvHalMedia           - Media type
 211  * \~english @param [in] filename
 212  *      const char*               - filename(Concatenated[category name/item name])
 213  * \~english @par
 214  *      - Delete data as encryption data when item name in the argument of filename (file name) is added Prefix "ENC_".
 215  *       - Non encryption data : D_BK_CA_GID_D/D_BK_ID_GID_D
 216  *       - Encryption data     : D_BK_CA_GID_D/ENC_D_BK_ID_GID_D
 217  * \~english @retval eFrameworkunifiedStatusOK OK
 218  * \~english @retval eFrameworkunifiedStatusInvldParam Parameter error
 219  * \~english @retval eFrameworkunifiedStatusFail Delete data failed
 220  * \~english @par Preconditions
 221  *      - There is no preconditions for this API.
 222  * \~english @par Change of internal state
 223  *      - Change of internal state according to the API does not occur.
 224  * \~english @par Conditions of processing failure
 225  *      - If the parameter media is less than \ref NVHALMEDIA_CACHEDRAM or greater than\n
 226  *        \ref NVHALMEDIA_NAND . [eFrameworkunifiedStatusInvldParam]
 227  *      - Parameter filename (filename) is NULL. [eFrameworkunifiedStatusInvldParam]
 228  *      - Internal IO error.[eFrameworkunifiedStatusFail]
 229  * \~english @par Detail
 230  *      - This API delete data according to specified media and filename.
 231  *      - This API delete encryption key if data is encrypted.
 232  *      - filename is managed by backup_manager.For details, refer to "Details about XML file" in external specification of backup_manager.
 233  *      - The API can only be used by 1 process.
 234  * \~english @par Classification
 235  *      Public
 236  * \~english @par Type
 237  *      Sync
 238  * \~english @see GetSizeNv ReadNv WriteNv
 239  */
 240 EFrameworkunifiedStatus DeleteNv(enum NvHalMedia media, const char *filename);
 241
 242 /** @}*/  // end of nv_hal
 243 /** @}*/  // end of backup_manager
 244
 245 #endif  // HAL_API_NV_HAL_H_