'\" t .\" Title: struct spi_master .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.78.1 .\" Date: January 2017 .\" Manual: Serial Peripheral Interface (SPI) .\" Source: Kernel Hackers Manual 4.8.15 .\" Language: English .\" .TH "STRUCT SPI_MASTER" "9" "January 2017" "Kernel Hackers Manual 4\&.8\&." "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_master \- interface to SPI master controller .SH "SYNOPSIS" .sp .nf struct spi_master { struct device dev; struct list_head list; s16 bus_num; u16 num_chipselect; u16 dma_alignment; u16 mode_bits; u32 bits_per_word_mask; #define SPI_BPW_MASK(bits) BIT((bits) \- 1) #define SPI_BIT_MASK(bits) (((bits) == 32) ? ~0U : (BIT(bits) \- 1)) #define SPI_BPW_RANGE_MASK(min# max) (SPI_BIT_MASK(max) \- SPI_BIT_MASK(min \- 1)) u32 min_speed_hz; u32 max_speed_hz; u16 flags; #define SPI_MASTER_HALF_DUPLEX BIT(0) #define SPI_MASTER_NO_RX BIT(1) #define SPI_MASTER_NO_TX BIT(2) #define SPI_MASTER_MUST_RX BIT(3) #define SPI_MASTER_MUST_TX BIT(4) size_t (* max_transfer_size) (struct spi_device *spi); struct mutex io_mutex; spinlock_t bus_lock_spinlock; struct mutex bus_lock_mutex; bool bus_lock_flag; int (* setup) (struct spi_device *spi); int (* transfer) (struct spi_device *spi,struct spi_message *mesg); void (* cleanup) (struct spi_device *spi); bool (* can_dma) (struct spi_master *master,struct spi_device *spi,struct spi_transfer *xfer); bool queued; struct kthread_worker kworker; struct task_struct * kworker_task; struct kthread_work pump_messages; spinlock_t queue_lock; struct list_head queue; struct spi_message * cur_msg; bool idling; bool busy; bool running; bool rt; bool auto_runtime_pm; bool cur_msg_prepared; bool cur_msg_mapped; struct completion xfer_completion; size_t max_dma_len; int (* prepare_transfer_hardware) (struct spi_master *master); int (* transfer_one_message) (struct spi_master *master,struct spi_message *mesg); int (* unprepare_transfer_hardware) (struct spi_master *master); int (* prepare_message) (struct spi_master *master,struct spi_message *message); int (* unprepare_message) (struct spi_master *master,struct spi_message *message); int (* spi_flash_read) (struct spi_device *spi,struct spi_flash_read_message *msg); bool (* flash_read_supported) (struct spi_device *spi); void (* set_cs) (struct spi_device *spi, bool enable); int (* transfer_one) (struct spi_master *master, struct spi_device *spi,struct spi_transfer *transfer); void (* handle_err) (struct spi_master *master,struct spi_message *message); int * cs_gpios; struct spi_statistics statistics; struct dma_chan * dma_tx; struct dma_chan * dma_rx; void * dummy_rx; void * dummy_tx; int (* fw_translate_cs) (struct spi_master *master, unsigned cs); }; .fi .SH "MEMBERS" .PP dev .RS 4 device interface to this driver .RE .PP list .RS 4 link with the global spi_master list .RE .PP bus_num .RS 4 board\-specific (and often SOC\-specific) identifier for a given SPI controller\&. .RE .PP num_chipselect .RS 4 chipselects are used to distinguish individual SPI slaves, and are numbered from zero to num_chipselects\&. each slave has a chipselect signal, but it\*(Aqs common that not every chipselect is connected to a slave\&. .RE .PP dma_alignment .RS 4 SPI controller constraint on DMA buffers alignment\&. .RE .PP mode_bits .RS 4 flags understood by this controller driver .RE .PP bits_per_word_mask .RS 4 A mask indicating which values of bits_per_word are supported by the driver\&. Bit n indicates that a bits_per_word n+1 is supported\&. If set, the SPI core will reject any transfer with an unsupported bits_per_word\&. If not set, this value is simply ignored, and it\*(Aqs up to the individual driver to perform any validation\&. .RE .PP min_speed_hz .RS 4 Lowest supported transfer speed .RE .PP max_speed_hz .RS 4 Highest supported transfer speed .RE .PP flags .RS 4 other constraints relevant to this driver .RE .PP max_transfer_size .RS 4 function that returns the max transfer size for a spi_device; may be \fBNULL\fR, so the default \fBSIZE_MAX\fR will be used\&. .RE .PP io_mutex .RS 4 mutex for physical bus access .RE .PP bus_lock_spinlock .RS 4 spinlock for SPI bus locking .RE .PP bus_lock_mutex .RS 4 mutex for exclusion of multiple callers .RE .PP bus_lock_flag .RS 4 indicates that the SPI bus is locked for exclusive use .RE .PP setup .RS 4 updates the device mode and clocking records used by a device\*(Aqs SPI controller; protocol code may call this\&. This must fail if an unrecognized or unsupported mode is requested\&. It\*(Aqs always safe to call this unless transfers are pending on the device whose settings are being modified\&. .RE .PP transfer .RS 4 adds a message to the controller\*(Aqs transfer queue\&. .RE .PP cleanup .RS 4 frees controller\-specific state .RE .PP can_dma .RS 4 determine whether this master supports DMA .RE .PP queued .RS 4 whether this master is providing an internal message queue .RE .PP kworker .RS 4 thread struct for message pump .RE .PP kworker_task .RS 4 pointer to task for message pump kworker thread .RE .PP pump_messages .RS 4 work struct for scheduling work to the message pump .RE .PP queue_lock .RS 4 spinlock to syncronise access to message queue .RE .PP queue .RS 4 message queue .RE .PP cur_msg .RS 4 the currently in\-flight message .RE .PP idling .RS 4 the device is entering idle state .RE .PP busy .RS 4 message pump is busy .RE .PP running .RS 4 message pump is running .RE .PP rt .RS 4 whether this queue is set to run as a realtime task .RE .PP auto_runtime_pm .RS 4 the core should ensure a runtime PM reference is held while the hardware is prepared, using the parent device for the spidev .RE .PP cur_msg_prepared .RS 4 spi_prepare_message was called for the currently in\-flight message .RE .PP cur_msg_mapped .RS 4 message has been mapped for DMA .RE .PP xfer_completion .RS 4 used by core \fBtransfer_one_message\fR .RE .PP max_dma_len .RS 4 Maximum length of a DMA transfer for the device\&. .RE .PP prepare_transfer_hardware .RS 4 a message will soon arrive from the queue so the subsystem requests the driver to prepare the transfer hardware by issuing this call .RE .PP transfer_one_message .RS 4 the subsystem calls the driver to transfer a single message while queuing transfers that arrive in the meantime\&. When the driver is finished with this message, it must call \fBspi_finalize_current_message\fR so the subsystem can issue the next message .RE .PP unprepare_transfer_hardware .RS 4 there are currently no more messages on the queue so the subsystem notifies the driver that it may relax the hardware by issuing this call .RE .PP prepare_message .RS 4 set up the controller to transfer a single message, for example doing DMA mapping\&. Called from threaded context\&. .RE .PP unprepare_message .RS 4 undo any work done by \fBprepare_message\fR\&. .RE .PP spi_flash_read .RS 4 to support spi\-controller hardwares that provide accelerated interface to read from flash devices\&. .RE .PP flash_read_supported .RS 4 spi device supports flash read .RE .PP set_cs .RS 4 set the logic level of the chip select line\&. May be called from interrupt context\&. .RE .PP transfer_one .RS 4 transfer a single spi_transfer\&. \- return 0 if the transfer is finished, \- return 1 if the transfer is still in progress\&. When the driver is finished with this transfer it must call \fBspi_finalize_current_transfer\fR so the subsystem can issue the next transfer\&. Note: transfer_one and transfer_one_message are mutually exclusive; when both are set, the generic subsystem does not call your transfer_one callback\&. .RE .PP handle_err .RS 4 the subsystem calls the driver to handle an error that occurs in the generic implementation of \fBtransfer_one_message\fR\&. .RE .PP cs_gpios .RS 4 Array of GPIOs to use as chip select lines; one per CS number\&. Any individual value may be \-ENOENT for CS lines that are not GPIOs (driven by the SPI controller itself)\&. .RE .PP statistics .RS 4 statistics for the spi_master .RE .PP dma_tx .RS 4 DMA transmit channel .RE .PP dma_rx .RS 4 DMA receive channel .RE .PP dummy_rx .RS 4 dummy receive buffer for full\-duplex devices .RE .PP dummy_tx .RS 4 dummy transmit buffer for full\-duplex devices .RE .PP fw_translate_cs .RS 4 If the boot firmware uses different numbering scheme what Linux expects, this optional hook can be used to translate between the two\&. .RE .SH "DESCRIPTION" .PP Each SPI master controller can communicate with one or more \fIspi_device\fR children\&. These make a small bus, sharing MOSI, MISO and SCK signals but not chip select signals\&. Each device may be configured to use a different clock rate, since those shared signals are ignored unless the chip is selected\&. .PP The driver for an SPI controller manages access to those devices through a queue of spi_message transactions, copying data between CPU memory and an SPI slave device\&. For each such message it queues, it calls the message\*(Aqs completion function when the transaction completes\&. .SH "COPYRIGHT" .br