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_rpmc_cap {
  99         bool rpmc_available;
 100         bool poll_op2_ext_stat;
 101         unsigned int number_of_counters;
 102         uint8_t op1_write_cmd;
 103         uint8_t op2_read_cmd;
 104 };
 105
 106 struct spi_flash {
 107         struct spi_slave spi;
 108         u8 vendor;
 109         union {
 110                 u8 raw;
 111                 struct {
 112                         u8 dual_output  : 1;
 113                         u8 dual_io      : 1;
 114                         u8 _reserved    : 6;
 115                 };
 116         } flags;
 117         u16 model;
 118         u32 size;
 119         u32 sector_size;
 120         u32 page_size;
 121         u8 erase_cmd;
 122         u8 status_cmd;
 123         u8 pp_cmd; /* Page program command. */
 124         u8 wren_cmd; /* Write Enable command. */
 125         const struct spi_flash_ops *ops;
 126         /* If !NULL all protection callbacks exist. */
 127         const struct spi_flash_protection_ops *prot_ops;
 128         const struct spi_flash_part_id *part;
 129         struct spi_flash_rpmc_cap rpmc_caps;
 130 };
 131
 132 void lb_spi_flash(struct lb_header *header);
 133
 134 /* SPI Flash Driver Public API */
 135
 136 /*
 137  * Probe for SPI flash chip on given SPI bus and chip select and fill info in
 138  * spi_flash structure.
 139  *
 140  * Params:
 141  * bus   = SPI Bus # for the flash chip
 142  * cs    = Chip select # for the flash chip
 143  * flash = Pointer to spi flash structure that needs to be filled
 144  *
 145  * Return value:
 146  * 0 = success
 147  * non-zero = error
 148  */
 149 int spi_flash_probe(unsigned int bus, unsigned int cs, struct spi_flash *flash);
 150
 151 /*
 152  * Generic probing for SPI flash chip based on the different flashes provided.
 153  *
 154  * Params:
 155  * spi   = Pointer to spi_slave structure
 156  * flash = Pointer to spi_flash structure that needs to be filled.
 157  *
 158  * Return value:
 159  * 0        = success
 160  * non-zero = error
 161  */
 162 int spi_flash_generic_probe(const struct spi_slave *slave,
 163                                 struct spi_flash *flash);
 164
 165 /* All the following functions return 0 on success and non-zero on error. */
 166 int spi_flash_read(const struct spi_flash *flash, u32 offset, size_t len,
 167                    void *buf);
 168 int spi_flash_write(const struct spi_flash *flash, u32 offset, size_t len,
 169                     const void *buf);
 170 int spi_flash_erase(const struct spi_flash *flash, u32 offset, size_t len);
 171 int spi_flash_status(const struct spi_flash *flash, u8 *reg);
 172
 173 /*
 174  * Return the vendor dependent SPI flash write protection state.
 175  * @param flash : A SPI flash device
 176  * @param region: A subregion of the device's region
 177  *
 178  * Returns:
 179  *  -1   on error
 180  *   0   if the device doesn't support block protection
 181  *   0   if the device doesn't enable block protection
 182  *   0   if given range isn't covered by block protection
 183  *   1   if given range is covered by block protection
 184  */
 185 int spi_flash_is_write_protected(const struct spi_flash *flash,
 186                                  const struct region *region);
 187 /*
 188  * Enable the vendor dependent SPI flash write protection. The region not
 189  * covered by write-protection will be set to write-able state.
 190  * Only a single write-protected region is supported.
 191  * Some flash ICs require the region to be aligned in the block size, sector
 192  * size or page size.
 193  * Some flash ICs require the region to start at TOP or BOTTOM.
 194  *
 195  * @param flash : A SPI flash device
 196  * @param region: A subregion of the device's region
 197  * @param mode: Optional lock-down of status register
 198
 199  * @return 0 on success
 200  */
 201 int
 202 spi_flash_set_write_protected(const struct spi_flash *flash,
 203                               const struct region *region,
 204                               const enum spi_flash_status_reg_lockdown mode);
 205
 206 /*
 207  * Some SPI controllers require exclusive access to SPI flash when volatile
 208  * operations like erase or write are being performed. In such cases,
 209  * volatile_group_begin will gain exclusive access to SPI flash if not already
 210  * acquired and volatile_group_end will end exclusive access if this was the
 211  * last request in the group. spi_flash_{write,erase} operations call
 212  * volatile_group_begin at the start of function and volatile_group_end after
 213  * erase/write operation is performed. These functions can also be used by any
 214  * components that wish to club multiple volatile operations into a single
 215  * group.
 216  */
 217 int spi_flash_volatile_group_begin(const struct spi_flash *flash);
 218 int spi_flash_volatile_group_end(const struct spi_flash *flash);
 219
 220 /*
 221  * These are callbacks for marking the start and end of volatile group as
 222  * handled by the chipset. Not every chipset requires this special handling. So,
 223  * these functions are expected to be implemented in Kconfig option for volatile
 224  * group is enabled (SPI_FLASH_HAS_VOLATILE_GROUP).
 225  */
 226 int chipset_volatile_group_begin(const struct spi_flash *flash);
 227 int chipset_volatile_group_end(const struct spi_flash *flash);
 228
 229 /* Return spi_flash object reference for the boot device. This is only valid
 230  * if CONFIG(BOOT_DEVICE_SPI_FLASH) is enabled. */
 231 const struct spi_flash *boot_device_spi_flash(void);
 232
 233 /* Protect a region of spi flash using its controller, if available. Returns
 234  * < 0 on error, else 0 on success. */
 235 int spi_flash_ctrlr_protect_region(const struct spi_flash *flash,
 236                                    const struct region *region,
 237                                    const enum ctrlr_prot_type type);
 238
 239 /*
 240  * This function is provided to support spi flash command-response transactions.
 241  * Only 2 vectors are supported and the 'func' is called with appropriate
 242  * write and read buffers together. This can be used for chipsets that
 243  * have specific spi flash controllers that don't conform to the normal
 244  * spi xfer API because they are specialized controllers and not generic.
 245  *
 246  * Returns 0 on success and non-zero on failure.
 247  */
 248 int spi_flash_vector_helper(const struct spi_slave *slave,
 249         struct spi_op vectors[], size_t count,
 250         int (*func)(const struct spi_slave *slave, const void *dout,
 251                     size_t bytesout, void *din, size_t bytesin));
 252
 253 /*
 254  * Fill in the memory mapped windows used by the SPI flash device. This is useful for payloads
 255  * to identify SPI flash to host space mapping.
 256  *
 257  * Returns number of windows added to the table.
 258  */
 259 uint32_t spi_flash_get_mmap_windows(struct flash_mmap_window *table);
 260
 261 /* Print the SFDP headers read from the SPI flash */
 262 void spi_flash_print_sfdp_headers(const struct spi_flash *flash);
 263
 264 #endif /* _SPI_FLASH_H_ */