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