doc/usage/extension.rst

   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     }