spi: davinci: add additional comments

Add comments describing the platform data members
and per-chip-select SPI configuration structure.

Also, add some comments describing the what happens
during the driver probe.

Signed-off-by: Brian Niebuhr <bniebuhr@efjohnson.com>
Tested-By: Michael Williamson <michael.williamson@criticallink.com>
Signed-off-by: Sekhar Nori <nsekhar@ti.com>

diff --git a/arch/arm/mach-davinci/include/mach/spi.h b/arch/arm/mach-davinci/include/mach/spi.h
index 1f8b7866bea39856b4b35c09e43a0ad0e7c4753d..38f4da5ca135cfa32adeda31fc29bd27e04d8405 100644 (file)
--- a/arch/arm/mach-davinci/include/mach/spi.h
+++ b/arch/arm/mach-davinci/include/mach/spi.h
@@ -26,6 +26,20 @@ enum {
        SPI_VERSION_2, /* For DA8xx */
 };
 
+/**
+ * davinci_spi_platform_data - Platform data for SPI master device on DaVinci
+ *
+ * @version:   version of the SPI IP. Different DaVinci devices have slightly
+ *             varying versions of the same IP.
+ * @num_chipselect: number of chipselects supported by this SPI master
+ * @intr_line: interrupt line used to connect the SPI IP to the ARM interrupt
+ *             controller withn the SoC. Possible values are 0 and 1.
+ * @chip_sel:  list of GPIOs which can act as chip-selects for the SPI.
+ *             SPI_INTERN_CS denotes internal SPI chip-select. Not necessary
+ *             to populate if all chip-selects are internal.
+ * @cshold_bug:        set this to true if the SPI controller on your chip requires
+ *             a write to CSHOLD bit in between transfers (like in DM355).
+ */
 struct davinci_spi_platform_data {
        u8      version;
        u8      num_chipselect;
@@ -34,6 +48,24 @@ struct davinci_spi_platform_data {
        bool    cshold_bug;
 };
 
+/**
+ * davinci_spi_config - Per-chip-select configuration for SPI slave devices
+ *
+ * @wdelay:    amount of delay between transmissions. Measured in number of
+ *             SPI module clocks.
+ * @odd_parity:        polarity of parity flag at the end of transmit data stream.
+ *             0 - odd parity, 1 - even parity.
+ * @parity_enable: enable transmission of parity at end of each transmit
+ *             data stream.
+ * @io_type:   type of IO transfer. Choose between polled, interrupt and DMA.
+ * @timer_disable: disable chip-select timers (setup and hold)
+ * @c2tdelay:  chip-select setup time. Measured in number of SPI module clocks.
+ * @t2cdelay:  chip-select hold time. Measured in number of SPI module clocks.
+ * @t2edelay:  transmit data finished to SPI ENAn pin inactive time. Measured
+ *             in number of SPI clocks.
+ * @c2edelay:  chip-select active to SPI ENAn signal active time. Measured in
+ *             number of SPI clocks.
+ */
 struct davinci_spi_config {
        u8      wdelay;
        u8      odd_parity;

diff --git a/drivers/spi/davinci_spi.c b/drivers/spi/davinci_spi.c
index 2ec5fd2f2e7ba3284931f2fc98e418c26ca7fe1c..f40f1be1528a647e1d6892280fcf4ef84779a030 100644 (file)
--- a/drivers/spi/davinci_spi.c
+++ b/drivers/spi/davinci_spi.c
@@ -787,6 +787,13 @@ rx_dma_failed:
 /**
  * davinci_spi_probe - probe function for SPI Master Controller
  * @pdev: platform_device structure which contains plateform specific data
+ *
+ * According to Linux Device Model this function will be invoked by Linux
+ * with platform_device struct which contains the device specific info.
+ * This function will map the SPI controller's memory, register IRQ,
+ * Reset SPI controller and setting its registers to default value.
+ * It will invoke spi_bitbang_start to create work queue so that client driver
+ * can register transfer method to work queue.
  */
 static int davinci_spi_probe(struct platform_device *pdev)
 {