Initial layout for Sphinx HTML docs
cover Initial layout for Sphinx HTML docs
At present there is Sphinx doc build system in U-Boot, however the contents are very limited, that only a few API descriptions for EFI, are included.
This series proposes an initial Sphinx doc layout for future extension, by converting some of the plain text documentation to reStructuredText format and add it to Sphinx TOC tree.
@Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
This series is available at u-boot-x86/doc for testing.
Bin Meng (9):
doc: Move existing rst files into api sub-directory
doc: Add top-level description about U-Boot documentation
doc: Add driver-model to Sphinx TOC tree
doc: driver-model: Convert README.txt to reST
doc: driver-model: Convert MIGRATION.txt to reST
doc: Add architecture specific info to Sphinx TOC tree
doc: arch: Convert README.mips to reST
doc: Add board to Sphinx TOC tree
doc: board: Add Intel Crown Bay board doc
doc/README.x86 | 37 --
doc/{ => api}/efi.rst | 3 +
doc/api/index.rst | 10 +
doc/{ => api}/linker_lists.rst | 3 +
doc/{ => api}/serial.rst | 3 +
doc/arch/index.rst | 8 +
doc/{README.mips => arch/mips.rst} | 14 +-
doc/board/index.rst | 8 +
doc/board/intel/crownbay.rst | 49 ++
doc/board/intel/index.rst | 4 +
doc/driver-model/{README.txt => design.rst} | 538 ++++++++++++----------
doc/driver-model/index.rst | 9 +
doc/driver-model/{MIGRATION.txt => migration.rst} | 42 +-
doc/index.rst | 69 ++-
14 files changed, 469 insertions(+), 328 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%)
create mode 100644 doc/arch/index.rst
rename doc/{README.mips => arch/mips.rst} (87%)
create mode 100644 doc/board/index.rst
create mode 100644 doc/board/intel/crownbay.rst
create mode 100644 doc/board/intel/index.rst
rename doc/driver-model/{README.txt => design.rst} (68%)
create mode 100644 doc/driver-model/index.rst
rename doc/driver-model/{MIGRATION.txt => migration.rst} (85%)Signature · 1 line
2.7.4
RFC PATCH 1/9 doc: Move existing rst files into api sub-directory
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.
---
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%)doc/api/efi.rst renamed from doc/efi.rst +3 -0
@@ -1,5 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ +.. toctree:: + :maxdepth: 2 + EFI subsystem =============
doc/api/index.rst new file +10 -0
@@ -0,0 +1,10 @@ +======================== +U-Boot API documentation +======================== + +.. toctree:: + :maxdepth: 2 + + efi + linker_lists + serial
doc/api/linker_lists.rst renamed from doc/linker_lists.rst +3 -0
@@ -1,5 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ +.. toctree:: + :maxdepth: 2 + Linker-Generated Arrays =======================
doc/api/serial.rst renamed from doc/serial.rst +3 -0
@@ -1,5 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ +.. toctree:: + :maxdepth: 2 + Serial system =============
doc/index.rst +11 -3
@@ -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
Signature · 1 line
2.7.4
RFC PATCH 1/9 doc: Move existing rst files into api sub-directory
Quoted 5 lines · Bin Meng
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 <[email protected]>
RFC PATCH 1/9 doc: Move existing rst files into api sub-directory
Quoted 9 lines · Heinrich Schuchardt
Quoted 5 lines · Bin Meng
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 <[email protected]>Reviewed-by Heinrich Schuchardt <[email protected]>
Hello Bin,
efi_loader: add more sources to Sphinx documentation
https://lists.denx.de/pipermail/u-boot/2019-July/376382.html
https://patchwork.ozlabs.org/patch/1131726/
This patch may lead to a merge conflict.
If you resubmit, consider rebasing on it.
Best regards
Heinrich
RFC PATCH 1/9 doc: Move existing rst files into api sub-directory
Hi Heinrich,
Quoted 14 lines · Heinrich Schuchardt
Quoted 9 lines · Heinrich Schuchardt
Quoted 5 lines · Bin Meng
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 <[email protected]>Reviewed-by Heinrich Schuchardt <[email protected]>Hello Bin,
Quoted 7 lines
efi_loader: add more sources to Sphinx documentation
https://lists.denx.de/pipermail/u-boot/2019-July/376382.html
https://patchwork.ozlabs.org/patch/1131726/This patch may lead to a merge conflict.
If you resubmit, consider rebasing on it.
Thanks for the review. I will rebase on that when I resubmit this series.
Regards,
Bin
RFC PATCH 2/9 doc: Add top-level description about U-Boot documentation
In reply to Bin MengThis 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.
---
doc/index.rst | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-)
doc/index.rst +19 -3
@@ -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`
Signature · 1 line
2.7.4
RFC PATCH 2/9 doc: Add top-level description about U-Boot documentation
Quoted 5 lines · Bin Meng
This updates the
index.rstto 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 <[email protected]>
RFC PATCH 3/9 doc: Add driver-model to Sphinx TOC tree
In reply to Bin MengAdd index.rst for driver model. More docs will be added later.
---
doc/driver-model/index.rst | 6 ++++++ doc/index.rst | 11 +++++++++++ 2 files changed, 17 insertions(+) create mode 100644 doc/driver-model/index.rst
doc/driver-model/index.rst new file +6 -0
@@ -0,0 +1,6 @@ +============ +Driver Model +============ + +.. toctree:: + :maxdepth: 2
doc/index.rst +11 -0
@@ -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 ------------------------
Signature · 1 line
2.7.4
RFC PATCH 3/9 doc: Add driver-model to Sphinx TOC tree
Quoted 3 lines · Bin Meng
Add
index.rstfor driver model. More docs will be added later.Signed-off-by Bin Meng <[email protected]>
RFC PATCH 4/9 doc: driver-model: Convert README.txt to reST
In reply to Bin MengConvert plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
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%)doc/driver-model/design.rst renamed from doc/driver-model/README.txt +282 -256
@@ -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 <[email protected]> - Pavel Herrmann <[email protected]> - Viktor Křivák <[email protected]> - Tomas Hlavacek <[email protected]> + * Marek Vasut <[email protected]> + * Pavel Herrmann <[email protected]> + * Viktor Křivák <[email protected]> + * Tomas Hlavacek <[email protected]> This has been both simplified and extended into the current implementation by: - Simon Glass <[email protected]> + * Simon Glass <[email protected]> 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 at 22230000"; -}; +.. code-block:: none + + aliases { + serial2 = "/serial at 22230000"; + }; This indicates that in the uclass called "serial", the named node ("/serial at 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 at 22230000 { -... -}; +.. code-block:: none + + aliases { + serial2 = &serial_2; + }; + ... + serial_2: serial at 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 at chromium.org -April 2013 -Updated 7-May-13 -Updated 14-Jun-13 -Updated 18-Oct-13 -Updated 5-Nov-13 +:author: Simon Glass <[email protected]> + +.. April 2013 +.. Updated 7-May-13 +.. Updated 14-Jun-13 +.. Updated 18-Oct-13 +.. Updated 5-Nov-13
doc/driver-model/index.rst +2 -0
@@ -4,3 +4,5 @@ Driver Model .. toctree:: :maxdepth: 2 + + design
Signature · 1 line
2.7.4
RFC PATCH 4/9 doc: driver-model: Convert README.txt to reST
Quoted 5 lines · Bin Meng
Convert plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
Signed-off-by Bin Meng <[email protected]>---
I think these could be converted to level 3 sub-headings
1. Bind stage
2. Activation/probe
3. Running stage
4. Removal stage
5. Unbind stage
And then convert a) - h) to an unnumbered list.
But that can also be done in a later patch.
Otherwise
RFC PATCH 4/9 doc: driver-model: Convert README.txt to reST
Hi Heinrich,
Quoted 10 lines · Heinrich Schuchardt
Quoted 5 lines · Bin Meng
Convert plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
Signed-off-by Bin Meng <[email protected]>---
I think these could be converted to level 3 sub-headings
Quoted 8 lines
1. Bind stage
2. Activation/probe
3. Running stage
4. Removal stage
5. Unbind stageAnd then convert a) - h) to an unnumbered list.
Thanks for the review. I will update the doc in the next version.
Quoted 5 lines
But that can also be done in a later patch.
Otherwise
Reviewed-by Heinrich Schuchardt <[email protected]>
Regards,
Bin
RFC PATCH 5/9 doc: driver-model: Convert MIGRATION.txt to reST
In reply to Bin MengConvert plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
doc/driver-model/index.rst | 1 +
doc/driver-model/{MIGRATION.txt => migration.rst} | 42 ++++++++++-------------
2 files changed, 20 insertions(+), 23 deletions(-)
rename doc/driver-model/{MIGRATION.txt => migration.rst} (85%)doc/driver-model/index.rst +1 -0
@@ -6,3 +6,4 @@ Driver Model :maxdepth: 2 design + migration
doc/driver-model/migration.rst renamed from doc/driver-model/MIGRATION.txt +19 -23
93 lines not on this page · raw message
Signature · 1 line
2.7.4
RFC PATCH 5/9 doc: driver-model: Convert MIGRATION.txt to reST
Quoted 4 lines · Bin Meng
Convert plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
Signed-off-by Bin Meng <[email protected]>
The conversion to RST is correct but we should rethink the values and effect of the deadlines.
RFC PATCH 6/9 doc: Add architecture specific info to Sphinx TOC tree
In reply to Bin MengAdd index.rst for architecture specific info. More docs will be added later.
---
doc/arch/index.rst | 6 ++++++ doc/index.rst | 11 +++++++++++ 2 files changed, 17 insertions(+) create mode 100644 doc/arch/index.rst
doc/arch/index.rst new file +6 -0
@@ -0,0 +1,6 @@ +========================= +Architecture-specific doc +========================= + +.. toctree:: + :maxdepth: 2
doc/index.rst +11 -0
@@ -40,6 +40,17 @@ needed). api/index +Architecture-specific doc +------------------------- + +These books provide programming details about architecture-specific +implementation. + +.. toctree:: + :maxdepth: 2 + + arch/index + Indices and tables ==================
Signature · 1 line
2.7.4
RFC PATCH 6/9 doc: Add architecture specific info to Sphinx TOC tree
Quoted 4 lines · Bin Meng
Add
index.rstfor architecture specific info. More docs will be added later.Signed-off-by Bin Meng <[email protected]>
RFC PATCH 7/9 doc: arch: Convert README.mips to reST
In reply to Bin MengConvert plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
doc/arch/index.rst | 2 ++
doc/{README.mips => arch/mips.rst} | 14 ++++++++------
2 files changed, 10 insertions(+), 6 deletions(-)
rename doc/{README.mips => arch/mips.rst} (87%)doc/arch/index.rst +2 -0
@@ -4,3 +4,5 @@ Architecture-specific doc .. toctree:: :maxdepth: 2 + + mips
doc/arch/mips.rst renamed from doc/README.mips +8 -6
@@ -1,17 +1,19 @@ +MIPS +==== Notes for the MIPS architecture port of U-Boot Toolchains ---------- - http://www.denx.de/wiki/DULG/ELDK - ELDK < DULG < DENX + * http://www.denx.de/wiki/DULG/ELDK + ELDK < DULG < DENX - http://www.emdebian.org/crosstools.html - Embedded Debian -- Cross-development toolchains + * http://www.emdebian.org/crosstools.html + Embedded Debian -- Cross-development toolchains - http://buildroot.uclibc.org/ - Buildroot + * http://buildroot.uclibc.org/ + Buildroot Known Issues ------------
Signature · 1 line
2.7.4
RFC PATCH 7/9 doc: arch: Convert README.mips to reST
Quoted 4 lines · Bin Meng
Convert plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
Signed-off-by Bin Meng <[email protected]>
RFC PATCH 8/9 doc: Add board to Sphinx TOC tree
In reply to Bin MengAdd index.rst for board. More docs will be added later.
---
doc/board/index.rst | 6 ++++++ doc/index.rst | 11 +++++++++++ 2 files changed, 17 insertions(+) create mode 100644 doc/board/index.rst
doc/board/index.rst new file +6 -0
@@ -0,0 +1,6 @@ +================== +Board-specific doc +================== + +.. toctree:: + :maxdepth: 2
doc/index.rst +11 -0
@@ -51,6 +51,17 @@ implementation. arch/index +Board-specific doc +------------------ + +These books provide details about board-specific information. They are +organized in a vendor subdirectory. + +.. toctree:: + :maxdepth: 2 + + board/index + Indices and tables ==================
Signature · 1 line
2.7.4
RFC PATCH 8/9 doc: Add board to Sphinx TOC tree
Quoted 3 lines · Bin Meng
Add
index.rstfor board. More docs will be added later.Signed-off-by Bin Meng <[email protected]>
RFC PATCH 9/9 doc: board: Add Intel Crown Bay board doc
In reply to Bin MengThis extracts Intel Crown Bay board specific information from README.x86, converts plain text documentation to reST format and adds it to Sphinx TOC tree. No essential content change.
---
doc/README.x86 | 37 --------------------------------- doc/board/index.rst | 2 ++ doc/board/intel/crownbay.rst | 49 ++++++++++++++++++++++++++++++++++++++++++++ doc/board/intel/index.rst | 4 ++++ 4 files changed, 55 insertions(+), 37 deletions(-) create mode 100644 doc/board/intel/crownbay.rst create mode 100644 doc/board/intel/index.rst
doc/README.x86 +0 -37
@@ -203,43 +203,6 @@ Flash map for samus / broadwell: --- -Intel Crown Bay specific instructions for bare mode: - -U-Boot support of Intel Crown Bay board [4] relies on a binary blob called -Firmware Support Package [5] to perform all the necessary initialization steps -as documented in the BIOS Writer Guide, including initialization of the CPU, -memory controller, chipset and certain bus interfaces. - -Download the Intel FSP for Atom E6xx series and Platform Controller Hub EG20T, -install it on your host and locate the FSP binary blob. Note this platform -also requires a Chipset Micro Code (CMC) state machine binary to be present in -the SPI flash where u-boot.rom resides, and this CMC binary blob can be found -in this FSP package too. - -* ./FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd -* ./Microcode/C0_22211.BIN - -Rename the first one to fsp.bin and second one to cmc.bin and put them in the -board directory. - -Note the FSP release version 001 has a bug which could cause random endless -loop during the FspInit call. This bug was published by Intel although Intel -did not describe any details. We need manually apply the patch to the FSP -binary using any hex editor (eg: bvi). Go to the offset 0x1fcd8 of the FSP -binary, change the following five bytes values from orginally E8 42 FF FF FF -to B8 00 80 0B 00. - -As for the video ROM, you need manually extract it from the Intel provided -BIOS for Crown Bay here [6], using the AMI MMTool [7]. Check PCI option ROM -ID 8086:4108, extract and save it as vga.bin in the board directory. - -Now you can build U-Boot and obtain u-boot.rom - -$ make crownbay_defconfig -$ make all - ---- - Intel Cougar Canyon 2 specific instructions for bare mode: This uses Intel FSP for 3rd generation Intel Core and Intel Celeron processors
doc/board/index.rst +2 -0
@@ -4,3 +4,5 @@ Board-specific doc .. toctree:: :maxdepth: 2 + + intel/index
doc/board/intel/crownbay.rst new file +49 -0
49 lines not on this page · raw message
doc/board/intel/index.rst new file +4 -0
@@ -0,0 +1,4 @@ +.. toctree:: + :maxdepth: 2 + + crownbay
Signature · 1 line
2.7.4
RFC PATCH 9/9 doc: board: Add Intel Crown Bay board doc
Quoted 115 lines · Bin Meng
This extracts Intel Crown Bay board specific information from README.x86, converts plain text documentation to reST format and adds it to Sphinx TOC tree. No essential content change.
Signed-off-by Bin Meng <[email protected]>---
doc/README.x86 | 37 --------------------------------- doc/board/index.rst | 2 ++ doc/board/intel/crownbay.rst | 49 ++++++++++++++++++++++++++++++++++++++++++++ doc/board/intel/index.rst | 4 ++++ 4 files changed, 55 insertions(+), 37 deletions(-) create mode 100644 doc/board/intel/crownbay.rst create mode 100644 doc/board/intel/index.rstdoc/README.x86 +0
-37@@ -203,43 +203,6 @@ Flash map for samus / broadwell: --- -Intel Crown Bay specific instructions for bare mode: - -U-Boot support of Intel Crown Bay board [4] relies on a binary blob called -Firmware Support Package [5] to perform all the necessary initialization steps -as documented in the BIOS Writer Guide, including initialization of the CPU, -memory controller, chipset and certain bus interfaces. - -Download the Intel FSP for Atom E6xx series and Platform Controller Hub EG20T, -install it on your host and locate the FSP binary blob. Note this platform -also requires a Chipset Micro Code (CMC) state machine binary to be present in -the SPI flash where u-boot.rom resides, and this CMC binary blob can be found -in this FSP package too. - -* ./FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd -* ./Microcode/C0_22211.BIN - -Rename the first one to fsp.bin and second one to cmc.bin and put them in the -board directory. - -Note the FSP release version 001 has a bug which could cause random endless -loop during the FspInit call. This bug was published by Intel although Intel -did not describe any details. We need manually apply the patch to the FSP -binary using any hex editor (eg: bvi). Go to the offset 0x1fcd8 of the FSP -binary, change the following five bytes values from orginally E8 42 FF FF FF -to B8 00 80 0B 00. - -As for the video ROM, you need manually extract it from the Intel provided -BIOS for Crown Bay here [6], using the AMI MMTool [7]. Check PCI option ROM -ID 8086:4108, extract and save it as vga.bin in the board directory. - -Now you can build U-Boot and obtain u-boot.rom - -$ make crownbay_defconfig -$ make all - ---- - Intel Cougar Canyon 2 specific instructions for bare mode: This uses Intel FSP for 3rd generation Intel Core and Intel Celeron processorsdoc/board/index.rst +2
-0@@ -4,3 +4,5 @@ Board-specific doc .. toctree:: :maxdepth: 2 + + intel/indexdoc/board/intel/crownbay.rst new file +35
-0@@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +:author: Bin Meng <[email protected]> + +.. toctree:: + :maxdepth: 2 + +Intel CrownBay CRB +================== + +U-Boot support of Intel Crown Bay board `[1]`_ relies on a binary blob called +Firmware Support Package `[2]`_ to perform all the necessary initialization +steps as documented in the BIOS Writer Guide, including initialization of the +CPU, memory controller, chipset and certain bus interfaces. + +Download the Intel FSP for Atom E6xx series and Platform Controller Hub EG20T, +install it on your host and locate the FSP binary blob. Note this platform +also requires a Chipset Micro Code (CMC) state machine binary to be present in +the SPI flash where u-boot.rom resides, and this CMC binary blob can be found +in this FSP package too. + +* ./FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd +* ./Microcode/C0_22211.BIN + +Rename the first one to fsp.bin and second one to cmc.bin and put them in the +board directory. + +Note the FSP release version 001 has a bug which could cause random endless +loop during the FspInit call. This bug was published by Intel although Intel +did not describe any details. We need manually apply the patch to the FSP +binary using any hex editor (eg: bvi). Go to the offset 0x1fcd8 of the FSP +binary, change the following five bytes values from orginally E8 42 FF FF FF +to B8 00 80 0B 00. + +As for the video ROM, you need manually extract it from the Intel provided
doc/board/intel/crownbay.rst line 45
Quoted 10 lines
doc/board/intel/crownbay.rst new file +10
-0+BIOS for Crown Bay here `[3]`_, using the AMI MMTool `[4]`_. Check PCI option +ROM ID 8086:4108, extract and save it as vga.bin in the board directory. + +Now you can build U-Boot and obtain u-boot.rom + +.. code-block:: shell + + $ make crownbay_defconfig + $ make all +
The following lines do not show up in the generated HTML. Please, recheck.
Best regards
Heinrich
Quoted 16 lines
doc/board/intel/crownbay.rst new file +4
-0+.. _[1]: http://www.intel.com/content/www/us/en/embedded/design-tools/evaluation-platforms/atom-e660-eg20t-development-kit.html +.. _[2]: http://www.intel.com/fsp +.. _[3]: http://www.intel.com/content/www/us/en/secure/intelligent-systems/privileged/e6xx-35-b1-cmc22211.html +.. _[4]: http://www.ami.com/products/bios-uefi-tools-and-utilities/bios-uefi-utilities/doc/board/intel/index.rst new file +4
-0@@ -0,0 +1,4 @@ +.. toctree:: + :maxdepth: 2 + + crownbay
RFC PATCH 9/9 doc: board: Add Intel Crown Bay board doc
Hi Heinrich,
Quoted 121 lines · Heinrich Schuchardt
Quoted 119 lines · Bin Meng
This extracts Intel Crown Bay board specific information from README.x86, converts plain text documentation to reST format and adds it to Sphinx TOC tree. No essential content change.
Signed-off-by Bin Meng <[email protected]>---
doc/README.x86 | 37 --------------------------------- doc/board/index.rst | 2 ++ doc/board/intel/crownbay.rst | 49 ++++++++++++++++++++++++++++++++++++++++++++ doc/board/intel/index.rst | 4 ++++ 4 files changed, 55 insertions(+), 37 deletions(-) create mode 100644 doc/board/intel/crownbay.rst create mode 100644 doc/board/intel/index.rstdoc/README.x86 +0
-37@@ -203,43 +203,6 @@ Flash map for samus / broadwell: --- -Intel Crown Bay specific instructions for bare mode: - -U-Boot support of Intel Crown Bay board [4] relies on a binary blob called -Firmware Support Package [5] to perform all the necessary initialization steps -as documented in the BIOS Writer Guide, including initialization of the CPU, -memory controller, chipset and certain bus interfaces. - -Download the Intel FSP for Atom E6xx series and Platform Controller Hub EG20T, -install it on your host and locate the FSP binary blob. Note this platform -also requires a Chipset Micro Code (CMC) state machine binary to be present in -the SPI flash where u-boot.rom resides, and this CMC binary blob can be found -in this FSP package too. - -* ./FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd -* ./Microcode/C0_22211.BIN - -Rename the first one to fsp.bin and second one to cmc.bin and put them in the -board directory. - -Note the FSP release version 001 has a bug which could cause random endless -loop during the FspInit call. This bug was published by Intel although Intel -did not describe any details. We need manually apply the patch to the FSP -binary using any hex editor (eg: bvi). Go to the offset 0x1fcd8 of the FSP -binary, change the following five bytes values from orginally E8 42 FF FF FF -to B8 00 80 0B 00. - -As for the video ROM, you need manually extract it from the Intel provided -BIOS for Crown Bay here [6], using the AMI MMTool [7]. Check PCI option ROM -ID 8086:4108, extract and save it as vga.bin in the board directory. - -Now you can build U-Boot and obtain u-boot.rom - -$ make crownbay_defconfig -$ make all - ---- - Intel Cougar Canyon 2 specific instructions for bare mode: This uses Intel FSP for 3rd generation Intel Core and Intel Celeron processorsdoc/board/index.rst +2
-0@@ -4,3 +4,5 @@ Board-specific doc .. toctree:: :maxdepth: 2 + + intel/indexdoc/board/intel/crownbay.rst new file +39
-0@@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +:author: Bin Meng <[email protected]> + +.. toctree:: + :maxdepth: 2 + +Intel CrownBay CRB +================== + +U-Boot support of Intel Crown Bay board `[1]`_ relies on a binary blob called +Firmware Support Package `[2]`_ to perform all the necessary initialization +steps as documented in the BIOS Writer Guide, including initialization of the +CPU, memory controller, chipset and certain bus interfaces. + +Download the Intel FSP for Atom E6xx series and Platform Controller Hub EG20T, +install it on your host and locate the FSP binary blob. Note this platform +also requires a Chipset Micro Code (CMC) state machine binary to be present in +the SPI flash where u-boot.rom resides, and this CMC binary blob can be found +in this FSP package too. + +* ./FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd +* ./Microcode/C0_22211.BIN + +Rename the first one to fsp.bin and second one to cmc.bin and put them in the +board directory. + +Note the FSP release version 001 has a bug which could cause random endless +loop during the FspInit call. This bug was published by Intel although Intel +did not describe any details. We need manually apply the patch to the FSP +binary using any hex editor (eg: bvi). Go to the offset 0x1fcd8 of the FSP +binary, change the following five bytes values from orginally E8 42 FF FF FF +to B8 00 80 0B 00. + +As for the video ROM, you need manually extract it from the Intel provided +BIOS for Crown Bay here `[3]`_, using the AMI MMTool `[4]`_. Check PCI option +ROM ID 8086:4108, extract and save it as vga.bin in the board directory. + +Now you can build U-Boot and obtain u-boot.rom
Quoted 9 lines
doc/board/intel/crownbay.rst line 45
Quoted 6 lines
doc/board/intel/crownbay.rst new file +6
-0+ +.. code-block:: shell + + $ make crownbay_defconfig + $ make all +The following lines do not show up in the generated HTML. Please, recheck.
There are hyperlinks, so will not show up in HTML.
I will update the doc a little bit, to remove the [1]/[2]/[3]/[4].
Regards,
Bin
cover Initial layout for Sphinx HTML docs
In reply to Bin MengQuoted 11 lines · Bin Meng
At present there is Sphinx doc build system in U-Boot, however the contents are very limited, that only a few API descriptions for EFI, are included.
This series proposes an initial Sphinx doc layout for future extension, by converting some of the plain text documentation to reStructuredText format and add it to Sphinx TOC tree.
@Wolfgang, is it possible to host the Sphinx HTML docs on denx.de?
This series is available at u-boot-x86/doc for testing.
Thanks a lot for this patch series. For proof-reading I have uploaded the generated pages to https://www.xypron.de/u-boot/index.html
The necessary theme for HTML generation is available here:
https://github.com/readthedocs/sphinx_rtd_theme
I applied this patch series:scripts/kernel-doc: update script from Linux 5.2
https://lists.denx.de/pipermail/u-boot/2019-July/376371.html
Best regards
Heinrich
Quoted 41 lines
Bin Meng (9):
doc: Move existing rst files into api sub-directory
doc: Add top-level description about U-Boot documentation
doc: Add driver-model to Sphinx TOC tree
doc: driver-model: Convert README.txt to reST
doc: driver-model: Convert MIGRATION.txt to reST
doc: Add architecture specific info to Sphinx TOC tree
doc: arch: Convert README.mips to reST
doc: Add board to Sphinx TOC tree
doc: board: Add Intel Crown Bay board docdoc/README.x86 | 37 -- doc/{ => api}/efi.rst | 3 + doc/api/index.rst | 10 + doc/{ => api}/linker_lists.rst | 3 + doc/{ => api}/serial.rst | 3 + doc/arch/index.rst | 8 + doc/{README.mips => arch/mips.rst} | 14 +- doc/board/index.rst | 8 + doc/board/intel/crownbay.rst | 49 ++ doc/board/intel/index.rst | 4 + doc/driver-model/{README.txt => design.rst} | 538 ++++++++++++---------- doc/driver-model/index.rst | 9 + doc/driver-model/{MIGRATION.txt => migration.rst} | 42 +- doc/index.rst | 69 ++- 14 files changed, 469 insertions(+), 328 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%) create mode 100644 doc/arch/index.rst rename doc/{README.mips => arch/mips.rst} (87%) create mode 100644 doc/board/index.rst create mode 100644 doc/board/intel/crownbay.rst create mode 100644 doc/board/intel/index.rst rename doc/driver-model/{README.txt => design.rst} (68%) create mode 100644 doc/driver-model/index.rst rename doc/driver-model/{MIGRATION.txt => migration.rst} (85%)