forked from mirrors/linux
spi: Update the "master/slave" terminology in documentation
Update the master/slave terminology wherever possible to adopt usage of the controller/host/target. Some parts have been left untouched because they were sysfs entries and will probably end up being inaccurate if simply replaced here. Signed-off-by: Dhruva Gole <d-gole@ti.com> Link: https://msgid.link/r/20240215085404.1711976-1-d-gole@ti.com Signed-off-by: Mark Brown <broonie@kernel.org>
This commit is contained in:
Dhruva Gole
Mark Brown
parent
125b28b189
commit
99769a5246
1 changed files with 20 additions and 20 deletions
|
|
@ -19,14 +19,14 @@ commonly used. Each clock cycle shifts data out and data in; the clock
|
|||
doesn't cycle except when there is a data bit to shift. Not all data bits
|
||||
are used though; not every protocol uses those full duplex capabilities.
|
||||
|
||||
SPI hosts use a fourth "chip select" line to activate a given SPI slave
|
||||
SPI hosts use a fourth "chip select" line to activate a given SPI target
|
||||
device, so those three signal wires may be connected to several chips
|
||||
in parallel. All SPI slaves support chipselects; they are usually active
|
||||
low signals, labeled nCSx for slave 'x' (e.g. nCS0). Some devices have
|
||||
in parallel. All SPI targets support chipselects; they are usually active
|
||||
low signals, labeled nCSx for target 'x' (e.g. nCS0). Some devices have
|
||||
other signals, often including an interrupt to the host.
|
||||
|
||||
Unlike serial busses like USB or SMBus, even low level protocols for
|
||||
SPI slave functions are usually not interoperable between vendors
|
||||
SPI target functions are usually not interoperable between vendors
|
||||
(except for commodities like SPI memory chips).
|
||||
|
||||
- SPI may be used for request/response style device protocols, as with
|
||||
|
|
@ -43,8 +43,8 @@ SPI slave functions are usually not interoperable between vendors
|
|||
|
||||
- Sometimes SPI is used to daisy-chain devices, like shift registers.
|
||||
|
||||
In the same way, SPI slaves will only rarely support any kind of automatic
|
||||
discovery/enumeration protocol. The tree of slave devices accessible from
|
||||
In the same way, SPI targets will only rarely support any kind of automatic
|
||||
discovery/enumeration protocol. The tree of target devices accessible from
|
||||
a given SPI host controller will normally be set up manually, with
|
||||
configuration tables.
|
||||
|
||||
|
|
@ -75,7 +75,7 @@ protocol supported by every MMC or SD memory card. (The older "DataFlash"
|
|||
cards, predating MMC cards but using the same connectors and card shape,
|
||||
support only SPI.) Some PC hardware uses SPI flash for BIOS code.
|
||||
|
||||
SPI slave chips range from digital/analog converters used for analog
|
||||
SPI target chips range from digital/analog converters used for analog
|
||||
sensors and codecs, to memory, to peripherals like USB controllers
|
||||
or Ethernet adapters; and more.
|
||||
|
||||
|
|
@ -119,7 +119,7 @@ trailing clock edge (CPHA=1), that's SPI mode 1.
|
|||
|
||||
Note that the clock mode is relevant as soon as the chipselect goes
|
||||
active. So the host must set the clock to inactive before selecting
|
||||
a slave, and the slave can tell the chosen polarity by sampling the
|
||||
a target, and the target can tell the chosen polarity by sampling the
|
||||
clock level when its select line goes active. That's why many devices
|
||||
support for example both modes 0 and 3: they don't care about polarity,
|
||||
and always clock data in/out on rising clock edges.
|
||||
|
|
@ -142,13 +142,13 @@ There are two types of SPI driver, here called:
|
|||
|
||||
Controller drivers ...
|
||||
controllers may be built into System-On-Chip
|
||||
processors, and often support both Master and Slave roles.
|
||||
processors, and often support both Controller and target roles.
|
||||
These drivers touch hardware registers and may use DMA.
|
||||
Or they can be PIO bitbangers, needing just GPIO pins.
|
||||
|
||||
Protocol drivers ...
|
||||
these pass messages through the controller
|
||||
driver to communicate with a Slave or Master device on the
|
||||
driver to communicate with a target or Controller device on the
|
||||
other side of an SPI link.
|
||||
|
||||
So for example one protocol driver might talk to the MTD layer to export
|
||||
|
|
@ -184,17 +184,17 @@ shows up in sysfs in several locations::
|
|||
MOSI, and MISO.
|
||||
|
||||
/sys/devices/.../CTLR/slave ... virtual file for (un)registering the
|
||||
slave device for an SPI slave controller.
|
||||
Writing the driver name of an SPI slave handler to this file
|
||||
registers the slave device; writing "(null)" unregisters the slave
|
||||
target device for an SPI target controller.
|
||||
Writing the driver name of an SPI target handler to this file
|
||||
registers the target device; writing "(null)" unregisters the target
|
||||
device.
|
||||
Reading from this file shows the name of the slave device ("(null)"
|
||||
Reading from this file shows the name of the target device ("(null)"
|
||||
if not registered).
|
||||
|
||||
/sys/class/spi_slave/spiB ... symlink to a logical node which could hold
|
||||
class related state for the SPI slave controller on bus "B". When
|
||||
class related state for the SPI target controller on bus "B". When
|
||||
registered, a single spiB.* device is present here, possible sharing
|
||||
the physical SPI bus segment with other SPI slave devices.
|
||||
the physical SPI bus segment with other SPI target devices.
|
||||
|
||||
At this time, the only class-specific state is the bus number ("B" in "spiB"),
|
||||
so those /sys/class entries are only useful to quickly identify busses.
|
||||
|
|
@ -270,10 +270,10 @@ same SOC controller is used. For example, on one board SPI might use
|
|||
an external clock, where another derives the SPI clock from current
|
||||
settings of some master clock.
|
||||
|
||||
Declare Slave Devices
|
||||
Declare target Devices
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The second kind of information is a list of what SPI slave devices exist
|
||||
The second kind of information is a list of what SPI target devices exist
|
||||
on the target board, often with some board-specific data needed for the
|
||||
driver to work correctly.
|
||||
|
||||
|
|
@ -469,7 +469,7 @@ routines are available to allocate and zero-initialize an spi_message
|
|||
with several transfers.
|
||||
|
||||
|
||||
How do I write an "SPI Master Controller Driver"?
|
||||
How do I write an "SPI Controller Driver"?
|
||||
-------------------------------------------------
|
||||
An SPI controller will probably be registered on the platform_bus; write
|
||||
a driver to bind to the device, whichever bus is involved.
|
||||
|
|
@ -527,7 +527,7 @@ SPI Host Controller Methods
|
|||
Drivers may change the defaults provided by board_info, and then
|
||||
call spi_setup(spi) to invoke this routine. It may sleep.
|
||||
|
||||
Unless each SPI slave has its own configuration registers, don't
|
||||
Unless each SPI target has its own configuration registers, don't
|
||||
change them right away ... otherwise drivers could corrupt I/O
|
||||
that's in progress for other SPI devices.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue