summaryrefslogtreecommitdiffstats
path: root/qemu/roms/u-boot/doc/driver-model
diff options
context:
space:
mode:
authorRajithaY <rajithax.yerrumsetty@intel.com>2017-04-25 03:31:15 -0700
committerRajitha Yerrumchetty <rajithax.yerrumsetty@intel.com>2017-05-22 06:48:08 +0000
commitbb756eebdac6fd24e8919e2c43f7d2c8c4091f59 (patch)
treeca11e03542edf2d8f631efeca5e1626d211107e3 /qemu/roms/u-boot/doc/driver-model
parenta14b48d18a9ed03ec191cf16b162206998a895ce (diff)
Adding qemu as a submodule of KVMFORNFV
This Patch includes the changes to add qemu as a submodule to kvmfornfv repo and make use of the updated latest qemu for the execution of all testcase Change-Id: I1280af507a857675c7f81d30c95255635667bdd7 Signed-off-by:RajithaY<rajithax.yerrumsetty@intel.com>
Diffstat (limited to 'qemu/roms/u-boot/doc/driver-model')
-rw-r--r--qemu/roms/u-boot/doc/driver-model/README.txt368
1 files changed, 0 insertions, 368 deletions
diff --git a/qemu/roms/u-boot/doc/driver-model/README.txt b/qemu/roms/u-boot/doc/driver-model/README.txt
deleted file mode 100644
index e0b395a61..000000000
--- a/qemu/roms/u-boot/doc/driver-model/README.txt
+++ /dev/null
@@ -1,368 +0,0 @@
-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 <marex@denx.de>
- Pavel Herrmann <morpheus.ibis@gmail.com>
- Viktor Křivák <viktor.krivak@gmail.com>
- Tomas Hlavacek <tmshlvck@gmail.com>
-
-This has been both simplified and extended into the current implementation
-by:
-
- Simon Glass <sjg@chromium.org>
-
-
-Terminology
------------
-
-Uclass - a group of devices 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
-
-(You can add '#define DEBUG' as suggested to check for memory leaks)
-
-
-What is going on?
------------------
-
-Let's start at the top. The demo command is in common/cmd_demo.c. It does
-the usual command procesing and then:
-
- struct device *demo_dev;
-
- ret = uclass_get_device(UCLASS_DEMO, devnum, &demo_dev);
-
-UCLASS_DEMO means the class of devices which implement 'demo'. Other
-classes might be MMC, or GPIO, hashing or serial. The idea is that the
-devices in the class all share a particular way of working. The class
-presents a unified view of all these devices to U-Boot.
-
-This function looks up a device for the demo uclass. Given a device
-number we can find the device because all devices have registered with
-the UCLASS_DEMO uclass.
-
-The device is automatically activated ready for use by uclass_get_device().
-
-Now that we have the device we can do things like:
-
- return demo_hello(demo_dev, ch);
-
-This function is in the demo uclass. It takes care of calling the 'hello'
-method of the relevant driver. Bearing in mind that there are two drivers,
-this particular device may use one or other of them.
-
-The code for demo_hello() is in drivers/demo/demo-uclass.c:
-
-int demo_hello(struct device *dev, int ch)
-{
- const struct demo_ops *ops = device_get_ops(dev);
-
- if (!ops->hello)
- return -ENOSYS;
-
- return ops->hello(dev, ch);
-}
-
-As you can see it just calls the relevant driver method. One of these is
-in drivers/demo/demo-simple.c:
-
-static int simple_hello(struct device *dev, int ch)
-{
- const struct dm_demo_pdata *pdata = dev_get_platdata(dev);
-
- printf("Hello from %08x: %s %d\n", map_to_sysmem(dev),
- pdata->colour, pdata->sides);
-
- return 0;
-}
-
-
-So that is a trip from top (command execution) to bottom (driver action)
-but it leaves a lot of topics to address.
-
-
-Declaring Drivers
------------------
-
-A driver declaration looks something like this (see
-drivers/demo/demo-shape.c):
-
-static const struct demo_ops shape_ops = {
- .hello = shape_hello,
- .status = shape_status,
-};
-
-U_BOOT_DRIVER(demo_shape_drv) = {
- .name = "demo_shape_drv",
- .id = UCLASS_DEMO,
- .ops = &shape_ops,
- .priv_data_size = sizeof(struct shape_data),
-};
-
-
-This driver has two methods (hello and status) and requires a bit of
-private data (accessible through dev_get_priv(dev) once the driver has
-been probed). It is a member of UCLASS_DEMO so will register itself
-there.
-
-In U_BOOT_DRIVER it is also possible to specify special methods for bind
-and unbind, and these are called at appropriate times. For many drivers
-it is hoped that only 'probe' and 'remove' will be needed.
-
-The U_BOOT_DRIVER macro creates a data structure accessible from C,
-so driver model can find the drivers that are available.
-
-The methods a device can provide are documented in the device.h header.
-Briefly, they are:
-
- bind - make the driver model aware of a device (bind it to its driver)
- unbind - make the driver model forget the device
- ofdata_to_platdata - convert device tree data to platdata - see later
- probe - make a device ready for use
- remove - remove a device so it cannot be used until probed again
-
-The sequence to get a device to work is bind, ofdata_to_platdata (if using
-device tree) and probe.
-
-
-Platform Data
--------------
-
-Where does the platform data come from? See demo-pdata.c which
-sets up a table of driver names and their associated platform data.
-The data can be interpreted by the drivers however they like - it is
-basically a communication scheme between the board-specific code and
-the generic drivers, which are intended to work on any board.
-
-Drivers can acceess their data via dev->info->platdata. Here is
-the declaration for the platform data, which would normally appear
-in the board file.
-
- static const struct dm_demo_cdata red_square = {
- .colour = "red",
- .sides = 4.
- };
- static const struct driver_info info[] = {
- {
- .name = "demo_shape_drv",
- .platdata = &red_square,
- },
- };
-
- demo1 = driver_bind(root, &info[0]);
-
-
-Device Tree
------------
-
-While platdata is useful, a more flexible way of providing device data is
-by using device tree. With device tree we replace the above code with the
-following device tree fragment:
-
- red-square {
- compatible = "demo-shape";
- colour = "red";
- sides = <4>;
- };
-
-
-The easiest way to make this work it to add a few members to the driver:
-
- .platdata_auto_alloc_size = sizeof(struct dm_test_pdata),
- .ofdata_to_platdata = testfdt_ofdata_to_platdata,
- .probe = testfdt_drv_probe,
-
-The 'auto_alloc' feature allowed space for the platdata to be allocated
-and zeroed before the driver's ofdata_to_platdata method is called. This
-method reads the information out of the device tree and puts it in
-dev->platdata. Then the probe method is called to set up the device.
-
-Note that both methods are optional. If you provide an ofdata_to_platdata
-method then it wlil be called first (after bind). If you provide a probe
-method it will be called next.
-
-If you don't want to have the platdata automatically allocated then you
-can leave out platdata_auto_alloc_size. In this case you can use malloc
-in your ofdata_to_platdata (or probe) method to allocate the required memory,
-and you should free it in the remove method.
-
-
-Declaring Uclasses
-------------------
-
-The demo uclass is declared like this:
-
-U_BOOT_CLASS(demo) = {
- .id = UCLASS_DEMO,
-};
-
-It is also possible to specify special methods for probe, etc. The uclass
-numbering comes from include/dm/uclass.h. To add a new uclass, add to the
-end of the enum there, then declare your uclass as above.
-
-
-Data Structures
----------------
-
-Driver model uses a doubly-linked list as the basic data structure. Some
-nodes have several lists running through them. Creating a more efficient
-data structure might be worthwhile in some rare cases, once we understand
-what the bottlenecks are.
-
-
-Changes since v1
-----------------
-
-For the record, this implementation uses a very similar approach to the
-original patches, but makes at least the following changes:
-
-- Tried to agressively remove boilerplate, so that for most drivers there
-is little or no 'driver model' code to write.
-- Moved some data from code into data structure - e.g. store a pointer to
-the driver operations structure in the driver, rather than passing it
-to the driver bind function.
-- Rename some structures to make them more similar to Linux (struct device
-instead of struct instance, struct platdata, etc.)
-- Change the name 'core' to 'uclass', meaning U-Boot class. It seems that
-this concept relates to a class of drivers (or a subsystem). We shouldn't
-use 'class' since it is a C++ reserved word, so U-Boot class (uclass) seems
-better than 'core'.
-- Remove 'struct driver_instance' and just use a single 'struct device'.
-This removes a level of indirection that doesn't seem necessary.
-- Built in device tree support, to avoid the need for platdata
-- Removed the concept of driver relocation, and just make it possible for
-the new driver (created after relocation) to access the old driver data.
-I feel that relocation is a very special case and will only apply to a few
-drivers, many of which can/will just re-init anyway. So the overhead of
-dealing with this might not be worth it.
-- Implemented a GPIO system, trying to keep it simple
-
-
-Things to punt for later
-------------------------
-
-- SPL support - this will have to be present before many drivers can be
-converted, but it seems like we can add it once we are happy with the
-core implementation.
-- Pre-relocation support - similar story
-
-That is not to say that no thinking has gone into these - in fact there
-is quite a lot there. However, getting these right is non-trivial and
-there is a high cost associated with going down the wrong path.
-
-For SPL, it may be possible to fit in a simplified driver model with only
-bind and probe methods, to reduce size.
-
-For pre-relocation we can simply call the driver model init function. Then
-post relocation we throw that away and re-init driver model again. For drivers
-which require some sort of continuity between pre- and post-relocation
-devices, we can provide access to the pre-relocation device pointers.
-
-Uclasses are statically numbered at compile time. It would be possible to
-change this to dynamic numbering, but then we would require some sort of
-lookup service, perhaps searching by name. This is slightly less efficient
-so has been left out for now. One small advantage of dynamic numbering might
-be fewer merge conflicts in uclass-id.h.
-
-
-Simon Glass
-sjg@chromium.org
-April 2013
-Updated 7-May-13
-Updated 14-Jun-13
-Updated 18-Oct-13
-Updated 5-Nov-13