1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>struct spi_transfer</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Linux Device Drivers"><link rel="up" href="spi.html" title="Chapter 9. Serial Peripheral Interface (SPI)"><link rel="prev" href="API-struct-spi-master.html" title="struct spi_master"><link rel="next" href="API-struct-spi-message.html" title="struct spi_message"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"><span class="phrase">struct spi_transfer</span></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-struct-spi-master.html">Prev</a> </td><th width="60%" align="center">Chapter 9. Serial Peripheral Interface (SPI)</th><td width="20%" align="right"> <a accesskey="n" href="API-struct-spi-message.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="API-struct-spi-transfer"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>struct spi_transfer — 2 a read/write buffer pair 3 </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="programlisting"> 4struct spi_transfer { 5 const void * tx_buf; 6 void * rx_buf; 7 unsigned len; 8 dma_addr_t tx_dma; 9 dma_addr_t rx_dma; 10 struct sg_table tx_sg; 11 struct sg_table rx_sg; 12 unsigned cs_change:1; 13 unsigned tx_nbits:3; 14 unsigned rx_nbits:3; 15#define SPI_NBITS_SINGLE 0x01 16#define SPI_NBITS_DUAL 0x02 17#define SPI_NBITS_QUAD 0x04 18 u8 bits_per_word; 19 u16 delay_usecs; 20 u32 speed_hz; 21 struct list_head transfer_list; 22}; </pre></div><div class="refsect1"><a name="idp1114904372"></a><h2>Members</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term">tx_buf</span></dt><dd><p> 23 data to be written (dma-safe memory), or NULL 24 </p></dd><dt><span class="term">rx_buf</span></dt><dd><p> 25 data to be read (dma-safe memory), or NULL 26 </p></dd><dt><span class="term">len</span></dt><dd><p> 27 size of rx and tx buffers (in bytes) 28 </p></dd><dt><span class="term">tx_dma</span></dt><dd><p> 29 DMA address of tx_buf, if <em class="parameter"><code>spi_message</code></em>.is_dma_mapped 30 </p></dd><dt><span class="term">rx_dma</span></dt><dd><p> 31 DMA address of rx_buf, if <em class="parameter"><code>spi_message</code></em>.is_dma_mapped 32 </p></dd><dt><span class="term">tx_sg</span></dt><dd><p> 33 Scatterlist for transmit, currently not for client use 34 </p></dd><dt><span class="term">rx_sg</span></dt><dd><p> 35 Scatterlist for receive, currently not for client use 36 </p></dd><dt><span class="term">cs_change</span></dt><dd><p> 37 affects chipselect after this transfer completes 38 </p></dd><dt><span class="term">tx_nbits</span></dt><dd><p> 39 number of bits used for writing. If 0 the default 40 (SPI_NBITS_SINGLE) is used. 41 </p></dd><dt><span class="term">rx_nbits</span></dt><dd><p> 42 number of bits used for reading. If 0 the default 43 (SPI_NBITS_SINGLE) is used. 44 </p></dd><dt><span class="term">bits_per_word</span></dt><dd><p> 45 select a bits_per_word other than the device default 46 for this transfer. If 0 the default (from <em class="parameter"><code>spi_device</code></em>) is used. 47 </p></dd><dt><span class="term">delay_usecs</span></dt><dd><p> 48 microseconds to delay after this transfer before 49 (optionally) changing the chipselect status, then starting 50 the next transfer or completing this <em class="parameter"><code>spi_message</code></em>. 51 </p></dd><dt><span class="term">speed_hz</span></dt><dd><p> 52 Select a speed other than the device default for this 53 transfer. If 0 the default (from <em class="parameter"><code>spi_device</code></em>) is used. 54 </p></dd><dt><span class="term">transfer_list</span></dt><dd><p> 55 transfers are sequenced through <em class="parameter"><code>spi_message</code></em>.transfers 56 </p></dd></dl></div></div><div class="refsect1"><a name="idp1114917452"></a><h2>Description</h2><p> 57 SPI transfers always write the same number of bytes as they read. 58 Protocol drivers should always provide <em class="parameter"><code>rx_buf</code></em> and/or <em class="parameter"><code>tx_buf</code></em>. 59 In some cases, they may also want to provide DMA addresses for 60 the data being transferred; that may reduce overhead, when the 61 underlying driver uses dma. 62 </p><p> 63 64 If the transmit buffer is null, zeroes will be shifted out 65 while filling <em class="parameter"><code>rx_buf</code></em>. If the receive buffer is null, the data 66 shifted in will be discarded. Only <span class="quote">“<span class="quote">len</span>”</span> bytes shift out (or in). 67 It's an error to try to shift out a partial word. (For example, by 68 shifting out three bytes with word size of sixteen or twenty bits; 69 the former uses two bytes per word, the latter uses four bytes.) 70 </p><p> 71 72 In-memory data values are always in native CPU byte order, translated 73 from the wire byte order (big-endian except with SPI_LSB_FIRST). So 74 for example when bits_per_word is sixteen, buffers are 2N bytes long 75 (<em class="parameter"><code>len</code></em> = 2N) and hold N sixteen bit words in CPU byte order. 76 </p><p> 77 78 When the word size of the SPI transfer is not a power-of-two multiple 79 of eight bits, those in-memory words include extra bits. In-memory 80 words are always seen by protocol drivers as right-justified, so the 81 undefined (rx) or unused (tx) bits are always the most significant bits. 82 </p><p> 83 84 All SPI transfers start with the relevant chipselect active. Normally 85 it stays selected until after the last transfer in a message. Drivers 86 can affect the chipselect signal using cs_change. 87 </p><p> 88 89 (i) If the transfer isn't the last one in the message, this flag is 90 used to make the chipselect briefly go inactive in the middle of the 91 message. Toggling chipselect in this way may be needed to terminate 92 a chip command, letting a single spi_message perform all of group of 93 chip transactions together. 94 </p><p> 95 96 (ii) When the transfer is the last one in the message, the chip may 97 stay selected until the next transfer. On multi-device SPI busses 98 with nothing blocking messages going to other devices, this is just 99 a performance hint; starting a message to another device deselects 100 this one. But in other cases, this can be used to ensure correctness. 101 Some devices need protocol transactions to be built from a series of 102 spi_message submissions, where the content of one message is determined 103 by the results of previous messages and where the whole transaction 104 ends when the chipselect goes intactive. 105 </p><p> 106 107 When SPI can transfer in 1x,2x or 4x. It can get this transfer information 108 from device through <em class="parameter"><code>tx_nbits</code></em> and <em class="parameter"><code>rx_nbits</code></em>. In Bi-direction, these 109 two should both be set. User can set transfer mode with SPI_NBITS_SINGLE(1x) 110 SPI_NBITS_DUAL(2x) and SPI_NBITS_QUAD(4x) to support these three transfer. 111 </p><p> 112 113 The code that submits an spi_message (and its spi_transfers) 114 to the lower layers is responsible for managing its memory. 115 Zero-initialize every field you don't set up explicitly, to 116 insulate against future API updates. After you submit a message 117 and its transfers, ignore them until its completion callback. 118</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-struct-spi-master.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="API-struct-spi-message.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">struct spi_master</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span class="phrase">struct spi_message</span></td></tr></table></div></body></html> 119