remoteproc-framework.rst 5.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169
  1. .. SPDX-License-Identifier: GPL-2.0+
  2. .. (C) Copyright 2015
  3. .. Texas Instruments Incorporated - http://www.ti.com/
  4. Remote Processor Framework
  5. ==========================
  6. Introduction
  7. ------------
  8. This is an introduction to driver-model for Remote Processors found
  9. on various System on Chip(SoCs). The term remote processor is used to
  10. indicate that this is not the processor on which U-Boot is operating
  11. on, instead is yet another processing entity that may be controlled by
  12. the processor on which we are functional.
  13. The simplified model depends on a single UCLASS - UCLASS_REMOTEPROC
  14. UCLASS_REMOTEPROC:
  15. - drivers/remoteproc/rproc-uclass.c
  16. - include/remoteproc.h
  17. Commands:
  18. - common/cmd_remoteproc.c
  19. Configuration:
  20. - CONFIG_REMOTEPROC is selected by drivers as needed
  21. - CONFIG_CMD_REMOTEPROC for the commands if required.
  22. How does it work - The driver
  23. -----------------------------
  24. Overall, the driver statemachine transitions are typically as follows::
  25. (entry)
  26. +-------+
  27. +---+ init |
  28. | | | <---------------------+
  29. | +-------+ |
  30. | |
  31. | |
  32. | +--------+ |
  33. Load| | reset | |
  34. | | | <----------+ |
  35. | +--------+ | |
  36. | |Load | |
  37. | | | |
  38. | +----v----+ reset | |
  39. +-> | | (opt) | |
  40. | Loaded +-----------+ |
  41. | | |
  42. +----+----+ |
  43. | Start |
  44. +---v-----+ (opt) |
  45. +->| Running | Stop |
  46. Ping +- | +--------------------+
  47. (opt) +---------+
  48. (is_running does not change state)
  49. opt: Optional state transition implemented by driver.
  50. NOTE: It depends on the remote processor as to the exact behavior
  51. of the statemachine, remoteproc core does not intent to implement
  52. statemachine logic. Certain processors may allow start/stop without
  53. reloading the image in the middle, certain other processors may only
  54. allow us to start the processor(image from a EEPROM/OTP) etc.
  55. It is hence the responsibility of the driver to handle the requisite
  56. state transitions of the device as necessary.
  57. Basic design assumptions:
  58. Remote processor can operate on a certain firmware that maybe loaded
  59. and released from reset.
  60. The driver follows a standard UCLASS DM.
  61. in the bare minimum form:
  62. .. code-block:: c
  63. static const struct dm_rproc_ops sandbox_testproc_ops = {
  64. .load = sandbox_testproc_load,
  65. .start = sandbox_testproc_start,
  66. };
  67. static const struct udevice_id sandbox_ids[] = {
  68. {.compatible = "sandbox,test-processor"},
  69. {}
  70. };
  71. U_BOOT_DRIVER(sandbox_testproc) = {
  72. .name = "sandbox_test_proc",
  73. .of_match = sandbox_ids,
  74. .id = UCLASS_REMOTEPROC,
  75. .ops = &sandbox_testproc_ops,
  76. .probe = sandbox_testproc_probe,
  77. };
  78. This allows for the device to be probed as part of the "init" command
  79. or invocation of 'rproc_init()' function as the system dependencies define.
  80. The driver is expected to maintain it's own statemachine which is
  81. appropriate for the device it maintains. It must, at the very least
  82. provide a load and start function. We assume here that the device
  83. needs to be loaded and started, else, there is no real purpose of
  84. using the remoteproc framework.
  85. Describing the device using platform data
  86. -----------------------------------------
  87. *IMPORTANT* NOTE: THIS SUPPORT IS NOT MEANT FOR USE WITH NEWER PLATFORM
  88. SUPPORT. THIS IS ONLY FOR LEGACY DEVICES. THIS MODE OF INITIALIZATION
  89. *WILL* BE EVENTUALLY REMOVED ONCE ALL NECESSARY PLATFORMS HAVE MOVED
  90. TO DM/FDT.
  91. Considering that many platforms are yet to move to device-tree model,
  92. a simplified definition of a device is as follows:
  93. .. code-block:: c
  94. struct dm_rproc_uclass_pdata proc_3_test = {
  95. .name = "proc_3_legacy",
  96. .mem_type = RPROC_INTERNAL_MEMORY_MAPPED,
  97. .driver_plat_data = &mydriver_data;
  98. };
  99. U_BOOT_DEVICE(proc_3_demo) = {
  100. .name = "sandbox_test_proc",
  101. .platdata = &proc_3_test,
  102. };
  103. There can be additional data that may be desired depending on the
  104. remoteproc driver specific needs (for example: SoC integration
  105. details such as clock handle or something similar). See appropriate
  106. documentation for specific remoteproc driver for further details.
  107. These are passed via driver_plat_data.
  108. Describing the device using device tree
  109. ---------------------------------------
  110. .. code-block: none
  111. / {
  112. ...
  113. aliases {
  114. ...
  115. remoteproc0 = &rproc_1;
  116. remoteproc1 = &rproc_2;
  117. };
  118. ...
  119. rproc_1: rproc@1 {
  120. compatible = "sandbox,test-processor";
  121. remoteproc-name = "remoteproc-test-dev1";
  122. };
  123. rproc_2: rproc@2 {
  124. compatible = "sandbox,test-processor";
  125. internal-memory-mapped;
  126. remoteproc-name = "remoteproc-test-dev2";
  127. };
  128. ...
  129. };
  130. aliases usage is optional, but it is usually recommended to ensure the
  131. users have a consistent usage model for a platform.
  132. the compatible string used here is specific to the remoteproc driver involved.