src/include/spi_flash.h

   1 /* Interface to SPI flash */
   2 /* SPDX-License-Identifier: GPL-2.0-only */
   3 #ifndef _SPI_FLASH_H_
   4 #define _SPI_FLASH_H_
   5
   6 #include <stdint.h>
   7 #include <stddef.h>
   8 #include <spi-generic.h>
   9 #include <boot/coreboot_tables.h>
  10
  11 /* SPI Flash opcodes */
  12 #define SPI_OPCODE_WREN 0x06
  13 #define SPI_OPCODE_FAST_READ 0x0b
  14
  15 struct spi_flash;
  16
  17 /*
  18  * SPI write protection is enforced by locking the status register.
  19  * The following modes are known. It depends on the flash chip if the
  20  * mode is actually supported.
  21  *
  22  * PRESERVE : Keep the previous status register lock-down setting (noop)
  23  * NONE     : Status register isn't locked
  24  * PIN      : Status register is locked as long as the ~WP pin is active
  25  * REBOOT   : Status register is locked until power failure
  26  * PERMANENT: Status register is permanently locked
  27  */
  28 enum spi_flash_status_reg_lockdown {
  29         SPI_WRITE_PROTECTION_PRESERVE = -1,
  30         SPI_WRITE_PROTECTION_NONE = 0,
  31         SPI_WRITE_PROTECTION_PIN,
  32         SPI_WRITE_PROTECTION_REBOOT,
  33         SPI_WRITE_PROTECTION_PERMANENT
  34 };
  35
  36 /*
  37  * Representation of SPI flash operations:
  38  * read:        Flash read operation.
  39  * write:       Flash write operation.
  40  * erase:       Flash erase operation.
  41  * status:      Read flash status register.
  42  */
  43 struct spi_flash_ops {
  44         int (*read)(const struct spi_flash *flash, u32 offset, size_t len,
  45                         void *buf);
  46         int (*write)(const struct spi_flash *flash, u32 offset, size_t len,
  47                         const void *buf);
  48         int (*erase)(const struct spi_flash *flash, u32 offset, size_t len);
  49         int (*status)(const struct spi_flash *flash, u8 *reg);
  50 };
  51
  52 /* Current code assumes all callbacks are supplied in this object. */
  53 struct spi_flash_protection_ops {
  54         /*
  55          * Returns 1 if the whole region is software write protected.
  56          * Hardware write protection mechanism aren't accounted.
  57          * If the write protection could be changed, due to unlocked status
  58          * register for example, 0 should be returned.
  59          * Returns 0 on success.
  60          */
  61         int (*get_write)(const struct spi_flash *flash,
  62                                     const struct region *region);
  63         /*
  64          * Enable the status register write protection, if supported on the
  65          * requested region, and optionally enable status register lock-down.
  66          * Returns 0 if the whole region was software write protected.
  67          * Hardware write protection mechanism aren't accounted.
  68          * If the status register is locked and the requested configuration
  69          * doesn't match the selected one, return an error.
  70          * Only a single region is supported !
  71          *
  72          * @return 0 on success
  73          */
  74         int
  75         (*set_write)(const struct spi_flash *flash,
  76                                 const struct region *region,
  77                                 const enum spi_flash_status_reg_lockdown mode);
  78
  79 };
  80
  81 struct spi_flash_part_id;
  82
  83 struct spi_flash {
  84         struct spi_slave spi;
  85         u8 vendor;
  86         union {
  87                 u8 raw;
  88                 struct {
  89                         u8 dual_spi     : 1;
  90                         u8 _reserved    : 7;
  91                 };
  92         } flags;
  93         u16 model;
  94         u32 size;
  95         u32 sector_size;
  96         u32 page_size;
  97         u8 erase_cmd;
  98         u8 status_cmd;
  99         u8 pp_cmd; /* Page program command. */
 100         u8 wren_cmd; /* Write Enable command. */
 101         const struct spi_flash_ops *ops;
 102         /* If !NULL all protection callbacks exist. */
 103         const struct spi_flash_protection_ops *prot_ops;
 104         const struct spi_flash_part_id *part;
 105 };
 106
 107 void lb_spi_flash(struct lb_header *header);
 108
 109 /* SPI Flash Driver Public API */
 110
 111 /*
 112  * Probe for SPI flash chip on given SPI bus and chip select and fill info in
 113  * spi_flash structure.
 114  *
 115  * Params:
 116  * bus   = SPI Bus # for the flash chip
 117  * cs    = Chip select # for the flash chip
 118  * flash = Pointer to spi flash structure that needs to be filled
 119  *
 120  * Return value:
 121  * 0 = success
 122  * non-zero = error
 123  */
 124 int spi_flash_probe(unsigned int bus, unsigned int cs, struct spi_flash *flash);
 125
 126 /*
 127  * Generic probing for SPI flash chip based on the different flashes provided.
 128  *
 129  * Params:
 130  * spi   = Pointer to spi_slave structure
 131  * flash = Pointer to spi_flash structure that needs to be filled.
 132  *
 133  * Return value:
 134  * 0        = success
 135  * non-zero = error
 136  */
 137 int spi_flash_generic_probe(const struct spi_slave *slave,
 138                                 struct spi_flash *flash);
 139
 140 /* All the following functions return 0 on success and non-zero on error. */
 141 int spi_flash_read(const struct spi_flash *flash, u32 offset, size_t len,
 142                    void *buf);
 143 int spi_flash_write(const struct spi_flash *flash, u32 offset, size_t len,
 144                     const void *buf);
 145 int spi_flash_erase(const struct spi_flash *flash, u32 offset, size_t len);
 146 int spi_flash_status(const struct spi_flash *flash, u8 *reg);
 147
 148 /*
 149  * Return the vendor dependent SPI flash write protection state.
 150  * @param flash : A SPI flash device
 151  * @param region: A subregion of the device's region
 152  *
 153  * Returns:
 154  *  -1   on error
 155  *   0   if the device doesn't support block protection
 156  *   0   if the device doesn't enable block protection
 157  *   0   if given range isn't covered by block protection
 158  *   1   if given range is covered by block protection
 159  */
 160 int spi_flash_is_write_protected(const struct spi_flash *flash,
 161                                  const struct region *region);
 162 /*
 163  * Enable the vendor dependent SPI flash write protection. The region not
 164  * covered by write-protection will be set to write-able state.
 165  * Only a single write-protected region is supported.
 166  * Some flash ICs require the region to be aligned in the block size, sector
 167  * size or page size.
 168  * Some flash ICs require the region to start at TOP or BOTTOM.
 169  *
 170  * @param flash : A SPI flash device
 171  * @param region: A subregion of the device's region
 172  * @param mode: Optional lock-down of status register
 173
 174  * @return 0 on success
 175  */
 176 int
 177 spi_flash_set_write_protected(const struct spi_flash *flash,
 178                               const struct region *region,
 179                               const enum spi_flash_status_reg_lockdown mode);
 180
 181 /*
 182  * Some SPI controllers require exclusive access to SPI flash when volatile
 183  * operations like erase or write are being performed. In such cases,
 184  * volatile_group_begin will gain exclusive access to SPI flash if not already
 185  * acquired and volatile_group_end will end exclusive access if this was the
 186  * last request in the group. spi_flash_{write,erase} operations call
 187  * volatile_group_begin at the start of function and volatile_group_end after
 188  * erase/write operation is performed. These functions can also be used by any
 189  * components that wish to club multiple volatile operations into a single
 190  * group.
 191  */
 192 int spi_flash_volatile_group_begin(const struct spi_flash *flash);
 193 int spi_flash_volatile_group_end(const struct spi_flash *flash);
 194
 195 /*
 196  * These are callbacks for marking the start and end of volatile group as
 197  * handled by the chipset. Not every chipset requires this special handling. So,
 198  * these functions are expected to be implemented in Kconfig option for volatile
 199  * group is enabled (SPI_FLASH_HAS_VOLATILE_GROUP).
 200  */
 201 int chipset_volatile_group_begin(const struct spi_flash *flash);
 202 int chipset_volatile_group_end(const struct spi_flash *flash);
 203
 204 /* Return spi_flash object reference for the boot device. This is only valid
 205  * if CONFIG(BOOT_DEVICE_SPI_FLASH) is enabled. */
 206 const struct spi_flash *boot_device_spi_flash(void);
 207
 208 /* Protect a region of spi flash using its controller, if available. Returns
 209  * < 0 on error, else 0 on success. */
 210 int spi_flash_ctrlr_protect_region(const struct spi_flash *flash,
 211                                    const struct region *region,
 212                                    const enum ctrlr_prot_type type);
 213
 214 /*
 215  * This function is provided to support spi flash command-response transactions.
 216  * Only 2 vectors are supported and the 'func' is called with appropriate
 217  * write and read buffers together. This can be used for chipsets that
 218  * have specific spi flash controllers that don't conform to the normal
 219  * spi xfer API because they are specialized controllers and not generic.
 220  *
 221  * Returns 0 on success and non-zero on failure.
 222  */
 223 int spi_flash_vector_helper(const struct spi_slave *slave,
 224         struct spi_op vectors[], size_t count,
 225         int (*func)(const struct spi_slave *slave, const void *dout,
 226                     size_t bytesout, void *din, size_t bytesin));
 227
 228 #endif /* _SPI_FLASH_H_ */