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. */
 115         SPI_CNTRLR_DEDUCT_CMD_LEN = 1 << 0,
 116         /* Remove the opcode size from the command length used in the
 117            spi_crop_chunk() calculation. Controllers which have a dedicated
 118            register for the command byte would set this flag which would
 119            allow the use of the maximum transfer size. */
 120         SPI_CNTRLR_DEDUCT_OPCODE_LEN = 1 << 1,
 121 };
 122
 123 /*-----------------------------------------------------------------------
 124  * Representation of a SPI controller. Note the xfer() and xfer_vector()
 125  * callbacks are meant to process full duplex transactions. If the
 126  * controller cannot handle these transactions then return an error when
 127  * din and dout are both set. See spi_xfer() below for more details.
 128  *
 129  * claim_bus:           Claim SPI bus and prepare for communication.
 130  * release_bus: Release SPI bus.
 131  * setup:               Setup given SPI device bus.
 132  * xfer:                Perform one SPI transfer operation.
 133  * xfer_vector: Vector of SPI transfer operations.
 134  * xfer_dual:           (optional) Perform one SPI transfer in Dual SPI mode.
 135  * max_xfer_size:       Maximum transfer size supported by the controller
 136  *                      (0 = invalid,
 137  *                       SPI_CTRLR_DEFAULT_MAX_XFER_SIZE = unlimited)
 138  * flags:               See SPI_CNTRLR_* enums above.
 139  *
 140  * Following member is provided by specialized SPI controllers that are
 141  * actually SPI flash controllers.
 142  *
 143  * flash_probe: Specialized probe function provided by SPI flash
 144  *                      controllers.
 145  * flash_protect: Protect a region of flash using the SPI flash controller.
 146  */
 147 struct spi_ctrlr {
 148         int (*claim_bus)(const struct spi_slave *slave);
 149         void (*release_bus)(const struct spi_slave *slave);
 150         int (*setup)(const struct spi_slave *slave);
 151         int (*xfer)(const struct spi_slave *slave, const void *dout,
 152                     size_t bytesout, void *din, size_t bytesin);
 153         int (*xfer_vector)(const struct spi_slave *slave,
 154                         struct spi_op vectors[], size_t count);
 155         int (*xfer_dual)(const struct spi_slave *slave, const void *dout,
 156                          size_t bytesout, void *din, size_t bytesin);
 157         uint32_t max_xfer_size;
 158         uint32_t flags;
 159         int (*flash_probe)(const struct spi_slave *slave,
 160                                 struct spi_flash *flash);
 161         int (*flash_protect)(const struct spi_flash *flash,
 162                                 const struct region *region,
 163                                 const enum ctrlr_prot_type type);
 164 };
 165
 166 /*-----------------------------------------------------------------------
 167  * Structure defining mapping of SPI buses to controller.
 168  *
 169  * ctrlr:       Pointer to controller structure managing the given SPI buses.
 170  * bus_start:   Start bus number managed by the controller.
 171  * bus_end:     End bus number manager by the controller.
 172  */
 173 struct spi_ctrlr_buses {
 174         const struct spi_ctrlr *ctrlr;
 175         unsigned int bus_start;
 176         unsigned int bus_end;
 177 };
 178
 179 /* Mapping of SPI buses to controllers - should be defined by platform. */
 180 extern const struct spi_ctrlr_buses spi_ctrlr_bus_map[];
 181 extern const size_t spi_ctrlr_bus_map_count;
 182
 183 /*-----------------------------------------------------------------------
 184  * Initialization, must be called once on start up.
 185  *
 186  */
 187 void spi_init(void);
 188
 189 /*
 190  * Get configuration of SPI bus.
 191  *
 192  * slave:     Pointer to slave structure.
 193  * cfg:       Pointer to SPI configuration that needs to be filled.
 194  *
 195  * Returns:
 196  * 0 on success, -1 on error
 197  */
 198 int spi_get_config(const struct spi_slave *slave, struct spi_cfg *cfg);
 199
 200 /*-----------------------------------------------------------------------
 201  * Set up communications parameters for a SPI slave.
 202  *
 203  * This must be called once for each slave. Note that this function
 204  * usually doesn't touch any actual hardware, it only initializes the
 205  * contents of spi_slave so that the hardware can be easily
 206  * initialized later.
 207  *
 208  *   bus:     Bus ID of the slave chip.
 209  *   cs:      Chip select ID of the slave chip on the specified bus.
 210  *   slave:   Pointer to slave structure that needs to be initialized.
 211  *
 212  * Returns:
 213  * 0 on success, -1 on error
 214  */
 215 int spi_setup_slave(unsigned int bus, unsigned int cs, struct spi_slave *slave);
 216
 217 /*-----------------------------------------------------------------------
 218  * Claim the bus and prepare it for communication with a given slave.
 219  *
 220  * This must be called before doing any transfers with a SPI slave. It
 221  * will enable and initialize any SPI hardware as necessary, and make
 222  * sure that the SCK line is in the correct idle state. It is not
 223  * allowed to claim the same bus for several slaves without releasing
 224  * the bus in between.
 225  *
 226  *   slave:     The SPI slave
 227  *
 228  * Returns: 0 if the bus was claimed successfully, or a negative value
 229  * if it wasn't.
 230  */
 231 int spi_claim_bus(const struct spi_slave *slave);
 232
 233 /*-----------------------------------------------------------------------
 234  * Release the SPI bus
 235  *
 236  * This must be called once for every call to spi_claim_bus() after
 237  * all transfers have finished. It may disable any SPI hardware as
 238  * appropriate.
 239  *
 240  *   slave:     The SPI slave
 241  */
 242 void spi_release_bus(const struct spi_slave *slave);
 243
 244 /*-----------------------------------------------------------------------
 245  * SPI transfer
 246  *
 247  * spi_xfer() interface:
 248  *   slave:     The SPI slave which will be sending/receiving the data.
 249  *   dout:      Pointer to a string of bytes to send out.
 250  *   bytesout:  How many bytes to write.
 251  *   din:       Pointer to a string of bytes that will be filled in.
 252  *   bytesin:   How many bytes to read.
 253  *
 254  * Note that din and dout are transferred simultaneously in a full duplex
 255  * transaction. The number of clocks within one transaction is calculated
 256  * as: MAX(bytesout*8, bytesin*8).
 257  *
 258  *   Returns: 0 on success, not 0 on failure
 259  */
 260 int spi_xfer(const struct spi_slave *slave, const void *dout, size_t bytesout,
 261              void *din, size_t bytesin);
 262
 263 /*-----------------------------------------------------------------------
 264  * Vector of SPI transfer operations
 265  *
 266  * spi_xfer_vector() interface:
 267  *   slave:     The SPI slave which will be sending/receiving the data.
 268  *   vectors:   Array of SPI op structures.
 269  *   count:     Number of SPI op vectors.
 270  *
 271  *   Returns: 0 on success, not 0 on failure
 272  */
 273 int spi_xfer_vector(const struct spi_slave *slave,
 274                 struct spi_op vectors[], size_t count);
 275
 276 /*-----------------------------------------------------------------------
 277  * Given command length and length of remaining data, return the maximum data
 278  * that can be transferred in next spi_xfer.
 279  *
 280  * Returns: 0 on error, non-zero data size that can be xfered on success.
 281  */
 282 unsigned int spi_crop_chunk(const struct spi_slave *slave, unsigned int cmd_len,
 283                         unsigned int buf_len);
 284
 285 /*-----------------------------------------------------------------------
 286  * Write 8 bits, then read 8 bits.
 287  *   slave:     The SPI slave we're communicating with
 288  *   byte:      Byte to be written
 289  *
 290  * Returns: The value that was read, or a negative value on error.
 291  *
 292  * TODO: This function probably shouldn't be inlined.
 293  */
 294 static inline int spi_w8r8(const struct spi_slave *slave, unsigned char byte)
 295 {
 296         unsigned char dout[2];
 297         unsigned char din[2];
 298         int ret;
 299
 300         dout[0] = byte;
 301         dout[1] = 0;
 302
 303         ret = spi_xfer(slave, dout, 2, din, 2);
 304         return ret < 0 ? ret : din[1];
 305 }
 306
 307 #endif  /* _SPI_GENERIC_H_ */