diff options
Diffstat (limited to 'Documentation/spi')
| -rw-r--r-- | Documentation/spi/.gitignore | 2 | ||||
| -rw-r--r-- | Documentation/spi/00-INDEX | 22 | ||||
| -rw-r--r-- | Documentation/spi/Makefile | 11 | ||||
| -rw-r--r-- | Documentation/spi/ep93xx_spi | 105 | ||||
| -rw-r--r-- | Documentation/spi/pxa2xx | 49 | ||||
| -rw-r--r-- | Documentation/spi/spi-lm70llp | 79 | ||||
| -rw-r--r-- | Documentation/spi/spi-sc18is602 | 36 | ||||
| -rw-r--r-- | Documentation/spi/spi-summary | 186 | ||||
| -rw-r--r-- | Documentation/spi/spidev | 174 | ||||
| -rw-r--r-- | Documentation/spi/spidev_fdx.c | 158 | ||||
| -rw-r--r-- | Documentation/spi/spidev_test.c | 243 |
11 files changed, 845 insertions, 220 deletions
diff --git a/Documentation/spi/.gitignore b/Documentation/spi/.gitignore new file mode 100644 index 00000000000..4280576397e --- /dev/null +++ b/Documentation/spi/.gitignore @@ -0,0 +1,2 @@ +spidev_fdx +spidev_test diff --git a/Documentation/spi/00-INDEX b/Documentation/spi/00-INDEX new file mode 100644 index 00000000000..a128fa83551 --- /dev/null +++ b/Documentation/spi/00-INDEX @@ -0,0 +1,22 @@ +00-INDEX + - this file. +Makefile + - Makefile for the example sourcefiles. +butterfly + - AVR Butterfly SPI driver overview and pin configuration. +ep93xx_spi + - Basic EP93xx SPI driver configuration. +pxa2xx + - PXA2xx SPI master controller build by spi_message fifo wq +spidev + - Intro to the userspace API for spi devices +spidev_fdx.c + - spidev example file +spi-lm70llp + - Connecting an LM70-LLP sensor to the kernel via the SPI subsys. +spi-sc18is602 + - NXP SC18IS602/603 I2C-bus to SPI bridge +spi-summary + - (Linux) SPI overview. If unsure about SPI or SPI in Linux, start here. +spidev_test.c + - SPI testing utility. diff --git a/Documentation/spi/Makefile b/Documentation/spi/Makefile new file mode 100644 index 00000000000..a5b03c88bea --- /dev/null +++ b/Documentation/spi/Makefile @@ -0,0 +1,11 @@ +# kbuild trick to avoid linker error. Can be omitted if a module is built. +obj- := dummy.o + +# List of programs to build +hostprogs-y := spidev_test spidev_fdx + +# Tell kbuild to always build the programs +always := $(hostprogs-y) + +HOSTCFLAGS_spidev_test.o += -I$(objtree)/usr/include +HOSTCFLAGS_spidev_fdx.o += -I$(objtree)/usr/include diff --git a/Documentation/spi/ep93xx_spi b/Documentation/spi/ep93xx_spi new file mode 100644 index 00000000000..832ddce6e5f --- /dev/null +++ b/Documentation/spi/ep93xx_spi @@ -0,0 +1,105 @@ +Cirrus EP93xx SPI controller driver HOWTO +========================================= + +ep93xx_spi driver brings SPI master support for EP93xx SPI controller. Chip +selects are implemented with GPIO lines. + +NOTE: If possible, don't use SFRMOUT (SFRM1) signal as a chip select. It will +not work correctly (it cannot be controlled by software). Use GPIO lines +instead. + +Sample configuration +==================== + +Typically driver configuration is done in platform board files (the files under +arch/arm/mach-ep93xx/*.c). In this example we configure MMC over SPI through +this driver on TS-7260 board. You can adapt the code to suit your needs. + +This example uses EGPIO9 as SD/MMC card chip select (this is wired in DIO1 +header on the board). + +You need to select CONFIG_MMC_SPI to use mmc_spi driver. + +arch/arm/mach-ep93xx/ts72xx.c: + +... +#include <linux/gpio.h> +#include <linux/spi/spi.h> + +#include <linux/platform_data/spi-ep93xx.h> + +/* this is our GPIO line used for chip select */ +#define MMC_CHIP_SELECT_GPIO EP93XX_GPIO_LINE_EGPIO9 + +static int ts72xx_mmc_spi_setup(struct spi_device *spi) +{ + int err; + + err = gpio_request(MMC_CHIP_SELECT_GPIO, spi->modalias); + if (err) + return err; + + gpio_direction_output(MMC_CHIP_SELECT_GPIO, 1); + + return 0; +} + +static void ts72xx_mmc_spi_cleanup(struct spi_device *spi) +{ + gpio_set_value(MMC_CHIP_SELECT_GPIO, 1); + gpio_direction_input(MMC_CHIP_SELECT_GPIO); + gpio_free(MMC_CHIP_SELECT_GPIO); +} + +static void ts72xx_mmc_spi_cs_control(struct spi_device *spi, int value) +{ + gpio_set_value(MMC_CHIP_SELECT_GPIO, value); +} + +static struct ep93xx_spi_chip_ops ts72xx_mmc_spi_ops = { + .setup = ts72xx_mmc_spi_setup, + .cleanup = ts72xx_mmc_spi_cleanup, + .cs_control = ts72xx_mmc_spi_cs_control, +}; + +static struct spi_board_info ts72xx_spi_devices[] __initdata = { + { + .modalias = "mmc_spi", + .controller_data = &ts72xx_mmc_spi_ops, + /* + * We use 10 MHz even though the maximum is 7.4 MHz. The driver + * will limit it automatically to max. frequency. + */ + .max_speed_hz = 10 * 1000 * 1000, + .bus_num = 0, + .chip_select = 0, + .mode = SPI_MODE_0, + }, +}; + +static struct ep93xx_spi_info ts72xx_spi_info = { + .num_chipselect = ARRAY_SIZE(ts72xx_spi_devices), +}; + +static void __init ts72xx_init_machine(void) +{ + ... + ep93xx_register_spi(&ts72xx_spi_info, ts72xx_spi_devices, + ARRAY_SIZE(ts72xx_spi_devices)); +} + +The driver can use DMA for the transfers also. In this case ts72xx_spi_info +becomes: + +static struct ep93xx_spi_info ts72xx_spi_info = { + .num_chipselect = ARRAY_SIZE(ts72xx_spi_devices), + .use_dma = true; +}; + +Note that CONFIG_EP93XX_DMA should be enabled as well. + +Thanks to +========= +Martin Guy, H. Hartley Sweeten and others who helped me during development of +the driver. Simplemachines.it donated me a Sim.One board which I used testing +the driver on EP9307. diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx index 215e3b8e726..3352f97430e 100644 --- a/Documentation/spi/pxa2xx +++ b/Documentation/spi/pxa2xx @@ -1,8 +1,8 @@ -PXA2xx SPI on SSP driver HOWTO +PXA2xx SPI on SSP driver HOWTO =================================================== This a mini howto on the pxa2xx_spi driver. The driver turns a PXA2xx synchronous serial port into a SPI master controller -(see Documentation/spi/spi_summary). The driver has the following features +(see Documentation/spi/spi-summary). The driver has the following features - Support for any PXA2xx SSP - SSP PIO and SSP DMA data transfers. @@ -19,18 +19,14 @@ Declaring PXA2xx Master Controllers ----------------------------------- Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a "platform device". The master configuration is passed to the driver via a table -found in include/asm-arm/arch-pxa/pxa2xx_spi.h: +found in include/linux/spi/pxa2xx_spi.h: struct pxa2xx_spi_master { - enum pxa_ssp_type ssp_type; u32 clock_enable; u16 num_chipselect; u8 enable_dma; }; -The "pxa2xx_spi_master.ssp_type" field must have a value between 1 and 3 and -informs the driver which features a particular SSP supports. - The "pxa2xx_spi_master.clock_enable" field is used to enable/disable the corresponding SSP peripheral block in the "Clock Enable Register (CKEN"). See the "PXA2xx Developer Manual" section "Clocks and Power Management". @@ -61,7 +57,6 @@ static struct resource pxa_spi_nssp_resources[] = { }; static struct pxa2xx_spi_master pxa_nssp_master_info = { - .ssp_type = PXA25x_NSSP, /* Type of SSP */ .clock_enable = CKEN_NSSP, /* NSSP Peripheral clock */ .num_chipselect = 1, /* Matches the number of chips attached to NSSP */ .enable_dma = 1, /* Enables NSSP DMA */ @@ -90,13 +85,13 @@ Declaring Slave Devices ----------------------- Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c using the "spi_board_info" structure found in "linux/spi/spi.h". See -"Documentation/spi/spi_summary" for additional information. +"Documentation/spi/spi-summary" for additional information. Each slave device attached to the PXA must provide slave specific configuration information via the structure "pxa2xx_spi_chip" found in -"include/asm-arm/arch-pxa/pxa2xx_spi.h". The pxa2xx_spi master controller driver +"include/linux/spi/pxa2xx_spi.h". The pxa2xx_spi master controller driver will uses the configuration whenever the driver communicates with the slave -device. +device. All fields are optional. struct pxa2xx_spi_chip { u8 tx_threshold; @@ -112,14 +107,17 @@ used to configure the SSP hardware fifo. These fields are critical to the performance of pxa2xx_spi driver and misconfiguration will result in rx fifo overruns (especially in PIO mode transfers). Good default values are - .tx_threshold = 12, - .rx_threshold = 4, + .tx_threshold = 8, + .rx_threshold = 8, + +The range is 1 to 16 where zero indicates "use default". The "pxa2xx_spi_chip.dma_burst_size" field is used to configure PXA2xx DMA engine and is related the "spi_device.bits_per_word" field. Read and understand the PXA2xx "Developer Manual" sections on the DMA controller and SSP Controllers to determine the correct value. An SSP configured for byte-wide transfers would -use a value of 8. +use a value of 8. The driver will determine a reasonable default if +dma_burst_size == 0. The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle trailing bytes in the SSP receiver fifo. The correct value for this field is @@ -137,7 +135,13 @@ function for asserting/deasserting a slave device chip select. If the field is NULL, the pxa2xx_spi master controller driver assumes that the SSP port is configured to use SSPFRM instead. -NSSP SALVE SAMPLE +NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the +chipselect is dropped after each spi_transfer. Most devices need chip select +asserted around the complete message. Use SSPFRM as a GPIO (through cs_control) +to accommodate these chips. + + +NSSP SLAVE SAMPLE ----------------- The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the "spi_board_info.controller_data" field. Below is a sample configuration using @@ -206,18 +210,21 @@ static void __init streetracer_init(void) DMA and PIO I/O Support ----------------------- -The pxa2xx_spi driver support both DMA and interrupt driven PIO message -transfers. The driver defaults to PIO mode and DMA transfers must enabled by -setting the "enable_dma" flag in the "pxa2xx_spi_master" structure and -ensuring that the "pxa2xx_spi_chip.dma_burst_size" field is non-zero. The DMA -mode support both coherent and stream based DMA mappings. +The pxa2xx_spi driver supports both DMA and interrupt driven PIO message +transfers. The driver defaults to PIO mode and DMA transfers must be enabled +by setting the "enable_dma" flag in the "pxa2xx_spi_master" structure. The DMA +mode supports both coherent and stream based DMA mappings. The following logic is used to determine the type of I/O to be used on a per "spi_transfer" basis: -if !enable_dma or dma_burst_size == 0 then +if !enable_dma then always use PIO transfers +if spi_message.len > 8191 then + print "rate limited" warning + use PIO transfers + if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then use coherent DMA mode diff --git a/Documentation/spi/spi-lm70llp b/Documentation/spi/spi-lm70llp new file mode 100644 index 00000000000..463f6d01fa1 --- /dev/null +++ b/Documentation/spi/spi-lm70llp @@ -0,0 +1,79 @@ +spi_lm70llp : LM70-LLP parport-to-SPI adapter +============================================== + +Supported board/chip: + * National Semiconductor LM70 LLP evaluation board + Datasheet: http://www.national.com/pf/LM/LM70.html + +Author: + Kaiwan N Billimoria <kaiwan@designergraphix.com> + +Description +----------- +This driver provides glue code connecting a National Semiconductor LM70 LLP +temperature sensor evaluation board to the kernel's SPI core subsystem. + +This is a SPI master controller driver. It can be used in conjunction with +(layered under) the LM70 logical driver (a "SPI protocol driver"). +In effect, this driver turns the parallel port interface on the eval board +into a SPI bus with a single device, which will be driven by the generic +LM70 driver (drivers/hwmon/lm70.c). + + +Hardware Interfacing +-------------------- +The schematic for this particular board (the LM70EVAL-LLP) is +available (on page 4) here: + + http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf + +The hardware interfacing on the LM70 LLP eval board is as follows: + + Parallel LM70 LLP + Port Direction JP2 Header + ----------- --------- ---------------- + D0 2 - - + D1 3 --> V+ 5 + D2 4 --> V+ 5 + D3 5 --> V+ 5 + D4 6 --> V+ 5 + D5 7 --> nCS 8 + D6 8 --> SCLK 3 + D7 9 --> SI/O 5 + GND 25 - GND 7 + Select 13 <-- SI/O 1 + ----------- --------- ---------------- + +Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin +is connected to both pin D7 (as Master Out) and Select (as Master In) +using an arrangement that lets either the parport or the LM70 pull the +pin low. This can't be shared with true SPI devices, but other 3-wire +devices might share the same SI/SO pin. + +The bitbanger routine in this driver (lm70_txrx) is called back from +the bound "hwmon/lm70" protocol driver through its sysfs hook, using a +spi_write_then_read() call. It performs Mode 0 (SPI/Microwire) bitbanging. +The lm70 driver then inteprets the resulting digital temperature value +and exports it through sysfs. + +A "gotcha": National Semiconductor's LM70 LLP eval board circuit schematic +shows that the SI/O line from the LM70 chip is connected to the base of a +transistor Q1 (and also a pullup, and a zener diode to D7); while the +collector is tied to VCC. + +Interpreting this circuit, when the LM70 SI/O line is High (or tristate +and not grounded by the host via D7), the transistor conducts and switches +the collector to zero, which is reflected on pin 13 of the DB25 parport +connector. When SI/O is Low (driven by the LM70 or the host) on the other +hand, the transistor is cut off and the voltage tied to it's collector is +reflected on pin 13 as a High level. + +So: the getmiso inline routine in this driver takes this fact into account, +inverting the value read at pin 13. + + +Thanks to +--------- +o David Brownell for mentoring the SPI-side driver development. +o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version. +o Nadir Billimoria for help interpreting the circuit schematic. diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602 new file mode 100644 index 00000000000..a45702865a3 --- /dev/null +++ b/Documentation/spi/spi-sc18is602 @@ -0,0 +1,36 @@ +Kernel driver spi-sc18is602 +=========================== + +Supported chips: + * NXP SI18IS602/602B/603 + Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf + +Author: + Guenter Roeck <linux@roeck-us.net> + + +Description +----------- + +This driver provides connects a NXP SC18IS602/603 I2C-bus to SPI bridge to the +kernel's SPI core subsystem. + +The driver does not probe for supported chips, since the SI18IS602/603 does not +support Chip ID registers. You will have to instantiate the devices explicitly. +Please see Documentation/i2c/instantiating-devices for details. + + +Usage Notes +----------- + +This driver requires the I2C adapter driver to support raw I2C messages. I2C +adapter drivers which can only handle the SMBus protocol are not supported. + +The maximum SPI message size supported by SC18IS602/603 is 200 bytes. Attempts +to initiate longer transfers will fail with -EINVAL. EEPROM read operations and +similar large accesses have to be split into multiple chunks of no more than +200 bytes per SPI message (128 bytes of data per message is recommended). This +means that programs such as "cp" or "od", which automatically use large block +sizes to access a device, can not be used directly to read data from EEPROM. +Programs such as dd, where the block size can be specified, should be used +instead. diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary index 795fbb48ffa..7982bcc4d15 100644 --- a/Documentation/spi/spi-summary +++ b/Documentation/spi/spi-summary @@ -1,26 +1,30 @@ Overview of Linux kernel SPI support ==================================== -02-Dec-2005 +02-Feb-2012 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. 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, Slave Out" (MISO) signals. (Other names are also used.) There are four clocking modes through which data is exchanged; mode-0 and mode-3 are most commonly used. Each clock cycle shifts data out and data in; the clock -doesn't cycle except when there is data to shift. +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 may use a "chip select" line to activate a given SPI slave +SPI masters use a fourth "chip select" line to activate a given SPI slave device, so those three signal wires may be connected to several chips -in parallel. All SPI slaves support chipselects. Some devices have +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. -Unlike serial busses like USB or SMBUS, even low level protocols for +Unlike serial busses like USB or SMBus, even low level protocols for SPI slave functions are usually not interoperable between vendors (except for commodities like SPI memory chips). @@ -30,9 +34,14 @@ SPI slave functions are usually not interoperable between vendors - It may also be used to stream data in either direction (half duplex), or both of them at the same time (full duplex). - - Some devices may use eight bit words. Others may different word + - Some devices may use eight bit words. Others may use different word lengths, such as streams of 12-bit or 20-bit digital samples. + - Words are usually sent with their most significant bit (MSB) first, + but sometimes the least significant bit (LSB) goes first instead. + + - 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 @@ -44,6 +53,14 @@ half-duplex SPI, for request/response protocols), SSP ("Synchronous Serial Protocol"), PSP ("Programmable Serial Protocol"), and other related protocols. +Some chips eliminate a signal line by combining MOSI and MISO, and +limiting themselves to half-duplex at the hardware level. In fact +some SPI chips have this signal mode as a strapping option. These +can be accessed using the same programming interface as SPI, but of +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) currently only supports the master side of SPI interactions. @@ -74,6 +91,39 @@ interfaces with SPI modes. Given SPI support, they could use MMC or SD cards without needing a special purpose MMC/SD/SDIO controller. +I'm confused. What are these four SPI "clock modes"? +----------------------------------------------------- +It's easy to be confused here, and the vendor documentation you'll +find isn't necessarily helpful. The four modes combine two mode bits: + + - CPOL indicates the initial clock polarity. CPOL=0 means the + clock starts low, so the first (leading) edge is rising, and + the second (trailing) edge is falling. CPOL=1 means the clock + starts high, so the first (leading) edge is falling. + + - CPHA indicates the clock phase used to sample data; CPHA=0 says + sample on the leading edge, CPHA=1 means the trailing edge. + + Since the signal needs to stablize before it's sampled, CPHA=0 + implies that its data is written half a clock before the first + clock edge. The chipselect may have made it become available. + +Chip specs won't always say "uses SPI mode X" in as many words, +but their timing diagrams will make the CPOL and CPHA modes clear. + +In the SPI mode number, CPOL is the high order bit and CPHA is the +low order bit. So when a chip's timing diagram shows the clock +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 +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. + + How do these driver programming interfaces work? ------------------------------------------------ The <linux/spi/spi.h> header file includes kerneldoc, as does the @@ -89,7 +139,7 @@ a command and then reading its response. There are two types of SPI driver, here called: - Controller drivers ... controllers may be built in to System-On-Chip + Controller drivers ... controllers may be built into System-On-Chip processors, and often support both Master and Slave roles. These drivers touch hardware registers and may use DMA. Or they can be PIO bitbangers, needing just GPIO pins. @@ -113,21 +163,29 @@ using the driver model to connect controller and protocol drivers using device tables provided by board specific initialization code. SPI shows up in sysfs in several locations: + /sys/devices/.../CTLR ... physical node for a given SPI controller + /sys/devices/.../CTLR/spiB.C ... spi_device on bus "B", chipselect C, accessed through CTLR. + /sys/bus/spi/devices/spiB.C ... symlink to that physical + .../CTLR/spiB.C device + /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver that should be used with this device (for hotplug/coldplug) - /sys/bus/spi/devices/spiB.C ... symlink to the physical - spiB.C device - /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices - /sys/class/spi_master/spiB ... class device for the controller - managing bus "B". All the spiB.* devices share the same + /sys/class/spi_master/spiB ... symlink (or actual device node) to + a logical node which could hold class related state for the + controller managing bus "B". All spiB.* devices share one physical SPI bus segment, with SCLK, MOSI, and MISO. +Note that the actual location of the controller's class state depends +on whether you enabled CONFIG_SYSFS_DEPRECATED or not. 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. + How does board-specific init code declare SPI devices? ------------------------------------------------------ @@ -152,12 +210,12 @@ board should normally be set up and registered. So for example arch/.../mach-*/board-*.c files might have code like: - #include <asm/arch/spi.h> /* for mysoc_spi_data */ + #include <mach/spi.h> /* for mysoc_spi_data */ /* if your mach-* infrastructure doesn't support kernels that can * run on multiple boards, pdata wouldn't benefit from "__init". */ - static struct mysoc_spi_data __init pdata = { ... }; + static struct mysoc_spi_data pdata __initdata = { ... }; static __init board_init(void) { @@ -169,7 +227,7 @@ So for example arch/.../mach-*/board-*.c files might have code like: And SOC-specific utility code might look something like: - #include <asm/arch/spi.h> + #include <mach/spi.h> static struct platform_device spi2 = { ... }; @@ -287,16 +345,17 @@ SPI protocol drivers somewhat resemble platform device drivers: }, .probe = CHIP_probe, - .remove = __devexit_p(CHIP_remove), + .remove = CHIP_remove, .suspend = CHIP_suspend, .resume = CHIP_resume, }; -The driver core will autmatically attempt to bind this driver to any SPI +The driver core will automatically attempt to bind this driver to any SPI device whose board_info gave a modalias of "CHIP". Your probe() code -might look like this unless you're creating a class_device: +might look like this unless you're creating a device which is managing +a bus (appearing under /sys/class/spi_master). - static int __devinit CHIP_probe(struct spi_device *spi) + static int CHIP_probe(struct spi_device *spi) { struct CHIP *chip; struct CHIP_platform_data *pdata; @@ -327,8 +386,14 @@ any more such messages. + when bidirectional reads and writes start ... by how its sequence of spi_transfer requests is arranged; + + which I/O buffers are used ... each spi_transfer wraps a + buffer for each transfer direction, supporting full duplex + (two pointers, maybe the same one in both cases) and half + duplex (one pointer is NULL) transfers; + + optionally defining short delays after transfers ... using - the spi_transfer.delay_usecs setting; + the spi_transfer.delay_usecs setting (this delay can be the + only protocol effect, if the buffer length is zero); + whether the chipselect becomes inactive after a transfer and any delay ... by using the spi_transfer.cs_change flag; @@ -399,7 +464,7 @@ 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 class_get_devdata() +Use spi_alloc_master() to allocate the master, and spi_master_get_devdata() to get the driver-private data allocated for that device. struct spi_master *master; @@ -409,7 +474,7 @@ to get the driver-private data allocated for that device. if (!master) return -ENODEV; - c = class_get_devdata(&master->cdev); + c = spi_master_get_devdata(master); 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 @@ -418,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(). @@ -446,28 +511,81 @@ SPI MASTER METHODS 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 change them right away ... otherwise drivers could corrupt I/O that's in progress for other SPI devices. - 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. + ** BUG ALERT: for some reason the first version of + ** many spi_master 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) 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 + message. This may sleep. + + master->transfer_one(struct spi_master *master, 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 + spi_finalize_current_transfer() so the subsystem can issue the next + transfer. This may sleep. Note: transfer_one and transfer_one_message + are mutually exclusive; when both are set, the generic subsystem does + not call your transfer_one callback. + + Return values: + negative errno: error + 0: transfer is finished + 1: transfer is still in progress + + DEPRECATED METHODS + + master->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 + 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 acess might be fine using synchronous PIO. +for low-frequency sensor access might be fine using synchronous PIO. But the queue will probably be very real, using message->queue, PIO, often DMA (especially if the root filesystem is in SPI flash), and @@ -490,4 +608,6 @@ Stephen Street Mark Underwood Andrew Victor Vitaly Wool - +Grant Likely +Mark Brown +Linus Walleij diff --git a/Documentation/spi/spidev b/Documentation/spi/spidev index 5c8e1b988a0..3d14035b176 100644 --- a/Documentation/spi/spidev +++ b/Documentation/spi/spidev @@ -85,6 +85,12 @@ settings for data transfer parameters: SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL (clock polarity, idle high iff this is set) or SPI_CPHA (clock phase, sample on trailing edge iff this is set) flags. + Note that this request is limited to SPI mode flags that fit in a + single byte. + + SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t + which will return (RD) or assign (WR) the full SPI transfer mode, + not limited to the bits that fit in one byte. SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte which will return (RD) or assign (WR) the bit justification used to @@ -126,8 +132,8 @@ NOTES: FULL DUPLEX CHARACTER DEVICE API ================================ -See the sample program below for one example showing the use of the full -duplex programming interface. (Although it doesn't perform a full duplex +See the spidev_fdx.c sample program for one example showing the use of the +full duplex programming interface. (Although it doesn't perform a full duplex transfer.) The model is the same as that used in the kernel spi_sync() request; the individual transfers offer the same capabilities as are available to kernel drivers (except that it's not asynchronous). @@ -141,167 +147,3 @@ and bitrate for each transfer segment.) To make a full duplex request, provide both rx_buf and tx_buf for the same transfer. It's even OK if those are the same buffer. - - -SAMPLE PROGRAM -============== - --------------------------------- CUT HERE -#include <stdio.h> -#include <unistd.h> -#include <stdlib.h> -#include <fcntl.h> -#include <string.h> - -#include <sys/ioctl.h> -#include <sys/types.h> -#include <sys/stat.h> - -#include <linux/types.h> -#include <linux/spi/spidev.h> - - -static int verbose; - -static void do_read(int fd, int len) -{ - unsigned char buf[32], *bp; - int status; - - /* read at least 2 bytes, no more than 32 */ - if (len < 2) - len = 2; - else if (len > sizeof(buf)) - len = sizeof(buf); - memset(buf, 0, sizeof buf); - - status = read(fd, buf, len); - if (status < 0) { - perror("read"); - return; - } - if (status != len) { - fprintf(stderr, "short read\n"); - return; - } - - printf("read(%2d, %2d): %02x %02x,", len, status, - buf[0], buf[1]); - status -= 2; - bp = buf + 2; - while (status-- > 0) - printf(" %02x", *bp++); - printf("\n"); -} - -static void do_msg(int fd, int len) -{ - struct spi_ioc_transfer xfer[2]; - unsigned char buf[32], *bp; - int status; - - memset(xfer, 0, sizeof xfer); - memset(buf, 0, sizeof buf); - - if (len > sizeof buf) - len = sizeof buf; - - buf[0] = 0xaa; - xfer[0].tx_buf = (__u64) buf; - xfer[0].len = 1; - - xfer[1].rx_buf = (__u64) buf; - xfer[1].len = len; - - status = ioctl(fd, SPI_IOC_MESSAGE(2), xfer); - if (status < 0) { - perror("SPI_IOC_MESSAGE"); - return; - } - - printf("response(%2d, %2d): ", len, status); - for (bp = buf; len; len--) - printf(" %02x", *bp++); - printf("\n"); -} - -static void dumpstat(const char *name, int fd) -{ - __u8 mode, lsb, bits; - __u32 speed; - - if (ioctl(fd, SPI_IOC_RD_MODE, &mode) < 0) { - perror("SPI rd_mode"); - return; - } - if (ioctl(fd, SPI_IOC_RD_LSB_FIRST, &lsb) < 0) { - perror("SPI rd_lsb_fist"); - return; - } - if (ioctl(fd, SPI_IOC_RD_BITS_PER_WORD, &bits) < 0) { - perror("SPI bits_per_word"); - return; - } - if (ioctl(fd, SPI_IOC_RD_MAX_SPEED_HZ, &speed) < 0) { - perror("SPI max_speed_hz"); - return; - } - - printf("%s: spi mode %d, %d bits %sper word, %d Hz max\n", - name, mode, bits, lsb ? "(lsb first) " : "", speed); -} - -int main(int argc, char **argv) -{ - int c; - int readcount = 0; - int msglen = 0; - int fd; - const char *name; - - while ((c = getopt(argc, argv, "hm:r:v")) != EOF) { - switch (c) { - case 'm': - msglen = atoi(optarg); - if (msglen < 0) - goto usage; - continue; - case 'r': - readcount = atoi(optarg); - if (readcount < 0) - goto usage; - continue; - case 'v': - verbose++; - continue; - case 'h': - case '?': -usage: - fprintf(stderr, - "usage: %s [-h] [-m N] [-r N] /dev/spidevB.D\n", - argv[0]); - return 1; - } - } - - if ((optind + 1) != argc) - goto usage; - name = argv[optind]; - - fd = open(name, O_RDWR); - if (fd < 0) { - perror("open"); - return 1; - } - - dumpstat(name, fd); - - if (msglen) - do_msg(fd, msglen); - - if (readcount) - do_read(fd, readcount); - - close(fd); - return 0; -} diff --git a/Documentation/spi/spidev_fdx.c b/Documentation/spi/spidev_fdx.c new file mode 100644 index 00000000000..0ea3e51292f --- /dev/null +++ b/Documentation/spi/spidev_fdx.c @@ -0,0 +1,158 @@ +#include <stdio.h> +#include <unistd.h> +#include <stdlib.h> +#include <fcntl.h> +#include <string.h> + +#include <sys/ioctl.h> +#include <sys/types.h> +#include <sys/stat.h> + +#include <linux/types.h> +#include <linux/spi/spidev.h> + + +static int verbose; + +static void do_read(int fd, int len) +{ + unsigned char buf[32], *bp; + int status; + + /* read at least 2 bytes, no more than 32 */ + if (len < 2) + len = 2; + else if (len > sizeof(buf)) + len = sizeof(buf); + memset(buf, 0, sizeof buf); + + status = read(fd, buf, len); + if (status < 0) { + perror("read"); + return; + } + if (status != len) { + fprintf(stderr, "short read\n"); + return; + } + + printf("read(%2d, %2d): %02x %02x,", len, status, + buf[0], buf[1]); + status -= 2; + bp = buf + 2; + while (status-- > 0) + printf(" %02x", *bp++); + printf("\n"); +} + +static void do_msg(int fd, int len) +{ + struct spi_ioc_transfer xfer[2]; + unsigned char buf[32], *bp; + int status; + + memset(xfer, 0, sizeof xfer); + memset(buf, 0, sizeof buf); + + if (len > sizeof buf) + len = sizeof buf; + + buf[0] = 0xaa; + xfer[0].tx_buf = (unsigned long)buf; + xfer[0].len = 1; + + xfer[1].rx_buf = (unsigned long) buf; + xfer[1].len = len; + + status = ioctl(fd, SPI_IOC_MESSAGE(2), xfer); + if (status < 0) { + perror("SPI_IOC_MESSAGE"); + return; + } + + printf("response(%2d, %2d): ", len, status); + for (bp = buf; len; len--) + printf(" %02x", *bp++); + printf("\n"); +} + +static void dumpstat(const char *name, int fd) +{ + __u8 lsb, bits; + __u32 mode, speed; + + if (ioctl(fd, SPI_IOC_RD_MODE32, &mode) < 0) { + perror("SPI rd_mode"); + return; + } + if (ioctl(fd, SPI_IOC_RD_LSB_FIRST, &lsb) < 0) { + perror("SPI rd_lsb_fist"); + return; + } + if (ioctl(fd, SPI_IOC_RD_BITS_PER_WORD, &bits) < 0) { + perror("SPI bits_per_word"); + return; + } + if (ioctl(fd, SPI_IOC_RD_MAX_SPEED_HZ, &speed) < 0) { + perror("SPI max_speed_hz"); + return; + } + + printf("%s: spi mode 0x%x, %d bits %sper word, %d Hz max\n", + name, mode, bits, lsb ? "(lsb first) " : "", speed); +} + +int main(int argc, char **argv) +{ + int c; + int readcount = 0; + int msglen = 0; + int fd; + const char *name; + + while ((c = getopt(argc, argv, "hm:r:v")) != EOF) { + switch (c) { + case 'm': + msglen = atoi(optarg); + if (msglen < 0) + goto usage; + continue; + case 'r': + readcount = atoi(optarg); + if (readcount < 0) + goto usage; + continue; + case 'v': + verbose++; + continue; + case 'h': + case '?': +usage: + fprintf(stderr, + "usage: %s [-h] [-m N] [-r N] /dev/spidevB.D\n", + argv[0]); + return 1; + } + } + + if ((optind + 1) != argc) + goto usage; + name = argv[optind]; + + fd = open(name, O_RDWR); + if (fd < 0) { + perror("open"); + return 1; + } + + dumpstat(name, fd); + + if (msglen) + do_msg(fd, msglen); + + if (readcount) + do_read(fd, readcount); + + close(fd); + return 0; +} diff --git a/Documentation/spi/spidev_test.c b/Documentation/spi/spidev_test.c new file mode 100644 index 00000000000..3a2f9d59eda --- /dev/null +++ b/Documentation/spi/spidev_test.c @@ -0,0 +1,243 @@ +/* + * SPI testing utility (using spidev driver) + * + * Copyright (c) 2007 MontaVista Software, Inc. + * Copyright (c) 2007 Anton Vorontsov <avorontsov@ru.mvista.com> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License. + * + * Cross-compile with cross-gcc -I/path/to/cross-kernel/include + */ + +#include <stdint.h> +#include <unistd.h> +#include <stdio.h> +#include <stdlib.h> +#include <getopt.h> +#include <fcntl.h> +#include <sys/ioctl.h> +#include <linux/types.h> +#include <linux/spi/spidev.h> + +#define ARRAY_SIZE(a) (sizeof(a) / sizeof((a)[0])) + +static void pabort(const char *s) +{ + perror(s); + abort(); +} + +static const char *device = "/dev/spidev1.1"; +static uint32_t mode; +static uint8_t bits = 8; +static uint32_t speed = 500000; +static uint16_t delay; + +static void transfer(int fd) +{ + int ret; + uint8_t tx[] = { + 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, + 0x40, 0x00, 0x00, 0x00, 0x00, 0x95, + 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, + 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, + 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, + 0xDE, 0xAD, 0xBE, 0xEF, 0xBA, 0xAD, + 0xF0, 0x0D, + }; + uint8_t rx[ARRAY_SIZE(tx)] = {0, }; + struct spi_ioc_transfer tr = { + .tx_buf = (unsigned long)tx, + .rx_buf = (unsigned long)rx, + .len = ARRAY_SIZE(tx), + .delay_usecs = delay, + .speed_hz = speed, + .bits_per_word = bits, + }; + + if (mode & SPI_TX_QUAD) + tr.tx_nbits = 4; + else if (mode & SPI_TX_DUAL) + tr.tx_nbits = 2; + if (mode & SPI_RX_QUAD) + tr.rx_nbits = 4; + else if (mode & SPI_RX_DUAL) + tr.rx_nbits = 2; + if (!(mode & SPI_LOOP)) { + if (mode & (SPI_TX_QUAD | SPI_TX_DUAL)) + tr.rx_buf = 0; + else if (mode & (SPI_RX_QUAD | SPI_RX_DUAL)) + tr.tx_buf = 0; + } + + ret = ioctl(fd, SPI_IOC_MESSAGE(1), &tr); + if (ret < 1) + pabort("can't send spi message"); + + for (ret = 0; ret < ARRAY_SIZE(tx); ret++) { + if (!(ret % 6)) + puts(""); + printf("%.2X ", rx[ret]); + } + puts(""); +} + +static void print_usage(const char *prog) +{ + printf("Usage: %s [-DsbdlHOLC3]\n", prog); + puts(" -D --device device to use (default /dev/spidev1.1)\n" + " -s --speed max speed (Hz)\n" + " -d --delay delay (usec)\n" + " -b --bpw bits per word \n" + " -l --loop loopback\n" + " -H --cpha clock phase\n" + " -O --cpol clock polarity\n" + " -L --lsb least significant bit first\n" + " -C --cs-high chip select active high\n" + " -3 --3wire SI/SO signals shared\n" + " -N --no-cs no chip select\n" + " -R --ready slave pulls low to pause\n" + " -2 --dual dual transfer\n" + " -4 --quad quad transfer\n"); + exit(1); +} + +static void parse_opts(int argc, char *argv[]) +{ + while (1) { + static const struct option lopts[] = { + { "device", 1, 0, 'D' }, + { "speed", 1, 0, 's' }, + { "delay", 1, 0, 'd' }, + { "bpw", 1, 0, 'b' }, + { "loop", 0, 0, 'l' }, + { "cpha", 0, 0, 'H' }, + { "cpol", 0, 0, 'O' }, + { "lsb", 0, 0, 'L' }, + { "cs-high", 0, 0, 'C' }, + { "3wire", 0, 0, '3' }, + { "no-cs", 0, 0, 'N' }, + { "ready", 0, 0, 'R' }, + { "dual", 0, 0, '2' }, + { "quad", 0, 0, '4' }, + { NULL, 0, 0, 0 }, + }; + int c; + + c = getopt_long(argc, argv, "D:s:d:b:lHOLC3NR24", lopts, NULL); + + if (c == -1) + break; + + switch (c) { + case 'D': + device = optarg; + break; + case 's': + speed = atoi(optarg); + break; + case 'd': + delay = atoi(optarg); + break; + case 'b': + bits = atoi(optarg); + break; + case 'l': + mode |= SPI_LOOP; + break; + case 'H': + mode |= SPI_CPHA; + break; + case 'O': + mode |= SPI_CPOL; + break; + case 'L': + mode |= SPI_LSB_FIRST; + break; + case 'C': + mode |= SPI_CS_HIGH; + break; + case '3': + mode |= SPI_3WIRE; + break; + case 'N': + mode |= SPI_NO_CS; + break; + case 'R': + mode |= SPI_READY; + break; + case '2': + mode |= SPI_TX_DUAL; + break; + case '4': + mode |= SPI_TX_QUAD; + break; + default: + print_usage(argv[0]); + break; + } + } + if (mode & SPI_LOOP) { + if (mode & SPI_TX_DUAL) + mode |= SPI_RX_DUAL; + if (mode & SPI_TX_QUAD) + mode |= SPI_RX_QUAD; + } +} + +int main(int argc, char *argv[]) +{ + int ret = 0; + int fd; + + parse_opts(argc, argv); + + fd = open(device, O_RDWR); + if (fd < 0) + pabort("can't open device"); + + /* + * spi mode + */ + ret = ioctl(fd, SPI_IOC_WR_MODE32, &mode); + if (ret == -1) + pabort("can't set spi mode"); + + ret = ioctl(fd, SPI_IOC_RD_MODE32, &mode); + if (ret == -1) + pabort("can't get spi mode"); + + /* + * bits per word + */ + ret = ioctl(fd, SPI_IOC_WR_BITS_PER_WORD, &bits); + if (ret == -1) + pabort("can't set bits per word"); + + ret = ioctl(fd, SPI_IOC_RD_BITS_PER_WORD, &bits); + if (ret == -1) + pabort("can't get bits per word"); + + /* + * max speed hz + */ + ret = ioctl(fd, SPI_IOC_WR_MAX_SPEED_HZ, &speed); + if (ret == -1) + pabort("can't set max speed hz"); + + ret = ioctl(fd, SPI_IOC_RD_MAX_SPEED_HZ, &speed); + if (ret == -1) + pabort("can't get max speed hz"); + + printf("spi mode: 0x%x\n", mode); + printf("bits per word: %d\n", bits); + printf("max speed: %d Hz (%d KHz)\n", speed, speed/1000); + + transfer(fd); + + close(fd); + + return ret; +} |