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