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