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