doc/driver-model/remoteproc-framework.rst

   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",
 130                 .platdata = &proc_3_test,
 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.