| Kory Maincent | 7444a7d | 2021-05-04 19:31:22 +0200 | [diff] [blame] | 1 | .. SPDX-License-Identifier: GPL-2.0+ |
| 2 | .. Copyright 2021, Kory Maincent <kory.maincent@bootlin.com> |
| 3 | |
| 4 | U-Boot extension board usage (CONFIG_EXTENSION) |
| 5 | =============================================== |
| 6 | |
| 7 | Synopsis |
| 8 | -------- |
| 9 | |
| 10 | :: |
| 11 | |
| 12 | extension scan |
| 13 | extension list |
| 14 | extension apply <extension number|all> |
| 15 | |
| 16 | Description |
| 17 | ----------- |
| 18 | |
| 19 | The "extension" command proposes a generic U-Boot mechanism to detect |
| 20 | extension boards connected to the HW platform, and apply the appropriate |
| 21 | Device Tree overlays depending on the detected extension boards. |
| 22 | |
| 23 | The "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 | |
| 34 | The 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 | |
| 43 | In order to enable this mechanism, board-specific code must implement |
| 44 | the extension_board_scan() function that fills in a linked list of |
| 45 | "struct extension", each describing one extension board. In addition, |
| 46 | the board-specific code must select the SUPPORT_EXTENSION_SCAN Kconfig |
| 47 | boolean. |
| 48 | |
| 49 | Usage example |
| 50 | ------------- |
| 51 | |
| 52 | 1. Make sure your devicetree is loaded and set as the working fdt tree. |
| 53 | |
| 54 | :: |
| 55 | |
| 56 | => run loadfdt |
| 57 | => fdt addr $fdtaddr |
| 58 | |
| 59 | 2. 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 | |
| 66 | 3. Detect the plugged extension board |
| 67 | |
| 68 | :: |
| 69 | |
| 70 | => extension scan |
| 71 | |
| 72 | 4. List the plugged extension board information and the devicetree |
| 73 | overlay name |
| 74 | |
| 75 | :: |
| 76 | |
| 77 | => extension list |
| 78 | |
| 79 | 5. Apply the appropriate devicetree overlay |
| 80 | |
| 81 | For apply the selected overlay: |
| 82 | |
| 83 | :: |
| 84 | |
| 85 | => extension apply 0 |
| 86 | |
| 87 | For apply all the overlays: |
| 88 | |
| 89 | :: |
| 90 | |
| 91 | => extension apply all |
| 92 | |
| 93 | Simple 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 | } |