pal_internalFlash.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2019 ARM Ltd.
00003 //
00004 // SPDX-License-Identifier: Apache-2.0
00005 //
00006 // Licensed under the Apache License, Version 2.0 (the "License");
00007 // you may not use this file except in compliance with the License.
00008 // You may obtain a copy of the License at
00009 //
00010 //     http://www.apache.org/licenses/LICENSE-2.0
00011 //
00012 // Unless required by applicable law or agreed to in writing, software
00013 // distributed under the License is distributed on an "AS IS" BASIS,
00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015 // See the License for the specific language governing permissions and
00016 // limitations under the License.
00017 // ----------------------------------------------------------------------------
00018 
00019 #ifndef PAL_FLASH_H
00020 #define PAL_FLASH_H
00021 
00022 #ifdef __cplusplus
00023 extern "C" {
00024 #endif
00025 
00026 
00027 #ifndef _PAL_H
00028     #error "Please do not include this file directly, use pal.h instead"
00029 #endif
00030 
00031 
00032 
00033 #define PAL_INT_FLASH_BLANK_VAL 0xFF
00034 
00035 
00036 /*! \brief This function initializes the flash API module, and must be called prior to any flash API calls.
00037  *
00038  * \return   PAL_SUCCESS upon successful operation.
00039  * \return   PAL_FILE_SYSTEM_ERROR - see error code \c palError_t.
00040  *
00041  * \note Should be called only once unless \c pal_internalFlashDeInit function is called.
00042  * \note This function is \e blocking till completion.
00043  *
00044  */
00045 palStatus_t pal_internalFlashInit(void);
00046 
00047 /*! \brief This function deinitializes the flash API module.
00048  *
00049  * \return PAL_SUCCESS upon successful operation. \n
00050  * \return PAL_ERR_INTERNAL_FLASH_ERROR - see error code \c palError_t.
00051  *
00052  * \note Should be called only after \c pal_internalFlashInit() is called.
00053  * \note Flash APIs will not work after calling this function.
00054  * \note This function is \e blocking till completion.
00055  *
00056  */
00057 palStatus_t pal_internalFlashDeInit(void);
00058 
00059 /*! \brief This function writes to the internal flash
00060 *
00061 * @param[in]    buffer - pointer to the buffer to be written
00062 * @param[in]    size - the size of the buffer in bytes.
00063 * @param[in]    address - the address of the internal flash. Must be aligned to minimum writing unit (page size).
00064 *
00065 * \return PAL_SUCCESS upon successful operation.
00066 * \return PAL_ERR_INTERNAL_FLASH_ERROR - see error code \c palError_t.
00067 *
00068 * \note Every address can be written to, including boot loader, program and other components.
00069 * \note This function is \e blocking till completion.
00070 * \note This function is thread safe.
00071 */
00072 palStatus_t pal_internalFlashWrite(const size_t size, const uint32_t address, const uint32_t * buffer);
00073 
00074 /*! \brief This function copies the memory data into the user-given buffer
00075 *
00076 * @param[in]    size - the size of the buffer in bytes.
00077 * @param[in]    address - the address of the internal flash.
00078 * @param[out]   buffer - pointer to the buffer to write to
00079 *
00080 * \return PAL_SUCCESS upon successful operation.
00081 * \return PAL_ERR_INTERNAL_FLASH_ERROR - see error code \c palError_t.
00082 *
00083 * \note This function is \e blocking till completion.
00084 * \note This function is thread safe.
00085 *
00086 */
00087 palStatus_t pal_internalFlashRead(const size_t size, const uint32_t address, uint32_t * buffer);
00088 
00089 /*! \brief This function Erase the sector
00090 *
00091 * @param[in]    size - the size to be erased
00092 * @param[in]    address - sector start address to be erased, must be align to sector.
00093 *
00094 * \return PAL_SUCCESS upon successful operation. \n
00095 * \return PAL_ERR_INTERNAL_FLASH_ERROR - see error code \c palError_t.
00096 *
00097 * \note Any sector can be erased. There is no protection given to bootloader, program or other component.
00098 * \note This function is \e blocking till completion.
00099 * \note Only one sector can be erased in each function call.
00100 * \note This function is thread safe.
00101 */
00102 palStatus_t pal_internalFlashErase(uint32_t address, size_t size);
00103 
00104 
00105 /*! \brief This function returns the minimum writing unit to the flash
00106 *
00107 * \return size_t the 2, 4, 8....
00108 */
00109 size_t pal_internalFlashGetPageSize(void);
00110 
00111 
00112 /*! \brief This function returns the sector size for the given address
00113  *
00114 * @param[in] address - the starting address of the sector in question
00115 *
00116 * \return size of the sector, or `0` in case of an error.
00117 */
00118 size_t pal_internalFlashGetSectorSize(uint32_t address);
00119 
00120 
00121 ///////////////////////////////////////////////////////////////
00122 //---------------------SOTP functions------------------------//
00123 ///////////////////////////////////////////////////////////////
00124 
00125 /*! \brief This function return the SOTP section data
00126 *
00127 * @param[in]    section - the section number (either 0 or 1)
00128 * @param[out]   data - the information about the section
00129 *
00130 * \return PAL_SUCCESS upon successful operation.
00131 * \return PAL_ERR_INTERNAL_FLASH_ERROR - see error code \c palError_t.
00132 *
00133 */
00134 palStatus_t pal_internalFlashGetAreaInfo(uint8_t section, palSotpAreaData_t *data);
00135 
00136 #ifdef __cplusplus
00137 }
00138 #endif
00139 #endif //PAL_FLASH_H