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