include/spi.h

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