src/main/drivers/flash_impl.h

   1 /*
   2  * This file is part of Cleanflight and Betaflight.
   3  *
   4  * Cleanflight and Betaflight are free software. You can redistribute
   5  * this software and/or modify this software under the terms of the
   6  * GNU General Public License as published by the Free Software
   7  * Foundation, either version 3 of the License, or (at your option)
   8  * any later version.
   9  *
  10  * Cleanflight and Betaflight are distributed in the hope that they
  11  * will be useful, but WITHOUT ANY WARRANTY; without even the implied
  12  * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  13  * See the GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this software.
  17  *
  18  * If not, see <http://www.gnu.org/licenses/>.
  19  */
  20
  21 /*
  22  * Author: jflyper
  23  */
  24
  25 /*
  26  * Each flash chip should:
  27  *
  28  * * expose a public `identify` method.
  29  *   - return true if the driver supports the passed JEDEC ID and false otherwise.
  30  *   - configure the `geometry` member of the flashDevice_t or set all `geometry` members to 0 if driver doesn't support the JEDEC ID.
  31  *   - configure the `vTable` member, with an appropriate API.
  32  *   - configure remaining flashDevice_t members, as appropriate.
  33  * * not reconfigure the bus or flash chip when in memory mapped mode.
  34  *   - the firmware is free to do whatever it wants when memory mapped mode is disabled
  35  *   - when memory mapped mode is restored, e.g. after saving config to external flash, it should be in
  36  *     the same state that firmware found it in before the firmware disabled memory mapped mode.
  37  *
  38  * When memory mapped mode is disabled the following applies to all flash chip drivers uses in a memory mapped system:
  39  *   - do not call any methods or use data from the flash chip.  i.e. memory mapped code/data is INACCESSIBLE.
  40  *     i.e. when saving the config, *ALL* the code to erase a block and write data should be in RAM,
  41  *     this includes any `delay` methods.
  42  *   - not require the use of use any ISRs - interrupts are disabled during flash access when memory mapped mode is disabled.
  43  *
  44  * When compiling a driver for use in a memory mapped flash system the following applies:
  45  *   - the vTable must live in RAM so it can be used when memory mapped mode is disabled.
  46  *   - other constant data structures that usually live in flash memory must be stored in RAM.
  47  *   - methods used to erase sectors, write data and read data much live in RAM.
  48  */
  49 #pragma once
  50
  51 #include "drivers/bus.h"
  52 #include "drivers/dma.h"
  53
  54 struct flashVTable_s;
  55
  56 typedef enum {
  57     FLASHIO_NONE = 0,
  58     FLASHIO_SPI,
  59     FLASHIO_QUADSPI,
  60     FLASHIO_OCTOSPI,
  61 } flashDeviceIoMode_e;
  62
  63 typedef struct flashDeviceIO_s {
  64     union {
  65     #ifdef USE_FLASH_SPI
  66         extDevice_t *dev; // Device interface dependent handle (spi/i2c)
  67     #endif
  68     #ifdef USE_FLASH_QUADSPI
  69         QUADSPI_TypeDef *quadSpi;
  70     #endif
  71     #ifdef USE_FLASH_OCTOSPI
  72         OCTOSPI_TypeDef *octoSpi;
  73     #endif
  74     } handle;
  75     flashDeviceIoMode_e mode;
  76 } flashDeviceIO_t;
  77
  78 typedef struct flashDevice_s {
  79     //
  80     // members to be configured by the flash chip implementation
  81     //
  82
  83     const struct flashVTable_s *vTable;
  84     flashGeometry_t geometry;
  85     uint32_t currentWriteAddress;
  86     bool isLargeFlash;
  87     // Whether we've performed an action that could have made the device busy
  88     // for writes. This allows us to avoid polling for writable status
  89     // when it is definitely ready already.
  90     bool couldBeBusy;
  91     uint32_t timeoutAt;
  92
  93     //
  94     // members configured by the flash detection system, read-only from the flash chip implementation's perspective.
  95     //
  96
  97     flashDeviceIO_t io;
  98     void (*callback)(uint32_t arg);
  99     uint32_t callbackArg;
 100 } flashDevice_t;
 101
 102 typedef struct flashVTable_s {
 103     void (*configure)(flashDevice_t *fdevice, uint32_t configurationFlags);
 104
 105     bool (*isReady)(flashDevice_t *fdevice);
 106     bool (*waitForReady)(flashDevice_t *fdevice);
 107
 108     void (*eraseSector)(flashDevice_t *fdevice, uint32_t address);
 109     void (*eraseCompletely)(flashDevice_t *fdevice);
 110
 111     void (*pageProgramBegin)(flashDevice_t *fdevice, uint32_t address, void (*callback)(uint32_t length));
 112     uint32_t (*pageProgramContinue)(flashDevice_t *fdevice, uint8_t const **buffers, uint32_t *bufferSizes, uint32_t bufferCount);
 113     void (*pageProgramFinish)(flashDevice_t *fdevice);
 114     void (*pageProgram)(flashDevice_t *fdevice, uint32_t address, const uint8_t *data, uint32_t length, void (*callback)(uint32_t length));
 115
 116     void (*flush)(flashDevice_t *fdevice);
 117
 118     int (*readBytes)(flashDevice_t *fdevice, uint32_t address, uint8_t *buffer, uint32_t length);
 119
 120     const flashGeometry_t *(*getGeometry)(flashDevice_t *fdevice);
 121 } flashVTable_t;