doc: driver-model: Convert remoteproc-framework.txt to reST

Convert plain text documentation to reStructuredText format and add
it to Sphinx TOC tree. No essential content change.

Signed-off-by: Bin Meng <bmeng.cn@gmail.com>

diff --git a/doc/driver-model/index.rst b/doc/driver-model/index.rst
index fd33215..c6353dc 100644 (file)
--- a/doc/driver-model/index.rst
+++ b/doc/driver-model/index.rst
@@ -15,3 +15,4 @@ Driver Model
    of-plat
    pci-info
    pmic-framework
    of-plat
    pci-info
    pmic-framework

+   remoteproc-framework

diff --git a/doc/driver-model/remoteproc-framework.txt b/doc/driver-model/remoteproc-framework.rst
similarity index 50%
rename from doc/driver-model/remoteproc-framework.txt
rename to doc/driver-model/remoteproc-framework.rst
index c6dc00d..f21de0a 100644 (file)
--- a/doc/driver-model/remoteproc-framework.txt
+++ b/doc/driver-model/remoteproc-framework.rst
@@ -1,19 +1,12 @@
-# SPDX-License-Identifier: GPL-2.0+
-#
-# (C) Copyright 2015
-# Texas Instruments Incorporated - http://www.ti.com/
-#
+.. SPDX-License-Identifier: GPL-2.0+
+.. (C) Copyright 2015
+.. Texas Instruments Incorporated - http://www.ti.com/

 
 Remote Processor Framework
 ==========================
 
 Remote Processor Framework
 ==========================

-TOC:
-1. Introduction
-2. How does it work - The driver
-3. Describing the device using platform data
-4. Describing the device using device tree

 
 

-1. Introduction
-===============
+Introduction
+------------

 
 This is an introduction to driver-model for Remote Processors found
 on various System on Chip(SoCs). The term remote processor is used to
 
 This is an introduction to driver-model for Remote Processors found
 on various System on Chip(SoCs). The term remote processor is used to


@@ -24,43 +17,44 @@ the processor on which we are functional.
 The simplified model depends on a single UCLASS - UCLASS_REMOTEPROC
 
 UCLASS_REMOTEPROC:
 The simplified model depends on a single UCLASS - UCLASS_REMOTEPROC
 
 UCLASS_REMOTEPROC:

-- drivers/remoteproc/rproc-uclass.c
-- include/remoteproc.h
+  - drivers/remoteproc/rproc-uclass.c
+  - include/remoteproc.h

 
 Commands:
 
 Commands:

-- common/cmd_remoteproc.c
+  - common/cmd_remoteproc.c

 
 Configuration:
 
 Configuration:

-CONFIG_REMOTEPROC is selected by drivers as needed
-CONFIG_CMD_REMOTEPROC for the commands if required.
-
-2. How does it work - The driver
-=================================
-
-Overall, the driver statemachine transitions are typically as follows:
-        (entry)
-        +-------+
-    +---+ init  |
-    |   |       | <---------------------+
-    |   +-------+                       |
-    |                                   |
-    |                                   |
-    |   +--------+                      |
-Load|   |  reset |                      |
-    |   |        | <----------+         |
-    |   +--------+            |         |
-    |        |Load            |         |
-    |        |                |         |
-    |   +----v----+   reset   |         |
-    +-> |         |    (opt)  |         |
-        |  Loaded +-----------+         |
-        |         |                     |
-        +----+----+                     |
-             | Start                    |
-         +---v-----+        (opt)       |
-      +->| Running |        Stop        |
-Ping  +- |         +--------------------+
-(opt)    +---------+
+  - CONFIG_REMOTEPROC is selected by drivers as needed
+  - CONFIG_CMD_REMOTEPROC for the commands if required.
+
+How does it work - The driver
+-----------------------------
+
+Overall, the driver statemachine transitions are typically as follows::
+
+           (entry)
+           +-------+
+       +---+ init  |
+       |   |       | <---------------------+
+       |   +-------+                       |
+       |                                   |
+       |                                   |
+       |   +--------+                      |
+   Load|   |  reset |                      |
+       |   |        | <----------+         |
+       |   +--------+            |         |
+       |        |Load            |         |
+       |        |                |         |
+       |   +----v----+   reset   |         |
+       +-> |         |    (opt)  |         |
+           |  Loaded +-----------+         |
+           |         |                     |
+           +----+----+                     |
+                | Start                    |
+            +---v-----+        (opt)       |
+         +->| Running |        Stop        |
+   Ping  +- |         +--------------------+
+   (opt)    +---------+

 
 (is_running does not change state)
 opt: Optional state transition implemented by driver.
 
 (is_running does not change state)
 opt: Optional state transition implemented by driver.


@@ -83,23 +77,25 @@ The driver follows a standard UCLASS DM.
 
 in the bare minimum form:
 
 
 in the bare minimum form:
 

-static const struct dm_rproc_ops sandbox_testproc_ops = {
-       .load = sandbox_testproc_load,
-       .start = sandbox_testproc_start,
-};
+.. code-block:: c

 
 

-static const struct udevice_id sandbox_ids[] = {
-       {.compatible = "sandbox,test-processor"},
-       {}
-};
+       static const struct dm_rproc_ops sandbox_testproc_ops = {
+               .load = sandbox_testproc_load,
+               .start = sandbox_testproc_start,
+       };
+
+       static const struct udevice_id sandbox_ids[] = {
+               {.compatible = "sandbox,test-processor"},
+               {}
+       };

 
 

-U_BOOT_DRIVER(sandbox_testproc) = {
-       .name = "sandbox_test_proc",
-       .of_match = sandbox_ids,
-       .id = UCLASS_REMOTEPROC,
-       .ops = &sandbox_testproc_ops,
-       .probe = sandbox_testproc_probe,
-};
+       U_BOOT_DRIVER(sandbox_testproc) = {
+               .name = "sandbox_test_proc",
+               .of_match = sandbox_ids,
+               .id = UCLASS_REMOTEPROC,
+               .ops = &sandbox_testproc_ops,
+               .probe = sandbox_testproc_probe,
+       };

 
 This allows for the device to be probed as part of the "init" command
 or invocation of 'rproc_init()' function as the system dependencies define.
 
 This allows for the device to be probed as part of the "init" command
 or invocation of 'rproc_init()' function as the system dependencies define.


@@ -110,8 +106,8 @@ provide a load and start function. We assume here that the device
 needs to be loaded and started, else, there is no real purpose of
 using the remoteproc framework.
 
 needs to be loaded and started, else, there is no real purpose of
 using the remoteproc framework.
 

-3. Describing the device using platform data
-============================================
+Describing the device using platform data
+-----------------------------------------

 
 *IMPORTANT* NOTE: THIS SUPPORT IS NOT MEANT FOR USE WITH NEWER PLATFORM
 SUPPORT. THIS IS ONLY FOR LEGACY DEVICES. THIS MODE OF INITIALIZATION
 
 *IMPORTANT* NOTE: THIS SUPPORT IS NOT MEANT FOR USE WITH NEWER PLATFORM
 SUPPORT. THIS IS ONLY FOR LEGACY DEVICES. THIS MODE OF INITIALIZATION


@@ -121,16 +117,18 @@ TO DM/FDT.
 Considering that many platforms are yet to move to device-tree model,
 a simplified definition of a device is as follows:
 
 Considering that many platforms are yet to move to device-tree model,
 a simplified definition of a device is as follows:
 

-struct dm_rproc_uclass_pdata proc_3_test = {
-       .name = "proc_3_legacy",
-       .mem_type = RPROC_INTERNAL_MEMORY_MAPPED,
-       .driver_plat_data = &mydriver_data;
-};
+.. code-block:: c

 
 

-U_BOOT_DEVICE(proc_3_demo) = {
-       .name = "sandbox_test_proc",
-       .platdata = &proc_3_test,
-};
+       struct dm_rproc_uclass_pdata proc_3_test = {
+               .name = "proc_3_legacy",
+               .mem_type = RPROC_INTERNAL_MEMORY_MAPPED,
+               .driver_plat_data = &mydriver_data;
+       };
+
+       U_BOOT_DEVICE(proc_3_demo) = {
+               .name = "sandbox_test_proc",
+               .platdata = &proc_3_test,
+       };

 
 There can be additional data that may be desired depending on the
 remoteproc driver specific needs (for example: SoC integration
 
 There can be additional data that may be desired depending on the
 remoteproc driver specific needs (for example: SoC integration


@@ -138,30 +136,33 @@ details such as clock handle or something similar). See appropriate
 documentation for specific remoteproc driver for further details.
 These are passed via driver_plat_data.
 
 documentation for specific remoteproc driver for further details.
 These are passed via driver_plat_data.
 

-3. Describing the device using device tree
-==========================================
-/ {
-       ...
-       aliases {
+Describing the device using device tree
+---------------------------------------
+
+.. code-block: none
+
+       / {

                ...
                ...

-               remoteproc0 = &rproc_1;
-               remoteproc1 = &rproc_2;
+               aliases {
+                       ...
+                       remoteproc0 = &rproc_1;
+                       remoteproc1 = &rproc_2;

 
 

-       };
-       ...
+               };
+               ...

 
 

-       rproc_1: rproc@1 {
-               compatible = "sandbox,test-processor";
-               remoteproc-name = "remoteproc-test-dev1";
-       };
+               rproc_1: rproc@1 {
+                       compatible = "sandbox,test-processor";
+                       remoteproc-name = "remoteproc-test-dev1";
+               };

 
 

-       rproc_2: rproc@2 {
-               compatible = "sandbox,test-processor";
-               internal-memory-mapped;
-               remoteproc-name = "remoteproc-test-dev2";
+               rproc_2: rproc@2 {
+                       compatible = "sandbox,test-processor";
+                       internal-memory-mapped;
+                       remoteproc-name = "remoteproc-test-dev2";
+               };
+               ...

        };
        };

-       ...
-};

 
 aliases usage is optional, but it is usually recommended to ensure the
 users have a consistent usage model for a platform.
 
 aliases usage is optional, but it is usually recommended to ensure the
 users have a consistent usage model for a platform.