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_ */ 249