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