spi_flash.h

Go to the documentation of this file.

/* 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_output  : 1;
                        u8 dual_io      : 1;
                        u8 _reserved    : 6;
                };
        } 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));
 
/*
 * Fill in the memory mapped windows used by the SPI flash device. This is useful for payloads
 * to identify SPI flash to host space mapping.
 *
 * Returns number of windows added to the table.
 */
uint32_t spi_flash_get_mmap_windows(struct flash_mmap_window *table);
 
#endif /* _SPI_FLASH_H_ */