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