---
name: "struct_spi_transfer"
section: "9"
platform: "linux"
package: "linux-manual-3.16"
version: "3.16.56-1+deb8u1"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/struct_spi_transfer"
---

# struct\_spi\_transfer(9)

a read/write buffer pair

## NAME

struct\_spi\_transfer - a read/write buffer pair

## SYNOPSIS

```
struct spi_transfer {
  const void * tx_buf;
  void * rx_buf;
  unsigned len;
  dma_addr_t tx_dma;
  dma_addr_t rx_dma;
  struct sg_table tx_sg;
  struct sg_table rx_sg;
  unsigned cs_change:1;
  unsigned tx_nbits:3;
  unsigned rx_nbits:3;
#define SPI_NBITS_SINGLE	0x01
#define SPI_NBITS_DUAL		0x02
#define SPI_NBITS_QUAD		0x04
  u8 bits_per_word;
  u16 delay_usecs;
  u32 speed_hz;
  struct list_head transfer_list;
};
```

## MEMBERS

tx\_buf

data to be written (dma-safe memory), or NULL

rx\_buf

data to be read (dma-safe memory), or NULL

len

size of rx and tx buffers (in bytes)

tx\_dma

DMA address of tx\_buf, if *spi\_message*.is\_dma\_mapped

rx\_dma

DMA address of rx\_buf, if *spi\_message*.is\_dma\_mapped

tx\_sg

Scatterlist for transmit, currently not for client use

rx\_sg

Scatterlist for receive, currently not for client use

cs\_change

affects chipselect after this transfer completes

tx\_nbits

number of bits used for writing. If 0 the default (SPI\_NBITS\_SINGLE) is used.

rx\_nbits

number of bits used for reading. If 0 the default (SPI\_NBITS\_SINGLE) is used.

bits\_per\_word

select a bits\_per\_word other than the device default for this transfer. If 0 the default (from *spi\_device*) is used.

delay\_usecs

microseconds to delay after this transfer before (optionally) changing the chipselect status, then starting the next transfer or completing this *spi\_message*.

speed\_hz

Select a speed other than the device default for this transfer. If 0 the default (from *spi\_device*) is used.

transfer\_list

transfers are sequenced through *spi\_message*.transfers

## DESCRIPTION

SPI transfers always write the same number of bytes as they read. Protocol drivers should always provide *rx\_buf* and/or *tx\_buf*. In some cases, they may also want to provide DMA addresses for the data being transferred; that may reduce overhead, when the underlying driver uses dma.

If the transmit buffer is null, zeroes will be shifted out while filling *rx\_buf*. If the receive buffer is null, the data shifted in will be discarded. Only “len” bytes shift out (or in). It's an error to try to shift out a partial word. (For example, by shifting out three bytes with word size of sixteen or twenty bits; the former uses two bytes per word, the latter uses four bytes.)

In-memory data values are always in native CPU byte order, translated from the wire byte order (big-endian except with SPI\_LSB\_FIRST). So for example when bits\_per\_word is sixteen, buffers are 2N bytes long (*len* = 2N) and hold N sixteen bit words in CPU byte order.

When the word size of the SPI transfer is not a power-of-two multiple of eight bits, those in-memory words include extra bits. In-memory words are always seen by protocol drivers as right-justified, so the undefined (rx) or unused (tx) bits are always the most significant bits.

All SPI transfers start with the relevant chipselect active. Normally it stays selected until after the last transfer in a message. Drivers can affect the chipselect signal using cs\_change.

(i) If the transfer isn't the last one in the message, this flag is used to make the chipselect briefly go inactive in the middle of the message. Toggling chipselect in this way may be needed to terminate a chip command, letting a single spi\_message perform all of group of chip transactions together.

(ii) When the transfer is the last one in the message, the chip may stay selected until the next transfer. On multi-device SPI busses with nothing blocking messages going to other devices, this is just a performance hint; starting a message to another device deselects this one. But in other cases, this can be used to ensure correctness. Some devices need protocol transactions to be built from a series of spi\_message submissions, where the content of one message is determined by the results of previous messages and where the whole transaction ends when the chipselect goes intactive.

When SPI can transfer in 1x,2x or 4x. It can get this transfer information from device through *tx\_nbits* and *rx\_nbits*. In Bi-direction, these two should both be set. User can set transfer mode with SPI\_NBITS\_SINGLE(1x) SPI\_NBITS\_DUAL(2x) and SPI\_NBITS\_QUAD(4x) to support these three transfer.

The code that submits an spi\_message (and its spi\_transfers) to the lower layers is responsible for managing its memory. Zero-initialize every field you don't set up explicitly, to insulate against future API updates. After you submit a message and its transfers, ignore them until its completion callback.

## COPYRIGHT