Skip to content

Commit

Permalink
Merge tag 'spi-v6.9' of git://git.kernel.org/pub/scm/linux/kernel/git…
Browse files Browse the repository at this point in the history
…/broonie/spi

Pull spi updates from Mark Brown:
 "This release sees some exciting changes from David Lechner which
  implements some optimisations that have been talked about for a long
  time which allows client drivers to pre-prepare SPI messages for
  repeated or low latency use. This lets us move work out of latency
  sensitive paths and avoid repeating work for frequently performed
  operations. As well as being useful in itself this will also be used
  in future to allow controllers to directly trigger SPI operations (eg,
  from interrupts).

  Otherwise this release has mostly been focused on cleanups, plus a
  couple of new devices:

   - Support for pre-optimising messages

   - A big set of updates from Uwe Kleine-König moving drivers to use
     APIs with more modern terminology for controllers

   - Major overhaul of the s3c64xx driver

   - Support for Google GS101 and Samsung Exynos850"

* tag 'spi-v6.9' of git://git.kernel.org/pub/scm/linux/kernel/git/broonie/spi: (122 commits)
  spi: Introduce SPI_INVALID_CS and is_valid_cs()
  spi: Fix types of the last chip select storage variables
  spi: Consistently use BIT for cs_index_mask
  spi: Exctract spi_dev_check_cs() helper
  spi: Exctract spi_set_all_cs_unused() helper
  spi: s3c64xx: switch exynos850 to new port config data
  spi: s3c64xx: switch gs101 to new port config data
  spi: s3c64xx: deprecate fifo_lvl_mask, rx_lvl_offset and port_id
  spi: s3c64xx: get rid of the OF alias ID dependency
  spi: s3c64xx: introduce s3c64xx_spi_set_port_id()
  spi: s3c64xx: let the SPI core determine the bus number
  spi: s3c64xx: allow FIFO depth to be determined from the compatible
  spi: s3c64xx: retrieve the FIFO depth from the device tree
  spi: s3c64xx: determine the fifo depth only once
  spi: s3c64xx: allow full FIFO masks
  spi: s3c64xx: define a magic value
  spi: dt-bindings: introduce FIFO depth properties
  spi: axi-spi-engine: use struct_size() macro
  spi: axi-spi-engine: use __counted_by() attribute
  spi: axi-spi-engine: remove p from struct spi_engine_message_state
  ...
  • Loading branch information
Linus Torvalds committed Mar 13, 2024
2 parents 21ac5a9 + be84be4 commit 6cdebf6
Show file tree
Hide file tree
Showing 72 changed files with 1,569 additions and 802 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@ properties:
- const: atmel,at91rm9200-spi
- items:
- const: microchip,sam9x7-spi
- const: microchip,sam9x60-spi
- const: atmel,at91rm9200-spi

reg:
Expand Down
4 changes: 2 additions & 2 deletions Documentation/devicetree/bindings/spi/samsung,spi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,13 @@ properties:
compatible:
oneOf:
- enum:
- google,gs101-spi
- samsung,s3c2443-spi # for S3C2443, S3C2416 and S3C2450
- samsung,s3c6410-spi
- samsung,s5pv210-spi # for S5PV210 and S5PC110
- samsung,exynos4210-spi
- samsung,exynos5433-spi
- samsung,exynos850-spi
- samsung,exynosautov9-spi
- tesla,fsd-spi
- const: samsung,exynos7-spi
Expand Down Expand Up @@ -74,8 +76,6 @@ required:
- compatible
- clocks
- clock-names
- dmas
- dma-names
- interrupts
- reg

Expand Down
27 changes: 27 additions & 0 deletions Documentation/devicetree/bindings/spi/spi-controller.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,21 @@ properties:
Should be generally avoided and be replaced by
spi-cs-high + ACTIVE_HIGH.
fifo-depth:
$ref: /schemas/types.yaml#/definitions/uint32
description:
Size of the RX and TX data FIFOs in bytes.

rx-fifo-depth:
$ref: /schemas/types.yaml#/definitions/uint32
description:
Size of the RX data FIFO in bytes.

tx-fifo-depth:
$ref: /schemas/types.yaml#/definitions/uint32
description:
Size of the TX data FIFO in bytes.

num-cs:
$ref: /schemas/types.yaml#/definitions/uint32
description:
Expand Down Expand Up @@ -116,6 +131,10 @@ patternProperties:
- compatible
- reg

dependencies:
rx-fifo-depth: [ tx-fifo-depth ]
tx-fifo-depth: [ rx-fifo-depth ]

allOf:
- if:
not:
Expand All @@ -129,6 +148,14 @@ allOf:
properties:
"#address-cells":
const: 0
- not:
required:
- fifo-depth
- rx-fifo-depth
- not:
required:
- fifo-depth
- tx-fifo-depth

additionalProperties: true

Expand Down
1 change: 1 addition & 0 deletions Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ properties:
- enum:
- fsl,imx8ulp-spi
- fsl,imx93-spi
- fsl,imx95-spi
- const: fsl,imx7ulp-spi
reg:
maxItems: 1
Expand Down
18 changes: 12 additions & 6 deletions Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,18 @@ allOf:

properties:
compatible:
enum:
- nxp,imx8dxl-fspi
- nxp,imx8mm-fspi
- nxp,imx8mp-fspi
- nxp,imx8qxp-fspi
- nxp,lx2160a-fspi
oneOf:
- enum:
- nxp,imx8dxl-fspi
- nxp,imx8mm-fspi
- nxp,imx8mp-fspi
- nxp,imx8qxp-fspi
- nxp,lx2160a-fspi
- items:
- enum:
- nxp,imx93-fspi
- nxp,imx95-fspi
- const: nxp,imx8mm-fspi

reg:
items:
Expand Down
2 changes: 1 addition & 1 deletion Documentation/driver-api/driver-model/devres.rst
Original file line number Diff line number Diff line change
Expand Up @@ -463,7 +463,7 @@ SLAVE DMA ENGINE
SPI
devm_spi_alloc_master()
devm_spi_alloc_slave()
devm_spi_register_master()
devm_spi_register_controller()

WATCHDOG
devm_watchdog_register_device()
114 changes: 57 additions & 57 deletions Documentation/spi/spi-summary.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ What is SPI?
The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
link used to connect microcontrollers to sensors, memory, and peripherals.
It's a simple "de facto" standard, not complicated enough to acquire a
standardization body. SPI uses a master/slave configuration.
standardization body. SPI uses a host/target configuration.

The three signal wires hold a clock (SCK, often on the order of 10 MHz),
and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In,
Expand All @@ -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 masters 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
other signals, often including an interrupt to the master.
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
Expand All @@ -43,10 +43,10 @@ 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
a given SPI master will normally be set up manually, with configuration
tables.
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.

SPI is only one of the names used by such four-wire protocols, and
most controllers have no problem handling "MicroWire" (think of it as
Expand All @@ -62,8 +62,8 @@ course they won't handle full duplex transfers. You may find such
chips described as using "three wire" signaling: SCK, data, nCSx.
(That data line is sometimes called MOMI or SISO.)

Microcontrollers often support both master and slave sides of the SPI
protocol. This document (and Linux) supports both the master and slave
Microcontrollers often support both host and target sides of the SPI
protocol. This document (and Linux) supports both the host and target
sides of SPI interactions.


Expand All @@ -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.

Expand Down Expand Up @@ -118,8 +118,8 @@ starting low (CPOL=0) and data stabilized for sampling during the
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 master must set the clock to inactive before selecting
a slave, and the slave can tell the chosen polarity by sampling the
active. So the host must set the clock to inactive before selecting
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.
Expand All @@ -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
Expand Down Expand Up @@ -179,22 +179,22 @@ shows up in sysfs in several locations::
/sys/bus/spi/drivers/D ... driver for one or more spi*.* devices

/sys/class/spi_master/spiB ... symlink to a logical node which could hold
class related state for the SPI master controller managing bus "B".
class related state for the SPI host controller managing bus "B".
All spiB.* devices share one physical SPI bus segment, with SCLK,
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.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -316,7 +316,7 @@ sharing a bus with a device that interprets chipselect "backwards" is
not possible until the infrastructure knows how to deselect it.

Then your board initialization code would register that table with the SPI
infrastructure, so that it's available later when the SPI master controller
infrastructure, so that it's available later when the SPI host controller
driver is registered::

spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
Expand Down Expand Up @@ -469,39 +469,39 @@ 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.

The main task of this type of driver is to provide an "spi_master".
Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
to get the driver-private data allocated for that device.
The main task of this type of driver is to provide an "spi_controller".
Use spi_alloc_host() to allocate the host controller, and
spi_controller_get_devdata() to get the driver-private data allocated for that
device.

::

struct spi_master *master;
struct spi_controller *ctlr;
struct CONTROLLER *c;

master = spi_alloc_master(dev, sizeof *c);
if (!master)
ctlr = spi_alloc_host(dev, sizeof *c);
if (!ctlr)
return -ENODEV;

c = spi_master_get_devdata(master);
c = spi_controller_get_devdata(ctlr);

The driver will initialize the fields of that spi_master, including the
bus number (maybe the same as the platform device ID) and three methods
used to interact with the SPI core and SPI protocol drivers. It will
also initialize its own internal state. (See below about bus numbering
and those methods.)
The driver will initialize the fields of that spi_controller, including the bus
number (maybe the same as the platform device ID) and three methods used to
interact with the SPI core and SPI protocol drivers. It will also initialize
its own internal state. (See below about bus numbering and those methods.)

After you initialize the spi_master, then use spi_register_master() to
After you initialize the spi_controller, then use spi_register_controller() to
publish it to the rest of the system. At that time, device nodes for the
controller and any predeclared spi devices will be made available, and
the driver model core will take care of binding them to drivers.

If you need to remove your SPI controller driver, spi_unregister_master()
will reverse the effect of spi_register_master().
If you need to remove your SPI controller driver, spi_unregister_controller()
will reverse the effect of spi_register_controller().


Bus Numbering
Expand All @@ -519,49 +519,49 @@ then be replaced by a dynamically assigned number. You'd then need to treat
this as a non-static configuration (see above).


SPI Master Methods
^^^^^^^^^^^^^^^^^^
SPI Host Controller Methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^

``master->setup(struct spi_device *spi)``
``ctlr->setup(struct spi_device *spi)``
This sets up the device clock rate, SPI mode, and word sizes.
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.

.. note::

BUG ALERT: for some reason the first version of
many spi_master drivers seems to get this wrong.
many spi_controller drivers seems to get this wrong.
When you code setup(), ASSUME that the controller
is actively processing transfers for another device.

``master->cleanup(struct spi_device *spi)``
``ctlr->cleanup(struct spi_device *spi)``
Your controller driver may use spi_device.controller_state to hold
state it dynamically associates with that device. If you do that,
be sure to provide the cleanup() method to free that state.

``master->prepare_transfer_hardware(struct spi_master *master)``
``ctlr->prepare_transfer_hardware(struct spi_controller *ctlr)``
This will be called by the queue mechanism to signal to the driver
that a message is coming in soon, so the subsystem requests the
driver to prepare the transfer hardware by issuing this call.
This may sleep.

``master->unprepare_transfer_hardware(struct spi_master *master)``
``ctlr->unprepare_transfer_hardware(struct spi_controller *ctlr)``
This will be called by the queue mechanism to signal to the driver
that there are no more messages pending in the queue and it may
relax the hardware (e.g. by power management calls). This may sleep.

``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
``ctlr->transfer_one_message(struct spi_controller *ctlr, struct spi_message *mesg)``
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
spi_finalize_current_message() so the subsystem can issue the next
message. This may sleep.

``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)``
``ctrl->transfer_one(struct spi_controller *ctlr, struct spi_device *spi, struct spi_transfer *transfer)``
The subsystem calls the driver to transfer a single transfer while
queuing transfers that arrive in the meantime. When the driver is
finished with this transfer, it must call
Expand All @@ -576,15 +576,15 @@ SPI Master Methods
* 0: transfer is finished
* 1: transfer is still in progress

``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
This method allows SPI client drivers to request SPI master controller
``ctrl->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
This method allows SPI client drivers to request SPI host controller
for configuring device specific CS setup, hold and inactive timing
requirements.

Deprecated Methods
^^^^^^^^^^^^^^^^^^

``master->transfer(struct spi_device *spi, struct spi_message *message)``
``ctrl->transfer(struct spi_device *spi, struct spi_message *message)``
This must not sleep. Its responsibility is to arrange that the
transfer happens and its complete() callback is issued. The two
will normally happen later, after other transfers complete, and
Expand Down
Loading

0 comments on commit 6cdebf6

Please sign in to comment.