Skip to contentSkip to conversation

Initial layout for Sphinx HTML docs

RFC PATCH New Bin Meng 2 participants 24 messages Jul 16, 2019 – Jul 17, 2019

lore
Share & tools
lore

Bin Meng

author
#0 lore raw

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
author
#1 lore raw

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
similarity index 92%
rename from doc/efi.rst
rename to doc/api/efi.rst
index 5337a55..3b2d544 100644
@@ -1,5 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
+.. toctree::
+   :maxdepth: 2
+
 EFI subsystem
 =============
 
doc/api/index.rst new file +10 -0
new file mode 100644
index 0000000..8e1e1a1
@@ -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
similarity index 99%
rename from doc/linker_lists.rst
rename to doc/api/linker_lists.rst
index 72f514e..477bbae 100644
@@ -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
similarity index 80%
rename from doc/serial.rst
rename to doc/api/serial.rst
index ed34e59..65f10d3 100644
@@ -1,5 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
+.. toctree::
+   :maxdepth: 2
+
 Serial system
 =============
 
doc/index.rst +11 -3
index 0353c10..1946d09 100644
@@ -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
#3 lore raw

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.

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

author
#4 lore raw

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.

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

author
#5 lore raw

RFC PATCH 2/9 doc: Add top-level description about U-Boot documentation

In reply to Bin Meng

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.

---

 doc/index.rst | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)
doc/index.rst +19 -3
index 1946d09..cfcf1dd 100644
@@ -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
author
#7 lore raw

RFC PATCH 3/9 doc: Add driver-model to Sphinx TOC tree

In reply to Bin Meng

Add 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
new file mode 100644
index 0000000..c16a544
@@ -0,0 +1,6 @@
+============
+Driver Model
+============
+
+.. toctree::
+   :maxdepth: 2
doc/index.rst +11 -0
index cfcf1dd..835decf 100644
@@ -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
author
#9 lore raw

RFC PATCH 4/9 doc: driver-model: Convert README.txt to reST

In reply to Bin Meng

Convert 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
similarity index 68%
rename from doc/driver-model/README.txt
rename to doc/driver-model/design.rst
index 532a771..c8ec2be 100644
@@ -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
index c16a544..ae28dc0 100644
@@ -4,3 +4,5 @@ Driver Model
 
 .. toctree::
    :maxdepth: 2
+
+   design
Signature · 1 line
2.7.4
#10 lore raw

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.

---

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

author
#11 lore raw

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.

---

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 stage

And 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

Regards,
Bin

author
#12 lore raw

RFC PATCH 5/9 doc: driver-model: Convert MIGRATION.txt to reST

In reply to Bin Meng

Convert 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
index ae28dc0..7d5faf3 100644
@@ -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
author
#14 lore raw

RFC PATCH 6/9 doc: Add architecture specific info to Sphinx TOC tree

In reply to Bin Meng

Add 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
new file mode 100644
index 0000000..920043a
@@ -0,0 +1,6 @@
+=========================
+Architecture-specific doc
+=========================
+
+.. toctree::
+   :maxdepth: 2
doc/index.rst +11 -0
index 835decf..562f1b7 100644
@@ -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
author
#16 lore raw

RFC PATCH 7/9 doc: arch: Convert README.mips to reST

In reply to Bin Meng

Convert 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
index 920043a..bdeccdb 100644
@@ -4,3 +4,5 @@ Architecture-specific doc
 
 .. toctree::
    :maxdepth: 2
+
+   mips
doc/arch/mips.rst renamed from doc/README.mips +8 -6
similarity index 87%
rename from doc/README.mips
rename to doc/arch/mips.rst
index b28f628..b51d0a1 100644
@@ -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
author
#18 lore raw

RFC PATCH 8/9 doc: Add board to Sphinx TOC tree

In reply to Bin Meng

Add 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
new file mode 100644
index 0000000..4a65def
@@ -0,0 +1,6 @@
+==================
+Board-specific doc
+==================
+
+.. toctree::
+   :maxdepth: 2
doc/index.rst +11 -0
index 562f1b7..fbdf50b 100644
@@ -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
author
#20 lore raw

RFC PATCH 9/9 doc: board: Add Intel Crown Bay board doc

In reply to 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.

---

 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
index 8e0a3f3..8077ff3 100644
@@ -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
index 4a65def..34e59de 100644
@@ -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
new file mode 100644
index 0000000..0e5eb47
@@ -0,0 +1,4 @@
+.. toctree::
+   :maxdepth: 2
+
+   crownbay
\ No newline at end of file
Signature · 1 line
2.7.4
#21 lore raw

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.

---

 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
index 8e0a3f3..8077ff3 100644
@@ -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
index 4a65def..34e59de 100644
@@ -4,3 +4,5 @@ Board-specific doc
 
 .. toctree::
    :maxdepth: 2
+
+   intel/index
doc/board/intel/crownbay.rst new file +35 -0
new file mode 100644
index 0000000..d77cece
@@ -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
new file mode 100644
index 0000000..0e5eb47
@@ -0,0 +1,4 @@
+.. toctree::
+   :maxdepth: 2
+
+   crownbay
\ No newline at end of file
author
#22 lore raw

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.

---

 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
index 8e0a3f3..8077ff3 100644
@@ -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
index 4a65def..34e59de 100644
@@ -4,3 +4,5 @@ Board-specific doc
 
 .. toctree::
    :maxdepth: 2
+
+   intel/index
doc/board/intel/crownbay.rst new file +39 -0
new file mode 100644
index 0000000..d77cece
@@ -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

#23 lore raw

cover Initial layout for Sphinx HTML docs

In reply to Bin Meng
Quoted 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 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%)