1.. SPDX-License-Identifier: GPL-2.0+
2.. (C) Copyright 2015
3.. Texas Instruments Incorporated - http://www.ti.com/
4
5Remote Processor Framework
6==========================
7
8Introduction
9------------
10
11This is an introduction to driver-model for Remote Processors found
12on various System on Chip(SoCs). The term remote processor is used to
13indicate that this is not the processor on which U-Boot is operating
14on, instead is yet another processing entity that may be controlled by
15the processor on which we are functional.
16
17The simplified model depends on a single UCLASS - UCLASS_REMOTEPROC
18
19UCLASS_REMOTEPROC:
20  - drivers/remoteproc/rproc-uclass.c
21  - include/remoteproc.h
22
23Commands:
24  - common/cmd_remoteproc.c
25
26Configuration:
27  - CONFIG_REMOTEPROC is selected by drivers as needed
28  - CONFIG_CMD_REMOTEPROC for the commands if required.
29
30How does it work - The driver
31-----------------------------
32
33Overall, 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)
60opt: Optional state transition implemented by driver.
61
62NOTE: It depends on the remote processor as to the exact behavior
63of the statemachine, remoteproc core does not intent to implement
64statemachine logic. Certain processors may allow start/stop without
65reloading the image in the middle, certain other processors may only
66allow us to start the processor(image from a EEPROM/OTP) etc.
67
68It is hence the responsibility of the driver to handle the requisite
69state transitions of the device as necessary.
70
71Basic design assumptions:
72
73Remote processor can operate on a certain firmware that maybe loaded
74and released from reset.
75
76The driver follows a standard UCLASS DM.
77
78in 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
100This allows for the device to be probed as part of the "init" command
101or invocation of 'rproc_init()' function as the system dependencies define.
102
103The driver is expected to maintain it's own statemachine which is
104appropriate for the device it maintains. It must, at the very least
105provide a load and start function. We assume here that the device
106needs to be loaded and started, else, there is no real purpose of
107using the remoteproc framework.
108
109Describing the device using platform data
110-----------------------------------------
111
112*IMPORTANT* NOTE: THIS SUPPORT IS NOT MEANT FOR USE WITH NEWER PLATFORM
113SUPPORT. THIS IS ONLY FOR LEGACY DEVICES. THIS MODE OF INITIALIZATION
114*WILL* BE EVENTUALLY REMOVED ONCE ALL NECESSARY PLATFORMS HAVE MOVED
115TO DM/FDT.
116
117Considering that many platforms are yet to move to device-tree model,
118a 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_DRVINFO(proc_3_demo) = {
129		.name = "sandbox_test_proc",
130		.plat = &proc_3_test,
131	};
132
133There can be additional data that may be desired depending on the
134remoteproc driver specific needs (for example: SoC integration
135details such as clock handle or something similar). See appropriate
136documentation for specific remoteproc driver for further details.
137These are passed via driver_plat_data.
138
139Describing 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
167aliases usage is optional, but it is usually recommended to ensure the
168users have a consistent usage model for a platform.
169the compatible string used here is specific to the remoteproc driver involved.
170