[U-Boot] [PATCH 06/14] dm: Add SPI API transition document
Marek Vasut
marex at denx.de
Wed Aug 8 13:42:22 CEST 2012
From: Viktor Krivak <viktor.krivak at gmail.com>
Signed-off-by: Viktor Krivak <viktor.krivak at gmail.com>
---
doc/driver-model/UDM-spi.txt | 200 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 200 insertions(+)
create mode 100644 doc/driver-model/UDM-spi.txt
diff --git a/doc/driver-model/UDM-spi.txt b/doc/driver-model/UDM-spi.txt
new file mode 100644
index 0000000..7442a32
--- /dev/null
+++ b/doc/driver-model/UDM-spi.txt
@@ -0,0 +1,200 @@
+The U-Boot Driver Model Project
+===============================
+SPI analysis
+============
+Viktor Krivak <viktor.krivak at gmail.com>
+2012-03-03
+
+I) Overview
+-----------
+
+ 1) The SPI driver
+ -----------------
+
+ At this moment U-Boot provides standard API that consist of 7 functions:
+
+ void spi_init(void);
+ struct spi_slave *spi_setup_slave(unsigned int bus, unsigned int cs,
+ unsigned int max_hz, unsigned int mode);
+ void spi_free_slave(struct spi_slave *slave);
+ int spi_claim_bus(struct spi_slave *slave);
+ void spi_release_bus(struct spi_slave *slave);
+ int spi_xfer(struct spi_slave *slave, unsigned int bitlen,
+ const void *dout, void *din, unsigned long flags);
+ int spi_cs_is_valid(unsigned int bus, unsigned int cs);
+ void spi_cs_activate(struct spi_slave *slave);
+ void spi_cs_deactivate(struct spi_slave *slave);
+ void spi_set_speed(struct spi_slave *slave, uint hz);
+
+ Method spi_init() is usually empty. All necessary configuration are sets by
+ spi_setup_slave(). But this configuration is usually stored only in memory.
+ No real hardware sets are made. All hardware settings are provided by method
+ spi_claim_bus(). This method claims the bus and it can't be claimed again
+ until it's release. That's mean all calls of method spi_claim_bus() will
+ fail. But lots of cpu implementation don't meet this behaviour.
+ Method spi_release_bus() does exact opposite. It release bus directly by
+ some hardware sets. spi_free_slave() only free memory allocated by
+ spi_setup_slave(). Method spi_xfer() do actually read and write operation
+ throw specified bus and cs. Other methods are self explanatory.
+
+ 2) Current limitations
+ ----------------------
+
+ Theoretically at this moment api allows use more then one bus per device at
+ the time. But in real this can be achieved only when all buses have their
+ own base addresses in memory.
+
+
+II) Approach
+------------
+
+ 1) Claiming bus
+ ---------------
+
+ The current api cannot be used because struct spi_slave have to be in
+ private data. In that case user are prohibited to use different bus on one
+ device at same time. But when base memory address for bus are different.
+ It's possible make more instance of this driver. Otherwise it can't can be
+ done because of hardware limitation.
+
+ 2) API change
+ -------------
+
+ Method spi_init() is moved to probe. Methods spi_setup_slave() and
+ spi_claim_bus() are joined to one method. This method checks if desired bus
+ exists and is available then configure necessary hardware and claims bus.
+ Method spi_release_bus() and spi_free_slave() are also joined to meet this
+ new approach. Other function remain same. Only struct spi_slave was change
+ to instance.
+
+ struct ops {
+ int (*spi_request_bus)(struct instance *i, unsigned int bus,
+ unsigned int cs, unsigned int max_hz,
+ unsigned int mode);
+ void (*spi_release_bus)(struct instance *i);
+ int (*spi_xfer) (struct instance *i, unsigned int bitlen,
+ const void *dout, void *din, unsigned long flags);
+ int (*spi_cs_is_valid)(struct instance *i, unsigned int bus,
+ unsigned int cs);
+ void (*spi_cs_activate)(struct instance *i);
+ void (*spi_cs_deactivate)(struct instance *i);
+ void (*spi_set_speed)(struct instance *i, uint hz);
+ }
+
+ 3) Legacy API
+ -------------
+
+ To easy conversion of the whole driver. Original and new api can exist next
+ to each other. New API is designed to be only a wrapper that extracts
+ necessary information from private_data and use old api. When driver can
+ use more than one bus at the time. New API require multiple instance. One
+ for each bus. In this case spi_slave have to be copied in each instance.
+
+ 4) Conversion TIME-LINE
+ -----------------------
+
+ To prevent build corruption api conversion have to be processed in several
+ independent steps. In first step all old API methods are renamed. After that
+ new API and core function are implemented. Next step is conversion of all
+ board init methods to set platform data. After all these steps it is possible
+ to start conversion of all remaining calls. This procedure guarantees that
+ build procedure and binaries are never broken.
+
+III) Analysis of in-tree drivers
+--------------------------------
+
+ 1) altera_spi.c
+ ---------------
+ All methods have designated structure. Simple conversion possible.
+
+ 2) andes_spi.c
+ --------------
+ All methods have designated structure. Simple conversion possible.
+
+ 3) andes_spi.h
+ --------------
+ Support file for andes_spi.c. No conversion is needed.
+
+ 4) armada100_spi.c
+ ------------------
+ All methods have designated structure. Simple conversion possible.
+
+ 5) atmel_dataflash_spi.c
+ ------------------------
+ Wrong placement. Will be moved to another location.
+
+ 6) atmel_spi.c
+ --------------
+ Supports more than one bus. Need some minor change.
+
+ 7) atmel_spi.h
+ --------------
+ Support file for andes_spi.c. No conversion is needed.
+
+ 8) bfin_spi.c
+ -------------
+ Supports more than one bus. Need some minor change.
+
+ 9) cf_spi.c
+ -----------
+ Cooperate with some cpu specific methods from other files. Hard conversion.
+
+ 10) davinci_spi.c
+ -----------------
+ All methods have designated structure. Simple conversion possible.
+
+ 11) davinci_spi.h
+ -----------------
+ Support file for davinci_spi.h. No conversion is needed.
+
+ 12) fsl_espi.c
+ --------------
+ All methods have designated structure. Simple conversion possible.
+
+ 13) kirkwood_spi.c
+ ------------------
+ All methods have designated structure. Simple conversion possible.
+
+ 14) mpc8xxx_spi.c
+ -----------------
+ All methods have designated structure. Simple conversion possible.
+
+ 15) mpc52xx_spi.c
+ -----------------
+ All methods have designated structure. Simple conversion possible.
+
+ 16) mxc_spi.c
+ -------------
+ All methods have designated structure. Simple conversion possible.
+
+ 17) mxs_spi.c
+ -------------
+ All methods have designated structure. Simple conversion possible.
+
+ 18) oc_tiny_spi.c
+ -----------------
+ Supports more than one bus. Need some minor change.
+
+ 19) omap3_spi.c
+ ---------------
+ Supports more than one bus. Need some minor change.
+
+ 20) omap3_spi.h
+ ---------------
+ Support file for omap3_spi.c. No conversion is needed.
+
+ 21) sh_spi.c
+ ------------
+ All methods have designated structure. Simple conversion possible.
+
+ 22) sh_spi.h
+ ------------
+ Support file for sh_spi.h. No conversion is needed.
+
+ 23) soft_spi.c
+ --------------
+ Use many board specific method linked from other files. Need careful debugging.
+
+ 24) tegra2_spi.c
+ ----------------
+ Some hardware specific problem when releasing bus.
--
1.7.10.4
More information about the U-Boot
mailing list