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  * Returns:     0 on success, or a negative value on error.
 357  */
 358 int spi_set_speed(struct spi_slave *slave, uint hz);
 359
 360 /**
 361  * Write 8 bits, then read 8 bits.
 362  * @slave:      The SPI slave we're communicating with
 363  * @byte:       Byte to be written
 364  *
 365  * Returns: The value that was read, or a negative value on error.
 366  *
 367  * TODO: This function probably shouldn't be inlined.
 368  */
 369 static inline int spi_w8r8(struct spi_slave *slave, unsigned char byte)
 370 {
 371         unsigned char dout[2];
 372         unsigned char din[2];
 373         int ret;
 374
 375         dout[0] = byte;
 376         dout[1] = 0;
 377
 378         ret = spi_xfer(slave, 16, dout, din, SPI_XFER_BEGIN | SPI_XFER_END);
 379         return ret < 0 ? ret : din[1];
 380 }
 381
 382 /**
 383  * struct spi_cs_info - Information about a bus chip select
 384  *
 385  * @dev:        Connected device, or NULL if none
 386  */
 387 struct spi_cs_info {
 388         struct udevice *dev;
 389 };
 390
 391 /**
 392  * struct struct dm_spi_ops - Driver model SPI operations
 393  *
 394  * The uclass interface is implemented by all SPI devices which use
 395  * driver model.
 396  */
 397 struct dm_spi_ops {
 398         /**
 399          * Claim the bus and prepare it for communication.
 400          *
 401          * The device provided is the slave device. It's parent controller
 402          * will be used to provide the communication.
 403          *
 404          * This must be called before doing any transfers with a SPI slave. It
 405          * will enable and initialize any SPI hardware as necessary, and make
 406          * sure that the SCK line is in the correct idle state. It is not
 407          * allowed to claim the same bus for several slaves without releasing
 408          * the bus in between.
 409          *
 410          * @dev:        The SPI slave
 411          *
 412          * Returns: 0 if the bus was claimed successfully, or a negative value
 413          * if it wasn't.
 414          */
 415         int (*claim_bus)(struct udevice *dev);
 416
 417         /**
 418          * Release the SPI bus
 419          *
 420          * This must be called once for every call to spi_claim_bus() after
 421          * all transfers have finished. It may disable any SPI hardware as
 422          * appropriate.
 423          *
 424          * @dev:        The SPI slave
 425          */
 426         int (*release_bus)(struct udevice *dev);
 427
 428         /**
 429          * Set the word length for SPI transactions
 430          *
 431          * Set the word length (number of bits per word) for SPI transactions.
 432          *
 433          * @bus:        The SPI slave
 434          * @wordlen:    The number of bits in a word
 435          *
 436          * Returns: 0 on success, -ve on failure.
 437          */
 438         int (*set_wordlen)(struct udevice *dev, unsigned int wordlen);
 439
 440         /**
 441          * SPI transfer
 442          *
 443          * This writes "bitlen" bits out the SPI MOSI port and simultaneously
 444          * clocks "bitlen" bits in the SPI MISO port.  That's just the way SPI
 445          * works.
 446          *
 447          * The source of the outgoing bits is the "dout" parameter and the
 448          * destination of the input bits is the "din" parameter.  Note that
 449          * "dout" and "din" can point to the same memory location, in which
 450          * case the input data overwrites the output data (since both are
 451          * buffered by temporary variables, this is OK).
 452          *
 453          * spi_xfer() interface:
 454          * @dev:        The slave device to communicate with
 455          * @bitlen:     How many bits to write and read.
 456          * @dout:       Pointer to a string of bits to send out.  The bits are
 457          *              held in a byte array and are sent MSB first.
 458          * @din:        Pointer to a string of bits that will be filled in.
 459          * @flags:      A bitwise combination of SPI_XFER_* flags.
 460          *
 461          * Returns: 0 on success, not -1 on failure
 462          */
 463         int (*xfer)(struct udevice *dev, unsigned int bitlen, const void *dout,
 464                     void *din, unsigned long flags);
 465
 466         /**
 467          * Optimized handlers for SPI memory-like operations.
 468          *
 469          * Optimized/dedicated operations for interactions with SPI memory. This
 470          * field is optional and should only be implemented if the controller
 471          * has native support for memory like operations.
 472          */
 473         const struct spi_controller_mem_ops *mem_ops;
 474
 475         /**
 476          * Set transfer speed.
 477          * This sets a new speed to be applied for next spi_xfer().
 478          * @bus:        The SPI bus
 479          * @hz:         The transfer speed
 480          * @return 0 if OK, -ve on error
 481          */
 482         int (*set_speed)(struct udevice *bus, uint hz);
 483
 484         /**
 485          * Set the SPI mode/flags
 486          *
 487          * It is unclear if we want to set speed and mode together instead
 488          * of separately.
 489          *
 490          * @bus:        The SPI bus
 491          * @mode:       Requested SPI mode (SPI_... flags)
 492          * @return 0 if OK, -ve on error
 493          */
 494         int (*set_mode)(struct udevice *bus, uint mode);
 495
 496         /**
 497          * Get information on a chip select
 498          *
 499          * This is only called when the SPI uclass does not know about a
 500          * chip select, i.e. it has no attached device. It gives the driver
 501          * a chance to allow activity on that chip select even so.
 502          *
 503          * @bus:        The SPI bus
 504          * @cs:         The chip select (0..n-1)
 505          * @info:       Returns information about the chip select, if valid.
 506          *              On entry info->dev is NULL
 507          * @return 0 if OK (and @info is set up), -EINVAL if the chip select
 508          *         is invalid, other -ve value on error
 509          */
 510         int (*cs_info)(struct udevice *bus, uint cs, struct spi_cs_info *info);
 511
 512         /**
 513          * get_mmap() - Get memory-mapped SPI
 514          *
 515          * @dev:        The SPI flash slave device
 516          * @map_basep:  Returns base memory address for mapped SPI
 517          * @map_sizep:  Returns size of mapped SPI
 518          * @offsetp:    Returns start offset of SPI flash where the map works
 519          *      correctly (offsets before this are not visible)
 520          * @return 0 if OK, -EFAULT if memory mapping is not available
 521          */
 522         int (*get_mmap)(struct udevice *dev, ulong *map_basep,
 523                         uint *map_sizep, uint *offsetp);
 524 };
 525
 526 struct dm_spi_emul_ops {
 527         /**
 528          * SPI transfer
 529          *
 530          * This writes "bitlen" bits out the SPI MOSI port and simultaneously
 531          * clocks "bitlen" bits in the SPI MISO port.  That's just the way SPI
 532          * works. Here the device is a slave.
 533          *
 534          * The source of the outgoing bits is the "dout" parameter and the
 535          * destination of the input bits is the "din" parameter.  Note that
 536          * "dout" and "din" can point to the same memory location, in which
 537          * case the input data overwrites the output data (since both are
 538          * buffered by temporary variables, this is OK).
 539          *
 540          * spi_xfer() interface:
 541          * @slave:      The SPI slave which will be sending/receiving the data.
 542          * @bitlen:     How many bits to write and read.
 543          * @dout:       Pointer to a string of bits sent to the device. The
 544          *              bits are held in a byte array and are sent MSB first.
 545          * @din:        Pointer to a string of bits that will be sent back to
 546          *              the master.
 547          * @flags:      A bitwise combination of SPI_XFER_* flags.
 548          *
 549          * Returns: 0 on success, not -1 on failure
 550          */
 551         int (*xfer)(struct udevice *slave, unsigned int bitlen,
 552                     const void *dout, void *din, unsigned long flags);
 553 };
 554
 555 /**
 556  * spi_find_bus_and_cs() - Find bus and slave devices by number
 557  *
 558  * Given a bus number and chip select, this finds the corresponding bus
 559  * device and slave device. Neither device is activated by this function,
 560  * although they may have been activated previously.
 561  *
 562  * @busnum:     SPI bus number
 563  * @cs:         Chip select to look for
 564  * @busp:       Returns bus device
 565  * @devp:       Return slave device
 566  * Return: 0 if found, -ENODEV on error
 567  */
 568 int spi_find_bus_and_cs(int busnum, int cs, struct udevice **busp,
 569                         struct udevice **devp);
 570
 571 /**
 572  * spi_get_bus_and_cs() - Find and activate bus and slave devices by number
 573  *
 574  * Given a bus number and chip select, this finds the corresponding bus
 575  * device and slave device.
 576  *
 577  * @busnum:     SPI bus number
 578  * @cs:         Chip select to look for
 579  * @busp:       Returns bus device
 580  * @devp:       Return slave device
 581  * @return 0 if found, -ve on error
 582  */
 583 int spi_get_bus_and_cs(int busnum, int cs,
 584                        struct udevice **busp, struct spi_slave **devp);
 585
 586 /**
 587  * _spi_get_bus_and_cs() - Find and activate bus and slave devices by number
 588  * As spi_flash_probe(), This is an old-style function. We should remove
 589  * it when all SPI flash drivers use dm
 590  *
 591  * Given a bus number and chip select, this finds the corresponding bus
 592  * device and slave device.
 593  *
 594  * If no such slave exists, and drv_name is not NULL, then a new slave device
 595  * is automatically bound on this chip select with requested speed and mode.
 596  *
 597  * Ths new slave device is probed ready for use with the speed and mode
 598  * from plat when available or the requested values.
 599  *
 600  * @busnum:     SPI bus number
 601  * @cs:         Chip select to look for
 602  * @speed:      SPI speed to use for this slave when not available in plat
 603  * @mode:       SPI mode to use for this slave when not available in plat
 604  * @drv_name:   Name of driver to attach to this chip select
 605  * @dev_name:   Name of the new device thus created
 606  * @busp:       Returns bus device
 607  * @devp:       Return slave device
 608  * Return: 0 if found, -ve on error
 609  */
 610 int _spi_get_bus_and_cs(int busnum, int cs, int speed, int mode,
 611                         const char *drv_name, const char *dev_name,
 612                         struct udevice **busp, struct spi_slave **devp);
 613
 614 /**
 615  * spi_chip_select() - Get the chip select for a slave
 616  *
 617  * Return: the chip select this slave is attached to
 618  */
 619 int spi_chip_select(struct udevice *slave);
 620
 621 /**
 622  * spi_find_chip_select() - Find the slave attached to chip select
 623  *
 624  * @bus:        SPI bus to search
 625  * @cs:         Chip select to look for
 626  * @devp:       Returns the slave device if found
 627  * Return: 0 if found, -EINVAL if cs is invalid, -ENODEV if no device attached,
 628  *         other -ve value on error
 629  */
 630 int spi_find_chip_select(struct udevice *bus, int cs, struct udevice **devp);
 631
 632 /**
 633  * spi_slave_of_to_plat() - decode standard SPI platform data
 634  *
 635  * This decodes the speed and mode for a slave from a device tree node
 636  *
 637  * @blob:       Device tree blob
 638  * @node:       Node offset to read from
 639  * @plat:       Place to put the decoded information
 640  */
 641 int spi_slave_of_to_plat(struct udevice *dev, struct dm_spi_slave_plat *plat);
 642
 643 /**
 644  * spi_cs_info() - Check information on a chip select
 645  *
 646  * This checks a particular chip select on a bus to see if it has a device
 647  * attached, or is even valid.
 648  *
 649  * @bus:        The SPI bus
 650  * @cs:         The chip select (0..n-1)
 651  * @info:       Returns information about the chip select, if valid
 652  * Return: 0 if OK (and @info is set up), -ENODEV if the chip select
 653  *         is invalid, other -ve value on error
 654  */
 655 int spi_cs_info(struct udevice *bus, uint cs, struct spi_cs_info *info);
 656
 657 struct sandbox_state;
 658
 659 /**
 660  * sandbox_spi_get_emul() - get an emulator for a SPI slave
 661  *
 662  * This provides a way to attach an emulated SPI device to a particular SPI
 663  * slave, so that xfer() operations on the slave will be handled by the
 664  * emulator. If a emulator already exists on that chip select it is returned.
 665  * Otherwise one is created.
 666  *
 667  * @state:      Sandbox state
 668  * @bus:        SPI bus requesting the emulator
 669  * @slave:      SPI slave device requesting the emulator
 670  * @emuip:      Returns pointer to emulator
 671  * Return: 0 if OK, -ve on error
 672  */
 673 int sandbox_spi_get_emul(struct sandbox_state *state,
 674                          struct udevice *bus, struct udevice *slave,
 675                          struct udevice **emulp);
 676
 677 /**
 678  * Claim the bus and prepare it for communication with a given slave.
 679  *
 680  * This must be called before doing any transfers with a SPI slave. It
 681  * will enable and initialize any SPI hardware as necessary, and make
 682  * sure that the SCK line is in the correct idle state. It is not
 683  * allowed to claim the same bus for several slaves without releasing
 684  * the bus in between.
 685  *
 686  * @dev:        The SPI slave device
 687  *
 688  * Returns: 0 if the bus was claimed successfully, or a negative value
 689  * if it wasn't.
 690  */
 691 int dm_spi_claim_bus(struct udevice *dev);
 692
 693 /**
 694  * Release the SPI bus
 695  *
 696  * This must be called once for every call to dm_spi_claim_bus() after
 697  * all transfers have finished. It may disable any SPI hardware as
 698  * appropriate.
 699  *
 700  * @slave:      The SPI slave device
 701  */
 702 void dm_spi_release_bus(struct udevice *dev);
 703
 704 /**
 705  * SPI transfer
 706  *
 707  * This writes "bitlen" bits out the SPI MOSI port and simultaneously clocks
 708  * "bitlen" bits in the SPI MISO port.  That's just the way SPI works.
 709  *
 710  * The source of the outgoing bits is the "dout" parameter and the
 711  * destination of the input bits is the "din" parameter.  Note that "dout"
 712  * and "din" can point to the same memory location, in which case the
 713  * input data overwrites the output data (since both are buffered by
 714  * temporary variables, this is OK).
 715  *
 716  * dm_spi_xfer() interface:
 717  * @dev:        The SPI slave device which will be sending/receiving the data.
 718  * @bitlen:     How many bits to write and read.
 719  * @dout:       Pointer to a string of bits to send out.  The bits are
 720  *              held in a byte array and are sent MSB first.
 721  * @din:        Pointer to a string of bits that will be filled in.
 722  * @flags:      A bitwise combination of SPI_XFER_* flags.
 723  *
 724  * Returns: 0 on success, not 0 on failure
 725  */
 726 int dm_spi_xfer(struct udevice *dev, unsigned int bitlen,
 727                 const void *dout, void *din, unsigned long flags);
 728
 729 /**
 730  * spi_get_mmap() - Get memory-mapped SPI
 731  *
 732  * @dev:        SPI slave device to check
 733  * @map_basep:  Returns base memory address for mapped SPI
 734  * @map_sizep:  Returns size of mapped SPI
 735  * @offsetp:    Returns start offset of SPI flash where the map works
 736  *      correctly (offsets before this are not visible)
 737  * Return: 0 if OK, -ENOSYS if no operation, -EFAULT if memory mapping is not
 738  *      available
 739  */
 740 int dm_spi_get_mmap(struct udevice *dev, ulong *map_basep, uint *map_sizep,
 741                     uint *offsetp);
 742
 743 /* Access the operations for a SPI device */
 744 #define spi_get_ops(dev)        ((struct dm_spi_ops *)(dev)->driver->ops)
 745 #define spi_emul_get_ops(dev)   ((struct dm_spi_emul_ops *)(dev)->driver->ops)
 746
 747 #endif  /* _SPI_H_ */