sotp.h

00001 /*
00002  * Copyright (c) 2016 ARM Limited. All rights reserved.
00003  * SPDX-License-Identifier: Apache-2.0
00004  * Licensed under the Apache License, Version 2.0 (the License); you may
00005  * not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
00012  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef __SOTP_H
00018 #define __SOTP_H
00019 
00020 #include <stdint.h>
00021 #include "pal.h"
00022 
00023 #define SYS_CONF_SOTP_DISABLED 0
00024 #define SYS_CONF_SOTP_ENABLED  1
00025 #define SYS_CONF_SOTP_LIMITED  2
00026 
00027 #if PAL_USE_INTERNAL_FLASH
00028     #ifndef SYS_CONF_SOTP
00029         #define SYS_CONF_SOTP   SYS_CONF_SOTP_ENABLED
00030     #endif
00031 #else
00032     #ifndef SYS_CONF_SOTP
00033         #define SYS_CONF_SOTP   SYS_CONF_SOTP_LIMITED
00034     #endif
00035 #endif
00036 
00037 #ifdef RBP_TESTING
00038 #undef SOTP_PROBE_ONLY
00039 #endif
00040 
00041 typedef enum {
00042     SOTP_SUCCESS                = 0,
00043     SOTP_READ_ERROR             = 1,
00044     SOTP_WRITE_ERROR            = 2,
00045     SOTP_NOT_FOUND              = 3,
00046     SOTP_DATA_CORRUPT           = 4,
00047     SOTP_BAD_VALUE              = 5,
00048     SOTP_BUFF_TOO_SMALL         = 6,
00049     SOTP_FLASH_AREA_TOO_SMALL   = 7,
00050     SOTP_OS_ERROR               = 8,
00051     SOTP_BUFF_NOT_ALIGNED       = 9,
00052     SOTP_ALREADY_EXISTS         = 10,
00053     SOTP_MEM_ALLOC_ERROR        = 11,
00054     SOTP_ERROR_MAXVAL           = 0xFFFF
00055 } sotp_result_e;
00056 
00057 #define SOTP_NUM_AREAS PAL_INT_FLASH_NUM_SECTIONS
00058 
00059 // Each type can be either OTP (One Time programmed) or RBP (RollBack protected)
00060 typedef enum {
00061     SOTP_TYPE_FACTORY_DONE = 0,
00062     SOTP_TYPE_RANDOM_SEED,
00063     SOTP_TYPE_SAVED_TIME,
00064     SOTP_TYPE_LAST_TIME_BACK,
00065     SOTP_TYPE_ROT,
00066     SOTP_TYPE_TRUSTED_TIME_SRV_ID,
00067     SOTP_TYPE_EXECUTION_MODE,
00068     SOTP_TYPE_OEM_TRANSFER_MODE_ENABLED,
00069     SOTP_TYPE_MIN_FW_VERSION,
00070 
00071     SOTP_LAST_TYPE = 15, // Keep as long as we have less than this
00072     SOTP_MAX_TYPES
00073 } sotp_type_e;
00074 
00075 #define SOTP_BLANK_FLASH_VAL PAL_INT_FLASH_BLANK_VAL
00076 
00077 
00078 #ifdef __cplusplus
00079 extern "C" {
00080 #endif
00081 
00082 // Check whether a type is an OTP type.
00083 /**
00084  * @brief Check whether a type is an OTP type (can be written once) or RBP (more than once).
00085  *
00086  * @param [in] type
00087  *               Given type.
00088  *
00089  * @returns false                   Type is RBP (can be written more than once).
00090  *          true                    Type is OTP (can be written only once).
00091  */
00092 bool sotp_is_otp_type(uint32_t type);
00093 
00094 /**
00095  * @brief Returns one item of data programmed on Flash, given type.
00096  *
00097  * @param [in] type
00098  *               Type of stored item (must be between 0-15).
00099  *
00100  * @param [in] buf_len_bytes
00101  *               Length of input buffer in bytes.
00102  *
00103  * @param [in] buf
00104  *               Buffer to store data on (must be aligned to a 32 bit boundary).
00105  *
00106  * @param [out] actual_len_bytes.
00107  *               Actual length of returned data
00108  *
00109  * @returns SOTP_SUCCESS           Value was found on Flash.
00110  *          SOTP_NOT_FOUND         Value was not found on Flash.
00111  *          SOTP_READ_ERROR        Physical error reading data.
00112  *          SOTP_DATA_CORRUPT      Data on Flash is corrupt.
00113  *          SOTP_BAD_VALUE         Bad value in any of the parameters.
00114  *          SOTP_BUFF_TOO_SMALL    Not enough memory in user buffer.
00115  *          SOTP_BUFF_NOT_ALIGNED  Buffer not aligned to 32 bits.
00116  */
00117 sotp_result_e sotp_get(uint32_t type, uint16_t buf_len_bytes, uint32_t *buf, uint16_t *actual_len_bytes);
00118 
00119 /**
00120  * @brief Returns one item of data programmed on Flash, given type.
00121  *
00122  * @param [in] type
00123  *               Type of stored item.
00124  *
00125  * @param [out] actual_len_bytes.
00126  *               Actual length of item
00127  *
00128  * @returns SOTP_SUCCESS           Value was found on Flash.
00129  *          SOTP_NOT_FOUND         Value was not found on Flash.
00130  *          SOTP_READ_ERROR        Physical error reading data.
00131  *          SOTP_DATA_CORRUPT      Data on Flash is corrupt.
00132  *          SOTP_BAD_VALUE         Bad value in any of the parameters.
00133  */
00134 sotp_result_e sotp_get_item_size(uint32_t type, uint16_t *actual_len_bytes);
00135 
00136 
00137 /**
00138  * @brief Programs one item of data on Flash, given type.
00139  *
00140  * @param [in] type
00141  *               Type of stored item (must be between 0-15).
00142  *
00143  * @param [in] buf_len_bytes
00144  *               Item length in bytes.
00145  *
00146  * @param [in] buf
00147  *               Buffer containing data  (must be aligned to a 32 bit boundary).
00148  *
00149  * @returns SOTP_SUCCESS           Value was successfully written on Flash.
00150  *          SOTP_WRITE_ERROR       Physical error writing data.
00151  *          SOTP_BAD_VALUE         Bad value in any of the parameters.
00152  *          SOTP_FLASH_AREA_TOO_SMALL
00153  *                                 Not enough space in Flash area.
00154  *          SOTP_BUFF_NOT_ALIGNED  Buffer not aligned to 32 bits.
00155  *          SOTP_ALREADY_EXISTS    Item (OTP type) already exists.
00156  *
00157  */
00158 sotp_result_e sotp_set(uint32_t type, uint16_t buf_len_bytes, const uint32_t *buf);
00159 
00160 #ifdef RBP_TESTING
00161 /**
00162  * @brief Delete an item from flash.
00163  *
00164  * @param [in] type
00165  *               Type of stored item (must be between 0-15).
00166  *
00167  * @param [in] buf_len_bytes
00168  *               Item length in bytes.
00169  *
00170  * @param [in] buf
00171  *               Buffer containing data  (must be aligned to a 32 bit boundary).
00172  *
00173  * @returns SOTP_SUCCESS           Value was successfully written on Flash.
00174  *          SOTP_WRITE_ERROR       Physical error writing data.
00175  *          SOTP_BAD_VALUE         Bad value in any of the parameters.
00176  *          SOTP_FLASH_AREA_TOO_SMALL
00177  *                                 Not enough space in Flash area.
00178  *          SOTP_BUFF_NOT_ALIGNED  Buffer not aligned to 32 bits.
00179  *
00180  */
00181 sotp_result_e sotp_delete(uint32_t type);
00182 
00183 /**
00184  * @brief Programs one item of data on Flash, given type. No OTP existing check.
00185  *
00186  * @param [in] type
00187  *               Type of stored item (must be between 0-15).
00188  *
00189  * @param [in] buf_len_bytes
00190  *               Item length in bytes.
00191  *
00192  * @param [in] buf
00193  *               Buffer containing data  (must be aligned to a 32 bit boundary).
00194  *
00195  * @returns SOTP_SUCCESS           Value was successfully written on Flash.
00196  *          SOTP_WRITE_ERROR       Physical error writing data.
00197  *          SOTP_BAD_VALUE         Bad value in any of the parameters.
00198  *          SOTP_FLASH_AREA_TOO_SMALL
00199  *                                 Not enough space in Flash area.
00200  *          SOTP_BUFF_NOT_ALIGNED  Buffer not aligned to 32 bits.
00201  *
00202  */
00203 sotp_result_e sotp_set_for_testing(uint32_t type, uint16_t buf_len_bytes, const uint32_t *buf);
00204 #endif
00205 
00206 /**
00207  * @brief Initializes SOTP component.
00208  *
00209  * @returns SOTP_SUCCESS       Initialization completed successfully.
00210  *          SOTP_READ_ERROR    Physical error reading data.
00211  *          SOTP_WRITE_ERROR   Physical error writing data (on recovery).
00212  *          SOTP_FLASH_AREA_TOO_SMALL
00213  *                             Not enough space in Flash area.
00214  */
00215 sotp_result_e sotp_init(void);
00216 
00217 /**
00218  * @brief Deinitializes SOTP component.
00219  *        Warning: This function is not thread safe and should not be called
00220  *        concurrently with other SOTP functions.
00221  *
00222  * @returns SOTP_SUCCESS       Deinitialization completed successfully.
00223  */
00224 sotp_result_e sotp_deinit(void);
00225 
00226 /**
00227  * @brief Reset Flash SOTP areas.
00228  *        Warning: This function is not thread safe and should not be called
00229  *        concurrently with other SOTP functions.
00230  *
00231  * @returns SOTP_SUCCESS       Reset completed successfully.
00232  *          SOTP_READ_ERROR    Physical error reading data.
00233  *          SOTP_WRITE_ERROR   Physical error writing data.
00234  */
00235 sotp_result_e sotp_reset(void);
00236 
00237 #ifdef RBP_TESTING
00238 
00239 /**
00240  * @brief Initiate a forced garbage collection.
00241  *
00242  * @returns SOTP_SUCCESS       GC completed successfully.
00243  *          SOTP_READ_ERROR    Physical error reading data.
00244  *          SOTP_WRITE_ERROR   Physical error writing data.
00245  *          SOTP_FLASH_AREA_TOO_SMALL
00246  *                             Not enough space in Flash area.
00247  */
00248 sotp_result_e sotp_force_garbage_collection(void);
00249 #endif
00250 
00251 /**
00252  * @brief Returns one item of data programmed on Flash, given type.
00253  *        This is the "initless" version of the function, traversing the flash if triggered.
00254  *
00255  * @param [in] type
00256  *               Type of stored item (must be between 0-15).
00257  *
00258  * @param [in] buf_len_bytes
00259  *               Length of input buffer in bytes.
00260  *
00261  * @param [in] buf
00262  *               Buffer to store data on (must be aligned to a 32 bit boundary).
00263  *
00264  * @param [out] actual_len_bytes.
00265  *               Actual length of returned data
00266  *
00267  * @returns SOTP_SUCCESS           Value was found on Flash.
00268  *          SOTP_NOT_FOUND         Value was not found on Flash.
00269  *          SOTP_READ_ERROR        Physical error reading data.
00270  *          SOTP_DATA_CORRUPT      Data on Flash is corrupt.
00271  *          SOTP_BAD_VALUE         Bad value in any of the parameters.
00272  *          SOTP_BUFF_TOO_SMALL    Not enough memory in user buffer.
00273  *          SOTP_BUFF_NOT_ALIGNED  Buffer not aligned to 32 bits.
00274  */
00275 sotp_result_e sotp_probe(uint32_t type, uint16_t buf_len_bytes, uint32_t *buf, uint16_t *actual_len_bytes);
00276 
00277 
00278 #ifdef __cplusplus
00279 }
00280 #endif
00281 
00282 #endif
00283 
00284