1.. SPDX-License-Identifier: GPL-2.0+
2.. Copyright 2021, Kory Maincent <kory.maincent@bootlin.com>
3
4extension command
5=================
6
7Synopsis
8--------
9
10::
11
12    extension scan
13    extension list
14    extension apply <extension number|all>
15
16Description
17-----------
18
19The "extension" command proposes a generic U-Boot mechanism to detect
20extension boards connected to the HW platform, and apply the appropriate
21Device Tree overlays depending on the detected extension boards.
22
23The "extension" command comes with three sub-commands:
24
25 - "extension scan" makes the generic code call the board-specific
26   extension_board_scan() function to retrieve the list of detected
27   extension boards.
28
29 - "extension list" allows to list the detected extension boards.
30
31 - "extension apply <number>|all" allows to apply the Device Tree
32   overlay(s) corresponding to one, or all, extension boards
33
34The latter requires two environment variables to exist:
35
36 - extension_overlay_addr: the RAM address where to load the Device
37   Tree overlays
38
39 - extension_overlay_cmd: the U-Boot command to load one overlay.
40   Indeed, the location and mechanism to load DT overlays is very setup
41   specific.
42
43In order to enable this mechanism, board-specific code must implement
44the extension_board_scan() function that fills in a linked list of
45"struct extension", each describing one extension board. In addition,
46the board-specific code must select the SUPPORT_EXTENSION_SCAN Kconfig
47boolean.
48
49Usage example
50-------------
51
521. Make sure your devicetree is loaded and set as the working fdt tree.
53
54::
55
56    => run loadfdt
57    => fdt addr $fdtaddr
58
592. Prepare the environment variables
60
61::
62
63    => setenv extension_overlay_addr 0x88080000
64    => setenv extension_overlay_cmd 'load mmc 0:1 ${extension_overlay_addr} /boot/${extension_overlay_name}'
65
663. Detect the plugged extension board
67
68::
69
70    => extension scan
71
724. List the plugged extension board information and the devicetree
73   overlay name
74
75::
76
77    => extension list
78
795. Apply the appropriate devicetree overlay
80
81For apply the selected overlay:
82
83::
84
85    => extension apply 0
86
87For apply all the overlays:
88
89::
90
91    => extension apply all
92
93Simple extension_board_scan function example
94--------------------------------------------
95
96.. code-block:: c
97
98    int extension_board_scan(struct list_head *extension_list)
99    {
100        struct extension *extension;
101
102        extension = calloc(1, sizeof(struct extension));
103        snprintf(extension->overlay, sizeof(extension->overlay), "overlay.dtbo");
104        snprintf(extension->name, sizeof(extension->name), "extension board");
105        snprintf(extension->owner, sizeof(extension->owner), "sandbox");
106        snprintf(extension->version, sizeof(extension->version), "1.1");
107        snprintf(extension->other, sizeof(extension->other), "Extension board information");
108        list_add_tail(&extension->list, extension_list);
109
110        return 1;
111    }
112