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