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