From 175ba0fe94c982d3a5f66944c8693b2624b3e0c3 Mon Sep 17 00:00:00 2001 From: Bin Meng Date: Thu, 18 Jul 2019 00:33:58 -0700 Subject: [PATCH] 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 --- doc/driver-model/index.rst | 1 + ...framework.txt => remoteproc-framework.rst} | 181 +++++++++--------- 2 files changed, 92 insertions(+), 90 deletions(-) rename doc/driver-model/{remoteproc-framework.txt => remoteproc-framework.rst} (50%) diff --git a/doc/driver-model/index.rst b/doc/driver-model/index.rst index fd332157ad..c6353dcf66 100644 --- a/doc/driver-model/index.rst +++ b/doc/driver-model/index.rst @@ -15,3 +15,4 @@ Driver Model 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 c6dc00dca3..f21de0a10f 100644 --- 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 ========================== -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 @@ -24,43 +17,44 @@ the processor on which we are functional. 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: -- common/cmd_remoteproc.c + - common/cmd_remoteproc.c 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. @@ -83,23 +77,25 @@ The driver follows a standard UCLASS DM. 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. @@ -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. -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 @@ -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: -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 @@ -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. -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. -- 2.25.1