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