Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  1) Serial Peripheral Interface (SPI)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  2) =================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  3) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) SPI is the "Serial Peripheral Interface", widely used with embedded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) systems because it is a simple and efficient interface: basically a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) multiplexed shift register. Its three signal wires hold a clock (SCK,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) often in the range of 1-20 MHz), a "Master Out, Slave In" (MOSI) data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) line, and a "Master In, Slave Out" (MISO) data line. SPI is a full
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) duplex protocol; for each bit shifted out the MOSI line (one per clock)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) another is shifted in on the MISO line. Those bits are assembled into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) words of various sizes on the way to and from system memory. An
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) additional chipselect line is usually active-low (nCS); four signals are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) normally used for each peripheral, plus sometimes an interrupt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) The SPI bus facilities listed here provide a generalized interface to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) declare SPI busses and devices, manage them according to the standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) Linux driver model, and perform input/output operations. At this time,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) only "master" side interfaces are supported, where Linux talks to SPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) peripherals and does not implement such a peripheral itself. (Interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) to support implementing SPI slaves would necessarily look different.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) The programming interface is structured around two kinds of driver, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) two kinds of device. A "Controller Driver" abstracts the controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) hardware, which may be as simple as a set of GPIO pins or as complex as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) a pair of FIFOs connected to dual DMA engines on the other side of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) SPI shift register (maximizing throughput). Such drivers bridge between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) whatever bus they sit on (often the platform bus) and SPI, and expose
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) the SPI side of their device as a :c:type:`struct spi_master
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) <spi_master>`. SPI devices are children of that master,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) represented as a :c:type:`struct spi_device <spi_device>` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) manufactured from :c:type:`struct spi_board_info
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) <spi_board_info>` descriptors which are usually provided by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) board-specific initialization code. A :c:type:`struct spi_driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) <spi_driver>` is called a "Protocol Driver", and is bound to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) spi_device using normal driver model calls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) The I/O model is a set of queued messages. Protocol drivers submit one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) or more :c:type:`struct spi_message <spi_message>` objects,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) which are processed and completed asynchronously. (There are synchronous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) wrappers, however.) Messages are built from one or more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) :c:type:`struct spi_transfer <spi_transfer>` objects, each of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) which wraps a full duplex SPI transfer. A variety of protocol tweaking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) options are needed, because different chips adopt very different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) policies for how they use the bits transferred with SPI.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) .. kernel-doc:: include/linux/spi/spi.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)    :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) .. kernel-doc:: drivers/spi/spi.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)    :functions: spi_register_board_info
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) .. kernel-doc:: drivers/spi/spi.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)    :export: