'\" t .\" Title: struct spi_transfer .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.78.1 .\" Date: May 2018 .\" Manual: Serial Peripheral Interface (SPI) .\" Source: Kernel Hackers Manual 3.16.56 .\" Language: English .\" .TH "STRUCT SPI_TRANSFER" "9" "May 2018" "Kernel Hackers Manual 3\&.16\&" "Serial Peripheral Interface (S" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" struct_spi_transfer \- a read/write buffer pair .SH "SYNOPSIS" .sp .nf 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; }; .fi .SH "MEMBERS" .PP tx_buf .RS 4 data to be written (dma\-safe memory), or NULL .RE .PP rx_buf .RS 4 data to be read (dma\-safe memory), or NULL .RE .PP len .RS 4 size of rx and tx buffers (in bytes) .RE .PP tx_dma .RS 4 DMA address of tx_buf, if \fIspi_message\fR\&.is_dma_mapped .RE .PP rx_dma .RS 4 DMA address of rx_buf, if \fIspi_message\fR\&.is_dma_mapped .RE .PP tx_sg .RS 4 Scatterlist for transmit, currently not for client use .RE .PP rx_sg .RS 4 Scatterlist for receive, currently not for client use .RE .PP cs_change .RS 4 affects chipselect after this transfer completes .RE .PP tx_nbits .RS 4 number of bits used for writing\&. If 0 the default (SPI_NBITS_SINGLE) is used\&. .RE .PP rx_nbits .RS 4 number of bits used for reading\&. If 0 the default (SPI_NBITS_SINGLE) is used\&. .RE .PP bits_per_word .RS 4 select a bits_per_word other than the device default for this transfer\&. If 0 the default (from \fIspi_device\fR) is used\&. .RE .PP delay_usecs .RS 4 microseconds to delay after this transfer before (optionally) changing the chipselect status, then starting the next transfer or completing this \fIspi_message\fR\&. .RE .PP speed_hz .RS 4 Select a speed other than the device default for this transfer\&. If 0 the default (from \fIspi_device\fR) is used\&. .RE .PP transfer_list .RS 4 transfers are sequenced through \fIspi_message\fR\&.transfers .RE .SH "DESCRIPTION" .PP SPI transfers always write the same number of bytes as they read\&. Protocol drivers should always provide \fIrx_buf\fR and/or \fItx_buf\fR\&. 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\&. .PP If the transmit buffer is null, zeroes will be shifted out while filling \fIrx_buf\fR\&. If the receive buffer is null, the data shifted in will be discarded\&. Only \(lqlen\(rq bytes shift out (or in)\&. It\*(Aqs 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\&.) .PP 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 (\fIlen\fR = 2N) and hold N sixteen bit words in CPU byte order\&. .PP 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\&. .PP 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\&. .PP (i) If the transfer isn\*(Aqt 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\&. .PP (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\&. .PP When SPI can transfer in 1x,2x or 4x\&. It can get this transfer information from device through \fItx_nbits\fR and \fIrx_nbits\fR\&. 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\&. .PP 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\*(Aqt set up explicitly, to insulate against future API updates\&. After you submit a message and its transfers, ignore them until its completion callback\&. .SH "COPYRIGHT" .br