include/spi.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * Common SPI Interface: Controller-specific definitions
   4  *
   5  * (C) Copyright 2001
   6  * Gerald Van Baren, Custom IDEAS, vanbaren@cideas.com.
   7  */
   8
   9 #ifndef _SPI_H_
  10 #define _SPI_H_
  11
  12 #include <common.h>
  13 #include <linux/bitops.h>
  14
  15 /* SPI mode flags */
  16 #define SPI_CPHA        BIT(0)  /* clock phase (1 = SPI_CLOCK_PHASE_SECOND) */
  17 #define SPI_CPOL        BIT(1)  /* clock polarity (1 = SPI_POLARITY_HIGH) */
  18 #define SPI_MODE_0      (0|0)                   /* (original MicroWire) */
  19 #define SPI_MODE_1      (0|SPI_CPHA)
  20 #define SPI_MODE_2      (SPI_CPOL|0)
  21 #define SPI_MODE_3      (SPI_CPOL|SPI_CPHA)
  22 #define SPI_CS_HIGH     BIT(2)                  /* CS active high */
  23 #define SPI_LSB_FIRST   BIT(3)                  /* per-word bits-on-wire */
  24 #define SPI_3WIRE       BIT(4)                  /* SI/SO signals shared */
  25 #define SPI_LOOP        BIT(5)                  /* loopback mode */
  26 #define SPI_SLAVE       BIT(6)                  /* slave mode */
  27 #define SPI_PREAMBLE    BIT(7)                  /* Skip preamble bytes */
  28 #define SPI_TX_BYTE     BIT(8)                  /* transmit with 1 wire byte */
  29 #define SPI_TX_DUAL     BIT(9)                  /* transmit with 2 wires */
  30 #define SPI_TX_QUAD     BIT(10)                 /* transmit with 4 wires */
  31 #define SPI_RX_SLOW     BIT(11)                 /* receive with 1 wire slow */
  32 #define SPI_RX_DUAL     BIT(12)                 /* receive with 2 wires */
  33 #define SPI_RX_QUAD     BIT(13)                 /* receive with 4 wires */
  34 #define SPI_TX_OCTAL    BIT(14)                 /* transmit with 8 wires */
  35 #define SPI_RX_OCTAL    BIT(15)                 /* receive with 8 wires */
  36
  37 /* Header byte that marks the start of the message */
  38 #define SPI_PREAMBLE_END_BYTE   0xec
  39
  40 #define SPI_DEFAULT_WORDLEN     8
  41
  42 /**
  43  * struct dm_spi_bus - SPI bus info
  44  *
  45  * This contains information about a SPI bus. To obtain this structure, use
  46  * dev_get_uclass_priv(bus) where bus is the SPI bus udevice.
  47  *
  48  * @max_hz:     Maximum speed that the bus can tolerate.
  49  * @speed:      Current bus speed. This is 0 until the bus is first claimed.
  50  * @mode:       Current bus mode. This is 0 until the bus is first claimed.
  51  *
  52  * TODO(sjg@chromium.org): Remove this and use max_hz from struct spi_slave.
  53  */
  54 struct dm_spi_bus {
  55         uint max_hz;
  56         uint speed;
  57         uint mode;
  58 };
  59
  60 /**
  61  * struct dm_spi_plat - platform data for all SPI slaves
  62  *
  63  * This describes a SPI slave, a child device of the SPI bus. To obtain this
  64  * struct from a spi_slave, use dev_get_parent_plat(dev) or
  65  * dev_get_parent_plat(slave->dev).
  66  *
  67  * This data is immutable. Each time the device is probed, @max_hz and @mode
  68  * will be copied to struct spi_slave.
  69  *
  70  * @cs:         Chip select number (0..n-1)
  71  * @max_hz:     Maximum bus speed that this slave can tolerate
  72  * @mode:       SPI mode to use for this device (see SPI mode flags)
  73  */
  74 struct dm_spi_slave_plat {
  75         unsigned int cs;
  76         uint max_hz;
  77         uint mode;
  78 };
  79
  80 /**
  81  * enum spi_clock_phase - indicates  the clock phase to use for SPI (CPHA)
  82  *
  83  * @SPI_CLOCK_PHASE_FIRST: Data sampled on the first phase
  84  * @SPI_CLOCK_PHASE_SECOND: Data sampled on the second phase
  85  */
  86 enum spi_clock_phase {
  87         SPI_CLOCK_PHASE_FIRST,
  88         SPI_CLOCK_PHASE_SECOND,
  89 };
  90
  91 /**
  92  * enum spi_wire_mode - indicates the number of wires used for SPI
  93  *
  94  * @SPI_4_WIRE_MODE: Normal bidirectional mode with MOSI and MISO
  95  * @SPI_3_WIRE_MODE: Unidirectional version with a single data line SISO
  96  */
  97 enum spi_wire_mode {
  98         SPI_4_WIRE_MODE,
  99         SPI_3_WIRE_MODE,
 100 };
 101
 102 /**
 103  * enum spi_polarity - indicates the polarity of the SPI bus (CPOL)
 104  *
 105  * @SPI_POLARITY_LOW: Clock is low in idle state
 106  * @SPI_POLARITY_HIGH: Clock is high in idle state
 107  */
 108 enum spi_polarity {
 109         SPI_POLARITY_LOW,
 110         SPI_POLARITY_HIGH,
 111 };
 112
 113 /**
 114  * struct spi_slave - Representation of a SPI slave
 115  *
 116  * For driver model this is the per-child data used by the SPI bus. It can
 117  * be accessed using dev_get_parent_priv() on the slave device. The SPI uclass
 118  * sets up per_child_auto to sizeof(struct spi_slave), and the
 119  * driver should not override it. Two platform data fields (max_hz and mode)
 120  * are copied into this structure to provide an initial value. This allows
 121  * them to be changed, since we should never change platform data in drivers.
 122  *
 123  * If not using driver model, drivers are expected to extend this with
 124  * controller-specific data.
 125  *
 126  * @dev:                SPI slave device
 127  * @max_hz:             Maximum speed for this slave
 128  * @bus:                ID of the bus that the slave is attached to. For
 129  *                      driver model this is the sequence number of the SPI
 130  *                      bus (dev_seq(bus)) so does not need to be stored
 131  * @cs:                 ID of the chip select connected to the slave.
 132  * @mode:               SPI mode to use for this slave (see SPI mode flags)
 133  * @wordlen:            Size of SPI word in number of bits
 134  * @max_read_size:      If non-zero, the maximum number of bytes which can
 135  *                      be read at once.
 136  * @max_write_size:     If non-zero, the maximum number of bytes which can
 137  *                      be written at once.
 138  * @memory_map:         Address of read-only SPI flash access.
 139  * @flags:              Indication of SPI flags.
 140  */
 141 struct spi_slave {
 142 #if CONFIG_IS_ENABLED(DM_SPI)
 143         struct udevice *dev;    /* struct spi_slave is dev->parentdata */
 144         uint max_hz;
 145 #else
 146         unsigned int bus;
 147         unsigned int cs;
 148 #endif
 149         uint mode;
 150         unsigned int wordlen;
 151         unsigned int max_read_size;
 152         unsigned int max_write_size;
 153         void *memory_map;
 154
 155         u8 flags;
 156 #define SPI_XFER_BEGIN          BIT(0)  /* Assert CS before transfer */
 157 #define SPI_XFER_END            BIT(1)  /* Deassert CS after transfer */
 158 #define SPI_XFER_ONCE           (SPI_XFER_BEGIN | SPI_XFER_END)
 159 };
 160
 161 /**
 162  * spi_do_alloc_slave - Allocate a new SPI slave (internal)
 163  *
 164  * Allocate and zero all fields in the spi slave, and set the bus/chip
 165  * select. Use the helper macro spi_alloc_slave() to call this.
 166  *
 167  * @offset:     Offset of struct spi_slave within slave structure.
 168  * @size:       Size of slave structure.
 169  * @bus:        Bus ID of the slave chip.
 170  * @cs:         Chip select ID of the slave chip on the specified bus.
 171  */
 172 void *spi_do_alloc_slave(int offset, int size, unsigned int bus,
 173                          unsigned int cs);
 174
 175 /**
 176  * spi_alloc_slave - Allocate a new SPI slave
 177  *
 178  * Allocate and zero all fields in the spi slave, and set the bus/chip
 179  * select.
 180  *
 181  * @_struct:    Name of structure to allocate (e.g. struct tegra_spi).
 182  *              This structure must contain a member 'struct spi_slave *slave'.
 183  * @bus:        Bus ID of the slave chip.
 184  * @cs:         Chip select ID of the slave chip on the specified bus.
 185  */
 186 #define spi_alloc_slave(_struct, bus, cs) \
 187         spi_do_alloc_slave(offsetof(_struct, slave), \
 188                             sizeof(_struct), bus, cs)
 189
 190 /**
 191  * spi_alloc_slave_base - Allocate a new SPI slave with no private data
 192  *
 193  * Allocate and zero all fields in the spi slave, and set the bus/chip
 194  * select.
 195  *
 196  * @bus:        Bus ID of the slave chip.
 197  * @cs:         Chip select ID of the slave chip on the specified bus.
 198  */
 199 #define spi_alloc_slave_base(bus, cs) \
 200         spi_do_alloc_slave(0, sizeof(struct spi_slave), bus, cs)
 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  * @max_hz:     Maximum SCK rate in Hz.
 213  * @mode:       Clock polarity, clock phase and other parameters.
 214  *
 215  * Returns: A spi_slave reference that can be used in subsequent SPI
 216  * calls, or NULL if one or more of the parameters are not supported.
 217  */
 218 struct spi_slave *spi_setup_slave(unsigned int bus, unsigned int cs,
 219                 unsigned int max_hz, unsigned int mode);
 220
 221 /**
 222  * Free any memory associated with a SPI slave.
 223  *
 224  * @slave:      The SPI slave
 225  */
 226 void spi_free_slave(struct spi_slave *slave);
 227
 228 /**
 229  * Claim the bus and prepare it for communication with a given slave.
 230  *
 231  * This must be called before doing any transfers with a SPI slave. It
 232  * will enable and initialize any SPI hardware as necessary, and make
 233  * sure that the SCK line is in the correct idle state. It is not
 234  * allowed to claim the same bus for several slaves without releasing
 235  * the bus in between.
 236  *
 237  * @slave:      The SPI slave
 238  *
 239  * Returns: 0 if the bus was claimed successfully, or a negative value
 240  * if it wasn't.
 241  */
 242 int spi_claim_bus(struct spi_slave *slave);
 243
 244 /**
 245  * Release the SPI bus
 246  *
 247  * This must be called once for every call to spi_claim_bus() after
 248  * all transfers have finished. It may disable any SPI hardware as
 249  * appropriate.
 250  *
 251  * @slave:      The SPI slave
 252  */
 253 void spi_release_bus(struct spi_slave *slave);
 254
 255 /**
 256  * Set the word length for SPI transactions
 257  *
 258  * Set the word length (number of bits per word) for SPI transactions.
 259  *
 260  * @slave:      The SPI slave
 261  * @wordlen:    The number of bits in a word
 262  *
 263  * Returns: 0 on success, -1 on failure.
 264  */
 265 int spi_set_wordlen(struct spi_slave *slave, unsigned int wordlen);
 266
 267 /**
 268  * SPI transfer (optional if mem_ops is used)
 269  *
 270  * This writes "bitlen" bits out the SPI MOSI port and simultaneously clocks
 271  * "bitlen" bits in the SPI MISO port.  That's just the way SPI works.
 272  *
 273  * The source of the outgoing bits is the "dout" parameter and the
 274  * destination of the input bits is the "din" parameter.  Note that "dout"
 275  * and "din" can point to the same memory location, in which case the
 276  * input data overwrites the output data (since both are buffered by
 277  * temporary variables, this is OK).
 278  *
 279  * spi_xfer() interface:
 280  * @slave:      The SPI slave which will be sending/receiving the data.
 281  * @bitlen:     How many bits to write and read.
 282  * @dout:       Pointer to a string of bits to send out.  The bits are
 283  *              held in a byte array and are sent MSB first.
 284  * @din:        Pointer to a string of bits that will be filled in.
 285  * @flags:      A bitwise combination of SPI_XFER_* flags.
 286  *
 287  * Returns: 0 on success, not 0 on failure
 288  */
 289 int  spi_xfer(struct spi_slave *slave, unsigned int bitlen, const void *dout,
 290                 void *din, unsigned long flags);
 291
 292 /**
 293  * spi_write_then_read - SPI synchronous write followed by read
 294  *
 295  * This performs a half duplex transaction in which the first transaction
 296  * is to send the opcode and if the length of buf is non-zero then it start
 297  * the second transaction as tx or rx based on the need from respective slave.
 298  *
 299  * @slave:      The SPI slave device with which opcode/data will be exchanged
 300  * @opcode:     opcode used for specific transfer
 301  * @n_opcode:   size of opcode, in bytes
 302  * @txbuf:      buffer into which data to be written
 303  * @rxbuf:      buffer into which data will be read
 304  * @n_buf:      size of buf (whether it's [tx|rx]buf), in bytes
 305  *
 306  * Returns: 0 on success, not 0 on failure
 307  */
 308 int spi_write_then_read(struct spi_slave *slave, const u8 *opcode,
 309                         size_t n_opcode, const u8 *txbuf, u8 *rxbuf,
 310                         size_t n_buf);
 311
 312 /* Copy memory mapped data */
 313 void spi_flash_copy_mmap(void *data, void *offset, size_t len);
 314
 315 /**
 316  * Determine if a SPI chipselect is valid.
 317  * This function is provided by the board if the low-level SPI driver
 318  * needs it to determine if a given chipselect is actually valid.
 319  *
 320  * Returns: 1 if bus:cs identifies a valid chip on this board, 0
 321  * otherwise.
 322  */
 323 int spi_cs_is_valid(unsigned int bus, unsigned int cs);
 324
 325 /*
 326  * These names are used in several drivers and these declarations will be
 327  * removed soon as part of the SPI DM migration. Drop them if driver model is
 328  * enabled for SPI.
 329  */
 330 #if !CONFIG_IS_ENABLED(DM_SPI)
 331 /**
 332  * Activate a SPI chipselect.
 333  * This function is provided by the board code when using a driver
 334  * that can't control its chipselects automatically (e.g.
 335  * common/soft_spi.c). When called, it should activate the chip select
 336  * to the device identified by "slave".
 337  */
 338 void spi_cs_activate(struct spi_slave *slave);
 339
 340 /**
 341  * Deactivate a SPI chipselect.
 342  * This function is provided by the board code when using a driver
 343  * that can't control its chipselects automatically (e.g.
 344  * common/soft_spi.c). When called, it should deactivate the chip
 345  * select to the device identified by "slave".
 346  */
 347 void spi_cs_deactivate(struct spi_slave *slave);
 348 #endif
 349
 350 /**
 351  * Set transfer speed.
 352  * This sets a new speed to be applied for next spi_xfer().
 353  * @slave:      The SPI slave
 354  * @hz:         The transfer speed
 355  */
 356 void spi_set_speed(struct spi_slave *slave, uint hz);
 357
 358 /**
 359  * Write 8 bits, then read 8 bits.
 360  * @slave:      The SPI slave we're communicating with
 361  * @byte:       Byte to be written
 362  *
 363  * Returns: The value that was read, or a negative value on error.
 364  *
 365  * TODO: This function probably shouldn't be inlined.
 366  */
 367 static inline int spi_w8r8(struct spi_slave *slave, unsigned char byte)
 368 {
 369         unsigned char dout[2];
 370         unsigned char din[2];
 371         int ret;
 372
 373         dout[0] = byte;
 374         dout[1] = 0;
 375
 376         ret = spi_xfer(slave, 16, dout, din, SPI_XFER_BEGIN | SPI_XFER_END);
 377         return ret < 0 ? ret : din[1];
 378 }
 379
 380 /**
 381  * struct spi_cs_info - Information about a bus chip select
 382  *
 383  * @dev:        Connected device, or NULL if none
 384  */
 385 struct spi_cs_info {
 386         struct udevice *dev;
 387 };
 388
 389 /**
 390  * struct struct dm_spi_ops - Driver model SPI operations
 391  *
 392  * The uclass interface is implemented by all SPI devices which use
 393  * driver model.
 394  */
 395 struct dm_spi_ops {
 396         /**
 397          * Claim the bus and prepare it for communication.
 398          *
 399          * The device provided is the slave device. It's parent controller
 400          * will be used to provide the communication.
 401          *
 402          * This must be called before doing any transfers with a SPI slave. It
 403          * will enable and initialize any SPI hardware as necessary, and make
 404          * sure that the SCK line is in the correct idle state. It is not
 405          * allowed to claim the same bus for several slaves without releasing
 406          * the bus in between.
 407          *
 408          * @dev:        The SPI slave
 409          *
 410          * Returns: 0 if the bus was claimed successfully, or a negative value
 411          * if it wasn't.
 412          */
 413         int (*claim_bus)(struct udevice *dev);
 414
 415         /**
 416          * Release the SPI bus
 417          *
 418          * This must be called once for every call to spi_claim_bus() after
 419          * all transfers have finished. It may disable any SPI hardware as
 420          * appropriate.
 421          *
 422          * @dev:        The SPI slave
 423          */
 424         int (*release_bus)(struct udevice *dev);
 425
 426         /**
 427          * Set the word length for SPI transactions
 428          *
 429          * Set the word length (number of bits per word) for SPI transactions.
 430          *
 431          * @bus:        The SPI slave
 432          * @wordlen:    The number of bits in a word
 433          *
 434          * Returns: 0 on success, -ve on failure.
 435          */
 436         int (*set_wordlen)(struct udevice *dev, unsigned int wordlen);
 437
 438         /**
 439          * SPI transfer
 440          *
 441          * This writes "bitlen" bits out the SPI MOSI port and simultaneously
 442          * clocks "bitlen" bits in the SPI MISO port.  That's just the way SPI
 443          * works.
 444          *
 445          * The source of the outgoing bits is the "dout" parameter and the
 446          * destination of the input bits is the "din" parameter.  Note that
 447          * "dout" and "din" can point to the same memory location, in which
 448          * case the input data overwrites the output data (since both are
 449          * buffered by temporary variables, this is OK).
 450          *
 451          * spi_xfer() interface:
 452          * @dev:        The slave device to communicate with
 453          * @bitlen:     How many bits to write and read.
 454          * @dout:       Pointer to a string of bits to send out.  The bits are
 455          *              held in a byte array and are sent MSB first.
 456          * @din:        Pointer to a string of bits that will be filled in.
 457          * @flags:      A bitwise combination of SPI_XFER_* flags.
 458          *
 459          * Returns: 0 on success, not -1 on failure
 460          */
 461         int (*xfer)(struct udevice *dev, unsigned int bitlen, const void *dout,
 462                     void *din, unsigned long flags);
 463
 464         /**
 465          * Optimized handlers for SPI memory-like operations.
 466          *
 467          * Optimized/dedicated operations for interactions with SPI memory. This
 468          * field is optional and should only be implemented if the controller
 469          * has native support for memory like operations.
 470          */
 471         const struct spi_controller_mem_ops *mem_ops;
 472
 473         /**
 474          * Set transfer speed.
 475          * This sets a new speed to be applied for next spi_xfer().
 476          * @bus:        The SPI bus
 477          * @hz:         The transfer speed
 478          * @return 0 if OK, -ve on error
 479          */
 480         int (*set_speed)(struct udevice *bus, uint hz);
 481
 482         /**
 483          * Set the SPI mode/flags
 484          *
 485          * It is unclear if we want to set speed and mode together instead
 486          * of separately.
 487          *
 488          * @bus:        The SPI bus
 489          * @mode:       Requested SPI mode (SPI_... flags)
 490          * @return 0 if OK, -ve on error
 491          */
 492         int (*set_mode)(struct udevice *bus, uint mode);
 493
 494         /**
 495          * Get information on a chip select
 496          *
 497          * This is only called when the SPI uclass does not know about a
 498          * chip select, i.e. it has no attached device. It gives the driver
 499          * a chance to allow activity on that chip select even so.
 500          *
 501          * @bus:        The SPI bus
 502          * @cs:         The chip select (0..n-1)
 503          * @info:       Returns information about the chip select, if valid.
 504          *              On entry info->dev is NULL
 505          * @return 0 if OK (and @info is set up), -EINVAL if the chip select
 506          *         is invalid, other -ve value on error
 507          */
 508         int (*cs_info)(struct udevice *bus, uint cs, struct spi_cs_info *info);
 509
 510         /**
 511          * get_mmap() - Get memory-mapped SPI
 512          *
 513          * @dev:        The SPI flash slave device
 514          * @map_basep:  Returns base memory address for mapped SPI
 515          * @map_sizep:  Returns size of mapped SPI
 516          * @offsetp:    Returns start offset of SPI flash where the map works
 517          *      correctly (offsets before this are not visible)
 518          * @return 0 if OK, -EFAULT if memory mapping is not available
 519          */
 520         int (*get_mmap)(struct udevice *dev, ulong *map_basep,
 521                         uint *map_sizep, uint *offsetp);
 522 };
 523
 524 struct dm_spi_emul_ops {
 525         /**
 526          * SPI transfer
 527          *
 528          * This writes "bitlen" bits out the SPI MOSI port and simultaneously
 529          * clocks "bitlen" bits in the SPI MISO port.  That's just the way SPI
 530          * works. Here the device is a slave.
 531          *
 532          * The source of the outgoing bits is the "dout" parameter and the
 533          * destination of the input bits is the "din" parameter.  Note that
 534          * "dout" and "din" can point to the same memory location, in which
 535          * case the input data overwrites the output data (since both are
 536          * buffered by temporary variables, this is OK).
 537          *
 538          * spi_xfer() interface:
 539          * @slave:      The SPI slave which will be sending/receiving the data.
 540          * @bitlen:     How many bits to write and read.
 541          * @dout:       Pointer to a string of bits sent to the device. The
 542          *              bits are held in a byte array and are sent MSB first.
 543          * @din:        Pointer to a string of bits that will be sent back to
 544          *              the master.
 545          * @flags:      A bitwise combination of SPI_XFER_* flags.
 546          *
 547          * Returns: 0 on success, not -1 on failure
 548          */
 549         int (*xfer)(struct udevice *slave, unsigned int bitlen,
 550                     const void *dout, void *din, unsigned long flags);
 551 };
 552
 553 /**
 554  * spi_find_bus_and_cs() - Find bus and slave devices by number
 555  *
 556  * Given a bus number and chip select, this finds the corresponding bus
 557  * device and slave device. Neither device is activated by this function,
 558  * although they may have been activated previously.
 559  *
 560  * @busnum:     SPI bus number
 561  * @cs:         Chip select to look for
 562  * @busp:       Returns bus device
 563  * @devp:       Return slave device
 564  * Return: 0 if found, -ENODEV on error
 565  */
 566 int spi_find_bus_and_cs(int busnum, int cs, struct udevice **busp,
 567                         struct udevice **devp);
 568
 569 /**
 570  * spi_get_bus_and_cs() - Find and activate bus and slave devices by number
 571  *
 572  * Given a bus number and chip select, this finds the corresponding bus
 573  * device and slave device.
 574  *
 575  * @busnum:     SPI bus number
 576  * @cs:         Chip select to look for
 577  * @busp:       Returns bus device
 578  * @devp:       Return slave device
 579  * @return 0 if found, -ve on error
 580  */
 581 int spi_get_bus_and_cs(int busnum, int cs,
 582                        struct udevice **busp, struct spi_slave **devp);
 583
 584 /**
 585  * _spi_get_bus_and_cs() - Find and activate bus and slave devices by number
 586  * As spi_flash_probe(), This is an old-style function. We should remove
 587  * it when all SPI flash drivers use dm
 588  *
 589  * Given a bus number and chip select, this finds the corresponding bus
 590  * device and slave device.
 591  *
 592  * If no such slave exists, and drv_name is not NULL, then a new slave device
 593  * is automatically bound on this chip select with requested speed and mode.
 594  *
 595  * Ths new slave device is probed ready for use with the speed and mode
 596  * from plat when available or the requested values.
 597  *
 598  * @busnum:     SPI bus number
 599  * @cs:         Chip select to look for
 600  * @speed:      SPI speed to use for this slave when not available in plat
 601  * @mode:       SPI mode to use for this slave when not available in plat
 602  * @drv_name:   Name of driver to attach to this chip select
 603  * @dev_name:   Name of the new device thus created
 604  * @busp:       Returns bus device
 605  * @devp:       Return slave device
 606  * Return: 0 if found, -ve on error
 607  */
 608 int _spi_get_bus_and_cs(int busnum, int cs, int speed, int mode,
 609                         const char *drv_name, const char *dev_name,
 610                         struct udevice **busp, struct spi_slave **devp);
 611
 612 /**
 613  * spi_chip_select() - Get the chip select for a slave
 614  *
 615  * Return: the chip select this slave is attached to
 616  */
 617 int spi_chip_select(struct udevice *slave);
 618
 619 /**
 620  * spi_find_chip_select() - Find the slave attached to chip select
 621  *
 622  * @bus:        SPI bus to search
 623  * @cs:         Chip select to look for
 624  * @devp:       Returns the slave device if found
 625  * Return: 0 if found, -EINVAL if cs is invalid, -ENODEV if no device attached,
 626  *         other -ve value on error
 627  */
 628 int spi_find_chip_select(struct udevice *bus, int cs, struct udevice **devp);
 629
 630 /**
 631  * spi_slave_of_to_plat() - decode standard SPI platform data
 632  *
 633  * This decodes the speed and mode for a slave from a device tree node
 634  *
 635  * @blob:       Device tree blob
 636  * @node:       Node offset to read from
 637  * @plat:       Place to put the decoded information
 638  */
 639 int spi_slave_of_to_plat(struct udevice *dev, struct dm_spi_slave_plat *plat);
 640
 641 /**
 642  * spi_cs_info() - Check information on a chip select
 643  *
 644  * This checks a particular chip select on a bus to see if it has a device
 645  * attached, or is even valid.
 646  *
 647  * @bus:        The SPI bus
 648  * @cs:         The chip select (0..n-1)
 649  * @info:       Returns information about the chip select, if valid
 650  * Return: 0 if OK (and @info is set up), -ENODEV if the chip select
 651  *         is invalid, other -ve value on error
 652  */
 653 int spi_cs_info(struct udevice *bus, uint cs, struct spi_cs_info *info);
 654
 655 struct sandbox_state;
 656
 657 /**
 658  * sandbox_spi_get_emul() - get an emulator for a SPI slave
 659  *
 660  * This provides a way to attach an emulated SPI device to a particular SPI
 661  * slave, so that xfer() operations on the slave will be handled by the
 662  * emulator. If a emulator already exists on that chip select it is returned.
 663  * Otherwise one is created.
 664  *
 665  * @state:      Sandbox state
 666  * @bus:        SPI bus requesting the emulator
 667  * @slave:      SPI slave device requesting the emulator
 668  * @emuip:      Returns pointer to emulator
 669  * Return: 0 if OK, -ve on error
 670  */
 671 int sandbox_spi_get_emul(struct sandbox_state *state,
 672                          struct udevice *bus, struct udevice *slave,
 673                          struct udevice **emulp);
 674
 675 /**
 676  * Claim the bus and prepare it for communication with a given slave.
 677  *
 678  * This must be called before doing any transfers with a SPI slave. It
 679  * will enable and initialize any SPI hardware as necessary, and make
 680  * sure that the SCK line is in the correct idle state. It is not
 681  * allowed to claim the same bus for several slaves without releasing
 682  * the bus in between.
 683  *
 684  * @dev:        The SPI slave device
 685  *
 686  * Returns: 0 if the bus was claimed successfully, or a negative value
 687  * if it wasn't.
 688  */
 689 int dm_spi_claim_bus(struct udevice *dev);
 690
 691 /**
 692  * Release the SPI bus
 693  *
 694  * This must be called once for every call to dm_spi_claim_bus() after
 695  * all transfers have finished. It may disable any SPI hardware as
 696  * appropriate.
 697  *
 698  * @slave:      The SPI slave device
 699  */
 700 void dm_spi_release_bus(struct udevice *dev);
 701
 702 /**
 703  * SPI transfer
 704  *
 705  * This writes "bitlen" bits out the SPI MOSI port and simultaneously clocks
 706  * "bitlen" bits in the SPI MISO port.  That's just the way SPI works.
 707  *
 708  * The source of the outgoing bits is the "dout" parameter and the
 709  * destination of the input bits is the "din" parameter.  Note that "dout"
 710  * and "din" can point to the same memory location, in which case the
 711  * input data overwrites the output data (since both are buffered by
 712  * temporary variables, this is OK).
 713  *
 714  * dm_spi_xfer() interface:
 715  * @dev:        The SPI slave device which will be sending/receiving the data.
 716  * @bitlen:     How many bits to write and read.
 717  * @dout:       Pointer to a string of bits to send out.  The bits are
 718  *              held in a byte array and are sent MSB first.
 719  * @din:        Pointer to a string of bits that will be filled in.
 720  * @flags:      A bitwise combination of SPI_XFER_* flags.
 721  *
 722  * Returns: 0 on success, not 0 on failure
 723  */
 724 int dm_spi_xfer(struct udevice *dev, unsigned int bitlen,
 725                 const void *dout, void *din, unsigned long flags);
 726
 727 /**
 728  * spi_get_mmap() - Get memory-mapped SPI
 729  *
 730  * @dev:        SPI slave device to check
 731  * @map_basep:  Returns base memory address for mapped SPI
 732  * @map_sizep:  Returns size of mapped SPI
 733  * @offsetp:    Returns start offset of SPI flash where the map works
 734  *      correctly (offsets before this are not visible)
 735  * Return: 0 if OK, -ENOSYS if no operation, -EFAULT if memory mapping is not
 736  *      available
 737  */
 738 int dm_spi_get_mmap(struct udevice *dev, ulong *map_basep, uint *map_sizep,
 739                     uint *offsetp);
 740
 741 /* Access the operations for a SPI device */
 742 #define spi_get_ops(dev)        ((struct dm_spi_ops *)(dev)->driver->ops)
 743 #define spi_emul_get_ops(dev)   ((struct dm_spi_emul_ops *)(dev)->driver->ops)
 744
 745 #endif  /* _SPI_H_ */