1 /* 2 * Copyright (c) 2013-2020 ARM Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 * 6 * Licensed under the Apache License, Version 2.0 (the License); you may 7 * not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an AS IS BASIS, WITHOUT 14 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 * 18 * $Date: 24. January 2020 19 * $Revision: V2.3 20 * 21 * Project: Flash Driver definitions 22 */ 23 24 /* History: 25 * Version 2.3 26 * Removed volatile from ARM_FLASH_STATUS 27 * Version 2.2 28 * Padding bytes added to ARM_FLASH_INFO 29 * Version 2.1 30 * ARM_FLASH_STATUS made volatile 31 * Version 2.0 32 * Renamed driver NOR -> Flash (more generic) 33 * Non-blocking operation 34 * Added Events, Status and Capabilities 35 * Linked Flash information (GetInfo) 36 * Version 1.11 37 * Changed prefix ARM_DRV -> ARM_DRIVER 38 * Version 1.10 39 * Namespace prefix ARM_ added 40 * Version 1.00 41 * Initial release 42 */ 43 44 #ifndef DRIVER_FLASH_H_ 45 #define DRIVER_FLASH_H_ 46 47 #ifdef __cplusplus 48 extern "C" 49 { 50 #endif 51 52 #include "Driver_Common.h" 53 54 #define ARM_FLASH_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,3) /* API version */ 55 56 57 #define _ARM_Driver_Flash_(n) Driver_Flash##n 58 #define ARM_Driver_Flash_(n) _ARM_Driver_Flash_(n) 59 60 61 #define ARM_FLASH_SECTOR_INFO(addr,size) { (addr), (addr)+(size)-1 } 62 63 /** 64 \brief Flash Sector information 65 */ 66 typedef struct _ARM_FLASH_SECTOR { 67 uint32_t start; ///< Sector Start address 68 uint32_t end; ///< Sector End address (start+size-1) 69 } const ARM_FLASH_SECTOR; 70 71 /** 72 \brief Flash information 73 */ 74 typedef struct _ARM_FLASH_INFO { 75 ARM_FLASH_SECTOR *sector_info; ///< Sector layout information (NULL=Uniform sectors) 76 uint32_t sector_count; ///< Number of sectors 77 uint32_t sector_size; ///< Uniform sector size in bytes (0=sector_info used) 78 uint32_t page_size; ///< Optimal programming page size in bytes 79 uint32_t program_unit; ///< Smallest programmable unit in bytes 80 uint8_t erased_value; ///< Contents of erased memory (usually 0xFF) 81 uint8_t reserved[3]; ///< Reserved (must be zero) 82 } const ARM_FLASH_INFO; 83 84 85 /** 86 \brief Flash Status 87 */ 88 typedef struct _ARM_FLASH_STATUS { 89 uint32_t busy : 1; ///< Flash busy flag 90 uint32_t error : 1; ///< Read/Program/Erase error flag (cleared on start of next operation) 91 uint32_t reserved : 30; 92 } ARM_FLASH_STATUS; 93 94 95 /****** Flash Event *****/ 96 #define ARM_FLASH_EVENT_READY (1UL << 0) ///< Flash Ready 97 #define ARM_FLASH_EVENT_ERROR (1UL << 1) ///< Read/Program/Erase Error 98 99 100 // Function documentation 101 /** 102 \fn ARM_DRIVER_VERSION ARM_Flash_GetVersion (void) 103 \brief Get driver version. 104 \return \ref ARM_DRIVER_VERSION 105 */ 106 /** 107 \fn ARM_FLASH_CAPABILITIES ARM_Flash_GetCapabilities (void) 108 \brief Get driver capabilities. 109 \return \ref ARM_FLASH_CAPABILITIES 110 */ 111 /** 112 \fn int32_t ARM_Flash_Initialize (ARM_Flash_SignalEvent_t cb_event) 113 \brief Initialize the Flash Interface. 114 \param[in] cb_event Pointer to \ref ARM_Flash_SignalEvent 115 \return \ref execution_status 116 */ 117 /** 118 \fn int32_t ARM_Flash_Uninitialize (void) 119 \brief De-initialize the Flash Interface. 120 \return \ref execution_status 121 */ 122 /** 123 \fn int32_t ARM_Flash_PowerControl (ARM_POWER_STATE state) 124 \brief Control the Flash interface power. 125 \param[in] state Power state 126 \return \ref execution_status 127 */ 128 /** 129 \fn int32_t ARM_Flash_ReadData (uint32_t addr, void *data, uint32_t cnt) 130 \brief Read data from Flash. 131 \param[in] addr Data address. 132 \param[out] data Pointer to a buffer storing the data read from Flash. 133 \param[in] cnt Number of data items to read. 134 \return number of data items read or \ref execution_status 135 */ 136 /** 137 \fn int32_t ARM_Flash_ProgramData (uint32_t addr, const void *data, uint32_t cnt) 138 \brief Program data to Flash. 139 \param[in] addr Data address. 140 \param[in] data Pointer to a buffer containing the data to be programmed to Flash. 141 \param[in] cnt Number of data items to program. 142 \return number of data items programmed or \ref execution_status 143 */ 144 /** 145 \fn int32_t ARM_Flash_EraseSector (uint32_t addr) 146 \brief Erase Flash Sector. 147 \param[in] addr Sector address 148 \return \ref execution_status 149 */ 150 /** 151 \fn int32_t ARM_Flash_EraseChip (void) 152 \brief Erase complete Flash. 153 Optional function for faster full chip erase. 154 \return \ref execution_status 155 */ 156 /** 157 \fn ARM_FLASH_STATUS ARM_Flash_GetStatus (void) 158 \brief Get Flash status. 159 \return Flash status \ref ARM_FLASH_STATUS 160 */ 161 /** 162 \fn ARM_FLASH_INFO * ARM_Flash_GetInfo (void) 163 \brief Get Flash information. 164 \return Pointer to Flash information \ref ARM_FLASH_INFO 165 */ 166 167 /** 168 \fn void ARM_Flash_SignalEvent (uint32_t event) 169 \brief Signal Flash event. 170 \param[in] event Event notification mask 171 \return none 172 */ 173 174 typedef void (*ARM_Flash_SignalEvent_t) (uint32_t event); ///< Pointer to \ref ARM_Flash_SignalEvent : Signal Flash Event. 175 176 177 /** 178 \brief Flash Driver Capabilities. 179 */ 180 typedef struct _ARM_FLASH_CAPABILITIES { 181 uint32_t event_ready : 1; ///< Signal Flash Ready event 182 uint32_t data_width : 2; ///< Data width: 0=8-bit, 1=16-bit, 2=32-bit 183 uint32_t erase_chip : 1; ///< Supports EraseChip operation 184 uint32_t reserved : 28; ///< Reserved (must be zero) 185 } ARM_FLASH_CAPABILITIES; 186 187 188 /** 189 \brief Access structure of the Flash Driver 190 */ 191 typedef struct _ARM_DRIVER_FLASH { 192 ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_Flash_GetVersion : Get driver version. 193 ARM_FLASH_CAPABILITIES (*GetCapabilities)(void); ///< Pointer to \ref ARM_Flash_GetCapabilities : Get driver capabilities. 194 int32_t (*Initialize) (ARM_Flash_SignalEvent_t cb_event); ///< Pointer to \ref ARM_Flash_Initialize : Initialize Flash Interface. 195 int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_Flash_Uninitialize : De-initialize Flash Interface. 196 int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_Flash_PowerControl : Control Flash Interface Power. 197 int32_t (*ReadData) (uint32_t addr, void *data, uint32_t cnt); ///< Pointer to \ref ARM_Flash_ReadData : Read data from Flash. 198 int32_t (*ProgramData) (uint32_t addr, const void *data, uint32_t cnt); ///< Pointer to \ref ARM_Flash_ProgramData : Program data to Flash. 199 int32_t (*EraseSector) (uint32_t addr); ///< Pointer to \ref ARM_Flash_EraseSector : Erase Flash Sector. 200 int32_t (*EraseChip) (void); ///< Pointer to \ref ARM_Flash_EraseChip : Erase complete Flash. 201 ARM_FLASH_STATUS (*GetStatus) (void); ///< Pointer to \ref ARM_Flash_GetStatus : Get Flash status. 202 ARM_FLASH_INFO * (*GetInfo) (void); ///< Pointer to \ref ARM_Flash_GetInfo : Get Flash information. 203 } const ARM_DRIVER_FLASH; 204 205 #ifdef __cplusplus 206 } 207 #endif 208 209 #endif /* DRIVER_FLASH_H_ */ 210
