229 lines
7.7 KiB
C
229 lines
7.7 KiB
C
/* Interface to SPI flash */
|
|
/* SPDX-License-Identifier: GPL-2.0-only */
|
|
#ifndef _SPI_FLASH_H_
|
|
#define _SPI_FLASH_H_
|
|
|
|
#include <stdint.h>
|
|
#include <stddef.h>
|
|
#include <spi-generic.h>
|
|
#include <boot/coreboot_tables.h>
|
|
|
|
/* SPI Flash opcodes */
|
|
#define SPI_OPCODE_WREN 0x06
|
|
#define SPI_OPCODE_FAST_READ 0x0b
|
|
|
|
struct spi_flash;
|
|
|
|
/*
|
|
* SPI write protection is enforced by locking the status register.
|
|
* The following modes are known. It depends on the flash chip if the
|
|
* mode is actually supported.
|
|
*
|
|
* PRESERVE : Keep the previous status register lock-down setting (noop)
|
|
* NONE : Status register isn't locked
|
|
* PIN : Status register is locked as long as the ~WP pin is active
|
|
* REBOOT : Status register is locked until power failure
|
|
* PERMANENT: Status register is permanently locked
|
|
*/
|
|
enum spi_flash_status_reg_lockdown {
|
|
SPI_WRITE_PROTECTION_PRESERVE = -1,
|
|
SPI_WRITE_PROTECTION_NONE = 0,
|
|
SPI_WRITE_PROTECTION_PIN,
|
|
SPI_WRITE_PROTECTION_REBOOT,
|
|
SPI_WRITE_PROTECTION_PERMANENT
|
|
};
|
|
|
|
/*
|
|
* Representation of SPI flash operations:
|
|
* read: Flash read operation.
|
|
* write: Flash write operation.
|
|
* erase: Flash erase operation.
|
|
* status: Read flash status register.
|
|
*/
|
|
struct spi_flash_ops {
|
|
int (*read)(const struct spi_flash *flash, u32 offset, size_t len,
|
|
void *buf);
|
|
int (*write)(const struct spi_flash *flash, u32 offset, size_t len,
|
|
const void *buf);
|
|
int (*erase)(const struct spi_flash *flash, u32 offset, size_t len);
|
|
int (*status)(const struct spi_flash *flash, u8 *reg);
|
|
};
|
|
|
|
/* Current code assumes all callbacks are supplied in this object. */
|
|
struct spi_flash_protection_ops {
|
|
/*
|
|
* Returns 1 if the whole region is software write protected.
|
|
* Hardware write protection mechanism aren't accounted.
|
|
* If the write protection could be changed, due to unlocked status
|
|
* register for example, 0 should be returned.
|
|
* Returns 0 on success.
|
|
*/
|
|
int (*get_write)(const struct spi_flash *flash,
|
|
const struct region *region);
|
|
/*
|
|
* Enable the status register write protection, if supported on the
|
|
* requested region, and optionally enable status register lock-down.
|
|
* Returns 0 if the whole region was software write protected.
|
|
* Hardware write protection mechanism aren't accounted.
|
|
* If the status register is locked and the requested configuration
|
|
* doesn't match the selected one, return an error.
|
|
* Only a single region is supported !
|
|
*
|
|
* @return 0 on success
|
|
*/
|
|
int
|
|
(*set_write)(const struct spi_flash *flash,
|
|
const struct region *region,
|
|
const enum spi_flash_status_reg_lockdown mode);
|
|
|
|
};
|
|
|
|
struct spi_flash_part_id;
|
|
|
|
struct spi_flash {
|
|
struct spi_slave spi;
|
|
u8 vendor;
|
|
union {
|
|
u8 raw;
|
|
struct {
|
|
u8 dual_spi : 1;
|
|
u8 _reserved : 7;
|
|
};
|
|
} flags;
|
|
u16 model;
|
|
u32 size;
|
|
u32 sector_size;
|
|
u32 page_size;
|
|
u8 erase_cmd;
|
|
u8 status_cmd;
|
|
u8 pp_cmd; /* Page program command. */
|
|
u8 wren_cmd; /* Write Enable command. */
|
|
const struct spi_flash_ops *ops;
|
|
/* If !NULL all protection callbacks exist. */
|
|
const struct spi_flash_protection_ops *prot_ops;
|
|
const struct spi_flash_part_id *part;
|
|
};
|
|
|
|
void lb_spi_flash(struct lb_header *header);
|
|
|
|
/* SPI Flash Driver Public API */
|
|
|
|
/*
|
|
* Probe for SPI flash chip on given SPI bus and chip select and fill info in
|
|
* spi_flash structure.
|
|
*
|
|
* Params:
|
|
* bus = SPI Bus # for the flash chip
|
|
* cs = Chip select # for the flash chip
|
|
* flash = Pointer to spi flash structure that needs to be filled
|
|
*
|
|
* Return value:
|
|
* 0 = success
|
|
* non-zero = error
|
|
*/
|
|
int spi_flash_probe(unsigned int bus, unsigned int cs, struct spi_flash *flash);
|
|
|
|
/*
|
|
* Generic probing for SPI flash chip based on the different flashes provided.
|
|
*
|
|
* Params:
|
|
* spi = Pointer to spi_slave structure
|
|
* flash = Pointer to spi_flash structure that needs to be filled.
|
|
*
|
|
* Return value:
|
|
* 0 = success
|
|
* non-zero = error
|
|
*/
|
|
int spi_flash_generic_probe(const struct spi_slave *slave,
|
|
struct spi_flash *flash);
|
|
|
|
/* All the following functions return 0 on success and non-zero on error. */
|
|
int spi_flash_read(const struct spi_flash *flash, u32 offset, size_t len,
|
|
void *buf);
|
|
int spi_flash_write(const struct spi_flash *flash, u32 offset, size_t len,
|
|
const void *buf);
|
|
int spi_flash_erase(const struct spi_flash *flash, u32 offset, size_t len);
|
|
int spi_flash_status(const struct spi_flash *flash, u8 *reg);
|
|
|
|
/*
|
|
* Return the vendor dependent SPI flash write protection state.
|
|
* @param flash : A SPI flash device
|
|
* @param region: A subregion of the device's region
|
|
*
|
|
* Returns:
|
|
* -1 on error
|
|
* 0 if the device doesn't support block protection
|
|
* 0 if the device doesn't enable block protection
|
|
* 0 if given range isn't covered by block protection
|
|
* 1 if given range is covered by block protection
|
|
*/
|
|
int spi_flash_is_write_protected(const struct spi_flash *flash,
|
|
const struct region *region);
|
|
/*
|
|
* Enable the vendor dependent SPI flash write protection. The region not
|
|
* covered by write-protection will be set to write-able state.
|
|
* Only a single write-protected region is supported.
|
|
* Some flash ICs require the region to be aligned in the block size, sector
|
|
* size or page size.
|
|
* Some flash ICs require the region to start at TOP or BOTTOM.
|
|
*
|
|
* @param flash : A SPI flash device
|
|
* @param region: A subregion of the device's region
|
|
* @param mode: Optional lock-down of status register
|
|
|
|
* @return 0 on success
|
|
*/
|
|
int
|
|
spi_flash_set_write_protected(const struct spi_flash *flash,
|
|
const struct region *region,
|
|
const enum spi_flash_status_reg_lockdown mode);
|
|
|
|
/*
|
|
* Some SPI controllers require exclusive access to SPI flash when volatile
|
|
* operations like erase or write are being performed. In such cases,
|
|
* volatile_group_begin will gain exclusive access to SPI flash if not already
|
|
* acquired and volatile_group_end will end exclusive access if this was the
|
|
* last request in the group. spi_flash_{write,erase} operations call
|
|
* volatile_group_begin at the start of function and volatile_group_end after
|
|
* erase/write operation is performed. These functions can also be used by any
|
|
* components that wish to club multiple volatile operations into a single
|
|
* group.
|
|
*/
|
|
int spi_flash_volatile_group_begin(const struct spi_flash *flash);
|
|
int spi_flash_volatile_group_end(const struct spi_flash *flash);
|
|
|
|
/*
|
|
* These are callbacks for marking the start and end of volatile group as
|
|
* handled by the chipset. Not every chipset requires this special handling. So,
|
|
* these functions are expected to be implemented in Kconfig option for volatile
|
|
* group is enabled (SPI_FLASH_HAS_VOLATILE_GROUP).
|
|
*/
|
|
int chipset_volatile_group_begin(const struct spi_flash *flash);
|
|
int chipset_volatile_group_end(const struct spi_flash *flash);
|
|
|
|
/* Return spi_flash object reference for the boot device. This is only valid
|
|
* if CONFIG(BOOT_DEVICE_SPI_FLASH) is enabled. */
|
|
const struct spi_flash *boot_device_spi_flash(void);
|
|
|
|
/* Protect a region of spi flash using its controller, if available. Returns
|
|
* < 0 on error, else 0 on success. */
|
|
int spi_flash_ctrlr_protect_region(const struct spi_flash *flash,
|
|
const struct region *region,
|
|
const enum ctrlr_prot_type type);
|
|
|
|
/*
|
|
* This function is provided to support spi flash command-response transactions.
|
|
* Only 2 vectors are supported and the 'func' is called with appropriate
|
|
* write and read buffers together. This can be used for chipsets that
|
|
* have specific spi flash controllers that don't conform to the normal
|
|
* spi xfer API because they are specialized controllers and not generic.
|
|
*
|
|
* Returns 0 on success and non-zero on failure.
|
|
*/
|
|
int spi_flash_vector_helper(const struct spi_slave *slave,
|
|
struct spi_op vectors[], size_t count,
|
|
int (*func)(const struct spi_slave *slave, const void *dout,
|
|
size_t bytesout, void *din, size_t bytesin));
|
|
|
|
#endif /* _SPI_FLASH_H_ */
|