begriffs open source - cmsis/blob - CMSIS/DoxyGen/Driver/src/Driver_Flash.c

   1 /* -----------------------------------------------------------------------------
   2  * Copyright (c) 2013-2014 ARM Limited. All rights reserved.
   3  *
   4  * $Date:        2. January 2014
   5  * $Revision:    V2.00
   6  *
   7  * Project:      Flash Driver API
   8  * -------------------------------------------------------------------------- */
   9
  10
  11 /**
  12 \defgroup flash_interface_gr Flash Interface
  13 \brief    Driver API for Flash Device Interface (%Driver_Flash.h)
  14 \details
  15 <a href="http://en.wikipedia.org/wiki/Flash_memory" target="_blank">Flash devices</a> based on NOR memory cells are the
  16 preferred technology for embedded applications requiring a discrete non-volatile memory device. The low read latency
  17 characteristic of these Flash devices allow a direct code execution
  18 (<a href="http://en.wikipedia.org/wiki/Execute_in_place" target="_blank">XIP</a>) and data storage in a single memory
  19 product.
  20
  21 **Flash API**
  22
  23 The \b Flash \b API provides a generic API suitable for Flashes with NOR memory cells independent from the actual interface
  24 to the MCU (memory bus, SPI, ...). <a href="http://en.wikipedia.org/wiki/Flash_memory#Serial_flash" target="_blank">SPI</a>
  25 flashes are typically not named NOR flashes but have usually same flash cell properties.
  26
  27 The following header files define the Application Programming Interface (API) for the Flash interface:
  28   - \b %Driver_Flash.h : Driver API for Flash Device Interface
  29
  30
  31 **Driver Functions**
  32
  33 The driver functions are published in the access struct as explained in \ref DriverFunctions
  34   - \ref ARM_DRIVER_FLASH : access struct for Flash driver functions
  35
  36 @{
  37 */
  38 /*
  39 \todo provide more text for the driver implementation above
  40
  41 A typical setup sequence for the driver is shown below:
  42
  43 <b>Example Code:</b>
  44
  45 \todo example
  46 *******************************************************************************************************************/
  47
  48
  49 /**
  50 \defgroup Flash_events Flash Events
  51 \ingroup flash_interface_gr
  52 \brief The Flash driver generates call back events that are notified via the function \ref ARM_Flash_SignalEvent.
  53 \details
  54 This section provides the event values for the \ref ARM_Flash_SignalEvent callback function.
  55
  56 The following call back notification events are generated:
  57 @{
  58 \def ARM_FLASH_EVENT_READY
  59 \def ARM_FLASH_EVENT_ERROR
  60 @}
  61 */
  62
  63
  64 /**
  65 \struct     ARM_FLASH_SECTOR
  66 \details
  67 Specifies sector start and end address.
  68
  69 <b>Element of</b>:
  70   - \ref ARM_FLASH_INFO structure
  71 *******************************************************************************************************************/
  72
  73 /**
  74 \struct     ARM_FLASH_INFO
  75 \details
  76 Stores the characteristics of a Flash device. This includes sector layout, programming size and a default value for erased memory.
  77 This information can be obtained from the Flash device datasheet and is used by the middleware in order to properly interact with the Flash device.
  78
  79 Sector layout is described by specifying the \em sector_info which points to an array of sector information (start and end address) and by specifying the \em sector_count which defines the number of sectors.
  80 The element \em sector_size is not used in this case and needs to be \em 0.
  81 Flash sectors need not to be aligned continuously. Gaps are allowed in the device memory space in order to reserve sectors for other usage (for example application code).
  82
  83 When the device has uniform sector size than the sector layout can be described by specifying the \em sector_size which defines the size of a single sector and by specifying the \em sector_count which defines the number of sectors.
  84 The element \em sector_info is not used in this case and needs to be \em NULL.
  85
  86 The smallest programmable unit within a sector is specified by the \em program_unit. It defines the granularity for programming data.
  87
  88 Optimal programming page size is specified by the \em page_size and defines the amount of data that should be programmed in one step to achieve maximum programming speed.
  89
  90 Contents of erased memory is specified by the \em erased_value and is typically \em 0xFF. This value can be used before erasing a sector to check if the sector is blank and erase can be skipped.
  91
  92 *******************************************************************************************************************/
  93
  94 /**
  95 \struct     ARM_DRIVER_FLASH
  96 \details
  97 The functions of the Flash driver are accessed by function pointers exposed by this structure. Refer to \ref DriverFunctions for overview information.
  98
  99 Each instance of a Flash interface provides such an access structure.
 100 The instance is identified by a postfix number in the symbol name of the access structure, for example:
 101  - \b Driver_Flash0 is the name of the access struct of the first instance (no. 0).
 102  - \b Driver_Flash1 is the name of the access struct of the second instance (no. 1).
 103
 104 A middleware configuration setting allows connecting the middleware to a specific driver instance \b %Driver_Flash<i>n</i>.
 105 The default is \token{0}, which connects a middleware to the first instance of a driver.
 106 *******************************************************************************************************************/
 107
 108 /**
 109 \struct     ARM_FLASH_CAPABILITIES
 110 \details
 111 A Flash driver can be implemented with different capabilities. The data fields of this struct encode
 112 the capabilities implemented by this driver.
 113
 114 The element \em event_ready indicates that the driver is able to generate the \ref ARM_FLASH_EVENT_READY event. In case that this event is not available it is possible to poll the driver status by calling the \ref ARM_Flash_GetStatus and check the \em busy flag.
 115
 116 The element \em data_width specifies the data access size and also defines the data type (uint8_t, uint16_t or uint32_t) for the \em data parameter in \ref ARM_Flash_ReadData and \ref ARM_Flash_ProgramData functions.
 117
 118 The element \em erase_chip specifies that the \ref ARM_Flash_EraseChip function is supported. Typically full chip erase is much faster than erasing the whole device sector per sector.
 119
 120 <b>Returned by:</b>
 121   - \ref ARM_Flash_GetCapabilities
 122 *******************************************************************************************************************/
 123
 124 /**
 125 \struct     ARM_FLASH_STATUS
 126 \details
 127 Structure with information about the status of the Flash.
 128
 129 The flag \em busy indicates that the driver is busy executing read/program/erase operation.
 130
 131 The flag \em error flag is cleared on start of read/program/erase operation and is set at the end of the current operation in case of error.
 132
 133 <b>Returned by:</b>
 134   - \ref ARM_Flash_GetStatus
 135 *****************************************************************************************************************/
 136
 137 /**
 138 \typedef    ARM_Flash_SignalEvent_t
 139 \details
 140 Provides the typedef for the callback function \ref ARM_Flash_SignalEvent.
 141
 142 <b>Parameter for:</b>
 143   - \ref ARM_Flash_Initialize
 144 *******************************************************************************************************************/
 145
 146
 147 //
 148 // Functions
 149 //
 150
 151 ARM_DRIVER_VERSION ARM_Flash_GetVersion (void)  {
 152   return { 0, 0 };
 153 }
 154 /**
 155 \fn ARM_DRIVER_VERSION ARM_Flash_GetVersion (void)
 156 \details
 157 The function \b ARM_Flash_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
 158  - API version is the version of the CMSIS-Driver specification used to implement this driver.
 159  - Driver version is source code version of the actual driver implementation.
 160
 161 Example:
 162 \code
 163 extern ARM_DRIVER_FLASH Driver_Flash0;
 164 ARM_DRIVER_FLASH *drv_info;
 165
 166 void read_version (void)  {
 167   ARM_DRIVER_VERSION  version;
 168
 169   drv_info = &Driver_Flash0;
 170   version = drv_info->GetVersion ();
 171   if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
 172     // error handling
 173     return;
 174   }
 175 }
 176 \endcode
 177 *******************************************************************************************************************/
 178
 179 ARM_FLASH_CAPABILITIES ARM_Flash_GetCapabilities (void)  {
 180   return { 0 };
 181 }
 182 /**
 183 \fn ARM_FLASH_CAPABILITIES ARM_Flash_GetCapabilities (void)
 184 \details
 185 The function \b ARM_Flash_GetCapabilities returns information about capabilities in this driver implementation.
 186 The data fields of the struct \ref ARM_FLASH_CAPABILITIES encode various capabilities, for example
 187 if a hardware is able to create signal events using the \ref ARM_Flash_SignalEvent callback function.
 188
 189 Example:
 190 \code
 191 extern ARM_DRIVER_FLASH Driver_Flash0;
 192 ARM_DRIVER_FLASH *drv_info;
 193
 194 void read_capabilities (void)  {
 195   ARM_FLASH_CAPABILITIES drv_capabilities;
 196
 197   drv_info = &Driver_Flash0;
 198   drv_capabilities = drv_info->GetCapabilities ();
 199   // interrogate capabilities
 200
 201 }
 202 \endcode
 203 *******************************************************************************************************************/
 204
 205 int32_t ARM_Flash_Initialize (ARM_Flash_SignalEvent_t cb_event)  {
 206   return 0;
 207 }
 208 /**
 209 \fn int32_t ARM_Flash_Initialize (ARM_Flash_SignalEvent_t cb_event)
 210 \details
 211 The function \b ARM_Flash_Initialize initializes the Flash interface.
 212 It is called when the middleware component starts operation.
 213
 214 The function performs the following operations:
 215   - Initializes the resources needed for the Flash interface.
 216   - Registers the \ref ARM_Flash_SignalEvent callback function.
 217
 218 The parameter \em cb_event is a pointer to the \ref ARM_Flash_SignalEvent callback function; use a NULL pointer
 219 when no callback signals are required.
 220
 221 \b Example:
 222  - see \ref flash_interface_gr - Driver Functions
 223
 224 *******************************************************************************************************************/
 225
 226 int32_t ARM_Flash_Uninitialize (void)  {
 227   return 0;
 228 }
 229 /**
 230 \fn int32_t ARM_Flash_Uninitialize (void)
 231 \details
 232 The function \b ARM_Flash_Uninitialize de-initializes the resources of Flash interface.
 233
 234 It is called when the middleware component stops operation and releases the software resources used by the interface.
 235 *******************************************************************************************************************/
 236
 237 int32_t ARM_Flash_PowerControl (ARM_POWER_STATE state)  {
 238   return 0;
 239 }
 240 /**
 241 \fn int32_t ARM_Flash_PowerControl (ARM_POWER_STATE state)
 242 \details
 243 The function \b ARM_Flash_PowerControl operates the power modes of the Flash interface.
 244
 245 The parameter \em state can have the following values:
 246   - \ref ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA. Can be called multiple times.
 247                           If the peripheral is already in this mode, then the function performs no operation and returns with \ref ARM_DRIVER_OK.
 248   - \ref ARM_POWER_LOW : may use power saving. Returns \ref ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
 249   - \ref ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
 250
 251 Refer to \ref CallSequence for more information.
 252 *******************************************************************************************************************/
 253
 254 int32_t ARM_Flash_ReadData (uint32_t addr, void *data, uint32_t cnt)  {
 255   return 0;
 256 }
 257 /**
 258 \fn int32_t ARM_Flash_ReadData (uint32_t addr, void *data, uint32_t cnt)
 259 \details
 260 This function \b ARM_Flash_ReadData reads data from the Flash device.
 261
 262 The parameter \em addr specifies the address from where to read data (needs to be aligned to data type size). \n
 263 The parameter \em data specifies the pointer to a buffer storing the data read.
 264 The data type is \em uint8_t, \em uint16_t or \em uint32_t and is specified by the \em data_width in \ref ARM_FLASH_CAPABILITIES. \n
 265 The parameter \em cnt specifies the number of data items to read.
 266
 267 The function executes in the following ways:
 268  - When the operation is non-blocking (typical for SPI Flash) then the function only starts the operation and returns with zero number of data items read.
 269    When the operation is completed the \ref ARM_FLASH_EVENT_READY event is generated (if supported and reported by \ref ARM_Flash_GetCapabilities).
 270    In case of errors the \ref ARM_FLASH_EVENT_ERROR event is generated at the same time.
 271    Progress of the operation can also be monitored by calling the \ref ARM_Flash_GetStatus function and checking the \em busy flag.
 272  - When the operation is blocking (typical for memory mapped Flash) then the function returns after the data is read and returns the number of data items read.
 273 *******************************************************************************************************************/
 274
 275 int32_t ARM_Flash_ProgramData (uint32_t addr, const void *data, uint32_t cnt)  {
 276   return 0;
 277 }
 278 /**
 279 \fn int32_t ARM_Flash_ProgramData (uint32_t addr, const void *data, uint32_t cnt)
 280 \details
 281 This function \b ARM_Flash_ProgramData programs data to the Flash device.
 282
 283 The parameter \em addr specifies the address to where to program data (needs to be aligned to \em program_unit specified in \ref ARM_FLASH_INFO). \n
 284 The parameter \em data specifies the pointer to a buffer containing data to be programmed.
 285 The data type is \em uint8_t, \em uint16_t or \em uint32_t and is specified by the \em data_width in \ref ARM_FLASH_CAPABILITIES. \n
 286 The parameter \em cnt specifies the number of data items to program (data size needs to be a multiple of \em program_unit).
 287
 288 The function executes in the following ways:
 289  - When the operation is non-blocking (typically) then the function only starts the operation and returns with zero number of data items programmed.
 290    When the operation is completed the \ref ARM_FLASH_EVENT_READY event is generated (if supported and reported by \ref ARM_Flash_GetCapabilities).
 291    In case of errors the \ref ARM_FLASH_EVENT_ERROR event is generated at the same time.
 292    Progress of the operation can also be monitored by calling the \ref ARM_Flash_GetStatus function and checking the \em busy flag.
 293  - When the operation is blocking then the function returns after the data is programmed and returns the number of data items programmed.
 294 *******************************************************************************************************************/
 295
 296 int32_t ARM_Flash_EraseSector (uint32_t addr)  {
 297   return 0;
 298 }
 299 /**
 300 \fn int32_t ARM_Flash_EraseSector (uint32_t addr)
 301 \details
 302 This function \b ARM_Flash_EraseSector erases a flash sector specified by the parameter <i>adr</i> (points to start of the sector).
 303
 304 The function is non-blocking and returns as soon as the driver has started the operation.
 305 When the operation is completed the \ref ARM_FLASH_EVENT_READY event is generated (if supported and reported by \ref ARM_Flash_GetCapabilities).
 306 In case of errors the \ref ARM_FLASH_EVENT_ERROR event is generated at the same time.
 307 Progress of the operation can also be monitored by calling the \ref ARM_Flash_GetStatus function and checking the \em busy flag.
 308 *******************************************************************************************************************/
 309
 310 int32_t ARM_Flash_EraseChip (void)  {
 311   return 0;
 312 }
 313 /**
 314 \fn int32_t ARM_Flash_EraseChip (void)
 315 \details
 316 The optional function \b ARM_Flash_EraseChip erases the complete device.
 317 If the device does not support global erase or only a portion of the Flash memory space is used for storing files,
 318 then the functions returns the error value \ref ARM_DRIVER_ERROR_UNSUPPORTED.
 319 The data field \em eras_chip = \token{1} of the structure \ref ARM_FLASH_CAPABILITIES encodes that \b ARM_Flash_EraseChip is supported.
 320 The field can be verified with the function \ref ARM_Flash_GetCapabilities.
 321
 322 The function is non-blocking and returns as soon as the driver has started the operation.
 323 When the operation is completed, the \ref ARM_FLASH_EVENT_READY event is generated (if supported and reported by \ref ARM_Flash_GetCapabilities).
 324 In case of errors, the \ref ARM_FLASH_EVENT_ERROR event is generated at the same time.
 325 Progress of the operation can also be monitored by calling the \ref ARM_Flash_GetStatus function and checking the \em busy flag.
 326
 327 <b>See also:</b>
 328  - ARM_Flash_SignalEvent
 329 *******************************************************************************************************************/
 330
 331 ARM_FLASH_STATUS ARM_Flash_GetStatus (void)  {
 332   return 0;
 333 }
 334 /**
 335 \fn ARM_FLASH_STATUS ARM_Flash_GetStatus (void)
 336 \details
 337 The function \b ARM_Flash_GetStatus returns the current Flash interface status stored in the structure \ref ARM_FLASH_STATUS.
 338 *******************************************************************************************************************/
 339
 340 ARM_FLASH_INFO * ARM_Flash_GetInfo (void)  {
 341   return NULL;
 342 }
 343 /**
 344 \fn ARM_FLASH_INFO * ARM_Flash_GetInfo (void)
 345 \details
 346 The function \b ARM_Flash_GetInfo returns information about the Flash device.
 347 *******************************************************************************************************************/
 348
 349 void ARM_Flash_SignalEvent (uint32_t event)  {
 350   return 0;
 351 }
 352 /**
 353 \fn void ARM_Flash_SignalEvent (uint32_t event)
 354 \details
 355
 356 The function \b ARM_Flash_SignalEvent is a callback function registered by the function \ref ARM_Flash_Initialize.
 357 The function is called automatically after read/program/erase operation completes.
 358
 359 The parameter \em event indicates one or more events that occurred during driver operation. Each event is coded in a separate bit and
 360 therefore it is possible to signal multiple events in the event call back function.
 361
 362 Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the
 363 data fields of the structure \ref ARM_FLASH_CAPABILITIES, which can be retrieved with the function \ref ARM_Flash_GetCapabilities.
 364
 365 The following events can be generated:
 366
 367 Parameter \em event                 | Bit | Description
 368 :-----------------------------------|:---:|:-----------
 369 \ref ARM_FLASH_EVENT_READY          |  0  | Occurs after read/program/erase operation completes.
 370 \ref ARM_FLASH_EVENT_ERROR          |  1  | Occurs together with \ref ARM_FLASH_EVENT_READY when operation completes with errors.
 371
 372 <b>See also:</b>
 373  - \ref ARM_Flash_EraseChip
 374 *******************************************************************************************************************/
 375
 376 /**
 377 @}
 378 */
 379 // End Flash Interface