systemservice/rom_access_library/library/include/system_service/nor_backup.h

   1 /*
   2  * @copyright Copyright (c) 2016-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 /**
  18  * @file nor_backup.h
  19  * @brief This file provides API for get nor flash information
  20  */
  21
  22 #ifndef ROM_ACCESS_LIBRARY_LIBRARY_INCLUDE_SYSTEM_SERVICE_NOR_BACKUP_H_
  23 #define ROM_ACCESS_LIBRARY_LIBRARY_INCLUDE_SYSTEM_SERVICE_NOR_BACKUP_H_
  24
  25 /** @addtogroup BaseSystem
  26  *  @{
  27  */
  28 /** @addtogroup system_service
  29  *  @ingroup BaseSystem
  30  *  @{
  31  */
  32 /** @addtogroup rom_access_library
  33  *  @ingroup system_service
  34  *  @{
  35  */
  36 #if defined(__cplusplus)
  37 extern "C" {
  38 #endif  // __cplusplus
  39
  40 /**
  41  * \~english Common return value: Normal return value of API
  42  */
  43 #define RET_DEV_NORMAL          0
  44
  45 /**
  46  * \~english Common return value: Parameter error return value of API
  47  */
  48 #define RET_DEV_ERR_PARAM       3
  49
  50 /**
  51  * \~english Common return value: Error of getting device info
  52  */
  53 #define RET_DEV_ERROR           4
  54
  55 /**
  56  * \~english Read API return value: Internal error
  57  */
  58 #define RET_DEV_RD_ERR_OTHER    1
  59
  60 /**
  61  * \~english Read API return value: Acquire buffer error(malloc)
  62  */
  63 #define RET_DEV_RD_ERR          2
  64
  65 /**
  66  * \~english Read API return value: error type 1
  67  */
  68 #define RET_DEV_RD_ERR_1        -1
  69
  70 /**
  71  * \~english Read API return value: error type 2
  72  */
  73 #define RET_DEV_RD_ERR_2        -2
  74
  75 /**
  76  * \~english Read API return value: error type 3
  77  */
  78 #define RET_DEV_RD_ERR_3        -3
  79
  80 /**
  81  * \~english Read API return value: error type 4
  82  */
  83 #define RET_DEV_RD_ERR_4        -4
  84
  85 /**
  86  * \~english Write API return value: Other error
  87  */
  88 #define RET_DEV_WT_ERR_OTHER    1
  89
  90 /**
  91  * \~english Write API return value: Internal error
  92  */
  93 #define RET_DEV_WT_ERR          2
  94
  95 /**\ingroup mtdn_backup_Read
  96  * \~english @par Brief
  97  *      Read data from norflash device.
  98  * \~english @param [in] path_name
  99  *      const char*           - Device path to read(such as "/dev/mtd1ro")
 100  * \~english @param [in] i_id
 101  *      int                   - Main block ID(0, 2, 4, ...)
 102  * \~english @param [in] i_offset
 103  *      int                   - Data offset
 104  * \~english @param [in] i_size
 105  *      int                   - Data size to read
 106  * \~english @param [in] p_buff
 107  *      Void*                 - Buffer for storing read data
 108  * \~english @retval RET_DEV_NORMAL OK
 109  * \~english @retval RET_DEV_ERROR Get device error
 110  * \~english @retval RET_DEV_ERR_PARAM Parameter error
 111  * \~english @retval RET_DEV_RD_ERR_OTHER Internal error
 112  * \~english @retval RET_DEV_RD_ERR Acquire buffer error(malloc)
 113  * \~english @retval RET_DEV_RD_ERR_1 Error type 1
 114  * \~english @retval RET_DEV_RD_ERR_2 Error type 2
 115  * \~english @retval RET_DEV_RD_ERR_3 Error type 3
 116  * \~english @retval RET_DEV_RD_ERR_4 Error type 4
 117  * \~english @par Preconditions
 118  *      - There is no preconditions for this API.
 119  * \~english @par Change of internal state
 120  *      - Change of internal state according to the API does not occur.
 121  * \~english @par Conditions of processing failure
 122  *      - Parameter path_name is NULL. [RET_DEV_ERR_PARAM]
 123  *      - Parameter p_buff is NULL. [RET_DEV_ERR_PARAM]
 124  *      - Value of parameter i_id is less than 0. [RET_DEV_ERR_PARAM]
 125  *      - Value of parameter i_offset is less than 0 or value of parameter i_size
 126  *        is not greater than 0. [RET_DEV_ERR_PARAM]
 127  *      - Device specified by path_name is invalid. [RET_DEV_ERR_PARAM]
 128  *      - Sum value of i_offset and i_size is greater than block size - 16byte.
 129  *        [RET_DEV_ERR_PARAM]
 130  *      - Failed to get device info. [RET_DEV_ERROR]
 131  *      - Failed to acquire the send/receive buffer(malloc). [RET_DEV_RD_ERR]
 132  *      - Internal IO error(open, read, close, ioctl, lseek, other error).
 133  *        [RET_DEV_RD_ERR_OTHER]
 134  *      - Check text error of main block and backup block. [RET_DEV_RD_ERR_1]
 135  *      - Check text error of main block and checksum error of backup block.
 136  *        [RET_DEV_RD_ERR_2]
 137  *      - Checksum error of main block and check text error of backup block.
 138  *        [RET_DEV_RD_ERR_3]
 139  *      - Checksum error of main block and backup block. [RET_DEV_RD_ERR_4]
 140  * \~english @par Detail
 141  *      - This API gets data from main or backup block according to specified\n
 142  *      norflash device pathname and main block ID.
 143  * \~english @par
 144  *      - When this API is executed, read data from main block first. If failed to\n
 145  *      read main block, return RET_DEV_RD_ERR_OTHER. If read main block success,\n
 146  *      but check main block data error, turn to read data from backup block which\n
 147  *      block ID is i_id + 1.
 148  * \~english @par Classification
 149  *      Public
 150  * \~english @par Type
 151  *      Sync Only
 152  * \~english @see mtdn_backup_Write
 153  */
 154 int mtdn_backup_Read(const char * path_name, int i_id, int i_offset, int i_size, void *p_buff);
 155
 156 /**\ingroup mtdn_backup_Write
 157  * \~english @par Brief
 158  *      Write data to norflash device.
 159  * \~english @param [in] path_name
 160  *      const char*           - Device path to write(such as "/dev/mtd")
 161  * \~english @param [in] i_id
 162  *      int                   - Main block ID(0, 2, 4, ...)
 163  * \~english @param [in] i_offset
 164  *      int                   - Data offset
 165  * \~english @param [in] i_size
 166  *      int                   - Data size to write
 167  * \~english @param [in] p_buff
 168  *      Void*                 - Buffer for storing written data
 169  * \~english @retval RET_DEV_NORMAL OK
 170  * \~english @retval RET_DEV_ERROR Get device error
 171  * \~english @retval RET_DEV_ERR_PARAM Parameter error
 172  * \~english @retval RET_DEV_WT_ERR_OTHER Other error
 173  * \~english @retval RET_DEV_WT_ERR Internal error
 174  * \~english @par Preconditions
 175  *      - There is no preconditions for this API.
 176  * \~english @par Change of internal state
 177  *      - Change of internal state according to the API does not occur.
 178  * \~english @par Conditions of processing failure
 179  *      - Parameter path_name is NULL. [RET_DEV_ERR_PARAM]
 180  *      - Parameter p_buff is NULL. [RET_DEV_ERR_PARAM]
 181  *      - Value of parameter i_id is less than 0. [RET_DEV_ERR_PARAM]
 182  *      - Value of parameter i_offset is less than 0 or value of parameter i_size
 183  *        is not greater than 0. [RET_DEV_ERR_PARAM]
 184  *      - Device specified by path_name is invalid. [RET_DEV_ERR_PARAM]
 185  *      - Sum value of i_offset and i_size is greater than block size - 16byte.
 186  *        [RET_DEV_ERR_PARAM]
 187  *      - Failed to get device info. [RET_DEV_ERROR]
 188  *      - Internal processing error(Other error). [RET_DEV_WT_ERR_OTHER]
 189  *      - Internal IO error(open, write, close, ioctl, malloc, lseek).
 190  *        [RET_DEV_WT_ERR]
 191  * \~english @par Detail
 192  *      - This API writes data to main and backup blocks according to specified\n
 193  *      norflash device pathname and main block ID.
 194  * \~english @par
 195  *      - When this API is executed, p_buff data will be write to main and backup\n
 196  *      blocks. If failed to write any block, return RET_DEV_WT_ERR.
 197  * \~english @par Classification
 198  *      Public
 199  * \~english @par Type
 200  *      Sync Only
 201  * \~english @see mtdn_backup_Read
 202  */
 203 int mtdn_backup_Write(const char * path_name, int i_id, int i_offset, int i_size, void *p_buff);
 204
 205 #if defined(__cplusplus)
 206 }
 207 #endif  // __cplusplus
 208
 209 /** @}*/  // end of rom_access_library
 210 /** @}*/  // end of system_service
 211 /** @}*/  // end of BaseSystem
 212 #endif  // ROM_ACCESS_LIBRARY_LIBRARY_INCLUDE_SYSTEM_SERVICE_NOR_BACKUP_H_