src/include/spi-generic.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2
   3 #ifndef _SPI_GENERIC_H_
   4 #define _SPI_GENERIC_H_
   5
   6 /* Common parameters -- kind of high, but they should only occur when there
   7  * is a problem (and well your system already is broken), so err on the side
   8  * of caution in case we're dealing with slower SPI buses and/or processors.
   9  */
  10 #define SPI_FLASH_PROG_TIMEOUT_MS               200
  11 #define SPI_FLASH_PAGE_ERASE_TIMEOUT_MS         500
  12
  13 #include <commonlib/region.h>
  14 #include <stdint.h>
  15 #include <stddef.h>
  16
  17 /* SPI vendor IDs */
  18 #define VENDOR_ID_ADESTO                        0x1f
  19 #define VENDOR_ID_AMIC                          0x37
  20 #define VENDOR_ID_ATMEL                         0x1f
  21 #define VENDOR_ID_EON                           0x1c
  22 #define VENDOR_ID_GIGADEVICE                    0xc8
  23 #define VENDOR_ID_MACRONIX                      0xc2
  24 #define VENDOR_ID_SPANSION                      0x01
  25 #define VENDOR_ID_SST                           0xbf
  26 #define VENDOR_ID_STMICRO                       0x20
  27 #define VENDOR_ID_WINBOND                       0xef
  28
  29 /* Controller-specific definitions: */
  30
  31 struct spi_ctrlr;
  32
  33 /*-----------------------------------------------------------------------
  34  * Representation of a SPI slave, i.e. what we're communicating with.
  35  *
  36  *   bus:       ID of the bus that the slave is attached to.
  37  *   cs:        ID of the chip select connected to the slave.
  38  *   ctrlr:     Pointer to SPI controller structure.
  39  */
  40 struct spi_slave {
  41         unsigned int    bus;
  42         unsigned int    cs;
  43         const struct spi_ctrlr *ctrlr;
  44 };
  45
  46 /* Representation of SPI operation status. */
  47 enum spi_op_status {
  48         SPI_OP_NOT_EXECUTED = 0,
  49         SPI_OP_SUCCESS = 1,
  50         SPI_OP_FAILURE = 2,
  51 };
  52
  53 /*
  54  * Representation of a SPI operation.
  55  *
  56  * dout:        Pointer to data to send.
  57  * bytesout:    Count of data in bytes to send.
  58  * din: Pointer to store received data.
  59  * bytesin:     Count of data in bytes to receive.
  60  */
  61 struct spi_op {
  62         const void *dout;
  63         size_t bytesout;
  64         void *din;
  65         size_t bytesin;
  66         enum spi_op_status status;
  67 };
  68
  69 enum spi_clock_phase {
  70         SPI_CLOCK_PHASE_FIRST,
  71         SPI_CLOCK_PHASE_SECOND
  72 };
  73
  74 enum spi_wire_mode {
  75         SPI_4_WIRE_MODE,
  76         SPI_3_WIRE_MODE
  77 };
  78
  79 enum spi_polarity {
  80         SPI_POLARITY_LOW,
  81         SPI_POLARITY_HIGH
  82 };
  83
  84 struct spi_cfg {
  85         /* CLK phase - 0: Phase first, 1: Phase second */
  86         enum spi_clock_phase clk_phase;
  87         /* CLK polarity - 0: Low, 1: High */
  88         enum spi_polarity clk_polarity;
  89         /* CS polarity - 0: Low, 1: High */
  90         enum spi_polarity cs_polarity;
  91         /* Wire mode - 0: 4-wire, 1: 3-wire */
  92         enum spi_wire_mode wire_mode;
  93         /* Data bit length. */
  94         unsigned int data_bit_length;
  95 };
  96
  97 /*
  98  * If there is no limit on the maximum transfer size for the controller,
  99  * max_xfer_size can be set to SPI_CTRLR_DEFAULT_MAX_XFER_SIZE which is equal to
 100  * UINT32_MAX.
 101  */
 102 #define SPI_CTRLR_DEFAULT_MAX_XFER_SIZE (UINT32_MAX)
 103
 104 struct spi_flash;
 105
 106 enum ctrlr_prot_type {
 107         READ_PROTECT = 1,
 108         WRITE_PROTECT = 2,
 109         READ_WRITE_PROTECT = 3,
 110 };
 111
 112 enum {
 113         /* Deduct the command length from the spi_crop_chunk() calculation for
 114            sizing a transaction. If SPI_CNTRLR_DEDUCT_OPCODE_LEN is set, only
 115            the bytes after the command byte will be deducted. */
 116         SPI_CNTRLR_DEDUCT_CMD_LEN = 1 << 0,
 117         /* Remove the opcode size from the command length used in the
 118            spi_crop_chunk() calculation. Controllers which have a dedicated
 119            register for the command byte would set this flag which would
 120            allow the use of the maximum transfer size. */
 121         SPI_CNTRLR_DEDUCT_OPCODE_LEN = 1 << 1,
 122 };
 123
 124 /*-----------------------------------------------------------------------
 125  * Representation of a SPI controller. Note the xfer() and xfer_vector()
 126  * callbacks are meant to process full duplex transactions. If the
 127  * controller cannot handle these transactions then return an error when
 128  * din and dout are both set. See spi_xfer() below for more details.
 129  *
 130  * claim_bus:           Claim SPI bus and prepare for communication.
 131  * release_bus: Release SPI bus.
 132  * setup:               Setup given SPI device bus.
 133  * xfer:                Perform one SPI transfer operation.
 134  * xfer_vector: Vector of SPI transfer operations.
 135  * xfer_dual:           (optional) Perform one SPI transfer in Dual SPI mode.
 136  * max_xfer_size:       Maximum transfer size supported by the controller
 137  *                      (0 = invalid,
 138  *                       SPI_CTRLR_DEFAULT_MAX_XFER_SIZE = unlimited)
 139  * flags:               See SPI_CNTRLR_* enums above.
 140  *
 141  * Following member is provided by specialized SPI controllers that are
 142  * actually SPI flash controllers.
 143  *
 144  * flash_probe: Specialized probe function provided by SPI flash
 145  *                      controllers.
 146  * flash_protect: Protect a region of flash using the SPI flash controller.
 147  */
 148 struct spi_ctrlr {
 149         int (*claim_bus)(const struct spi_slave *slave);
 150         void (*release_bus)(const struct spi_slave *slave);
 151         int (*setup)(const struct spi_slave *slave);
 152         int (*xfer)(const struct spi_slave *slave, const void *dout,
 153                     size_t bytesout, void *din, size_t bytesin);
 154         int (*xfer_vector)(const struct spi_slave *slave,
 155                         struct spi_op vectors[], size_t count);
 156         int (*xfer_dual)(const struct spi_slave *slave, const void *dout,
 157                          size_t bytesout, void *din, size_t bytesin);
 158         uint32_t max_xfer_size;
 159         uint32_t flags;
 160         int (*flash_probe)(const struct spi_slave *slave,
 161                                 struct spi_flash *flash);
 162         int (*flash_protect)(const struct spi_flash *flash,
 163                                 const struct region *region,
 164                                 const enum ctrlr_prot_type type);
 165 };
 166
 167 /*-----------------------------------------------------------------------
 168  * Structure defining mapping of SPI buses to controller.
 169  *
 170  * ctrlr:       Pointer to controller structure managing the given SPI buses.
 171  * bus_start:   Start bus number managed by the controller.
 172  * bus_end:     End bus number manager by the controller.
 173  */
 174 struct spi_ctrlr_buses {
 175         const struct spi_ctrlr *ctrlr;
 176         unsigned int bus_start;
 177         unsigned int bus_end;
 178 };
 179
 180 /* Mapping of SPI buses to controllers - should be defined by platform. */
 181 extern const struct spi_ctrlr_buses spi_ctrlr_bus_map[];
 182 extern const size_t spi_ctrlr_bus_map_count;
 183
 184 /*-----------------------------------------------------------------------
 185  * Initialization, must be called once on start up.
 186  *
 187  */
 188 void spi_init(void);
 189
 190 /*
 191  * Get configuration of SPI bus.
 192  *
 193  * slave:     Pointer to slave structure.
 194  * cfg:       Pointer to SPI configuration that needs to be filled.
 195  *
 196  * Returns:
 197  * 0 on success, -1 on error
 198  */
 199 int spi_get_config(const struct spi_slave *slave, struct spi_cfg *cfg);
 200
 201 /*-----------------------------------------------------------------------
 202  * Set up communications parameters for a SPI slave.
 203  *
 204  * This must be called once for each slave. Note that this function
 205  * usually doesn't touch any actual hardware, it only initializes the
 206  * contents of spi_slave so that the hardware can be easily
 207  * initialized later.
 208  *
 209  *   bus:     Bus ID of the slave chip.
 210  *   cs:      Chip select ID of the slave chip on the specified bus.
 211  *   slave:   Pointer to slave structure that needs to be initialized.
 212  *
 213  * Returns:
 214  * 0 on success, -1 on error
 215  */
 216 int spi_setup_slave(unsigned int bus, unsigned int cs, struct spi_slave *slave);
 217
 218 /*-----------------------------------------------------------------------
 219  * Claim the bus and prepare it for communication with a given slave.
 220  *
 221  * This must be called before doing any transfers with a SPI slave. It
 222  * will enable and initialize any SPI hardware as necessary, and make
 223  * sure that the SCK line is in the correct idle state. It is not
 224  * allowed to claim the same bus for several slaves without releasing
 225  * the bus in between.
 226  *
 227  *   slave:     The SPI slave
 228  *
 229  * Returns: 0 if the bus was claimed successfully, or a negative value
 230  * if it wasn't.
 231  */
 232 int spi_claim_bus(const struct spi_slave *slave);
 233
 234 /*-----------------------------------------------------------------------
 235  * Release the SPI bus
 236  *
 237  * This must be called once for every call to spi_claim_bus() after
 238  * all transfers have finished. It may disable any SPI hardware as
 239  * appropriate.
 240  *
 241  *   slave:     The SPI slave
 242  */
 243 void spi_release_bus(const struct spi_slave *slave);
 244
 245 /*-----------------------------------------------------------------------
 246  * SPI transfer
 247  *
 248  * spi_xfer() interface:
 249  *   slave:     The SPI slave which will be sending/receiving the data.
 250  *   dout:      Pointer to a string of bytes to send out.
 251  *   bytesout:  How many bytes to write.
 252  *   din:       Pointer to a string of bytes that will be filled in.
 253  *   bytesin:   How many bytes to read.
 254  *
 255  * Note that din and dout are transferred simultaneously in a full duplex
 256  * transaction. The number of clocks within one transaction is calculated
 257  * as: MAX(bytesout*8, bytesin*8).
 258  *
 259  *   Returns: 0 on success, not 0 on failure
 260  */
 261 int spi_xfer(const struct spi_slave *slave, const void *dout, size_t bytesout,
 262              void *din, size_t bytesin);
 263
 264 /*-----------------------------------------------------------------------
 265  * Vector of SPI transfer operations
 266  *
 267  * spi_xfer_vector() interface:
 268  *   slave:     The SPI slave which will be sending/receiving the data.
 269  *   vectors:   Array of SPI op structures.
 270  *   count:     Number of SPI op vectors.
 271  *
 272  *   Returns: 0 on success, not 0 on failure
 273  */
 274 int spi_xfer_vector(const struct spi_slave *slave,
 275                 struct spi_op vectors[], size_t count);
 276
 277 /*-----------------------------------------------------------------------
 278  * Given command length and length of remaining data, return the maximum data
 279  * that can be transferred in next spi_xfer.
 280  *
 281  * Returns: 0 on error, non-zero data size that can be xfered on success.
 282  */
 283 unsigned int spi_crop_chunk(const struct spi_slave *slave, unsigned int cmd_len,
 284                         unsigned int buf_len);
 285
 286 /*-----------------------------------------------------------------------
 287  * Write 8 bits, then read 8 bits.
 288  *   slave:     The SPI slave we're communicating with
 289  *   byte:      Byte to be written
 290  *
 291  * Returns: The value that was read, or a negative value on error.
 292  *
 293  * TODO: This function probably shouldn't be inlined.
 294  */
 295 static inline int spi_w8r8(const struct spi_slave *slave, unsigned char byte)
 296 {
 297         unsigned char dout[2];
 298         unsigned char din[2];
 299         int ret;
 300
 301         dout[0] = byte;
 302         dout[1] = 0;
 303
 304         ret = spi_xfer(slave, dout, 2, din, 2);
 305         return ret < 0 ? ret : din[1];
 306 }
 307
 308 #endif  /* _SPI_GENERIC_H_ */