boot_hal/hal_api/boot_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_BOOT_HAL_H_
  18 #define HAL_API_BOOT_HAL_H_
  19
  20 #include <stdint.h>
  21 #include <native_service/frameworkunified_types.h>
  22
  23 /**
  24  * @file boot_hal.h
  25  * @brief This file provides API for get boot info from boot device, set boot info to boot device,
  26  *        set next boot mode to coldstart and get current boot mode
  27  */
  28
  29 /** @addtogroup reproservice
  30  *  @{
  31  */
  32 /** @addtogroup boot_hal
  33  *  @ingroup reprogramming_service
  34  *  @{
  35  */
  36
  37 /**
  38  * \~english BootHalBootMode
  39  */
  40 enum BootHalBootMode{
  41   /**
  42    * \~english cold start
  43    */
  44   COLD_START = 0,
  45   /**
  46    * \~english hot start
  47    */
  48   HOT_START = 1,
  49 };
  50
  51 /**
  52  * \~english BootHalUpTableID
  53  */
  54 enum BootHalUpTableID{
  55   /**
  56    * \~english UBOOT
  57    */
  58   BOOTHAL_SIDE_IDX_UBOOT = 0,
  59   /**
  60    * \~english Secure loader
  61    */
  62   BOOTHAL_SIDE_IDX_SECURE = 1,
  63   /**
  64    * \~english MAIN software
  65    */
  66   BOOTHAL_SIDE_IDX_MAINSOFT = 2,
  67   /**
  68    * \~english Max num of modules(include reserves)
  69    */
  70   BOOTHAL_NUMTARGS = 20
  71 };
  72
  73 /**
  74  * \~english BootHalStatus
  75  */
  76 typedef enum BootHalStatus {
  77 /**
  78  * \~english Success
  79  */
  80   BOOTHAL_RET_SUCCESS = 0,
  81 /**
  82  * \~english No permission to operate
  83  */
  84   BOOTHAL_RET_ERR_PERMISSION = 1,
  85 /**
  86  * \~english Time out
  87  */
  88   BOOTHAL_RET_ERR_TIMEOUT = 2,
  89 /**
  90  * \~english Status error
  91  */
  92   BOOTHAL_RET_ERR_STATUS = 3,
  93 /**
  94  * \~english Write error
  95  */
  96   BOOTHAL_RET_ERR_WRITE = 4,
  97 /**
  98  * \~english Paramater error
  99  */
 100   BOOTHAL_RET_ERR_PARAM = 5,
 101 /**
 102  * \~english Internal IO error(open, read, write, strstr, close)
 103  */
 104   BOOTHAL_RET_ERR_FAIL = 6,
 105 } BootHalStatus;
 106
 107 /**
 108  * \~english Not rewrite.
 109  */
 110 #define BOOTHAL_SIDE_NONE 0
 111 /**
 112  * \~english Rewrites side A.
 113  */
 114 #define BOOTHAL_SIDE_A 1
 115 /**
 116  * \~english Rewrites side B.
 117  */
 118 #define BOOTHAL_SIDE_B 2
 119 /**
 120  * \~english Max parameter num
 121  */
 122 #define BOOTHAL_NUMSIDE_MAX 3
 123
 124 /**\ingroup setSide
 125  * \~english @par Brief
 126  *      This API set boot info to boot device, the caller control this API not be called at the
 127  *      same time
 128  * \~english @param [in] upTableID
 129  *      unsigned int           - Boot info
 130  * \~english @retval BOOTHAL_RET_SUCCESS OK
 131  * \~english @retval BOOTHAL_RET_ERR_PARAM Parameter error
 132  * \~english @retval BOOTHAL_RET_ERR_WRITE Write error
 133  * \~english @retval BOOTHAL_RET_ERR_FAIL Internal IO error
 134  * \~english @par Preconditions
 135  *      - There is no preconditions for this API.
 136  * \~english @par Change of internal state
 137  *      - Change of internal state according to the API does not occur.
 138  * \~english @par Conditions of processing failure
 139  *      - If the parameter upTableId is NULL. [BOOTHAL_RET_ERR_PARAM]
 140  *      - If write /dev/mmcblk0boot1 return -1. [BOOTHAL_RET_ERR_WRITE]
 141  *      - Internal IO error(open, read, lseek). [BOOTHAL_RET_ERR_FAIL]
 142  * \~english @par Detail
 143  *      - This API set boot info.
 144  *      - The API can only be used by 1 process.
 145  * \~english @par Classification
 146  *      Public
 147  * \~english @par Type
 148  *      Sync
 149  * \~english @see getSide
 150  */
 151 BootHalStatus setSide(unsigned int upTableID[]);
 152
 153 /**\ingroup getSide
 154  * \~english @par Brief
 155  *      Get boot info from boot device
 156  * \~english @param [out] upTableID
 157  *      unsigned int              - boot info
 158  * \~english @retval BOOTHAL_RET_SUCCESS OK
 159  * \~english @retval BOOTHAL_RET_ERR_PARAM Parameter error
 160  * \~english @retval BOOTHAL_RET_ERR_FAIL Internal IO error
 161  * \~english @par Preconditions
 162  *      - There is no preconditions for this API.
 163  * \~english @par Change of internal state
 164  *      - Change of internal state according to the API does not occur.
 165  * \~english @par Conditions of processing failure
 166  *      - If the parameter upTableId is NULL. [BOOTHAL_RET_ERR_PARAM]
 167  *      - Internal IO error.[BOOTHAL_RET_ERR_FAIL]
 168  * \~english @par Detail
 169  *      - This API get boot info from boot device.
 170  *      - The API can only be used by 1 process.
 171  * \~english @par Classification
 172  *      Public
 173  * \~english @par Type
 174  *      Sync
 175  * \~english @see setSide
 176  */
 177 BootHalStatus getSide(unsigned int upTableID[]);
 178
 179 /**\ingroup setBootColdStart
 180  * \~english @par Brief
 181  *     Set next boot to ColdStart mode.
 182  * \~english @retval BOOTHAL_RET_SUCCESS OK
 183  * \~english @retval BOOTHAL_RET_ERR_FAIL set next boot start mode failed
 184  * \~english @par Preconditions
 185  *      - There is no preconditions for this API.
 186  * \~english @par Change of internal state
 187  *      - Change of internal state according to the API does not occur.
 188  * \~english @par Conditions of processing failure
 189  *      - Internal IO error.[BOOTHAL_RET_ERR_FAIL]
 190  * \~english @par Detail
 191  *      - This API Set next boot to ColdStart mode.
 192  *      - The API can only be used by 1 process.
 193  * \~english @par Classification
 194  *      Public
 195  * \~english @par Type
 196  *      Sync
 197  * \~english @see getBootMode
 198  */
 199 BootHalStatus setBootColdStart(void);
 200
 201 /**\ingroup getBootMode
 202  * \~english @par Brief
 203  *      Get boot mode.
 204  * \~english @param [out] mode
 205  *      unsigned int              - boot mode(COLD_START or HOT_START)
 206  * \~english @retval BOOTHAL_RET_SUCCESS OK
 207  * \~english @retval BOOTHAL_RET_ERR_PARAM Parameter error
 208  * \~english @par Preconditions
 209  *      - There is no preconditions for this API.
 210  * \~english @par Change of internal state
 211  *      - Change of internal state according to the API does not occur.
 212  * \~english @par Conditions of processing failure
 213  *      - If the parameter mode is NULL. [BOOTHAL_RET_ERR_PARAM]
 214  * \~english @par Detail
 215  *      - This API get boot mode.
 216  *      - The API can only be used by 1 process.
 217  * \~english @par Classification
 218  *      Public
 219  * \~english @par Type
 220  *      Sync
 221  * \~english @see setBootColdStart
 222  */
 223 BootHalStatus getBootMode(uint32_t *mode);
 224
 225 /** @}*/  // end of boot_hal
 226 /** @}*/  // end of reprogramming_service
 227
 228 #endif  // HAL_API_BOOT_HAL_H_