begriffs open source - cmsis/blob - CMSIS/Driver/Include/Driver_Flash.h

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