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