Currently the Sphinx doc only contains API descriptions of several U-Boot subsystems. For future extension, group these existing docs into an API sub-directory.

Signed-off-by: Bin Meng bmeng.cn@gmail.com ---

doc/{ => api}/efi.rst | 3 +++ doc/api/index.rst | 10 ++++++++++ doc/{ => api}/linker_lists.rst | 3 +++ doc/{ => api}/serial.rst | 3 +++ doc/index.rst | 14 +++++++++++--- 5 files changed, 30 insertions(+), 3 deletions(-) rename doc/{ => api}/efi.rst (92%) create mode 100644 doc/api/index.rst rename doc/{ => api}/linker_lists.rst (99%) rename doc/{ => api}/serial.rst (80%)

diff --git a/doc/efi.rst b/doc/api/efi.rst similarity index 92% rename from doc/efi.rst rename to doc/api/efi.rst index 5337a55..3b2d544 100644 --- a/doc/efi.rst +++ b/doc/api/efi.rst @@ -1,5 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+

+.. toctree:: + :maxdepth: 2 + EFI subsystem =============

diff --git a/doc/api/index.rst b/doc/api/index.rst new file mode 100644 index 0000000..8e1e1a1 --- /dev/null +++ b/doc/api/index.rst @@ -0,0 +1,10 @@ +======================== +U-Boot API documentation +======================== + +.. toctree:: + :maxdepth: 2 + + efi + linker_lists + serial diff --git a/doc/linker_lists.rst b/doc/api/linker_lists.rst similarity index 99% rename from doc/linker_lists.rst rename to doc/api/linker_lists.rst index 72f514e..477bbae 100644 --- a/doc/linker_lists.rst +++ b/doc/api/linker_lists.rst @@ -1,5 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+

+.. toctree:: + :maxdepth: 2 + Linker-Generated Arrays =======================

diff --git a/doc/serial.rst b/doc/api/serial.rst similarity index 80% rename from doc/serial.rst rename to doc/api/serial.rst index ed34e59..65f10d3 100644 --- a/doc/serial.rst +++ b/doc/api/serial.rst @@ -1,5 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+

+.. toctree:: + :maxdepth: 2 + Serial system =============

diff --git a/doc/index.rst b/doc/index.rst index 0353c10..1946d09 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -4,8 +4,16 @@ U-Boot Developer Manual #######################

+U-Boot API documentation +------------------------ + +These books get into the details of how specific U-Boot subsystems work +from the point of view of a U-Boot developer. Much of the information here +is taken directly from the U-Boot source, with supplemental material added +as needed (or at least as we managed to add it - probably *not* all that is +needed). + .. toctree:: + :maxdepth: 2

- efi - linker_lists - serial + api/index

This updates the index.rst to add top-level description about U-Boot documentation. Words are taken from Linux kernel docs and modified for U-Boot.

Signed-off-by: Bin Meng bmeng.cn@gmail.com ---

doc/index.rst | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/doc/index.rst b/doc/index.rst index 1946d09..cfcf1dd 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,8 +1,19 @@ .. SPDX-License-Identifier: GPL-2.0+

-####################### -U-Boot Developer Manual -####################### +.. _u-boot_doc: + +The U-Boot documentation +======================== + +This is the top level of the U-Boot's documentation tree. U-Boot +documentation, like the U-Boot itself, is very much a work in progress; +that is especially true as we work to integrate our many scattered +documents into a coherent whole. Please note that improvements to the +documentation are welcome; join the U-Boot list at http://lists.denx.de +if you want to help out. + +.. toctree:: + :maxdepth: 2

U-Boot API documentation ------------------------ @@ -17,3 +28,8 @@ needed). :maxdepth: 2

api/index + +Indices and tables +================== + +* :ref:`genindex`

Add index.rst for driver model. More docs will be added later.

Signed-off-by: Bin Meng bmeng.cn@gmail.com ---

doc/driver-model/index.rst | 6 ++++++ doc/index.rst | 11 +++++++++++ 2 files changed, 17 insertions(+) create mode 100644 doc/driver-model/index.rst

diff --git a/doc/driver-model/index.rst b/doc/driver-model/index.rst new file mode 100644 index 0000000..c16a544 --- /dev/null +++ b/doc/driver-model/index.rst @@ -0,0 +1,6 @@ +============ +Driver Model +============ + +.. toctree:: + :maxdepth: 2 diff --git a/doc/index.rst b/doc/index.rst index cfcf1dd..835decf 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -15,6 +15,17 @@ if you want to help out. .. toctree:: :maxdepth: 2

+Driver-Model documentation +-------------------------- +The following holds information on the U-Boot device driver framework: +driver-model, including the design details of itself and several driver +subsystems. + +.. toctree:: + :maxdepth: 2 + + driver-model/index + U-Boot API documentation ------------------------

Convert plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.

Signed-off-by: Bin Meng bmeng.cn@gmail.com ---

doc/driver-model/{README.txt => design.rst} | 538 +++++++++++++++------------- doc/driver-model/index.rst | 2 + 2 files changed, 284 insertions(+), 256 deletions(-) rename doc/driver-model/{README.txt => design.rst} (68%)

diff --git a/doc/driver-model/README.txt b/doc/driver-model/design.rst similarity index 68% rename from doc/driver-model/README.txt rename to doc/driver-model/design.rst index 532a771..c8ec2be 100644 --- a/doc/driver-model/README.txt +++ b/doc/driver-model/design.rst @@ -1,40 +1,43 @@ -Driver Model -============ +Design Details +==============

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 + * 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 + * Simon Glass sjg@chromium.org

Terminology -----------

-Uclass - a group of devices which operate in the same way. A uclass provides - a way of accessing individual 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. +Uclass + a group of devices which operate in the same way. A uclass provides + a way of accessing individual 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. +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. +Device + an instance of a driver, tied to a particular port or peripheral.

How to try it -------------

-Build U-Boot sandbox and run it: +Build U-Boot sandbox and run it::

make sandbox_defconfig make @@ -56,31 +59,31 @@ 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 -=> +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 @@ -88,139 +91,139 @@ 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: +are provided in test/dm. To run them, try::

./test/py/test.py --bd sandbox --build -k ut_dm -v

-You should see something like this: - -(venv)$ ./test/py/test.py --bd sandbox --build -k ut_dm -v -+make O=/root/u-boot/build-sandbox -s sandbox_defconfig -+make O=/root/u-boot/build-sandbox -s -j8 -============================= test session starts ============================== -platform linux2 -- Python 2.7.5, pytest-2.9.0, py-1.4.31, pluggy-0.3.1 -- /root/u-boot/venv/bin/python -cachedir: .cache -rootdir: /root/u-boot, inifile: -collected 199 items - -test/py/tests/test_ut.py::test_ut_dm_init PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_adc_bind] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_conversion] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_shot] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_conversion] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_shot] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_adc_supply] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_adc_wrong_channel_selection] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_autobind] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_alloc] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_valid] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_autoprobe] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind_uclass] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_pre_probe_uclass] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_bus_children] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_funcs] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_iterators] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data_uclass] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_ops] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata_uclass] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_children] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_clk_base] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_clk_periph] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_device_get_uclass_id] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_eth] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_eth_act] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_eth_alias] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_eth_prime] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_eth_rotate] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_fdt] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_fdt_offset] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_fdt_pre_reloc] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_fdt_uclass_seq] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_gpio] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_gpio_anon] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_gpio_copy] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_gpio_leak] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_gpio_phandles] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_gpio_requestf] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_i2c_bytewise] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_i2c_find] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset_len] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_i2c_probe_empty] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_i2c_read_write] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_i2c_speed] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_leak] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_led_base] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_led_gpio] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_led_label] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_lifecycle] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_mmc_base] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_net_retry] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_operations] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_ordering] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_pci_base] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_pci_busnum] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_pci_swapcase] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_platdata] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_get] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_io] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset_list] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_get] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_current] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_enable] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_mode] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_voltage] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_pre_reloc] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_ram_base] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_regmap_base] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_regmap_syscon] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_remoteproc_base] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_remove] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_reset_base] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_reset_walk] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_rtc_base] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_rtc_dual] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_rtc_reset] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_rtc_set_get] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_spi_find] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_spi_flash] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_spi_xfer] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_syscon_base] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_syscon_by_driver_data] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_timer_base] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_uclass] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_uclass_before_ready] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find_by_name] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get_by_name] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_usb_base] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_usb_flash] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_usb_keyb] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_usb_multi] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_usb_remove] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_remove] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_reorder] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_video_base] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp_comp] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_video_chars] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_video_context] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation1] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation2] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation3] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_video_text] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_bs] PASSED -test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_scroll] PASSED - -======================= 84 tests deselected by '-kut_dm' ======================= -================== 115 passed, 84 deselected in 3.77 seconds =================== +You should see something like this:: + + (venv)$ ./test/py/test.py --bd sandbox --build -k ut_dm -v + +make O=/root/u-boot/build-sandbox -s sandbox_defconfig + +make O=/root/u-boot/build-sandbox -s -j8 + ============================= test session starts ============================== + platform linux2 -- Python 2.7.5, pytest-2.9.0, py-1.4.31, pluggy-0.3.1 -- /root/u-boot/venv/bin/python + cachedir: .cache + rootdir: /root/u-boot, inifile: + collected 199 items + + test/py/tests/test_ut.py::test_ut_dm_init PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_bind] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_conversion] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_shot] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_conversion] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_shot] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_supply] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_wrong_channel_selection] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_autobind] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_alloc] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_valid] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_autoprobe] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_pre_probe_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_children] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_funcs] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_iterators] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_ops] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_children] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_clk_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_clk_periph] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_device_get_uclass_id] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth_act] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth_alias] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth_prime] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth_rotate] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_fdt] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_fdt_offset] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_fdt_pre_reloc] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_fdt_uclass_seq] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_anon] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_copy] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_leak] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_phandles] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_requestf] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_bytewise] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_find] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset_len] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_probe_empty] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_read_write] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_speed] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_leak] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_led_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_led_gpio] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_led_label] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_lifecycle] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_mmc_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_net_retry] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_operations] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_ordering] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_pci_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_pci_busnum] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_pci_swapcase] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_platdata] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_get] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_io] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset_list] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_get] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_current] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_enable] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_mode] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_voltage] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_pre_reloc] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_ram_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_regmap_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_regmap_syscon] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_remoteproc_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_remove] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_reset_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_reset_walk] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_rtc_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_rtc_dual] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_rtc_reset] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_rtc_set_get] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_spi_find] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_spi_flash] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_spi_xfer] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_syscon_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_syscon_by_driver_data] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_timer_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_before_ready] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find_by_name] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get_by_name] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_flash] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_keyb] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_multi] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_remove] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_remove] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_reorder] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp_comp] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_chars] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_context] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation1] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation2] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation3] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_text] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_bs] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_scroll] PASSED + + ======================= 84 tests deselected by '-kut_dm' ======================= + ================== 115 passed, 84 deselected in 3.77 seconds ===================

What is going on? ----------------- @@ -228,6 +231,8 @@ What is going on? Let's start at the top. The demo command is in common/cmd_demo.c. It does the usual command processing and then:

+.. code-block:: c + struct udevice *demo_dev;

ret = uclass_get_device(UCLASS_DEMO, devnum, &demo_dev); @@ -245,6 +250,8 @@ The device is automatically activated ready for use by uclass_get_device().

Now that we have the device we can do things like:

+.. code-block:: c + return demo_hello(demo_dev, ch);

This function is in the demo uclass. It takes care of calling the 'hello' @@ -253,28 +260,32 @@ 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 udevice *dev, int ch) -{ - const struct demo_ops *ops = device_get_ops(dev); +.. code-block:: c + + int demo_hello(struct udevice *dev, int ch) + { + const struct demo_ops *ops = device_get_ops(dev);

- if (!ops->hello) - return -ENOSYS; + if (!ops->hello) + return -ENOSYS;

- return ops->hello(dev, ch); -} + 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 udevice *dev, int ch) -{ - const struct dm_demo_pdata *pdata = dev_get_platdata(dev); +.. code-block:: c

- printf("Hello from %08x: %s %d\n", map_to_sysmem(dev), - pdata->colour, pdata->sides); + static int simple_hello(struct udevice *dev, int ch) + { + const struct dm_demo_pdata *pdata = dev_get_platdata(dev);

- return 0; -} + 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) @@ -285,19 +296,21 @@ Declaring Drivers -----------------

A driver declaration looks something like this (see -drivers/demo/demo-shape.c): +drivers/demo/demo-shape.c). + +.. code-block:: c

-static const struct demo_ops shape_ops = { - .hello = shape_hello, - .status = shape_status, -}; + 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), -}; + 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 @@ -315,11 +328,11 @@ 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 + * 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. @@ -328,14 +341,14 @@ device tree) and probe. Platform Data -------------

-*** Note: platform data is the old way of doing things. It is -*** basically a C structure which is passed to drivers to tell them about -*** platform-specific settings like the address of its registers, bus -*** speed, etc. Device tree is now the preferred way of handling this. -*** Unless you have a good reason not to use device tree (the main one -*** being you need serial support in SPL and don't have enough SRAM for -*** the cut-down device tree and libfdt libraries) you should stay away -*** from platform data. +Note: platform data is the old way of doing things. It is +basically a C structure which is passed to drivers to tell them about +platform-specific settings like the address of its registers, bus +speed, etc. Device tree is now the preferred way of handling this. +Unless you have a good reason not to use device tree (the main one +being you need serial support in SPL and don't have enough SRAM for +the cut-down device tree and libfdt libraries) you should stay away +from platform data.

Platform data is like Linux platform data, if you are familiar with that. It provides the board-specific information to start up a device. @@ -366,9 +379,9 @@ Examples of platform data include:

- The base address of the IP block's register space - Configuration options, like: - - the SPI polarity and maximum speed for a SPI controller - - the I2C speed to use for an I2C device - - the number of GPIOs available in a GPIO device + - the SPI polarity and maximum speed for a SPI controller + - the I2C speed to use for an I2C device + - the number of GPIOs available in a GPIO device

Where does the platform data come from? It is either held in a structure which is compiled into U-Boot, or it can be parsed from the Device Tree @@ -382,12 +395,15 @@ the generic drivers, which are intended to work on any board.

Drivers can access their data via dev->info->platdata. Here is the declaration for the platform data, which would normally appear -in the board file. +in the board file: + +.. code-block:: c

static const struct dm_demo_cdata red_square = { .colour = "red", .sides = 4. }; + static const struct driver_info info[] = { { .name = "demo_shape_drv", @@ -409,6 +425,8 @@ necessary. With device tree we replace the above code with the following device tree fragment:

+.. code-block:: c + red-square { compatible = "demo-shape"; colour = "red"; @@ -425,6 +443,8 @@ the board first!).

The easiest way to make this work it to add a few members to the driver:

+.. code-block:: c + .platdata_auto_alloc_size = sizeof(struct dm_test_pdata), .ofdata_to_platdata = testfdt_ofdata_to_platdata,

@@ -464,9 +484,11 @@ Declaring Uclasses

The demo uclass is declared like this:

-U_BOOT_CLASS(demo) = { - .id = UCLASS_DEMO, -}; +.. code-block:: c + + 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 @@ -496,9 +518,11 @@ device will be automatically allocated the next available sequence number. To specify the sequence number in the device tree an alias is typically used. Make sure that the uclass has the DM_UC_FLAG_SEQ_ALIAS flag set.

-aliases { - serial2 = "/serial@22230000"; -}; +.. code-block:: none + + aliases { + serial2 = "/serial@22230000"; + };

This indicates that in the uclass called "serial", the named node ("/serial@22230000") will be given sequence number 2. Any command or driver @@ -506,13 +530,15 @@ which requests serial device 2 will obtain this device.

More commonly you can use node references, which expand to the full path:

-aliases { - serial2 = &serial_2; -}; -... -serial_2: serial@22230000 { -... -}; +.. code-block:: none + + aliases { + serial2 = &serial_2; + }; + ... + serial_2: serial@22230000 { + ... + };

The alias resolves to the same string in this case, but this version is easier to read. @@ -547,7 +573,7 @@ children are bound and probed.

Here an explanation of how a bus fits with a uclass may be useful. Consider a USB bus with several devices attached to it, each from a different (made -up) uclass: +up) uclass::

xhci_usb (UCLASS_USB) eth (UCLASS_ETHERNET) @@ -579,7 +605,7 @@ Note that the information that controls this behaviour is in the bus's driver, not the child's. In fact it is possible that child has no knowledge that it is connected to a bus. The same child device may even be used on two different bus types. As an example. the 'flash' device shown above may also -be connected on a SATA bus or standalone with no bus: +be connected on a SATA bus or standalone with no bus::

xhci_usb (UCLASS_USB) flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by USB bus @@ -617,16 +643,16 @@ methods actually defined.

U-Boot discovers devices using one of these two methods:

- - Scan the U_BOOT_DEVICE() definitions. U-Boot looks up the name specified -by each, to find the appropriate U_BOOT_DRIVER() definition. In this case, -there is no path by which driver_data may be provided, but the U_BOOT_DEVICE() -may provide platdata. +- Scan the U_BOOT_DEVICE() definitions. U-Boot looks up the name specified + by each, to find the appropriate U_BOOT_DRIVER() definition. In this case, + there is no path by which driver_data may be provided, but the U_BOOT_DEVICE() + may provide platdata.

- - Scan through the device tree definitions. U-Boot looks at top-level -nodes in the the device tree. It looks at the compatible string in each node -and uses the of_match table of the U_BOOT_DRIVER() structure to find the -right driver for each node. In this case, the of_match table may provide a -driver_data value, but platdata cannot be provided until later. +- Scan through the device tree definitions. U-Boot looks at top-level + nodes in the the device tree. It looks at the compatible string in each node + and uses the of_match table of the U_BOOT_DRIVER() structure to find the + right driver for each node. In this case, the of_match table may provide a + driver_data value, but platdata cannot be provided until later.

For each device that is discovered, U-Boot then calls device_bind() to create a new device, initializes various core fields of the device object such as name, @@ -805,24 +831,24 @@ For the record, this implementation uses a very similar approach to the original patches, but makes at least the following changes:

- Tried to aggressively remove boilerplate, so that for most drivers there -is little or no 'driver model' code to write. + 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. + 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 udevice -instead of struct instance, struct platdata, etc.) + 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'. + 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 udevice'. -This removes a level of indirection that doesn't seem necessary. + 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. + 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

@@ -905,10 +931,10 @@ 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 +:author: Simon Glass sjg@chromium.org + +.. April 2013 +.. Updated 7-May-13 +.. Updated 14-Jun-13 +.. Updated 18-Oct-13 +.. Updated 5-Nov-13 diff --git a/doc/driver-model/index.rst b/doc/driver-model/index.rst index c16a544..ae28dc0 100644 --- a/doc/driver-model/index.rst +++ b/doc/driver-model/index.rst @@ -4,3 +4,5 @@ Driver Model

.. toctree:: :maxdepth: 2 + + design