1224135Sdim/* SPDX-License-Identifier: GPL-2.0+ */ 2224135Sdim/* 3224135Sdim * Common SPI Interface: Controller-specific definitions 4224135Sdim * 5224135Sdim * (C) Copyright 2001 6224135Sdim * Gerald Van Baren, Custom IDEAS, vanbaren@cideas.com. 7224135Sdim */ 8224135Sdim 9224135Sdim#ifndef _SPI_H_ 10224135Sdim#define _SPI_H_ 11224135Sdim 12224135Sdim#include <linux/bitops.h> 13224135Sdim 14245431Sdim/* SPI mode flags */ 15224135Sdim#define SPI_CPHA BIT(0) /* clock phase (1 = SPI_CLOCK_PHASE_SECOND) */ 16245431Sdim#define SPI_CPOL BIT(1) /* clock polarity (1 = SPI_POLARITY_HIGH) */ 17245431Sdim#define SPI_MODE_0 (0|0) /* (original MicroWire) */ 18224135Sdim#define SPI_MODE_1 (0|SPI_CPHA) 19224135Sdim#define SPI_MODE_2 (SPI_CPOL|0) 20224135Sdim#define SPI_MODE_3 (SPI_CPOL|SPI_CPHA) 21224135Sdim#define SPI_CS_HIGH BIT(2) /* CS active high */ 22224135Sdim#define SPI_LSB_FIRST BIT(3) /* per-word bits-on-wire */ 23224135Sdim#define SPI_3WIRE BIT(4) /* SI/SO signals shared */ 24224135Sdim#define SPI_LOOP BIT(5) /* loopback mode */ 25224135Sdim#define SPI_SLAVE BIT(6) /* slave mode */ 26224135Sdim#define SPI_PREAMBLE BIT(7) /* Skip preamble bytes */ 27224135Sdim#define SPI_TX_BYTE BIT(8) /* transmit with 1 wire byte */ 28224135Sdim#define SPI_TX_DUAL BIT(9) /* transmit with 2 wires */ 29224135Sdim#define SPI_TX_QUAD BIT(10) /* transmit with 4 wires */ 30224135Sdim#define SPI_RX_SLOW BIT(11) /* receive with 1 wire slow */ 31224135Sdim#define SPI_RX_DUAL BIT(12) /* receive with 2 wires */ 32226890Sdim#define SPI_RX_QUAD BIT(13) /* receive with 4 wires */ 33226890Sdim#define SPI_TX_OCTAL BIT(14) /* transmit with 8 wires */ 34224135Sdim#define SPI_RX_OCTAL BIT(15) /* receive with 8 wires */ 35226890Sdim 36224135Sdim/* Header byte that marks the start of the message */ 37224135Sdim#define SPI_PREAMBLE_END_BYTE 0xec 38226890Sdim 39226890Sdim#define SPI_DEFAULT_WORDLEN 8 40226890Sdim 41226890Sdim/** 42224135Sdim * struct dm_spi_bus - SPI bus info 43224135Sdim * 44226890Sdim * This contains information about a SPI bus. To obtain this structure, use 45226890Sdim * dev_get_uclass_priv(bus) where bus is the SPI bus udevice. 46226890Sdim * 47226890Sdim * @max_hz: Maximum speed that the bus can tolerate. 48224135Sdim * @speed: Current bus speed. This is 0 until the bus is first claimed. 49226890Sdim * @mode: Current bus mode. This is 0 until the bus is first claimed. 50224135Sdim * 51226890Sdim * TODO(sjg@chromium.org): Remove this and use max_hz from struct spi_slave. 52224135Sdim */ 53224135Sdimstruct dm_spi_bus { 54224135Sdim uint max_hz; 55226890Sdim uint speed; 56224135Sdim uint mode; 57224135Sdim}; 58224135Sdim 59224135Sdim/** 60224135Sdim * struct dm_spi_plat - platform data for all SPI slaves 61224135Sdim * 62224135Sdim * This describes a SPI slave, a child device of the SPI bus. To obtain this 63226890Sdim * struct from a spi_slave, use dev_get_parent_plat(dev) or 64226890Sdim * dev_get_parent_plat(slave->dev). 65224135Sdim * 66224135Sdim * This data is immutable. Each time the device is probed, @max_hz and @mode 67226890Sdim * will be copied to struct spi_slave. 68224135Sdim * 69226890Sdim * @cs: Chip select number (0..n-1) 70226890Sdim * @max_hz: Maximum bus speed that this slave can tolerate 71226890Sdim * @mode: SPI mode to use for this device (see SPI mode flags) 72224135Sdim */ 73224135Sdimstruct dm_spi_slave_plat { 74224135Sdim unsigned int cs; 75226890Sdim uint max_hz; 76224135Sdim uint mode; 77226890Sdim}; 78224135Sdim 79224135Sdim/** 80224135Sdim * enum spi_clock_phase - indicates the clock phase to use for SPI (CPHA) 81224135Sdim * 82224135Sdim * @SPI_CLOCK_PHASE_FIRST: Data sampled on the first phase 83224135Sdim * @SPI_CLOCK_PHASE_SECOND: Data sampled on the second phase 84224135Sdim */ 85224135Sdimenum spi_clock_phase { 86224135Sdim SPI_CLOCK_PHASE_FIRST, 87224135Sdim SPI_CLOCK_PHASE_SECOND, 88224135Sdim}; 89224135Sdim 90224135Sdim/** 91224135Sdim * enum spi_wire_mode - indicates the number of wires used for SPI 92224135Sdim * 93224135Sdim * @SPI_4_WIRE_MODE: Normal bidirectional mode with MOSI and MISO 94224135Sdim * @SPI_3_WIRE_MODE: Unidirectional version with a single data line SISO 95224135Sdim */ 96224135Sdimenum spi_wire_mode { 97224135Sdim SPI_4_WIRE_MODE, 98226890Sdim SPI_3_WIRE_MODE, 99224135Sdim}; 100235633Sdim 101235633Sdim/** 102226890Sdim * enum spi_polarity - indicates the polarity of the SPI bus (CPOL) 103224135Sdim * 104224135Sdim * @SPI_POLARITY_LOW: Clock is low in idle state 105226890Sdim * @SPI_POLARITY_HIGH: Clock is high in idle state 106226890Sdim */ 107224135Sdimenum spi_polarity { 108224135Sdim SPI_POLARITY_LOW, 109224135Sdim SPI_POLARITY_HIGH, 110224135Sdim}; 111226890Sdim 112224135Sdim/** 113224135Sdim * struct spi_slave - Representation of a SPI slave 114224135Sdim * 115224135Sdim * For driver model this is the per-child data used by the SPI bus. It can 116224135Sdim * be accessed using dev_get_parent_priv() on the slave device. The SPI uclass 117224135Sdim * sets up per_child_auto to sizeof(struct spi_slave), and the 118224135Sdim * driver should not override it. Two platform data fields (max_hz and mode) 119224135Sdim * are copied into this structure to provide an initial value. This allows 120224135Sdim * them to be changed, since we should never change platform data in drivers. 121224135Sdim * 122224135Sdim * If not using driver model, drivers are expected to extend this with 123224135Sdim * controller-specific data. 124224135Sdim * 125224135Sdim * @dev: SPI slave device 126224135Sdim * @max_hz: Maximum speed for this slave 127224135Sdim * @bus: ID of the bus that the slave is attached to. For 128224135Sdim * driver model this is the sequence number of the SPI 129224135Sdim * bus (dev_seq(bus)) so does not need to be stored 130224135Sdim * @cs: ID of the chip select connected to the slave. 131224135Sdim * @mode: SPI mode to use for this slave (see SPI mode flags) 132224135Sdim * @wordlen: Size of SPI word in number of bits 133224135Sdim * @max_read_size: If non-zero, the maximum number of bytes which can 134224135Sdim * be read at once. 135224135Sdim * @max_write_size: If non-zero, the maximum number of bytes which can 136224135Sdim * be written at once. 137224135Sdim * @memory_map: Address of read-only SPI flash access. 138224135Sdim * @flags: Indication of SPI flags. 139224135Sdim */ 140224135Sdimstruct spi_slave { 141224135Sdim#if CONFIG_IS_ENABLED(DM_SPI) 142224135Sdim struct udevice *dev; /* struct spi_slave is dev->parentdata */ 143224135Sdim uint max_hz; 144224135Sdim#else 145235633Sdim unsigned int bus; 146235633Sdim unsigned int cs; 147224135Sdim#endif 148224135Sdim uint mode; 149252723Sdim unsigned int wordlen; 150224135Sdim unsigned int max_read_size; 151252723Sdim unsigned int max_write_size; 152224135Sdim void *memory_map; 153235633Sdim 154235633Sdim u8 flags; 155252723Sdim#define SPI_XFER_BEGIN BIT(0) /* Assert CS before transfer */ 156224135Sdim#define SPI_XFER_END BIT(1) /* Deassert CS after transfer */ 157235633Sdim#define SPI_XFER_ONCE (SPI_XFER_BEGIN | SPI_XFER_END) 158252723Sdim}; 159235633Sdim 160235633Sdim/** 161252723Sdim * spi_do_alloc_slave - Allocate a new SPI slave (internal) 162252723Sdim * 163235633Sdim * Allocate and zero all fields in the spi slave, and set the bus/chip 164235633Sdim * select. Use the helper macro spi_alloc_slave() to call this. 165235633Sdim * 166235633Sdim * @offset: Offset of struct spi_slave within slave structure. 167235633Sdim * @size: Size of slave structure. 168245431Sdim * @bus: Bus ID of the slave chip. 169245431Sdim * @cs: Chip select ID of the slave chip on the specified bus. 170224135Sdim */ 171224135Sdimvoid *spi_do_alloc_slave(int offset, int size, unsigned int bus, 172226890Sdim unsigned int cs); 173224135Sdim 174224135Sdim/** 175224135Sdim * spi_alloc_slave - Allocate a new SPI slave 176224135Sdim * 177224135Sdim * Allocate and zero all fields in the spi slave, and set the bus/chip 178224135Sdim * select. 179224135Sdim * 180224135Sdim * @_struct: Name of structure to allocate (e.g. struct tegra_spi). 181 * This structure must contain a member 'struct spi_slave *slave'. 182 * @bus: Bus ID of the slave chip. 183 * @cs: Chip select ID of the slave chip on the specified bus. 184 */ 185#define spi_alloc_slave(_struct, bus, cs) \ 186 spi_do_alloc_slave(offsetof(_struct, slave), \ 187 sizeof(_struct), bus, cs) 188 189/** 190 * spi_alloc_slave_base - Allocate a new SPI slave with no private data 191 * 192 * Allocate and zero all fields in the spi slave, and set the bus/chip 193 * select. 194 * 195 * @bus: Bus ID of the slave chip. 196 * @cs: Chip select ID of the slave chip on the specified bus. 197 */ 198#define spi_alloc_slave_base(bus, cs) \ 199 spi_do_alloc_slave(0, sizeof(struct spi_slave), bus, cs) 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 * @max_hz: Maximum SCK rate in Hz. 212 * @mode: Clock polarity, clock phase and other parameters. 213 * 214 * Returns: A spi_slave reference that can be used in subsequent SPI 215 * calls, or NULL if one or more of the parameters are not supported. 216 */ 217struct spi_slave *spi_setup_slave(unsigned int bus, unsigned int cs, 218 unsigned int max_hz, unsigned int mode); 219 220/** 221 * Free any memory associated with a SPI slave. 222 * 223 * @slave: The SPI slave 224 */ 225void spi_free_slave(struct spi_slave *slave); 226 227/** 228 * Claim the bus and prepare it for communication with a given slave. 229 * 230 * This must be called before doing any transfers with a SPI slave. It 231 * will enable and initialize any SPI hardware as necessary, and make 232 * sure that the SCK line is in the correct idle state. It is not 233 * allowed to claim the same bus for several slaves without releasing 234 * the bus in between. 235 * 236 * @slave: The SPI slave 237 * 238 * Returns: 0 if the bus was claimed successfully, or a negative value 239 * if it wasn't. 240 */ 241int spi_claim_bus(struct spi_slave *slave); 242 243/** 244 * Release the SPI bus 245 * 246 * This must be called once for every call to spi_claim_bus() after 247 * all transfers have finished. It may disable any SPI hardware as 248 * appropriate. 249 * 250 * @slave: The SPI slave 251 */ 252void spi_release_bus(struct spi_slave *slave); 253 254/** 255 * Set the word length for SPI transactions 256 * 257 * Set the word length (number of bits per word) for SPI transactions. 258 * 259 * @slave: The SPI slave 260 * @wordlen: The number of bits in a word 261 * 262 * Returns: 0 on success, -1 on failure. 263 */ 264int spi_set_wordlen(struct spi_slave *slave, unsigned int wordlen); 265 266/** 267 * SPI transfer (optional if mem_ops is used) 268 * 269 * This writes "bitlen" bits out the SPI MOSI port and simultaneously clocks 270 * "bitlen" bits in the SPI MISO port. That's just the way SPI works. 271 * 272 * The source of the outgoing bits is the "dout" parameter and the 273 * destination of the input bits is the "din" parameter. Note that "dout" 274 * and "din" can point to the same memory location, in which case the 275 * input data overwrites the output data (since both are buffered by 276 * temporary variables, this is OK). 277 * 278 * spi_xfer() interface: 279 * @slave: The SPI slave which will be sending/receiving the data. 280 * @bitlen: How many bits to write and read. 281 * @dout: Pointer to a string of bits to send out. The bits are 282 * held in a byte array and are sent MSB first. 283 * @din: Pointer to a string of bits that will be filled in. 284 * @flags: A bitwise combination of SPI_XFER_* flags. 285 * 286 * Returns: 0 on success, not 0 on failure 287 */ 288int spi_xfer(struct spi_slave *slave, unsigned int bitlen, const void *dout, 289 void *din, unsigned long flags); 290 291/** 292 * spi_write_then_read - SPI synchronous write followed by read 293 * 294 * This performs a half duplex transaction in which the first transaction 295 * is to send the opcode and if the length of buf is non-zero then it start 296 * the second transaction as tx or rx based on the need from respective slave. 297 * 298 * @slave: The SPI slave device with which opcode/data will be exchanged 299 * @opcode: opcode used for specific transfer 300 * @n_opcode: size of opcode, in bytes 301 * @txbuf: buffer into which data to be written 302 * @rxbuf: buffer into which data will be read 303 * @n_buf: size of buf (whether it's [tx|rx]buf), in bytes 304 * 305 * Returns: 0 on success, not 0 on failure 306 */ 307int spi_write_then_read(struct spi_slave *slave, const u8 *opcode, 308 size_t n_opcode, const u8 *txbuf, u8 *rxbuf, 309 size_t n_buf); 310 311/* Copy memory mapped data */ 312void spi_flash_copy_mmap(void *data, void *offset, size_t len); 313 314/** 315 * Determine if a SPI chipselect is valid. 316 * This function is provided by the board if the low-level SPI driver 317 * needs it to determine if a given chipselect is actually valid. 318 * 319 * Returns: 1 if bus:cs identifies a valid chip on this board, 0 320 * otherwise. 321 */ 322int spi_cs_is_valid(unsigned int bus, unsigned int cs); 323 324/* 325 * These names are used in several drivers and these declarations will be 326 * removed soon as part of the SPI DM migration. Drop them if driver model is 327 * enabled for SPI. 328 */ 329#if !CONFIG_IS_ENABLED(DM_SPI) 330/** 331 * Activate a SPI chipselect. 332 * This function is provided by the board code when using a driver 333 * that can't control its chipselects automatically (e.g. 334 * common/soft_spi.c). When called, it should activate the chip select 335 * to the device identified by "slave". 336 */ 337void spi_cs_activate(struct spi_slave *slave); 338 339/** 340 * Deactivate a SPI chipselect. 341 * This function is provided by the board code when using a driver 342 * that can't control its chipselects automatically (e.g. 343 * common/soft_spi.c). When called, it should deactivate the chip 344 * select to the device identified by "slave". 345 */ 346void spi_cs_deactivate(struct spi_slave *slave); 347#endif 348 349/** 350 * Set transfer speed. 351 * This sets a new speed to be applied for next spi_xfer(). 352 * @slave: The SPI slave 353 * @hz: The transfer speed 354 * 355 * Returns: 0 on success, or a negative value on error. 356 */ 357int spi_set_speed(struct spi_slave *slave, uint hz); 358 359/** 360 * Write 8 bits, then read 8 bits. 361 * @slave: The SPI slave we're communicating with 362 * @byte: Byte to be written 363 * 364 * Returns: The value that was read, or a negative value on error. 365 * 366 * TODO: This function probably shouldn't be inlined. 367 */ 368static inline int spi_w8r8(struct spi_slave *slave, unsigned char byte) 369{ 370 unsigned char dout[2]; 371 unsigned char din[2]; 372 int ret; 373 374 dout[0] = byte; 375 dout[1] = 0; 376 377 ret = spi_xfer(slave, 16, dout, din, SPI_XFER_BEGIN | SPI_XFER_END); 378 return ret < 0 ? ret : din[1]; 379} 380 381/** 382 * struct spi_cs_info - Information about a bus chip select 383 * 384 * @dev: Connected device, or NULL if none 385 */ 386struct spi_cs_info { 387 struct udevice *dev; 388}; 389 390/** 391 * struct struct dm_spi_ops - Driver model SPI operations 392 * 393 * The uclass interface is implemented by all SPI devices which use 394 * driver model. 395 */ 396struct dm_spi_ops { 397 /** 398 * Claim the bus and prepare it for communication. 399 * 400 * The device provided is the slave device. It's parent controller 401 * will be used to provide the communication. 402 * 403 * This must be called before doing any transfers with a SPI slave. It 404 * will enable and initialize any SPI hardware as necessary, and make 405 * sure that the SCK line is in the correct idle state. It is not 406 * allowed to claim the same bus for several slaves without releasing 407 * the bus in between. 408 * 409 * @dev: The SPI slave 410 * 411 * Returns: 0 if the bus was claimed successfully, or a negative value 412 * if it wasn't. 413 */ 414 int (*claim_bus)(struct udevice *dev); 415 416 /** 417 * Release the SPI bus 418 * 419 * This must be called once for every call to spi_claim_bus() after 420 * all transfers have finished. It may disable any SPI hardware as 421 * appropriate. 422 * 423 * @dev: The SPI slave 424 */ 425 int (*release_bus)(struct udevice *dev); 426 427 /** 428 * Set the word length for SPI transactions 429 * 430 * Set the word length (number of bits per word) for SPI transactions. 431 * 432 * @bus: The SPI slave 433 * @wordlen: The number of bits in a word 434 * 435 * Returns: 0 on success, -ve on failure. 436 */ 437 int (*set_wordlen)(struct udevice *dev, unsigned int wordlen); 438 439 /** 440 * SPI transfer 441 * 442 * This writes "bitlen" bits out the SPI MOSI port and simultaneously 443 * clocks "bitlen" bits in the SPI MISO port. That's just the way SPI 444 * works. 445 * 446 * The source of the outgoing bits is the "dout" parameter and the 447 * destination of the input bits is the "din" parameter. Note that 448 * "dout" and "din" can point to the same memory location, in which 449 * case the input data overwrites the output data (since both are 450 * buffered by temporary variables, this is OK). 451 * 452 * spi_xfer() interface: 453 * @dev: The slave device to communicate with 454 * @bitlen: How many bits to write and read. 455 * @dout: Pointer to a string of bits to send out. The bits are 456 * held in a byte array and are sent MSB first. 457 * @din: Pointer to a string of bits that will be filled in. 458 * @flags: A bitwise combination of SPI_XFER_* flags. 459 * 460 * Returns: 0 on success, not -1 on failure 461 */ 462 int (*xfer)(struct udevice *dev, unsigned int bitlen, const void *dout, 463 void *din, unsigned long flags); 464 465 /** 466 * Optimized handlers for SPI memory-like operations. 467 * 468 * Optimized/dedicated operations for interactions with SPI memory. This 469 * field is optional and should only be implemented if the controller 470 * has native support for memory like operations. 471 */ 472 const struct spi_controller_mem_ops *mem_ops; 473 474 /** 475 * Set transfer speed. 476 * This sets a new speed to be applied for next spi_xfer(). 477 * @bus: The SPI bus 478 * @hz: The transfer speed 479 * @return 0 if OK, -ve on error 480 */ 481 int (*set_speed)(struct udevice *bus, uint hz); 482 483 /** 484 * Set the SPI mode/flags 485 * 486 * It is unclear if we want to set speed and mode together instead 487 * of separately. 488 * 489 * @bus: The SPI bus 490 * @mode: Requested SPI mode (SPI_... flags) 491 * @return 0 if OK, -ve on error 492 */ 493 int (*set_mode)(struct udevice *bus, uint mode); 494 495 /** 496 * Get information on a chip select 497 * 498 * This is only called when the SPI uclass does not know about a 499 * chip select, i.e. it has no attached device. It gives the driver 500 * a chance to allow activity on that chip select even so. 501 * 502 * @bus: The SPI bus 503 * @cs: The chip select (0..n-1) 504 * @info: Returns information about the chip select, if valid. 505 * On entry info->dev is NULL 506 * @return 0 if OK (and @info is set up), -EINVAL if the chip select 507 * is invalid, other -ve value on error 508 */ 509 int (*cs_info)(struct udevice *bus, uint cs, struct spi_cs_info *info); 510 511 /** 512 * get_mmap() - Get memory-mapped SPI 513 * 514 * @dev: The SPI flash slave device 515 * @map_basep: Returns base memory address for mapped SPI 516 * @map_sizep: Returns size of mapped SPI 517 * @offsetp: Returns start offset of SPI flash where the map works 518 * correctly (offsets before this are not visible) 519 * @return 0 if OK, -EFAULT if memory mapping is not available 520 */ 521 int (*get_mmap)(struct udevice *dev, ulong *map_basep, 522 uint *map_sizep, uint *offsetp); 523}; 524 525struct dm_spi_emul_ops { 526 /** 527 * SPI transfer 528 * 529 * This writes "bitlen" bits out the SPI MOSI port and simultaneously 530 * clocks "bitlen" bits in the SPI MISO port. That's just the way SPI 531 * works. Here the device is a slave. 532 * 533 * The source of the outgoing bits is the "dout" parameter and the 534 * destination of the input bits is the "din" parameter. Note that 535 * "dout" and "din" can point to the same memory location, in which 536 * case the input data overwrites the output data (since both are 537 * buffered by temporary variables, this is OK). 538 * 539 * spi_xfer() interface: 540 * @slave: The SPI slave which will be sending/receiving the data. 541 * @bitlen: How many bits to write and read. 542 * @dout: Pointer to a string of bits sent to the device. The 543 * bits are held in a byte array and are sent MSB first. 544 * @din: Pointer to a string of bits that will be sent back to 545 * the master. 546 * @flags: A bitwise combination of SPI_XFER_* flags. 547 * 548 * Returns: 0 on success, not -1 on failure 549 */ 550 int (*xfer)(struct udevice *slave, unsigned int bitlen, 551 const void *dout, void *din, unsigned long flags); 552}; 553 554/** 555 * spi_find_bus_and_cs() - Find bus and slave devices by number 556 * 557 * Given a bus number and chip select, this finds the corresponding bus 558 * device and slave device. Neither device is activated by this function, 559 * although they may have been activated previously. 560 * 561 * @busnum: SPI bus number 562 * @cs: Chip select to look for 563 * @busp: Returns bus device 564 * @devp: Return slave device 565 * Return: 0 if found, -ENODEV on error 566 */ 567int spi_find_bus_and_cs(int busnum, int cs, struct udevice **busp, 568 struct udevice **devp); 569 570/** 571 * spi_get_bus_and_cs() - Find and activate bus and slave devices by number 572 * 573 * Given a bus number and chip select, this finds the corresponding bus 574 * device and slave device. 575 * 576 * @busnum: SPI bus number 577 * @cs: Chip select to look for 578 * @busp: Returns bus device 579 * @devp: Return slave device 580 * @return 0 if found, -ve on error 581 */ 582int spi_get_bus_and_cs(int busnum, int cs, 583 struct udevice **busp, struct spi_slave **devp); 584 585/** 586 * _spi_get_bus_and_cs() - Find and activate bus and slave devices by number 587 * As spi_flash_probe(), This is an old-style function. We should remove 588 * it when all SPI flash drivers use dm 589 * 590 * Given a bus number and chip select, this finds the corresponding bus 591 * device and slave device. 592 * 593 * If no such slave exists, and drv_name is not NULL, then a new slave device 594 * is automatically bound on this chip select with requested speed and mode. 595 * 596 * Ths new slave device is probed ready for use with the speed and mode 597 * from plat when available or the requested values. 598 * 599 * @busnum: SPI bus number 600 * @cs: Chip select to look for 601 * @speed: SPI speed to use for this slave when not available in plat 602 * @mode: SPI mode to use for this slave when not available in plat 603 * @drv_name: Name of driver to attach to this chip select 604 * @dev_name: Name of the new device thus created 605 * @busp: Returns bus device 606 * @devp: Return slave device 607 * Return: 0 if found, -ve on error 608 */ 609int _spi_get_bus_and_cs(int busnum, int cs, int speed, int mode, 610 const char *drv_name, const char *dev_name, 611 struct udevice **busp, struct spi_slave **devp); 612 613/** 614 * spi_chip_select() - Get the chip select for a slave 615 * 616 * Return: the chip select this slave is attached to 617 */ 618int spi_chip_select(struct udevice *slave); 619 620/** 621 * spi_find_chip_select() - Find the slave attached to chip select 622 * 623 * @bus: SPI bus to search 624 * @cs: Chip select to look for 625 * @devp: Returns the slave device if found 626 * Return: 0 if found, -EINVAL if cs is invalid, -ENODEV if no device attached, 627 * other -ve value on error 628 */ 629int spi_find_chip_select(struct udevice *bus, int cs, struct udevice **devp); 630 631/** 632 * spi_slave_of_to_plat() - decode standard SPI platform data 633 * 634 * This decodes the speed and mode for a slave from a device tree node 635 * 636 * @blob: Device tree blob 637 * @node: Node offset to read from 638 * @plat: Place to put the decoded information 639 */ 640int spi_slave_of_to_plat(struct udevice *dev, struct dm_spi_slave_plat *plat); 641 642/** 643 * spi_cs_info() - Check information on a chip select 644 * 645 * This checks a particular chip select on a bus to see if it has a device 646 * attached, or is even valid. 647 * 648 * @bus: The SPI bus 649 * @cs: The chip select (0..n-1) 650 * @info: Returns information about the chip select, if valid 651 * Return: 0 if OK (and @info is set up), -ENODEV if the chip select 652 * is invalid, other -ve value on error 653 */ 654int spi_cs_info(struct udevice *bus, uint cs, struct spi_cs_info *info); 655 656struct sandbox_state; 657 658/** 659 * sandbox_spi_get_emul() - get an emulator for a SPI slave 660 * 661 * This provides a way to attach an emulated SPI device to a particular SPI 662 * slave, so that xfer() operations on the slave will be handled by the 663 * emulator. If a emulator already exists on that chip select it is returned. 664 * Otherwise one is created. 665 * 666 * @state: Sandbox state 667 * @bus: SPI bus requesting the emulator 668 * @slave: SPI slave device requesting the emulator 669 * @emuip: Returns pointer to emulator 670 * Return: 0 if OK, -ve on error 671 */ 672int sandbox_spi_get_emul(struct sandbox_state *state, 673 struct udevice *bus, struct udevice *slave, 674 struct udevice **emulp); 675 676/** 677 * Claim the bus and prepare it for communication with a given slave. 678 * 679 * This must be called before doing any transfers with a SPI slave. It 680 * will enable and initialize any SPI hardware as necessary, and make 681 * sure that the SCK line is in the correct idle state. It is not 682 * allowed to claim the same bus for several slaves without releasing 683 * the bus in between. 684 * 685 * @dev: The SPI slave device 686 * 687 * Returns: 0 if the bus was claimed successfully, or a negative value 688 * if it wasn't. 689 */ 690int dm_spi_claim_bus(struct udevice *dev); 691 692/** 693 * Release the SPI bus 694 * 695 * This must be called once for every call to dm_spi_claim_bus() after 696 * all transfers have finished. It may disable any SPI hardware as 697 * appropriate. 698 * 699 * @slave: The SPI slave device 700 */ 701void dm_spi_release_bus(struct udevice *dev); 702 703/** 704 * SPI transfer 705 * 706 * This writes "bitlen" bits out the SPI MOSI port and simultaneously clocks 707 * "bitlen" bits in the SPI MISO port. That's just the way SPI works. 708 * 709 * The source of the outgoing bits is the "dout" parameter and the 710 * destination of the input bits is the "din" parameter. Note that "dout" 711 * and "din" can point to the same memory location, in which case the 712 * input data overwrites the output data (since both are buffered by 713 * temporary variables, this is OK). 714 * 715 * dm_spi_xfer() interface: 716 * @dev: The SPI slave device which will be sending/receiving the data. 717 * @bitlen: How many bits to write and read. 718 * @dout: Pointer to a string of bits to send out. The bits are 719 * held in a byte array and are sent MSB first. 720 * @din: Pointer to a string of bits that will be filled in. 721 * @flags: A bitwise combination of SPI_XFER_* flags. 722 * 723 * Returns: 0 on success, not 0 on failure 724 */ 725int dm_spi_xfer(struct udevice *dev, unsigned int bitlen, 726 const void *dout, void *din, unsigned long flags); 727 728/** 729 * spi_get_mmap() - Get memory-mapped SPI 730 * 731 * @dev: SPI slave device to check 732 * @map_basep: Returns base memory address for mapped SPI 733 * @map_sizep: Returns size of mapped SPI 734 * @offsetp: Returns start offset of SPI flash where the map works 735 * correctly (offsets before this are not visible) 736 * Return: 0 if OK, -ENOSYS if no operation, -EFAULT if memory mapping is not 737 * available 738 */ 739int dm_spi_get_mmap(struct udevice *dev, ulong *map_basep, uint *map_sizep, 740 uint *offsetp); 741 742/* Access the operations for a SPI device */ 743#define spi_get_ops(dev) ((struct dm_spi_ops *)(dev)->driver->ops) 744#define spi_emul_get_ops(dev) ((struct dm_spi_emul_ops *)(dev)->driver->ops) 745 746#endif /* _SPI_H_ */ 747