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