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