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