1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>struct spi_master</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-module-spi-driver.html" title="module_spi_driver"><link rel="next" href="API-struct-spi-transfer.html" title="struct spi_transfer"></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_master</span></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-module-spi-driver.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-transfer.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="API-struct-spi-master"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>struct spi_master — 2 interface to SPI master controller 3 </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="programlisting"> 4struct spi_master { 5 struct device dev; 6 struct list_head list; 7 s16 bus_num; 8 u16 num_chipselect; 9 u16 dma_alignment; 10 u16 mode_bits; 11 u32 bits_per_word_mask; 12#define SPI_BPW_MASK(bits) BIT((bits) - 1) 13#define SPI_BIT_MASK(bits) (((bits) == 32) ? ~0U : (BIT(bits) - 1)) 14#define SPI_BPW_RANGE_MASK(min# max) (SPI_BIT_MASK(max) - SPI_BIT_MASK(min - 1)) 15 u32 min_speed_hz; 16 u32 max_speed_hz; 17 u16 flags; 18#define SPI_MASTER_HALF_DUPLEX BIT(0) 19#define SPI_MASTER_NO_RX BIT(1) 20#define SPI_MASTER_NO_TX BIT(2) 21#define SPI_MASTER_MUST_RX BIT(3) 22#define SPI_MASTER_MUST_TX BIT(4) 23 spinlock_t bus_lock_spinlock; 24 struct mutex bus_lock_mutex; 25 bool bus_lock_flag; 26 int (* setup) (struct spi_device *spi); 27 int (* transfer) (struct spi_device *spi,struct spi_message *mesg); 28 void (* cleanup) (struct spi_device *spi); 29 bool (* can_dma) (struct spi_master *master,struct spi_device *spi,struct spi_transfer *xfer); 30 bool queued; 31 struct kthread_worker kworker; 32 struct task_struct * kworker_task; 33 struct kthread_work pump_messages; 34 spinlock_t queue_lock; 35 struct list_head queue; 36 struct spi_message * cur_msg; 37 bool idling; 38 bool busy; 39 bool running; 40 bool rt; 41 bool auto_runtime_pm; 42 bool cur_msg_prepared; 43 bool cur_msg_mapped; 44 struct completion xfer_completion; 45 size_t max_dma_len; 46 int (* prepare_transfer_hardware) (struct spi_master *master); 47 int (* transfer_one_message) (struct spi_master *master,struct spi_message *mesg); 48 int (* unprepare_transfer_hardware) (struct spi_master *master); 49 int (* prepare_message) (struct spi_master *master,struct spi_message *message); 50 int (* unprepare_message) (struct spi_master *master,struct spi_message *message); 51 void (* set_cs) (struct spi_device *spi, bool enable); 52 int (* transfer_one) (struct spi_master *master, struct spi_device *spi,struct spi_transfer *transfer); 53 void (* handle_err) (struct spi_master *master,struct spi_message *message); 54 int * cs_gpios; 55 struct dma_chan * dma_tx; 56 struct dma_chan * dma_rx; 57 void * dummy_rx; 58 void * dummy_tx; 59}; </pre></div><div class="refsect1"><a name="idp1114861100"></a><h2>Members</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term">dev</span></dt><dd><p> 60 device interface to this driver 61 </p></dd><dt><span class="term">list</span></dt><dd><p> 62 link with the global spi_master list 63 </p></dd><dt><span class="term">bus_num</span></dt><dd><p> 64 board-specific (and often SOC-specific) identifier for a 65 given SPI controller. 66 </p></dd><dt><span class="term">num_chipselect</span></dt><dd><p> 67 chipselects are used to distinguish individual 68 SPI slaves, and are numbered from zero to num_chipselects. 69 each slave has a chipselect signal, but it's common that not 70 every chipselect is connected to a slave. 71 </p></dd><dt><span class="term">dma_alignment</span></dt><dd><p> 72 SPI controller constraint on DMA buffers alignment. 73 </p></dd><dt><span class="term">mode_bits</span></dt><dd><p> 74 flags understood by this controller driver 75 </p></dd><dt><span class="term">bits_per_word_mask</span></dt><dd><p> 76 A mask indicating which values of bits_per_word are 77 supported by the driver. Bit n indicates that a bits_per_word n+1 is 78 supported. If set, the SPI core will reject any transfer with an 79 unsupported bits_per_word. If not set, this value is simply ignored, 80 and it's up to the individual driver to perform any validation. 81 </p></dd><dt><span class="term">min_speed_hz</span></dt><dd><p> 82 Lowest supported transfer speed 83 </p></dd><dt><span class="term">max_speed_hz</span></dt><dd><p> 84 Highest supported transfer speed 85 </p></dd><dt><span class="term">flags</span></dt><dd><p> 86 other constraints relevant to this driver 87 </p></dd><dt><span class="term">bus_lock_spinlock</span></dt><dd><p> 88 spinlock for SPI bus locking 89 </p></dd><dt><span class="term">bus_lock_mutex</span></dt><dd><p> 90 mutex for SPI bus locking 91 </p></dd><dt><span class="term">bus_lock_flag</span></dt><dd><p> 92 indicates that the SPI bus is locked for exclusive use 93 </p></dd><dt><span class="term">setup</span></dt><dd><p> 94 updates the device mode and clocking records used by a 95 device's SPI controller; protocol code may call this. This 96 must fail if an unrecognized or unsupported mode is requested. 97 It's always safe to call this unless transfers are pending on 98 the device whose settings are being modified. 99 </p></dd><dt><span class="term">transfer</span></dt><dd><p> 100 adds a message to the controller's transfer queue. 101 </p></dd><dt><span class="term">cleanup</span></dt><dd><p> 102 frees controller-specific state 103 </p></dd><dt><span class="term">can_dma</span></dt><dd><p> 104 determine whether this master supports DMA 105 </p></dd><dt><span class="term">queued</span></dt><dd><p> 106 whether this master is providing an internal message queue 107 </p></dd><dt><span class="term">kworker</span></dt><dd><p> 108 thread struct for message pump 109 </p></dd><dt><span class="term">kworker_task</span></dt><dd><p> 110 pointer to task for message pump kworker thread 111 </p></dd><dt><span class="term">pump_messages</span></dt><dd><p> 112 work struct for scheduling work to the message pump 113 </p></dd><dt><span class="term">queue_lock</span></dt><dd><p> 114 spinlock to syncronise access to message queue 115 </p></dd><dt><span class="term">queue</span></dt><dd><p> 116 message queue 117 </p></dd><dt><span class="term">cur_msg</span></dt><dd><p> 118 the currently in-flight message 119 </p></dd><dt><span class="term">idling</span></dt><dd><p> 120 the device is entering idle state 121 </p></dd><dt><span class="term">busy</span></dt><dd><p> 122 message pump is busy 123 </p></dd><dt><span class="term">running</span></dt><dd><p> 124 message pump is running 125 </p></dd><dt><span class="term">rt</span></dt><dd><p> 126 whether this queue is set to run as a realtime task 127 </p></dd><dt><span class="term">auto_runtime_pm</span></dt><dd><p> 128 the core should ensure a runtime PM reference is held 129 while the hardware is prepared, using the parent 130 device for the spidev 131 </p></dd><dt><span class="term">cur_msg_prepared</span></dt><dd><p> 132 spi_prepare_message was called for the currently 133 in-flight message 134 </p></dd><dt><span class="term">cur_msg_mapped</span></dt><dd><p> 135 message has been mapped for DMA 136 </p></dd><dt><span class="term">xfer_completion</span></dt><dd><p> 137 used by core <code class="function">transfer_one_message</code> 138 </p></dd><dt><span class="term">max_dma_len</span></dt><dd><p> 139 Maximum length of a DMA transfer for the device. 140 </p></dd><dt><span class="term">prepare_transfer_hardware</span></dt><dd><p> 141 a message will soon arrive from the queue 142 so the subsystem requests the driver to prepare the transfer hardware 143 by issuing this call 144 </p></dd><dt><span class="term">transfer_one_message</span></dt><dd><p> 145 the subsystem calls the driver to transfer a single 146 message while queuing transfers that arrive in the meantime. When the 147 driver is finished with this message, it must call 148 <code class="function">spi_finalize_current_message</code> so the subsystem can issue the next 149 message 150 </p></dd><dt><span class="term">unprepare_transfer_hardware</span></dt><dd><p> 151 there are currently no more messages on the 152 queue so the subsystem notifies the driver that it may relax the 153 hardware by issuing this call 154 </p></dd><dt><span class="term">prepare_message</span></dt><dd><p> 155 set up the controller to transfer a single message, 156 for example doing DMA mapping. Called from threaded 157 context. 158 </p></dd><dt><span class="term">unprepare_message</span></dt><dd><p> 159 undo any work done by <code class="function">prepare_message</code>. 160 </p></dd><dt><span class="term">set_cs</span></dt><dd><p> 161 set the logic level of the chip select line. May be called 162 from interrupt context. 163 </p></dd><dt><span class="term">transfer_one</span></dt><dd><p> 164 transfer a single spi_transfer. 165 - return 0 if the transfer is finished, 166 - return 1 if the transfer is still in progress. When 167 the driver is finished with this transfer it must 168 call <code class="function">spi_finalize_current_transfer</code> so the subsystem 169 can issue the next transfer. Note: transfer_one and 170 transfer_one_message are mutually exclusive; when both 171 are set, the generic subsystem does not call your 172 transfer_one callback. 173 </p></dd><dt><span class="term">handle_err</span></dt><dd><p> 174 the subsystem calls the driver to handle an error that occurs 175 in the generic implementation of <code class="function">transfer_one_message</code>. 176 </p></dd><dt><span class="term">cs_gpios</span></dt><dd><p> 177 Array of GPIOs to use as chip select lines; one per CS 178 number. Any individual value may be -ENOENT for CS lines that 179 are not GPIOs (driven by the SPI controller itself). 180 </p></dd><dt><span class="term">dma_tx</span></dt><dd><p> 181 DMA transmit channel 182 </p></dd><dt><span class="term">dma_rx</span></dt><dd><p> 183 DMA receive channel 184 </p></dd><dt><span class="term">dummy_rx</span></dt><dd><p> 185 dummy receive buffer for full-duplex devices 186 </p></dd><dt><span class="term">dummy_tx</span></dt><dd><p> 187 dummy transmit buffer for full-duplex devices 188 </p></dd></dl></div></div><div class="refsect1"><a name="idp1114898436"></a><h2>Description</h2><p> 189 Each SPI master controller can communicate with one or more <em class="parameter"><code>spi_device</code></em> 190 children. These make a small bus, sharing MOSI, MISO and SCK signals 191 but not chip select signals. Each device may be configured to use a 192 different clock rate, since those shared signals are ignored unless 193 the chip is selected. 194 </p><p> 195 196 The driver for an SPI controller manages access to those devices through 197 a queue of spi_message transactions, copying data between CPU memory and 198 an SPI slave device. For each such message it queues, it calls the 199 message's completion function when the transaction completes. 200</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-module-spi-driver.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-transfer.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">module_spi_driver</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_transfer</span></td></tr></table></div></body></html> 201