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_ */