This adds a README to help with understanding of this series.
Signed-off-by: Simon Glass s...@chromium.org
---
Changes in v6:
- Rename platform_data to platdata
- Revise and update README
Changes in v5: None
Changes in v4: None
Changes in v3:
- Updated README.txt to cover changes since version 2
Changes in v2:
- Add GPIO uclass and tests
- Add U_BOOT_DEVICE to declare platform_data
- Add a single include/dm.h to bring in driver model code
- Add auto-probing feature for platform_data to avoid driver_bind() calls
- Add automatic allocation of device-specific priv data for uclasses
- Add automatic allocation of platform_data for FDT
- Add automatic allocation of priv data for devices
- Add device tree support in driver model
- Add dm_warn() to warn about impending doom
- Add integration tests for driver model
- Add new header file for lists
- Add new util file to hold utility functions
- Add sandbox GPIO driver
- Add script to run tests
- Add simple unit test functions
- Add test infrastructure for driver model
- Add tests for core code
- Allow a driver to bind to only one uclass
- Allow driver_bind() to support a NULL parent
- Put platform_data definitions in their own header file
- Remove relocation functions
- Remove unneeded arguments to uclass_bind(), uclass_unbind()
- Removed pointer return values in favour of integer
- Rename data structures to hopefully be clearer
- Rename struct device's 'bus' to 'parent'
- Standardise variable names (e.g. uclass instead of class)
- Update gpio command to use driver model
- Use driver_bind() in dm_init() instead of writing new code
doc/driver-model/README.txt | 368
1 file changed, 368 insertions(+)
create mode 100644 doc/driver-model/README.txt
diff --git a/doc/driver-model/README.txt b/doc/driver-model/README.txt
new file mode 100644
index 000..22c1481
--- /dev/null
+++ b/doc/driver-model/README.txt
@@ -0,0 +1,368 @@
+Driver Model
+
+
+This README contains high-level information about driver model, a unified
+way of declaring and accessing drivers in U-Boot. The original work was done
+by:
+
+ Marek Vasut ma...@denx.de
+ Pavel Herrmann morpheus.i...@gmail.com
+ Viktor Křivák viktor.kri...@gmail.com
+ Tomas Hlavacek tmshl...@gmail.com
+
+This has been both simplified and extended into the current implementation
+by:
+
+ Simon Glass s...@chromium.org
+
+
+Terminology
+---
+
+Uclass - a group of device which operate in the same way. A uclass provides
+ a way of accessing invidual devices within the group, but always
+ using the same interface. For example a GPIO uclass provides
+ operations for get/set value. An I2C uclass may have 10 I2C ports,
+ 4 with one driver, and 6 with another.
+
+Driver - some code which talks to a peripheral and presents a higher-level
+ interface to it.
+
+Device - an instance of a driver, tied to a particular port or peripheral.
+
+
+How to try it
+-
+
+Build U-Boot sandbox and run it:
+
+ make sandbox_config
+ make
+ ./u-boot
+
+ (type 'reset' to exit U-Boot)
+
+
+There is a uclass called 'demo'. This uclass handles
+saying hello, and reporting its status. There are two drivers in this
+uclass:
+
+ - simple: Just prints a message for hello, doesn't implement status
+ - shape: Prints shapes and reports number of characters printed as status
+
+The demo class is pretty simple, but not trivial. The intention is that it
+can be used for testing, so it will implement all driver model features and
+provide good code coverage of them. It does have multiple drivers, it
+handles parameter data and platdata (data which tells the driver how
+to operate on a particular platform) and it uses private driver data.
+
+To try it, see the example session below:
+
+=demo hello 1
+Hello '@' from 07981110: red 4
+=demo status 2
+Status: 0
+=demo hello 2
+g
+r@
+e@@
+e@@@
+n
+g@
+=demo status 2
+Status: 21
+=demo hello 4 ^
+ y^^^
+ e^
+l^^^
+l^^^
+ o^
+ w^^^
+=demo status 4
+Status: 36
+=
+
+
+Running the tests
+-
+
+The intent with driver model is that the core portion has 100% test coverage
+in sandbox, and every uclass has its own test. As a move towards this, tests
+are provided in test/dm. To run them, try:
+
+ ./test/dm/test-dm.sh
+
+You should see something like this:
+
+...U-Boot banner...
+Running 12 driver model tests
+Test: dm_test_autobind
+Test: dm_test_autoprobe
+Test: dm_test_children
+Test: dm_test_fdt
+Test: dm_test_gpio
+sandbox_gpio: sb_gpio_get_value: error: offset 4 not reserved
+Test: dm_test_leak
+Warning: Please add '#define DEBUG' to the top of common/dlmalloc.c
+Warning: Please add '#define DEBUG' to the top of common/dlmalloc.c
+Test: dm_test_lifecycle
+Test: dm_test_operations
+Test: dm_test_ordering
+Test: dm_test_platdata
+Test: dm_test_remove
+Test: dm_test_uclass
+Failures: 0
