aboutsummaryrefslogtreecommitdiffstats
path: root/include/linux
diff options
context:
space:
mode:
authorDavid Brownell <david-b@pacbell.net>2007-07-31 03:39:44 -0400
committerLinus Torvalds <torvalds@woody.linux-foundation.org>2007-07-31 18:39:44 -0400
commit2604288f45605d1b2844f001dc3141149667b3d1 (patch)
tree49e811d40c231e69570cf7382ead8b5731f8ae89 /include/linux
parentdb7526f925b79293dc3b361a70db7f340870a298 (diff)
spi kerneldoc update
This adds kerneldoc to the SPI framework. The "spi_driver" and "spi_board_info" structs were previously not described. Signed-off-by: David Brownell <dbrownell@users.sourceforge.net> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'include/linux')
-rw-r--r--include/linux/spi/spi.h58
1 files changed, 57 insertions, 1 deletions
diff --git a/include/linux/spi/spi.h b/include/linux/spi/spi.h
index e180615ed25a..002a3cddbdd5 100644
--- a/include/linux/spi/spi.h
+++ b/include/linux/spi/spi.h
@@ -139,6 +139,32 @@ struct spi_message;
139 139
140 140
141 141
142/**
143 * struct spi_driver - Host side "protocol" driver
144 * @probe: Binds this driver to the spi device. Drivers can verify
145 * that the device is actually present, and may need to configure
146 * characteristics (such as bits_per_word) which weren't needed for
147 * the initial configuration done during system setup.
148 * @remove: Unbinds this driver from the spi device
149 * @shutdown: Standard shutdown callback used during system state
150 * transitions such as powerdown/halt and kexec
151 * @suspend: Standard suspend callback used during system state transitions
152 * @resume: Standard resume callback used during system state transitions
153 * @driver: SPI device drivers should initialize the name and owner
154 * field of this structure.
155 *
156 * This represents the kind of device driver that uses SPI messages to
157 * interact with the hardware at the other end of a SPI link. It's called
158 * a "protocol" driver because it works through messages rather than talking
159 * directly to SPI hardware (which is what the underlying SPI controller
160 * driver does to pass those messages). These protocols are defined in the
161 * specification for the device(s) supported by the driver.
162 *
163 * As a rule, those device protocols represent the lowest level interface
164 * supported by a driver, and it will support upper level interfaces too.
165 * Examples of such upper levels include frameworks like MTD, networking,
166 * MMC, RTC, filesystem character device nodes, and hardware monitoring.
167 */
142struct spi_driver { 168struct spi_driver {
143 int (*probe)(struct spi_device *spi); 169 int (*probe)(struct spi_device *spi);
144 int (*remove)(struct spi_device *spi); 170 int (*remove)(struct spi_device *spi);
@@ -668,7 +694,37 @@ static inline ssize_t spi_w8r16(struct spi_device *spi, u8 cmd)
668 * parport adapters, or microcontrollers acting as USB-to-SPI bridges. 694 * parport adapters, or microcontrollers acting as USB-to-SPI bridges.
669 */ 695 */
670 696
671/* board-specific information about each SPI device */ 697/**
698 * struct spi_board_info - board-specific template for a SPI device
699 * @modalias: Initializes spi_device.modalias; identifies the driver.
700 * @platform_data: Initializes spi_device.platform_data; the particular
701 * data stored there is driver-specific.
702 * @controller_data: Initializes spi_device.controller_data; some
703 * controllers need hints about hardware setup, e.g. for DMA.
704 * @irq: Initializes spi_device.irq; depends on how the board is wired.
705 * @max_speed_hz: Initializes spi_device.max_speed_hz; based on limits
706 * from the chip datasheet and board-specific signal quality issues.
707 * @bus_num: Identifies which spi_master parents the spi_device; unused
708 * by spi_new_device(), and otherwise depends on board wiring.
709 * @chip_select: Initializes spi_device.chip_select; depends on how
710 * the board is wired.
711 * @mode: Initializes spi_device.mode; based on the chip datasheet, board
712 * wiring (some devices support both 3WIRE and standard modes), and
713 * possibly presence of an inverter in the chipselect path.
714 *
715 * When adding new SPI devices to the device tree, these structures serve
716 * as a partial device template. They hold information which can't always
717 * be determined by drivers. Information that probe() can establish (such
718 * as the default transfer wordsize) is not included here.
719 *
720 * These structures are used in two places. Their primary role is to
721 * be stored in tables of board-specific device descriptors, which are
722 * declared early in board initialization and then used (much later) to
723 * populate a controller's device tree after the that controller's driver
724 * initializes. A secondary (and atypical) role is as a parameter to
725 * spi_new_device() call, which happens after those controller drivers
726 * are active in some dynamic board configuration models.
727 */
672struct spi_board_info { 728struct spi_board_info {
673 /* the device name and module name are coupled, like platform_bus; 729 /* the device name and module name are coupled, like platform_bus;
674 * "modalias" is normally the driver name. 730 * "modalias" is normally the driver name.