dm: core: Add documentation for the dm command

Add a description and examples for the dm subcommands.

Signed-off-by: Simon Glass <sjg@chromium.org>

2 files changed, 488 insertions, 0 deletions

diff --git a/doc/usage/cmd/dm.rst b/doc/usage/cmd/dm.rst
new file mode 100644
index 0000000..7bc1962
--- /dev/null
+++ b/doc/usage/cmd/dm.rst
@@ -0,0 +1,487 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+dm command
+==========
+
+Synopis
+-------
+
+::
+
+    dm compat
+    dm devres
+    dm drivers
+    dm static
+    dm tree
+    dm uclass
+
+Description
+-----------
+
+The *dm* command allows viewing information about driver model, including the
+tree of devices and list of available uclasses.
+
+
+dm compat
+~~~~~~~~~
+
+This shows the compatible strings associated with each driver. Often there
+is only one, but multiple strings are shown on their own line. These strings
+can be looked up in the device tree files for each board, to see which driver is
+used for each node.
+
+dm devres
+~~~~~~~~~
+
+This shows a list of a `devres` (device resource) records for a device. Some
+drivers use the devres API to allocate memory, so that it can be freed
+automatically (without any code needed in the driver's remove() method) when the
+device is removed.
+
+This feature is controlled by CONFIG_DEVRES so no useful output is obtained if
+this option is disabled.
+
+dm drivers
+~~~~~~~~~~
+
+This shows all the available drivers, their uclass and a list of devices that
+use that driver, each on its own line. Drivers with no devices are shown with
+`<none>` as the driver name.
+
+
+dm mem
+~~~~~~
+
+This subcommand is really just for debugging and exploration. It can be enabled
+with the `CONFIG_DM_STATS` option.
+
+All output is in hex except that in brackets which is decimal.
+
+The output consists of a header shows the size of the main device model
+structures (struct udevice, struct driver, struct uclass and struct uc_driver)
+and the count and memory used by each (number of devices, memory used by
+devices, memory used by device names, number of uclasses, memory used by
+uclasses).
+
+After that is a table of information about each type of data that can be
+attached to a device, showing the number that have non-null data for that type,
+the total size of all that data, the amount of memory used in total, the
+amount that would be used if this type uses tags instead and the amount that
+would be thus saved.
+
+The `driver_data` line shows the number of devices which have non-NULL driver
+data.
+
+The `tags` line shows the number of tags and the memory used by those.
+
+At the bottom is an indication of the total memory usage obtained by undertaking
+various changes, none of which is currently implemented in U-Boot:
+
+With tags
+    Using tags instead of all attached types
+
+Singly linked
+    Using a singly linked list
+
+driver index
+    Using a driver index instead of a pointer
+
+uclass index
+    Using a uclass index instead of a pointer
+
+Drop device name
+    Using empty device names
+
+
+dm static
+~~~~~~~~~
+
+This shows devices bound by platform data, i.e. not from the device tree. There
+are normally none of these, but some boards may use static devices for space
+reasons.
+
+
+dm tree
+~~~~~~~
+
+This shows the full tree of devices including the following fields:
+
+uclass
+    Shows the name of the uclass for the device
+
+Index
+    Shows the index number of the device, within the uclass. This shows the
+    ordering within the uclass, but not the sequence number.
+
+Probed
+    Shows `+` if the device is active
+
+Driver
+    Shows the name of the driver that this device uses
+
+Name
+    Shows the device name as well as the tree structure, since child devices are
+    shown attached to their parent.
+
+
+dm uclass
+~~~~~~~~~
+
+This shows each uclass along with a list of devices in that uclass. The uclass
+ID is shown (e.g. uclass 7) and its name.
+
+For each device, the format is::
+
+    n    name @ a, seq s
+
+where `n` is the index within the uclass, `a` is the address of the device in
+memory and `s` is the sequence number of the device.
+
+
+Examples
+--------
+
+dm compat
+~~~~~~~~~
+
+This example shows an abridged version of the sandbox output::
+
+    => dm compat
+    Driver                Compatible
+    --------------------------------
+    act8846_reg
+    sandbox_adder         sandbox,adder
+    axi_sandbox_bus       sandbox,axi
+    blk_partition
+    bootcount-rtc         u-boot,bootcount-rtc
+    ...
+    rockchip_rk805        rockchip,rk805
+                          rockchip,rk808
+                          rockchip,rk809
+                          rockchip,rk816
+                          rockchip,rk817
+                          rockchip,rk818
+    root_driver
+    rtc-rv8803            microcrystal,rv8803
+                          epson,rx8803
+                          epson,rx8900
+    ...
+    wdt_gpio              linux,wdt-gpio
+    wdt_sandbox           sandbox,wdt
+
+
+dm devres
+~~~~~~~~~
+
+This example shows an abridged version of the sandbox test output (running
+U-Boot with the -T flag)::
+
+    => dm devres
+    - root_driver
+    - demo_shape_drv
+    - demo_simple_drv
+    - demo_shape_drv
+    ...
+    - h-test
+    - devres-test
+        00000000130194e0 (100 byte) devm_kmalloc_release  BIND
+    - another-test
+    ...
+    - syscon@3
+    - a-mux-controller
+        0000000013025e60 (96 byte) devm_kmalloc_release  PROBE
+        0000000013025f00 (24 byte) devm_kmalloc_release  PROBE
+        0000000013026010 (24 byte) devm_kmalloc_release  PROBE
+        0000000013026070 (24 byte) devm_kmalloc_release  PROBE
+        00000000130260d0 (24 byte) devm_kmalloc_release  PROBE
+    - syscon@3
+    - a-mux-controller
+        0000000013026150 (96 byte) devm_kmalloc_release  PROBE
+        00000000130261f0 (24 byte) devm_kmalloc_release  PROBE
+        0000000013026300 (24 byte) devm_kmalloc_release  PROBE
+        0000000013026360 (24 byte) devm_kmalloc_release  PROBE
+        00000000130263c0 (24 byte) devm_kmalloc_release  PROBE
+    - emul-mux-controller
+        0000000013025fa0 (32 byte) devm_kmalloc_release  PROBE
+    - testfdtm0
+    - testfdtm1
+    ...
+    - pinmux_spi0_pins
+    - pinmux_uart0_pins
+    - pinctrl-single-bits
+        0000000013229180 (320 byte) devm_kmalloc_release  PROBE
+        0000000013229300 (40 byte) devm_kmalloc_release  PROBE
+        0000000013229370 (160 byte) devm_kmalloc_release  PROBE
+        000000001322c190 (40 byte) devm_kmalloc_release  PROBE
+        000000001322c200 (32 byte) devm_kmalloc_release  PROBE
+    - pinmux_i2c0_pins
+    ...
+    - reg@0
+    - reg@1
+
+
+dm drivers
+~~~~~~~~~~
+
+This example shows an abridged version of the sandbox output::
+
+    => dm drivers
+    Driver                    uid uclass               Devices
+    ----------------------------------------------------------
+    act8846_reg               087 regulator            <none>
+    sandbox_adder             021 axi                  adder
+                                                    adder
+    axi_sandbox_bus           021 axi                  axi@0
+    ...
+    da7219                    061 misc                 <none>
+    demo_shape_drv            001 demo                 demo_shape_drv
+                                                    demo_shape_drv
+                                                    demo_shape_drv
+    demo_simple_drv           001 demo                 demo_simple_drv
+                                                    demo_simple_drv
+    testfdt_drv               003 testfdt              a-test
+                                                    b-test
+                                                    d-test
+                                                    e-test
+                                                    f-test
+                                                    g-test
+                                                    another-test
+                                                    chosen-test
+    testbus_drv               005 testbus              some-bus
+                                                    mmio-bus@0
+                                                    mmio-bus@1
+    dsa-port                  039 ethernet             lan0
+                                                    lan1
+    dsa_sandbox               035 dsa                  dsa-test
+    eep_sandbox               121 w1_eeprom            <none>
+    ...
+    pfuze100_regulator        087 regulator            <none>
+    phy_sandbox               077 phy                  bind-test-child1
+                                                    gen_phy@0
+                                                    gen_phy@1
+                                                    gen_phy@2
+    pinconfig                 078 pinconfig            gpios
+                                                    gpio0
+                                                    gpio1
+                                                    gpio2
+                                                    gpio3
+                                                    i2c
+                                                    groups
+                                                    pins
+                                                    i2s
+                                                    spi
+                                                    cs
+                                                    pinmux_pwm_pins
+                                                    pinmux_spi0_pins
+                                                    pinmux_uart0_pins
+                                                    pinmux_i2c0_pins
+                                                    pinmux_lcd_pins
+    pmc_sandbox               017 power-mgr            pci@1e,0
+    act8846 pmic              080 pmic                 <none>
+    max77686_pmic             080 pmic                 <none>
+    mc34708_pmic              080 pmic                 pmic@41
+    ...
+    wdt_gpio                  122 watchdog             gpio-wdt
+    wdt_sandbox               122 watchdog             wdt@0
+    =>
+
+
+dm mem
+~~~~~~
+
+This example shows the sandbox output::
+
+    > dm mem
+    Struct sizes: udevice b0, driver 80, uclass 30, uc_driver 78
+    Memory: device fe:aea0, device names a16, uclass 5e:11a0
+
+    Attached type    Count   Size    Cur   Tags   Save
+    ---------------  -----  -----  -----  -----  -----
+    plat                45    a8f   aea0   a7c4    6dc (1756)
+    parent_plat         1a    3b8   aea0   a718    788 (1928)
+    uclass_plat         3d    6b4   aea0   a7a4    6fc (1788)
+    priv                8a   68f3   aea0   a8d8    5c8 (1480)
+    parent_priv          8   38a0   aea0   a6d0    7d0 (2000)
+    uclass_priv         4e   14a6   aea0   a7e8    6b8 (1720)
+    driver_data          f      0   aea0   a6ec    7b4 (1972)
+    uclass               6     20
+    Attached total     191   cb54                  3164 (12644)
+    tags                 0      0
+
+    Total size: 18b94 (101268)
+
+    With tags:       15a30 (88624)
+    - singly-linked: 14260 (82528)
+    - driver index:  13b6e (80750)
+    - uclass index:  1347c (78972)
+    Drop device name (not SRAM): a16 (2582)
+    =>
+
+
+dm static
+~~~~~~~~~
+
+This example shows the sandbox output::
+
+    => dm static
+    Driver                    Address
+    ---------------------------------
+    demo_shape_drv            0000562edab8dca0
+    demo_simple_drv           0000562edab8dca0
+    demo_shape_drv            0000562edab8dc90
+    demo_simple_drv           0000562edab8dc80
+    demo_shape_drv            0000562edab8dc80
+    test_drv                  0000562edaae8840
+    test_drv                  0000562edaae8848
+    test_drv                  0000562edaae8850
+    sandbox_gpio              0000000000000000
+    mod_exp_sw                0000000000000000
+    sandbox_test_proc         0000562edabb5330
+    qfw_sandbox               0000000000000000
+    sandbox_timer             0000000000000000
+    sandbox_serial            0000562edaa8ed00
+    sysreset_sandbox          0000000000000000
+
+
+dm tree
+-------
+
+This example shows the abridged sandbox output::
+
+    => dm tree
+    Class     Index  Probed  Driver                Name
+    -----------------------------------------------------------
+    root          0  [ + ]   root_driver           root_driver
+    demo          0  [   ]   demo_shape_drv        |-- demo_shape_drv
+    demo          1  [   ]   demo_simple_drv       |-- demo_simple_drv
+    demo          2  [   ]   demo_shape_drv        |-- demo_shape_drv
+    demo          3  [   ]   demo_simple_drv       |-- demo_simple_drv
+    demo          4  [   ]   demo_shape_drv        |-- demo_shape_drv
+    test          0  [   ]   test_drv              |-- test_drv
+    test          1  [   ]   test_drv              |-- test_drv
+    test          2  [   ]   test_drv              |-- test_drv
+    ..
+    sysreset      0  [   ]   sysreset_sandbox      |-- sysreset_sandbox
+    bootstd       0  [   ]   bootstd_drv           |-- bootstd
+    bootmeth      0  [   ]   bootmeth_distro       |   |-- syslinux
+    bootmeth      1  [   ]   bootmeth_efi          |   `-- efi
+    reboot-mod    0  [   ]   reboot-mode-gpio      |-- reboot-mode0
+    reboot-mod    1  [   ]   reboot-mode-rtc       |-- reboot-mode@14
+    ...
+    ethernet      7  [ + ]   dsa-port              |   `-- lan1
+    pinctrl       0  [ + ]   sandbox_pinctrl_gpio  |-- pinctrl-gpio
+    gpio          1  [ + ]   sandbox_gpio          |   |-- base-gpios
+    nop           0  [ + ]   gpio_hog              |   |   |-- hog_input_active_low
+    nop           1  [ + ]   gpio_hog              |   |   |-- hog_input_active_high
+    nop           2  [ + ]   gpio_hog              |   |   |-- hog_output_low
+    nop           3  [ + ]   gpio_hog              |   |   `-- hog_output_high
+    gpio          2  [   ]   sandbox_gpio          |   |-- extra-gpios
+    gpio          3  [   ]   sandbox_gpio          |   `-- pinmux-gpios
+    i2c           0  [ + ]   sandbox_i2c           |-- i2c@0
+    i2c_eeprom    0  [   ]   i2c_eeprom            |   |-- eeprom@2c
+    i2c_eeprom    1  [   ]   i2c_eeprom_partition  |   |   `-- bootcount@10
+    rtc           0  [   ]   sandbox_rtc           |   |-- rtc@43
+    rtc           1  [ + ]   sandbox_rtc           |   |-- rtc@61
+    i2c_emul_p    0  [ + ]   sandbox_i2c_emul_par  |   |-- emul
+    i2c_emul      0  [   ]   sandbox_i2c_eeprom_e  |   |   |-- emul-eeprom
+    i2c_emul      1  [   ]   sandbox_i2c_rtc_emul  |   |   |-- emul0
+    i2c_emul      2  [ + ]   sandbox_i2c_rtc_emul  |   |   |-- emull
+    i2c_emul      3  [   ]   sandbox_i2c_pmic_emu  |   |   |-- pmic-emul0
+    i2c_emul      4  [   ]   sandbox_i2c_pmic_emu  |   |   `-- pmic-emul1
+    pmic          0  [   ]   sandbox_pmic          |   |-- sandbox_pmic
+    regulator     0  [   ]   sandbox_buck          |   |   |-- buck1
+    regulator     1  [   ]   sandbox_buck          |   |   |-- buck2
+    regulator     2  [   ]   sandbox_ldo           |   |   |-- ldo1
+    regulator     3  [   ]   sandbox_ldo           |   |   |-- ldo2
+    regulator     4  [   ]   sandbox_buck          |   |   `-- no_match_by_nodename
+    pmic          1  [   ]   mc34708_pmic          |   `-- pmic@41
+    bootcount     0  [ + ]   bootcount-rtc         |-- bootcount@0
+    bootcount     1  [   ]   bootcount-i2c-eeprom  |-- bootcount
+    ...
+    clk           4  [   ]   fixed_clock           |-- osc
+    firmware      0  [   ]   sandbox_firmware      |-- sandbox-firmware
+    scmi_agent    0  [   ]   sandbox-scmi_agent    `-- scmi
+    clk           5  [   ]   scmi_clk                  |-- protocol@14
+    reset         2  [   ]   scmi_reset_domain         |-- protocol@16
+    nop           8  [   ]   scmi_voltage_domain       `-- regulators
+    regulator     5  [   ]   scmi_regulator                |-- reg@0
+    regulator     6  [   ]   scmi_regulator                `-- reg@1
+    =>
+
+
+dm uclass
+~~~~~~~~~
+
+This example shows the abridged sandbox output::
+
+    => dm uclass
+    uclass 0: root
+    0   * root_driver @ 03015460, seq 0
+
+    uclass 1: demo
+    0     demo_shape_drv @ 03015560, seq 0
+    1     demo_simple_drv @ 03015620, seq 1
+    2     demo_shape_drv @ 030156e0, seq 2
+    3     demo_simple_drv @ 030157a0, seq 3
+    4     demo_shape_drv @ 03015860, seq 4
+
+    uclass 2: test
+    0     test_drv @ 03015980, seq 0
+    1     test_drv @ 03015a60, seq 1
+    2     test_drv @ 03015b40, seq 2
+    ...
+    uclass 20: audio-codec
+    0     audio-codec @ 030168e0, seq 0
+
+    uclass 21: axi
+    0     adder @ 0301db60, seq 1
+    1     adder @ 0301dc40, seq 2
+    2     axi@0 @ 030217d0, seq 0
+
+    uclass 22: blk
+    0     mmc2.blk @ 0301ca00, seq 0
+    1     mmc1.blk @ 0301cee0, seq 1
+    2     mmc0.blk @ 0301d380, seq 2
+
+    uclass 23: bootcount
+    0   * bootcount@0 @ 0301b3f0, seq 0
+    1     bootcount @ 0301b4b0, seq 1
+    2     bootcount_4@0 @ 0301b570, seq 2
+    3     bootcount_2@0 @ 0301b630, seq 3
+
+    uclass 24: bootdev
+    0     mmc2.bootdev @ 0301cbb0, seq 0
+    1     mmc1.bootdev @ 0301d050, seq 1
+    2     mmc0.bootdev @ 0301d4f0, seq 2
+
+    ...
+    uclass 78: pinconfig
+    0     gpios @ 03022410, seq 0
+    1     gpio0 @ 030224d0, seq 1
+    2     gpio1 @ 03022590, seq 2
+    3     gpio2 @ 03022650, seq 3
+    4     gpio3 @ 03022710, seq 4
+    5     i2c @ 030227d0, seq 5
+    6     groups @ 03022890, seq 6
+    7     pins @ 03022950, seq 7
+    8     i2s @ 03022a10, seq 8
+    9     spi @ 03022ad0, seq 9
+    10    cs @ 03022b90, seq 10
+    11    pinmux_pwm_pins @ 03022e10, seq 11
+    12    pinmux_spi0_pins @ 03022ed0, seq 12
+    13    pinmux_uart0_pins @ 03022f90, seq 13
+    14  * pinmux_i2c0_pins @ 03023130, seq 14
+    15  * pinmux_lcd_pins @ 030231f0, seq 15
+
+    ...
+    uclass 119: virtio
+    0     sandbox_virtio1 @ 030220d0, seq 0
+    1     sandbox_virtio2 @ 03022190, seq 1
+
+    uclass 120: w1
+    uclass 121: w1_eeprom
+    uclass 122: watchdog
+    0   * gpio-wdt @ 0301c070, seq 0
+    1   * wdt@0 @ 03021710, seq 1
+
+    =>
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 8d08ea1..8b98629 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -33,6 +33,7 @@ Shell commands
    cmd/bootz
    cmd/cbsysinfo
    cmd/conitrace
+   cmd/dm
    cmd/echo
    cmd/env
    cmd/event