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

   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_ */