summaryrefslogtreecommitdiff
path: root/Documentation/spi
diff options
context:
space:
mode:
authorLinus Walleij <linus.walleij@linaro.org>2012-02-22 10:05:38 +0100
committerGrant Likely <grant.likely@secretlab.ca>2012-03-07 19:19:48 -0700
commitffbbdd21329f3e15eeca6df2d4bc11c04d9d91c0 (patch)
tree964ce05f044aa6917b4a1ed58ed055ed2e899dcc /Documentation/spi
parent0b2182ddac4b8837bbba996d03b7b28f4346db0a (diff)
spi: create a message queueing infrastructure
This rips the message queue in the PL022 driver out and pushes it into (optional) common infrastructure. Drivers that want to use the message pumping thread will need to define the new per-messags transfer methods and leave the deprecated transfer() method as NULL. Most of the design is described in the documentation changes that are included in this patch. Since there is a queue that need to be stopped when the system is suspending/resuming, two new calls are implemented for the device drivers to call in their suspend()/resume() functions: spi_master_suspend() and spi_master_resume(). ChangeLog v1->v2: - Remove Kconfig entry and do not make the queue support optional at all, instead be more agressive and have it as part of the compulsory infrastructure. - If the .transfer() method is implemented, delete print a small deprecation notice and do not start the transfer pump. - Fix a bitrotted comment. ChangeLog v2->v3: - Fix up a problematic sequence courtesy of Chris Blair. - Stop rather than destroy the queue on suspend() courtesy of Chris Blair. Signed-off-by: Chris Blair <chris.blair@stericsson.com> Signed-off-by: Linus Walleij <linus.walleij@linaro.org> Tested-by: Mark Brown <broonie@opensource.wolfsonmicro.com> Reviewed-by: Mark Brown <broonie@opensource.wolfsonmicro.com> Signed-off-by: Grant Likely <grant.likely@secretlab.ca>
Diffstat (limited to 'Documentation/spi')
-rw-r--r--Documentation/spi/spi-summary58
1 files changed, 46 insertions, 12 deletions
diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary
index 4884cb33845d..7312ec14dd89 100644
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary
@@ -1,7 +1,7 @@
Overview of Linux kernel SPI support
====================================
-21-May-2007
+02-Feb-2012
What is SPI?
------------
@@ -483,9 +483,9 @@ 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
-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.
+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().
@@ -521,21 +521,53 @@ SPI MASTER METHODS
** When you code setup(), ASSUME that the controller
** is actively processing transfers for another device.
- master->transfer(struct spi_device *spi, struct spi_message *message)
- This must not sleep. Its responsibility is arrange that the
- transfer happens and its complete() callback is issued. The two
- will normally happen later, after other transfers complete, and
- if the controller is idle it will need to be kickstarted.
-
master->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)
+ 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)
+ 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)
+ 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
+ transfer. This may sleep.
+
+ DEPRECATED METHODS
+
+ master->transfer(struct spi_device *spi, struct spi_message *message)
+ This must not sleep. Its responsibility is arrange that the
+ transfer happens and its complete() callback is issued. The two
+ will normally happen later, after other transfers complete, and
+ if the controller is idle it will need to be kickstarted. This
+ method is not used on queued controllers and must be NULL if
+ transfer_one_message() and (un)prepare_transfer_hardware() are
+ implemented.
+
SPI MESSAGE QUEUE
-The bulk of the driver will be managing the I/O queue fed by transfer().
+If you are happy with the standard queueing mechanism provided by the
+SPI subsystem, just implement the queued methods specified above. Using
+the message queue has the upside of centralizing a lot of code and
+providing pure process-context execution of methods. The message queue
+can also be elevated to realtime priority on high-priority SPI traffic.
+
+Unless the queueing mechanism in the SPI subsystem is selected, the bulk
+of the driver will be managing the I/O queue fed by the now deprecated
+function transfer().
That queue could be purely conceptual. For example, a driver used only
for low-frequency sensor access might be fine using synchronous PIO.
@@ -561,4 +593,6 @@ Stephen Street
Mark Underwood
Andrew Victor
Vitaly Wool
-
+Grant Likely
+Mark Brown
+Linus Walleij