src/include/spi_flash.h

   1 /*
   2  * Interface to SPI flash
   3  *
   4  * Copyright (C) 2008 Atmel Corporation
   5  *
   6  * This program is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU General Public License
   8  * version 2 as published by the Free Software Foundation.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  */
  15 #ifndef _SPI_FLASH_H_
  16 #define _SPI_FLASH_H_
  17
  18 #include <stdint.h>
  19 #include <stddef.h>
  20 #include <spi-generic.h>
  21 #include <boot/coreboot_tables.h>
  22
  23 /* SPI Flash opcodes */
  24 #define SPI_OPCODE_WREN 0x06
  25 #define SPI_OPCODE_FAST_READ 0x0b
  26
  27 struct spi_flash;
  28
  29 /*
  30  * Representation of SPI flash operations:
  31  * read:        Flash read operation.
  32  * write:       Flash write operation.
  33  * erase:       Flash erase operation.
  34  * status:      Read flash status register.
  35  */
  36 struct spi_flash_ops {
  37         int (*read)(const struct spi_flash *flash, u32 offset, size_t len,
  38                         void *buf);
  39         int (*write)(const struct spi_flash *flash, u32 offset, size_t len,
  40                         const void *buf);
  41         int (*erase)(const struct spi_flash *flash, u32 offset, size_t len);
  42         int (*status)(const struct spi_flash *flash, u8 *reg);
  43         /*
  44          * Returns 1 if the whole region is software write protected.
  45          * Hardware write protection mechanism aren't accounted.
  46          * If the write protection could be changed, due to unlocked status
  47          * register for example, 0 should be returned.
  48          * Returns -1 on error.
  49          */
  50         int (*get_write_protection)(const struct spi_flash *flash,
  51                                     const struct region *region);
  52
  53 };
  54
  55 struct spi_flash {
  56         struct spi_slave spi;
  57         const char *name;
  58         u32 size;
  59         u32 sector_size;
  60         u32 page_size;
  61         u8 erase_cmd;
  62         u8 status_cmd;
  63         const struct spi_flash_ops *ops;
  64         const void *driver_private;
  65 };
  66
  67 void lb_spi_flash(struct lb_header *header);
  68
  69 /* SPI Flash Driver Public API */
  70
  71 /*
  72  * Probe for SPI flash chip on given SPI bus and chip select and fill info in
  73  * spi_flash structure.
  74  *
  75  * Params:
  76  * bus   = SPI Bus # for the flash chip
  77  * cs    = Chip select # for the flash chip
  78  * flash = Pointer to spi flash structure that needs to be filled
  79  *
  80  * Return value:
  81  * 0 = success
  82  * non-zero = error
  83  */
  84 int spi_flash_probe(unsigned int bus, unsigned int cs, struct spi_flash *flash);
  85
  86 /*
  87  * Generic probing for SPI flash chip based on the different flashes provided.
  88  *
  89  * Params:
  90  * spi   = Pointer to spi_slave structure
  91  * flash = Pointer to spi_flash structure that needs to be filled.
  92  *
  93  * Return value:
  94  * 0        = success
  95  * non-zero = error
  96  */
  97 int spi_flash_generic_probe(const struct spi_slave *slave,
  98                                 struct spi_flash *flash);
  99
 100 /* All the following functions return 0 on success and non-zero on error. */
 101 int spi_flash_read(const struct spi_flash *flash, u32 offset, size_t len,
 102                    void *buf);
 103 int spi_flash_write(const struct spi_flash *flash, u32 offset, size_t len,
 104                     const void *buf);
 105 int spi_flash_erase(const struct spi_flash *flash, u32 offset, size_t len);
 106 int spi_flash_status(const struct spi_flash *flash, u8 *reg);
 107
 108 /*
 109  * Return the vendor dependent SPI flash write protection state.
 110  * @param flash : A SPI flash device
 111  * @param region: A subregion of the device's region
 112  *
 113  * Returns:
 114  *  -1   on error
 115  *   0   if the device doesn't support block protection
 116  *   0   if the device doesn't enable block protection
 117  *   0   if given range isn't covered by block protection
 118  *   1   if given range is covered by block protection
 119  */
 120 int spi_flash_is_write_protected(const struct spi_flash *flash,
 121                                  const struct region *region);
 122 /*
 123  * Some SPI controllers require exclusive access to SPI flash when volatile
 124  * operations like erase or write are being performed. In such cases,
 125  * volatile_group_begin will gain exclusive access to SPI flash if not already
 126  * acquired and volatile_group_end will end exclusive access if this was the
 127  * last request in the group. spi_flash_{write,erase} operations call
 128  * volatile_group_begin at the start of function and volatile_group_end after
 129  * erase/write operation is performed. These functions can also be used by any
 130  * components that wish to club multiple volatile operations into a single
 131  * group.
 132  */
 133 int spi_flash_volatile_group_begin(const struct spi_flash *flash);
 134 int spi_flash_volatile_group_end(const struct spi_flash *flash);
 135
 136 /*
 137  * These are callbacks for marking the start and end of volatile group as
 138  * handled by the chipset. Not every chipset requires this special handling. So,
 139  * these functions are expected to be implemented in Kconfig option for volatile
 140  * group is enabled (SPI_FLASH_HAS_VOLATILE_GROUP).
 141  */
 142 int chipset_volatile_group_begin(const struct spi_flash *flash);
 143 int chipset_volatile_group_end(const struct spi_flash *flash);
 144
 145 /* Return spi_flash object reference for the boot device. This is only valid
 146  * if CONFIG_BOOT_DEVICE_SPI_FLASH is enabled. */
 147 const struct spi_flash *boot_device_spi_flash(void);
 148
 149 /* Protect a region of spi flash using its controller, if available. Returns
 150  * < 0 on error, else 0 on success. */
 151 int spi_flash_ctrlr_protect_region(const struct spi_flash *flash,
 152                                         const struct region *region);
 153
 154 /*
 155  * This function is provided to support spi flash command-response transactions.
 156  * Only 2 vectors are supported and the 'func' is called with appropriate
 157  * write and read buffers together. This can be used for chipsets that
 158  * have specific spi flash controllers that don't conform to the normal
 159  * spi xfer API because they are specialized controllers and not generic.
 160  *
 161  * Returns 0 on success and non-zero on failure.
 162  */
 163 int spi_flash_vector_helper(const struct spi_slave *slave,
 164         struct spi_op vectors[], size_t count,
 165         int (*func)(const struct spi_slave *slave, const void *dout,
 166                     size_t bytesout, void *din, size_t bytesin));
 167
 168 #endif /* _SPI_FLASH_H_ */