extension.rst 2.9 KB

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