Documentation/remoteproc/core.rst | 252 ++++++++++++ Documentation/remoteproc/index.rst | 27 ++ Documentation/remoteproc/rproc-api.rst | 75 ++++ Documentation/remoteproc/rproc-kernel-api.rst | 239 ++++++++++++ Documentation/staging/index.rst | 1 - Documentation/staging/remoteproc.rst | 360 ------------------ Documentation/staging/rpmsg.rst | 2 +- 7 files changed, 594 insertions(+), 362 deletions(-) create mode 100644 Documentation/remoteproc/core.rst create mode 100644 Documentation/remoteproc/index.rst create mode 100644 Documentation/remoteproc/rproc-api.rst create mode 100644 Documentation/remoteproc/rproc-kernel-api.rst delete mode 100644 Documentation/staging/remoteproc.rst
Add the documentation in the mainline from
staging and add the relvant information from
current mainline.
Added:
1. userspace api documentation.
2. kernel api documentation.
3. Driver framework core details added.
Signed-off-by: anish kumar <yesanishhere@gmail.com>
---
Documentation/remoteproc/core.rst | 252 ++++++++++++
Documentation/remoteproc/index.rst | 27 ++
Documentation/remoteproc/rproc-api.rst | 75 ++++
Documentation/remoteproc/rproc-kernel-api.rst | 239 ++++++++++++
Documentation/staging/index.rst | 1 -
Documentation/staging/remoteproc.rst | 360 ------------------
Documentation/staging/rpmsg.rst | 2 +-
7 files changed, 594 insertions(+), 362 deletions(-)
create mode 100644 Documentation/remoteproc/core.rst
create mode 100644 Documentation/remoteproc/index.rst
create mode 100644 Documentation/remoteproc/rproc-api.rst
create mode 100644 Documentation/remoteproc/rproc-kernel-api.rst
delete mode 100644 Documentation/staging/remoteproc.rst
diff --git a/Documentation/remoteproc/core.rst b/Documentation/remoteproc/core.rst
new file mode 100644
index 000000000000..a59c2c5bc8e6
--- /dev/null
+++ b/Documentation/remoteproc/core.rst
@@ -0,0 +1,252 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============================================
+General description of the remoteproc subsystem
+===============================================
+
+Authors:
+ - anish kumar <yesanishhere@gmail.com>
+
+.. Contents:
+
+ 1. Introduction
+ 2. Remoteproc framework responsibilities
+ 3. Remoteproc driver responsibilities
+ 4. Virtio and rpmsg
+
+1. Introduction
+======================
+
+Modern System on Chips (SoCs) typically integrate heterogeneous remote
+processor devices in asymmetric multiprocessing (AMP) configurations.
+These processors may run different operating systems, such as Linux and
+various real-time operating systems (RTOS).
+
+For example, the OMAP4 platform features dual Cortex-A9 cores, dual
+Cortex-M3 cores, and a C64x+ DSP. In a standard setup, the Cortex-A9
+cores execute Linux in a symmetric multiprocessing (SMP) configuration,
+while the M3 cores and DSP run independent instances of an RTOS.
+
+The remoteproc framework allows various platforms and architectures to
+manage remote processors, including operations such as powering on,
+loading firmware, and powering off. This framework abstracts hardware
+differences, promoting code reuse and minimizing duplication. It also
+supports rpmsg virtio devices for remote processors that utilize this
+communication method. Consequently, platform-specific remoteproc drivers
+need only implement a few low-level handlers, enabling seamless operation
+of all rpmsg drivers. (For more details about the virtio-based rpmsg
+bus and its drivers, refer to :doc:`Documentation/staging/rpmsg.rst`.)
+
+Additionally, the framework allows for the registration of various
+virtio devices. Firmware can publish the types of virtio devices it
+supports, facilitating their addition to the remoteproc framework. This
+flexibility enables the reuse of existing virtio drivers with remote
+processor backends at minimal development cost.
+
+The primary purpose of the remoteproc framework is to download firmware
+for remote processors and manage their lifecycle. The framework consists
+of several key components:
+
+- **Character Driver**: Provides userspace access to control the remote
+ processor.
+- **ELF Utility**: Offers functions for handling ELF files and managing
+ resources requested by the remote processor.
+- **Remoteproc Core**: Manages firmware downloads and recovery actions
+ in case of a remote processor crash.
+- **Coredump**: Provides facilities for coredumping and tracing from
+ the remote processor in the event of a crash.
+- **Userspace Interaction**: Uses sysfs and debugfs to manage the
+ lifecycle and status of the remote processor.
+- **Virtio Support**: Facilitates interaction with the virtio and
+ rpmsg bus.
+
+From here on, references to "framework" denote the remoteproc
+framework, and "driver" refers to the remoteproc driver that utilizes
+the framework for managing remote processors.
+
+2. Remoteproc framework Responsibilities
+========================================
+
+The framework begins by gathering information about the firmware file
+to be downloaded through the request_firmware function. It supports
+the ELF format and parses the firmware image to identify the physical
+addresses that need to be populated from the corresponding ELF sections.
+The framework also requires knowledge of the logical or I/O-mapped
+addresses in the application processor. Once this information is
+obtained from the driver, the framework transfers the data to the
+specified addresses and starts the remote, along with
+any devices physically or logically connected to it.
+
+Dependent devices, referred to as `subdevices` within the framework,
+are also managed post-registration by their respective drivers.
+Subdevices can register themselves using `rproc_(add/remove)_subdev`.
+Non-remoteproc drivers can use subdevices as a way to logically connect
+to remote and get lifecycle notifications of the remote.
+
+The framework oversees the lifecycle of the remote and
+provides the `rproc_report_crash` function, which the driver invokes
+upon receiving a crash notification from the remote. The
+notification method can differ based on the design of the remote
+processor and its communication with the application processor. For
+instance, if the remote is a DSP equipped with a watchdog,
+unresponsive behavior triggers the watchdog, generating an interrupt
+that routes to the application processor, allowing it to call
+`rproc_report_crash` in the driver's interrupt context.
+
+During crash handling, the framework performs the following actions:
+
+a. Sends a request to stop the remote and any connected or
+ dependent subdevices.
+b. Generates a coredump, dumping all `resources` requested by the
+ remote alongside relevant debugging information. Resources are
+ explained below.
+c. Reloads the firmware and restarts the remote.
+
+If the `RPROC_FEAT_ATTACH_ON_RECOVERY` flag is set, the detach and
+attach callbacks of the driver are invoked without reloading the
+firmware. This is useful when the remote requires no
+assistance for recovery, or when the application processor can restart
+independently. After recovery, the application processor can reattach
+to the remote.
+
+The remote can request resources from the framework, which
+allocates a ".resource_table" section. During the ELF parsing phase,
+the framework identifies this section and calls the appropriate
+handler to allocate the requested resources.
+
+Resource management within the framework can accommodate any type of
+`fw_resource_type`.
+
+.. code-block:: c
+
+ enum fw_resource_type {
+ RSC_CARVEOUT = 0,
+ RSC_DEVMEM = 1,
+ RSC_TRACE = 2,
+ RSC_VDEV = 3,
+ RSC_LAST = 4,
+ RSC_VENDOR_START = 128,
+ RSC_VENDOR_END = 512,
+ };
+
+ struct resource_table {
+ u32 ver;
+ u32 num;
+ u32 reserved[2];
+ u32 offset[];
+ } __packed;
+
+ struct fw_rsc_hdr {
+ u32 type;
+ u8 data[];
+ } __packed;
+
+For example, if the remote requests both `RSC_TRACE` and
+`RSC_CARVEOUT` for memory allocation, the ELF firmware can be structured
+as follows:
+
+.. code-block:: c
+
+ #define MAX_SHARED_RESOURCE 2
+ #define LOG_BUF_SIZE 1000
+ #define CARVEOUT_DUMP_PA 0x12345678
+ #define CARVEOUT_DUMP_SIZE 2000
+
+ struct shared_resource_table {
+ u32 ver;
+ u32 num;
+ u32 reserved[2];
+ u32 offset[MAX_SHARED_RESOURCE];
+ struct fw_rsc_trace log_trace;
+ struct fw_rsc_carveout dump_carveout;
+ };
+
+ volatile struct shared_resource_table table = {
+ .ver = 1,
+ .num = 2,
+ .reserved = {0, 0},
+ .offset = {
+ offsetof(struct resource_table, log_trace),
+ offsetof(struct resource_table, dump_carveout),
+ },
+ .log_trace = {
+ RSC_TRACE,
+ (u32)log_buf, LOG_BUF_SIZE, 0, "log_trace",
+ },
+ .dump_carveout = {
+ RSC_CARVEOUT,
+ (u32)FW_RSC_ADDR_ANY, CARVEOUT_PA, 0, "carveout_dump",
+ },
+ };
+
+The framework creates a sysfs file when it encounters the `RSC_TRACE`
+type to expose log information to userspace. Other resource types are
+handled accordingly. In the example above, `CARVEOUT_DUMP_SIZE` bytes
+of DMA memory will be allocated starting from `CARVEOUT_DUMP_PA`.
+
+
+3. Remoteproc driver responsibilities
+=====================================
+
+The driver must provide the following information to the core:
+
+a. Translate device addresses (physical addresses) found in the ELF
+ firmware to virtual addresses in Linux using the `da_to_va`
+ callback. This allows the framework to copy ELF firmware from the
+ filesystem to the addresses expected by the remote since
+ the framework cannot directly access those physical addresses.
+b. Prepare/unprepare the remote prior to firmware loading,
+ which may involve allocating carveout and reserved memory regions.
+c. Implement methods for starting and stopping the remote,
+ whether by setting registers or sending explicit interrupts,
+ depending on the hardware design.
+d. Provide attach and detach callbacks to start the remote
+ without loading the firmware. This is beneficial when the remote
+ processor is already loaded and running.
+e. Implement a load callback for firmware loading, typically using
+ the ELF loader provided by the framework; currently, only ELF
+ format is supported.
+f. Invoke the framework's crash handler API upon detecting a remote
+ crash.
+
+Drivers must fill the `rproc_ops` structure and call `rproc_alloc`
+to register themselves with the framework.
+
+.. code-block:: c
+
+ struct rproc_ops {
+ int (*prepare)(struct rproc *rproc);
+ int (*unprepare)(struct rproc *rproc);
+ int (*start)(struct rproc *rproc);
+ int (*stop)(struct rproc *rproc);
+ int (*attach)(struct rproc *rproc);
+ int (*detach)(struct rproc *rproc);
+ void * (*da_to_va)(struct rproc *rproc, u64 da, size_t len,
+ bool *is_iomem);
+ int (*parse_fw)(struct rproc *rproc, const struct firmware *fw);
+ int (*handle_rsc)(struct rproc *rproc, u32 rsc_type,
+ void *rsc, int offset, int avail);
+ int (*load)(struct rproc *rproc, const struct firmware *fw);
+ //snip
+ };
+
+
+4. Virtio and Remoteproc
+========================
+
+The firmware must provide remoteproc with information regarding the
+virtio devices it supports and their configurations: an `RSC_VDEV`
+resource entry should detail the virtio device ID (as defined in
+`virtio_ids.h`), virtio features, virtio config space, vrings
+information, etc.
+
+Upon registration of a new remote, the remoteproc framework
+searches for its resource table and registers the supported virtio
+devices. A firmware may support multiple virtio devices, of various
+types (a single remote can support multiple rpmsg virtio
+devices if required).
+
+Moreover, `RSC_VDEV` resource entries suffice for static allocation
+of virtio devices. Dynamic allocations will also be supported using
+the rpmsg bus, akin to the handling of dynamic allocations for rpmsg
+channels. For more information, refer to `rpmsg.txt`.
diff --git a/Documentation/remoteproc/index.rst b/Documentation/remoteproc/index.rst
new file mode 100644
index 000000000000..631797f49b32
--- /dev/null
+++ b/Documentation/remoteproc/index.rst
@@ -0,0 +1,27 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================================================================
+remoteproc - remote processor subsystem in Linux(TM) kernel
+========================================================================
+
+Authors:
+ - anish kumar <yesanishhere@gmail.com>
+
+ remote processor subsystem is a way to manage the lifecycle of
+ a subsytem that is external to the Linux. The remoteproc framework
+ allows different platforms/architectures to control (power on,
+ load firmware, power off) those remote processors while abstracting
+ the hardware differences, so the entire driver doesn't need to be
+ duplicated.
+
+.. toctree::
+ :maxdepth: 1
+
+ core
+ rproc-api
+ rproc-kernel-api
+
+Mailing List
+------------
+To post a message, send an email to
+linux-remoteproc@vger.kernel.org
diff --git a/Documentation/remoteproc/rproc-api.rst b/Documentation/remoteproc/rproc-api.rst
new file mode 100644
index 000000000000..548d3658fc1c
--- /dev/null
+++ b/Documentation/remoteproc/rproc-api.rst
@@ -0,0 +1,75 @@
+==================================
+The Linux Remoteproc userspace API
+==================================
+
+Introduction
+============
+
+A Remoteproc (rproc) is a subsystem for managing the lifecycle
+of a processor that is connected to Linux.
+
+At times, userspace may need to check the state of the remote processor to
+prevent other processes from using it. For instance, if the remote processor
+is a DSP used for playback, there may be situations where the DSP is
+undergoing recovery and cannot be used. In such cases, attempts to access the
+DSP for playback should be blocked. The rproc framework provides sysfs APIs
+to inform userspace of the processor's current status which should be utilised
+to achieve the same.
+
+Additionally, there are scenarios where userspace applications need to explicitly
+control the rproc. In these cases, rproc also offers the file descriptors.
+
+The simplest API
+================
+
+Below set of api's can be used to start and stop the rproc
+where 'X' refers to instance of associated remoteproc. There can be systems
+where there are more than one rprocs such as multiple DSP's
+connected to application processors running Linux.
+::
+ echo start > /sys/class/remoteproc/remoteprocX/state
+ echo stop > /sys/class/remoteproc/remoteprocX/state
+
+To know the state of rproc:
+
+.. code-block::
+
+ cat /sys/class/remoteproc/remoteprocX/state
+
+
+To dynamically replace firmware, execute the following commands:
+
+.. code-block::
+
+ echo stop > /sys/class/remoteproc/remoteprocX/state
+ echo -n <firmware_name> >
+ /sys/class/remoteproc/remoteprocX/firmware
+ echo start > /sys/class/remoteproc/remoteprocX/state
+
+To simulate a remote crash, execute:
+
+.. code-block::
+
+ echo 1 > /sys/kernel/debug/remoteproc/remoteprocX/crash
+
+To get the trace logs, execute
+
+.. code-block::
+
+ cat /sys/kernel/debug/remoteproc/remoteprocX/crashX
+
+where X will be 0 or 1 if there are 2 resources. Also, this
+file will only exist if resources are defined in ELF firmware
+file.
+
+The coredump feature can be disabled with the following command:
+
+.. code-block::
+
+ echo disabled > /sys/kernel/debug/remoteproc/remoteprocX/coredump
+
+Userspace can also control start/stop of rproc by using a
+remoteproc Character Device, it can open the open a file descriptor
+and write `start` to initiate it, and `stop` to terminate it.
+
+[FIXME -- better explanations]
diff --git a/Documentation/remoteproc/rproc-kernel-api.rst b/Documentation/remoteproc/rproc-kernel-api.rst
new file mode 100644
index 000000000000..8604f2b3e6b1
--- /dev/null
+++ b/Documentation/remoteproc/rproc-kernel-api.rst
@@ -0,0 +1,239 @@
+=====================================================
+The Linux Remoteproc subsystem Driver Core kernel API
+=====================================================
+
+anish kumar <yesanishhere@gmail.com>
+
+Introduction
+------------
+This document does not describe what a Remote processor subsystem
+(RPROC) Driver or Device is. It also does not describe the API
+which can be used by user space to communicate with a RPROC driver.
+If you want to know this then please read the following
+file: Documentation/remotproc/remoteproc-api.rst .
+
+So what does this document describe? It describes the API that can be used by
+remote processor Drivers that want to use the remote processor Driver Core
+Framework. This framework provides all interfacing towards user space so that
+the same code does not have to be reproduced each time. This also means that
+a remote processor driver then only needs to provide the different routines
+(operations) that control the remote processor.
+
+The API
+-------
+Each remote processor driver that wants to use the remote processor Driver Core
+must #include <linux/remoteproc.h> (you would have to do this anyway when
+writing a rproc device driver). This include file contains following
+register routine::
+
+ int devm_rproc_add(struct device *dev, struct rproc *rproc)
+
+The devm_rproc_add routine registers a remote processor device.
+The parameter of this routine is a pointer to a rproc device structure.
+This routine returns zero on success and a negative errno code for failure.
+
+The rproc device structure looks like this::
+
+ struct rproc {
+ struct list_head node;
+ struct iommu_domain *domain;
+ const char *name;
+ const char *firmware;
+ void *priv;
+ struct rproc_ops *ops;
+ struct device dev;
+ atomic_t power;
+ unsigned int state;
+ enum rproc_dump_mechanism dump_conf;
+ struct mutex lock;
+ struct dentry *dbg_dir;
+ struct list_head traces;
+ int num_traces;
+ struct list_head carveouts;
+ struct list_head mappings;
+ u64 bootaddr;
+ struct list_head rvdevs;
+ struct list_head subdevs;
+ struct idr notifyids;
+ int index;
+ struct work_struct crash_handler;
+ unsigned int crash_cnt;
+ bool recovery_disabled;
+ int max_notifyid;
+ struct resource_table *table_ptr;
+ struct resource_table *clean_table;
+ struct resource_table *cached_table;
+ size_t table_sz;
+ bool has_iommu;
+ bool auto_boot;
+ bool sysfs_read_only;
+ struct list_head dump_segments;
+ int nb_vdev;
+ u8 elf_class;
+ u16 elf_machine;
+ struct cdev cdev;
+ bool cdev_put_on_release;
+ DECLARE_BITMAP(features, RPROC_MAX_FEATURES);
+ };
+
+It contains following fields:
+
+* node: list node of this rproc object
+* domain: iommu domain
+* name: human readable name of the rproc
+* firmware: name of firmware file to be loaded
+* priv: private data which belongs to the platform-specific rproc module
+* ops: platform-specific start/stop rproc handlers
+* dev: virtual device for refcounting and common remoteproc behavior
+* power: refcount of users who need this rproc powered up
+* state: state of the device
+* dump_conf: Currently selected coredump configuration
+* lock: lock which protects concurrent manipulations of the rproc
+* dbg_dir: debugfs directory of this rproc device
+* traces: list of trace buffers
+* num_traces: number of trace buffers
+* carveouts: list of physically contiguous memory allocations
+* mappings: list of iommu mappings we initiated, needed on shutdown
+* bootaddr: address of first instruction to boot rproc with (optional)
+* rvdevs: list of remote virtio devices
+* subdevs: list of subdevices, to following the running state
+* notifyids: idr for dynamically assigning rproc-wide unique notify ids
+* index: index of this rproc device
+* crash_handler: workqueue for handling a crash
+* crash_cnt: crash counter
+* recovery_disabled: flag that state if recovery was disabled
+* max_notifyid: largest allocated notify id.
+* table_ptr: pointer to the resource table in effect
+* clean_table: copy of the resource table without modifications. Used
+* when a remote processor is attached or detached from the core
+* cached_table: copy of the resource table
+* table_sz: size of @cached_table
+* has_iommu: flag to indicate if remote processor is behind an MMU
+* auto_boot: flag to indicate if remote processor should be auto-started
+* sysfs_read_only: flag to make remoteproc sysfs files read only
+* dump_segments: list of segments in the firmware
+* nb_vdev: number of vdev currently handled by rproc
+* elf_class: firmware ELF class
+* elf_machine: firmware ELF machine
+* cdev: character device of the rproc
+* cdev_put_on_release: flag to indicate if remoteproc should be shutdown on @char_dev release
+* features: indicate remoteproc features
+
+The list of rproc operations is defined as::
+
+ struct rproc_ops {
+ int (*prepare)(struct rproc *rproc);
+ int (*unprepare)(struct rproc *rproc);
+ int (*start)(struct rproc *rproc);
+ int (*stop)(struct rproc *rproc);
+ int (*attach)(struct rproc *rproc);
+ int (*detach)(struct rproc *rproc);
+ void (*kick)(struct rproc *rproc, int vqid);
+ void * (*da_to_va)(struct rproc *rproc, u64 da, size_t len, bool *is_iomem);
+ int (*parse_fw)(struct rproc *rproc, const struct firmware *fw);
+ int (*handle_rsc)(struct rproc *rproc, u32 rsc_type, void *rsc,
+ int offset, int avail);
+ struct resource_table *(*find_loaded_rsc_table)(
+ struct rproc *rproc, const struct firmware *fw);
+ struct resource_table *(*get_loaded_rsc_table)(
+ struct rproc *rproc, size_t *size);
+ int (*load)(struct rproc *rproc, const struct firmware *fw);
+ int (*sanity_check)(struct rproc *rproc, const struct firmware *fw);
+ u64 (*get_boot_addr)(struct rproc *rproc, const struct firmware *fw);
+ unsigned long (*panic)(struct rproc *rproc);
+ void (*coredump)(struct rproc *rproc);
+ };
+
+Most of the operations are optional. Currently in the implementation
+there are no mandatory operations, however from the practical standpoint
+minimum ops are:
+
+* start: this is a pointer to the routine that starts the remote processor
+ device.
+ The routine needs a pointer to the remote processor device structure as a
+ parameter. It returns zero on success or a negative errno code for failure.
+
+* stop: with this routine the remote processor device is being stopped.
+
+ The routine needs a pointer to the remote processor device structure as a
+ parameter. It returns zero on success or a negative errno code for failure.
+
+* da_to_va: this is the routine that needs to translate device address to
+ application processor virtual address that it can copy code to.
+
+ The routine needs a pointer to the remote processor device structure as a
+ parameter. It returns zero on success or a negative errno code for failure.
+
+ The routine provides the device address it finds in the ELF firmware and asks
+ the driver to convert that to virtual address.
+
+All other callbacks are optional in case of ELF provided firmware.
+
+* load: this is to load the firmware on to the remote device.
+
+ The routine needs firmware file that it needs to load on to the remote processor.
+ If the driver overrides this callback then default ELF loader will not get used.
+ Otherwise default framework provided loader gets used.
+
+ load = rproc_elf_load_segments;
+ parse_fw = rproc_elf_load_rsc_table;
+ find_loaded_rsc_table = rproc_elf_find_loaded_rsc_table;
+ sanity_check = rproc_elf_sanity_check;
+ get_boot_addr = rproc_elf_get_boot_addr;
+
+* parse_fw: this routing parses the provided firmware. In case of ELF format,
+ framework provided rproc_elf_load_rsc_table function can be used.
+
+* sanity_check: Check the format of the firmware.
+
+* coredump: If the driver prefers to manage coredumps independently, it can
+ implement its own coredump handling. However, the framework offers a default
+ implementation for the ELF format by assigning this callback to
+ rproc_coredump, unless the driver has overridden it.
+
+* get_boot_addr: In case the bootaddr defined in ELF firmware is different, driver
+ can use this callback to set a different boot address for remote processor to
+ starts its reset vector from.
+
+* find_loaded_rsc_table: this routine gets the loaded resource table from the firmware.
+
+ resource table should have a section named (.resource_table) for the framework
+ to understand and interpret its content. Resource table is a way for remote
+ processor to ask for resources such as memory for dumping and logging. Look
+ at core documentation to know how to create the ELF section for the same.
+
+* get_loaded_rsc_table: Driver can customize passing the resource table by overriding
+ this callback. Framework doesn't provide any default implementation for the same.
+
+
+The rproc_report_crash function allows you to report a crash when crash is
+detected by the driver.
+
+::
+
+ void rproc_report_crash(struct rproc *rproc, enum rproc_crash_type type);
+
+To add a subdev corresponding driver can call::
+
+ void rproc_add_subdev(struct rproc *rproc, struct rproc_subdev *subdev);
+
+To remove a subdev, driver can call.
+
+::
+
+ void rproc_remove_subdev(struct rproc *rproc, struct rproc_subdev *subdev);
+
+To work with ELF coredump below function can be called::
+
+ void rproc_coredump_cleanup(struct rproc *rproc);
+ void rproc_coredump(struct rproc *rproc);
+ void rproc_coredump_using_sections(struct rproc *rproc);
+ int rproc_coredump_add_segment(struct rproc *rproc, dma_addr_t da, size_t size);
+ int rproc_coredump_add_custom_segment(struct rproc *rproc,
+ dma_addr_t da, size_t size,
+ void (*dumpfn)(struct rproc *rproc,
+ struct rproc_dump_segment *segment,
+ void *dest, size_t offset,
+ size_t size),
+
+Remember that coredump functions provided by the framework only works with ELF format.
diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst
index 77bae5e5328b..d2c2b75fade8 100644
--- a/Documentation/staging/index.rst
+++ b/Documentation/staging/index.rst
@@ -9,7 +9,6 @@ Unsorted Documentation
crc32
lzo
magic-number
- remoteproc
rpmsg
speculation
static-keys
diff --git a/Documentation/staging/remoteproc.rst b/Documentation/staging/remoteproc.rst
deleted file mode 100644
index 348ee7e508ac..000000000000
--- a/Documentation/staging/remoteproc.rst
+++ /dev/null
@@ -1,360 +0,0 @@
-==========================
-Remote Processor Framework
-==========================
-
-Introduction
-============
-
-Modern SoCs typically have heterogeneous remote processor devices in asymmetric
-multiprocessing (AMP) configurations, which may be running different instances
-of operating system, whether it's Linux or any other flavor of real-time OS.
-
-OMAP4, for example, has dual Cortex-A9, dual Cortex-M3 and a C64x+ DSP.
-In a typical configuration, the dual cortex-A9 is running Linux in a SMP
-configuration, and each of the other three cores (two M3 cores and a DSP)
-is running its own instance of RTOS in an AMP configuration.
-
-The remoteproc framework allows different platforms/architectures to
-control (power on, load firmware, power off) those remote processors while
-abstracting the hardware differences, so the entire driver doesn't need to be
-duplicated. In addition, this framework also adds rpmsg virtio devices
-for remote processors that supports this kind of communication. This way,
-platform-specific remoteproc drivers only need to provide a few low-level
-handlers, and then all rpmsg drivers will then just work
-(for more information about the virtio-based rpmsg bus and its drivers,
-please read Documentation/staging/rpmsg.rst).
-Registration of other types of virtio devices is now also possible. Firmwares
-just need to publish what kind of virtio devices do they support, and then
-remoteproc will add those devices. This makes it possible to reuse the
-existing virtio drivers with remote processor backends at a minimal development
-cost.
-
-User API
-========
-
-::
-
- int rproc_boot(struct rproc *rproc)
-
-Boot a remote processor (i.e. load its firmware, power it on, ...).
-
-If the remote processor is already powered on, this function immediately
-returns (successfully).
-
-Returns 0 on success, and an appropriate error value otherwise.
-Note: to use this function you should already have a valid rproc
-handle. There are several ways to achieve that cleanly (devres, pdata,
-the way remoteproc_rpmsg.c does this, or, if this becomes prevalent, we
-might also consider using dev_archdata for this).
-
-::
-
- int rproc_shutdown(struct rproc *rproc)
-
-Power off a remote processor (previously booted with rproc_boot()).
-In case @rproc is still being used by an additional user(s), then
-this function will just decrement the power refcount and exit,
-without really powering off the device.
-
-Returns 0 on success, and an appropriate error value otherwise.
-Every call to rproc_boot() must (eventually) be accompanied by a call
-to rproc_shutdown(). Calling rproc_shutdown() redundantly is a bug.
-
-.. note::
-
- we're not decrementing the rproc's refcount, only the power refcount.
- which means that the @rproc handle stays valid even after
- rproc_shutdown() returns, and users can still use it with a subsequent
- rproc_boot(), if needed.
-
-::
-
- struct rproc *rproc_get_by_phandle(phandle phandle)
-
-Find an rproc handle using a device tree phandle. Returns the rproc
-handle on success, and NULL on failure. This function increments
-the remote processor's refcount, so always use rproc_put() to
-decrement it back once rproc isn't needed anymore.
-
-Typical usage
-=============
-
-::
-
- #include <linux/remoteproc.h>
-
- /* in case we were given a valid 'rproc' handle */
- int dummy_rproc_example(struct rproc *my_rproc)
- {
- int ret;
-
- /* let's power on and boot our remote processor */
- ret = rproc_boot(my_rproc);
- if (ret) {
- /*
- * something went wrong. handle it and leave.
- */
- }
-
- /*
- * our remote processor is now powered on... give it some work
- */
-
- /* let's shut it down now */
- rproc_shutdown(my_rproc);
- }
-
-API for implementors
-====================
-
-::
-
- struct rproc *rproc_alloc(struct device *dev, const char *name,
- const struct rproc_ops *ops,
- const char *firmware, int len)
-
-Allocate a new remote processor handle, but don't register
-it yet. Required parameters are the underlying device, the
-name of this remote processor, platform-specific ops handlers,
-the name of the firmware to boot this rproc with, and the
-length of private data needed by the allocating rproc driver (in bytes).
-
-This function should be used by rproc implementations during
-initialization of the remote processor.
-
-After creating an rproc handle using this function, and when ready,
-implementations should then call rproc_add() to complete
-the registration of the remote processor.
-
-On success, the new rproc is returned, and on failure, NULL.
-
-.. note::
-
- **never** directly deallocate @rproc, even if it was not registered
- yet. Instead, when you need to unroll rproc_alloc(), use rproc_free().
-
-::
-
- void rproc_free(struct rproc *rproc)
-
-Free an rproc handle that was allocated by rproc_alloc.
-
-This function essentially unrolls rproc_alloc(), by decrementing the
-rproc's refcount. It doesn't directly free rproc; that would happen
-only if there are no other references to rproc and its refcount now
-dropped to zero.
-
-::
-
- int rproc_add(struct rproc *rproc)
-
-Register @rproc with the remoteproc framework, after it has been
-allocated with rproc_alloc().
-
-This is called by the platform-specific rproc implementation, whenever
-a new remote processor device is probed.
-
-Returns 0 on success and an appropriate error code otherwise.
-Note: this function initiates an asynchronous firmware loading
-context, which will look for virtio devices supported by the rproc's
-firmware.
-
-If found, those virtio devices will be created and added, so as a result
-of registering this remote processor, additional virtio drivers might get
-probed.
-
-::
-
- int rproc_del(struct rproc *rproc)
-
-Unroll rproc_add().
-
-This function should be called when the platform specific rproc
-implementation decides to remove the rproc device. it should
-_only_ be called if a previous invocation of rproc_add()
-has completed successfully.
-
-After rproc_del() returns, @rproc is still valid, and its
-last refcount should be decremented by calling rproc_free().
-
-Returns 0 on success and -EINVAL if @rproc isn't valid.
-
-::
-
- void rproc_report_crash(struct rproc *rproc, enum rproc_crash_type type)
-
-Report a crash in a remoteproc
-
-This function must be called every time a crash is detected by the
-platform specific rproc implementation. This should not be called from a
-non-remoteproc driver. This function can be called from atomic/interrupt
-context.
-
-Implementation callbacks
-========================
-
-These callbacks should be provided by platform-specific remoteproc
-drivers::
-
- /**
- * struct rproc_ops - platform-specific device handlers
- * @start: power on the device and boot it
- * @stop: power off the device
- * @kick: kick a virtqueue (virtqueue id given as a parameter)
- */
- struct rproc_ops {
- int (*start)(struct rproc *rproc);
- int (*stop)(struct rproc *rproc);
- void (*kick)(struct rproc *rproc, int vqid);
- };
-
-Every remoteproc implementation should at least provide the ->start and ->stop
-handlers. If rpmsg/virtio functionality is also desired, then the ->kick handler
-should be provided as well.
-
-The ->start() handler takes an rproc handle and should then power on the
-device and boot it (use rproc->priv to access platform-specific private data).
-The boot address, in case needed, can be found in rproc->bootaddr (remoteproc
-core puts there the ELF entry point).
-On success, 0 should be returned, and on failure, an appropriate error code.
-
-The ->stop() handler takes an rproc handle and powers the device down.
-On success, 0 is returned, and on failure, an appropriate error code.
-
-The ->kick() handler takes an rproc handle, and an index of a virtqueue
-where new message was placed in. Implementations should interrupt the remote
-processor and let it know it has pending messages. Notifying remote processors
-the exact virtqueue index to look in is optional: it is easy (and not
-too expensive) to go through the existing virtqueues and look for new buffers
-in the used rings.
-
-Binary Firmware Structure
-=========================
-
-At this point remoteproc supports ELF32 and ELF64 firmware binaries. However,
-it is quite expected that other platforms/devices which we'd want to
-support with this framework will be based on different binary formats.
-
-When those use cases show up, we will have to decouple the binary format
-from the framework core, so we can support several binary formats without
-duplicating common code.
-
-When the firmware is parsed, its various segments are loaded to memory
-according to the specified device address (might be a physical address
-if the remote processor is accessing memory directly).
-
-In addition to the standard ELF segments, most remote processors would
-also include a special section which we call "the resource table".
-
-The resource table contains system resources that the remote processor
-requires before it should be powered on, such as allocation of physically
-contiguous memory, or iommu mapping of certain on-chip peripherals.
-Remotecore will only power up the device after all the resource table's
-requirement are met.
-
-In addition to system resources, the resource table may also contain
-resource entries that publish the existence of supported features
-or configurations by the remote processor, such as trace buffers and
-supported virtio devices (and their configurations).
-
-The resource table begins with this header::
-
- /**
- * struct resource_table - firmware resource table header
- * @ver: version number
- * @num: number of resource entries
- * @reserved: reserved (must be zero)
- * @offset: array of offsets pointing at the various resource entries
- *
- * The header of the resource table, as expressed by this structure,
- * contains a version number (should we need to change this format in the
- * future), the number of available resource entries, and their offsets
- * in the table.
- */
- struct resource_table {
- u32 ver;
- u32 num;
- u32 reserved[2];
- u32 offset[0];
- } __packed;
-
-Immediately following this header are the resource entries themselves,
-each of which begins with the following resource entry header::
-
- /**
- * struct fw_rsc_hdr - firmware resource entry header
- * @type: resource type
- * @data: resource data
- *
- * Every resource entry begins with a 'struct fw_rsc_hdr' header providing
- * its @type. The content of the entry itself will immediately follow
- * this header, and it should be parsed according to the resource type.
- */
- struct fw_rsc_hdr {
- u32 type;
- u8 data[0];
- } __packed;
-
-Some resources entries are mere announcements, where the host is informed
-of specific remoteproc configuration. Other entries require the host to
-do something (e.g. allocate a system resource). Sometimes a negotiation
-is expected, where the firmware requests a resource, and once allocated,
-the host should provide back its details (e.g. address of an allocated
-memory region).
-
-Here are the various resource types that are currently supported::
-
- /**
- * enum fw_resource_type - types of resource entries
- *
- * @RSC_CARVEOUT: request for allocation of a physically contiguous
- * memory region.
- * @RSC_DEVMEM: request to iommu_map a memory-based peripheral.
- * @RSC_TRACE: announces the availability of a trace buffer into which
- * the remote processor will be writing logs.
- * @RSC_VDEV: declare support for a virtio device, and serve as its
- * virtio header.
- * @RSC_LAST: just keep this one at the end
- * @RSC_VENDOR_START: start of the vendor specific resource types range
- * @RSC_VENDOR_END: end of the vendor specific resource types range
- *
- * Please note that these values are used as indices to the rproc_handle_rsc
- * lookup table, so please keep them sane. Moreover, @RSC_LAST is used to
- * check the validity of an index before the lookup table is accessed, so
- * please update it as needed.
- */
- enum fw_resource_type {
- RSC_CARVEOUT = 0,
- RSC_DEVMEM = 1,
- RSC_TRACE = 2,
- RSC_VDEV = 3,
- RSC_LAST = 4,
- RSC_VENDOR_START = 128,
- RSC_VENDOR_END = 512,
- };
-
-For more details regarding a specific resource type, please see its
-dedicated structure in include/linux/remoteproc.h.
-
-We also expect that platform-specific resource entries will show up
-at some point. When that happens, we could easily add a new RSC_PLATFORM
-type, and hand those resources to the platform-specific rproc driver to handle.
-
-Virtio and remoteproc
-=====================
-
-The firmware should provide remoteproc information about virtio devices
-that it supports, and their configurations: a RSC_VDEV resource entry
-should specify the virtio device id (as in virtio_ids.h), virtio features,
-virtio config space, vrings information, etc.
-
-When a new remote processor is registered, the remoteproc framework
-will look for its resource table and will register the virtio devices
-it supports. A firmware may support any number of virtio devices, and
-of any type (a single remote processor can also easily support several
-rpmsg virtio devices this way, if desired).
-
-Of course, RSC_VDEV resource entries are only good enough for static
-allocation of virtio devices. Dynamic allocations will also be made possible
-using the rpmsg bus (similar to how we already do dynamic allocations of
-rpmsg channels; read more about it in rpmsg.txt).
diff --git a/Documentation/staging/rpmsg.rst b/Documentation/staging/rpmsg.rst
index 3713adaa1608..c1eb5343bf37 100644
--- a/Documentation/staging/rpmsg.rst
+++ b/Documentation/staging/rpmsg.rst
@@ -5,7 +5,7 @@ Remote Processor Messaging (rpmsg) Framework
.. note::
This document describes the rpmsg bus and how to write rpmsg drivers.
- To learn how to add rpmsg support for new platforms, check out remoteproc.txt
+ To learn how to add rpmsg support for new platforms, check out remoteproc
(also a resident of Documentation/).
Introduction
--
2.39.3 (Apple Git-146)Hi Anish,
First and foremost, there are kernel bot problems to fix.
On Mon, Oct 14, 2024 at 07:58:31PM -0700, anish kumar wrote:
> Add the documentation in the mainline from
> staging and add the relvant information from
> current mainline.
>
> Added:
> 1. userspace api documentation.
> 2. kernel api documentation.
> 3. Driver framework core details added.
You are doing everything in the same patch, making it impossible for me to
understand what is just a move from staging to core and what is new material.
First do a patch that does the move and then do the enhancements, one topic at a
time.
Thanks,
Mathieu
>
> Signed-off-by: anish kumar <yesanishhere@gmail.com>
> ---
> Documentation/remoteproc/core.rst | 252 ++++++++++++
> Documentation/remoteproc/index.rst | 27 ++
> Documentation/remoteproc/rproc-api.rst | 75 ++++
> Documentation/remoteproc/rproc-kernel-api.rst | 239 ++++++++++++
> Documentation/staging/index.rst | 1 -
> Documentation/staging/remoteproc.rst | 360 ------------------
> Documentation/staging/rpmsg.rst | 2 +-
> 7 files changed, 594 insertions(+), 362 deletions(-)
> create mode 100644 Documentation/remoteproc/core.rst
> create mode 100644 Documentation/remoteproc/index.rst
> create mode 100644 Documentation/remoteproc/rproc-api.rst
> create mode 100644 Documentation/remoteproc/rproc-kernel-api.rst
> delete mode 100644 Documentation/staging/remoteproc.rst
>
> diff --git a/Documentation/remoteproc/core.rst b/Documentation/remoteproc/core.rst
> new file mode 100644
> index 000000000000..a59c2c5bc8e6
> --- /dev/null
> +++ b/Documentation/remoteproc/core.rst
> @@ -0,0 +1,252 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============================================
> +General description of the remoteproc subsystem
> +===============================================
> +
> +Authors:
> + - anish kumar <yesanishhere@gmail.com>
> +
> +.. Contents:
> +
> + 1. Introduction
> + 2. Remoteproc framework responsibilities
> + 3. Remoteproc driver responsibilities
> + 4. Virtio and rpmsg
> +
> +1. Introduction
> +======================
> +
> +Modern System on Chips (SoCs) typically integrate heterogeneous remote
> +processor devices in asymmetric multiprocessing (AMP) configurations.
> +These processors may run different operating systems, such as Linux and
> +various real-time operating systems (RTOS).
> +
> +For example, the OMAP4 platform features dual Cortex-A9 cores, dual
> +Cortex-M3 cores, and a C64x+ DSP. In a standard setup, the Cortex-A9
> +cores execute Linux in a symmetric multiprocessing (SMP) configuration,
> +while the M3 cores and DSP run independent instances of an RTOS.
> +
> +The remoteproc framework allows various platforms and architectures to
> +manage remote processors, including operations such as powering on,
> +loading firmware, and powering off. This framework abstracts hardware
> +differences, promoting code reuse and minimizing duplication. It also
> +supports rpmsg virtio devices for remote processors that utilize this
> +communication method. Consequently, platform-specific remoteproc drivers
> +need only implement a few low-level handlers, enabling seamless operation
> +of all rpmsg drivers. (For more details about the virtio-based rpmsg
> +bus and its drivers, refer to :doc:`Documentation/staging/rpmsg.rst`.)
> +
> +Additionally, the framework allows for the registration of various
> +virtio devices. Firmware can publish the types of virtio devices it
> +supports, facilitating their addition to the remoteproc framework. This
> +flexibility enables the reuse of existing virtio drivers with remote
> +processor backends at minimal development cost.
> +
> +The primary purpose of the remoteproc framework is to download firmware
> +for remote processors and manage their lifecycle. The framework consists
> +of several key components:
> +
> +- **Character Driver**: Provides userspace access to control the remote
> + processor.
> +- **ELF Utility**: Offers functions for handling ELF files and managing
> + resources requested by the remote processor.
> +- **Remoteproc Core**: Manages firmware downloads and recovery actions
> + in case of a remote processor crash.
> +- **Coredump**: Provides facilities for coredumping and tracing from
> + the remote processor in the event of a crash.
> +- **Userspace Interaction**: Uses sysfs and debugfs to manage the
> + lifecycle and status of the remote processor.
> +- **Virtio Support**: Facilitates interaction with the virtio and
> + rpmsg bus.
> +
> +From here on, references to "framework" denote the remoteproc
> +framework, and "driver" refers to the remoteproc driver that utilizes
> +the framework for managing remote processors.
> +
> +2. Remoteproc framework Responsibilities
> +========================================
> +
> +The framework begins by gathering information about the firmware file
> +to be downloaded through the request_firmware function. It supports
> +the ELF format and parses the firmware image to identify the physical
> +addresses that need to be populated from the corresponding ELF sections.
> +The framework also requires knowledge of the logical or I/O-mapped
> +addresses in the application processor. Once this information is
> +obtained from the driver, the framework transfers the data to the
> +specified addresses and starts the remote, along with
> +any devices physically or logically connected to it.
> +
> +Dependent devices, referred to as `subdevices` within the framework,
> +are also managed post-registration by their respective drivers.
> +Subdevices can register themselves using `rproc_(add/remove)_subdev`.
> +Non-remoteproc drivers can use subdevices as a way to logically connect
> +to remote and get lifecycle notifications of the remote.
> +
> +The framework oversees the lifecycle of the remote and
> +provides the `rproc_report_crash` function, which the driver invokes
> +upon receiving a crash notification from the remote. The
> +notification method can differ based on the design of the remote
> +processor and its communication with the application processor. For
> +instance, if the remote is a DSP equipped with a watchdog,
> +unresponsive behavior triggers the watchdog, generating an interrupt
> +that routes to the application processor, allowing it to call
> +`rproc_report_crash` in the driver's interrupt context.
> +
> +During crash handling, the framework performs the following actions:
> +
> +a. Sends a request to stop the remote and any connected or
> + dependent subdevices.
> +b. Generates a coredump, dumping all `resources` requested by the
> + remote alongside relevant debugging information. Resources are
> + explained below.
> +c. Reloads the firmware and restarts the remote.
> +
> +If the `RPROC_FEAT_ATTACH_ON_RECOVERY` flag is set, the detach and
> +attach callbacks of the driver are invoked without reloading the
> +firmware. This is useful when the remote requires no
> +assistance for recovery, or when the application processor can restart
> +independently. After recovery, the application processor can reattach
> +to the remote.
> +
> +The remote can request resources from the framework, which
> +allocates a ".resource_table" section. During the ELF parsing phase,
> +the framework identifies this section and calls the appropriate
> +handler to allocate the requested resources.
> +
> +Resource management within the framework can accommodate any type of
> +`fw_resource_type`.
> +
> +.. code-block:: c
> +
> + enum fw_resource_type {
> + RSC_CARVEOUT = 0,
> + RSC_DEVMEM = 1,
> + RSC_TRACE = 2,
> + RSC_VDEV = 3,
> + RSC_LAST = 4,
> + RSC_VENDOR_START = 128,
> + RSC_VENDOR_END = 512,
> + };
> +
> + struct resource_table {
> + u32 ver;
> + u32 num;
> + u32 reserved[2];
> + u32 offset[];
> + } __packed;
> +
> + struct fw_rsc_hdr {
> + u32 type;
> + u8 data[];
> + } __packed;
> +
> +For example, if the remote requests both `RSC_TRACE` and
> +`RSC_CARVEOUT` for memory allocation, the ELF firmware can be structured
> +as follows:
> +
> +.. code-block:: c
> +
> + #define MAX_SHARED_RESOURCE 2
> + #define LOG_BUF_SIZE 1000
> + #define CARVEOUT_DUMP_PA 0x12345678
> + #define CARVEOUT_DUMP_SIZE 2000
> +
> + struct shared_resource_table {
> + u32 ver;
> + u32 num;
> + u32 reserved[2];
> + u32 offset[MAX_SHARED_RESOURCE];
> + struct fw_rsc_trace log_trace;
> + struct fw_rsc_carveout dump_carveout;
> + };
> +
> + volatile struct shared_resource_table table = {
> + .ver = 1,
> + .num = 2,
> + .reserved = {0, 0},
> + .offset = {
> + offsetof(struct resource_table, log_trace),
> + offsetof(struct resource_table, dump_carveout),
> + },
> + .log_trace = {
> + RSC_TRACE,
> + (u32)log_buf, LOG_BUF_SIZE, 0, "log_trace",
> + },
> + .dump_carveout = {
> + RSC_CARVEOUT,
> + (u32)FW_RSC_ADDR_ANY, CARVEOUT_PA, 0, "carveout_dump",
> + },
> + };
> +
> +The framework creates a sysfs file when it encounters the `RSC_TRACE`
> +type to expose log information to userspace. Other resource types are
> +handled accordingly. In the example above, `CARVEOUT_DUMP_SIZE` bytes
> +of DMA memory will be allocated starting from `CARVEOUT_DUMP_PA`.
> +
> +
> +3. Remoteproc driver responsibilities
> +=====================================
> +
> +The driver must provide the following information to the core:
> +
> +a. Translate device addresses (physical addresses) found in the ELF
> + firmware to virtual addresses in Linux using the `da_to_va`
> + callback. This allows the framework to copy ELF firmware from the
> + filesystem to the addresses expected by the remote since
> + the framework cannot directly access those physical addresses.
> +b. Prepare/unprepare the remote prior to firmware loading,
> + which may involve allocating carveout and reserved memory regions.
> +c. Implement methods for starting and stopping the remote,
> + whether by setting registers or sending explicit interrupts,
> + depending on the hardware design.
> +d. Provide attach and detach callbacks to start the remote
> + without loading the firmware. This is beneficial when the remote
> + processor is already loaded and running.
> +e. Implement a load callback for firmware loading, typically using
> + the ELF loader provided by the framework; currently, only ELF
> + format is supported.
> +f. Invoke the framework's crash handler API upon detecting a remote
> + crash.
> +
> +Drivers must fill the `rproc_ops` structure and call `rproc_alloc`
> +to register themselves with the framework.
> +
> +.. code-block:: c
> +
> + struct rproc_ops {
> + int (*prepare)(struct rproc *rproc);
> + int (*unprepare)(struct rproc *rproc);
> + int (*start)(struct rproc *rproc);
> + int (*stop)(struct rproc *rproc);
> + int (*attach)(struct rproc *rproc);
> + int (*detach)(struct rproc *rproc);
> + void * (*da_to_va)(struct rproc *rproc, u64 da, size_t len,
> + bool *is_iomem);
> + int (*parse_fw)(struct rproc *rproc, const struct firmware *fw);
> + int (*handle_rsc)(struct rproc *rproc, u32 rsc_type,
> + void *rsc, int offset, int avail);
> + int (*load)(struct rproc *rproc, const struct firmware *fw);
> + //snip
> + };
> +
> +
> +4. Virtio and Remoteproc
> +========================
> +
> +The firmware must provide remoteproc with information regarding the
> +virtio devices it supports and their configurations: an `RSC_VDEV`
> +resource entry should detail the virtio device ID (as defined in
> +`virtio_ids.h`), virtio features, virtio config space, vrings
> +information, etc.
> +
> +Upon registration of a new remote, the remoteproc framework
> +searches for its resource table and registers the supported virtio
> +devices. A firmware may support multiple virtio devices, of various
> +types (a single remote can support multiple rpmsg virtio
> +devices if required).
> +
> +Moreover, `RSC_VDEV` resource entries suffice for static allocation
> +of virtio devices. Dynamic allocations will also be supported using
> +the rpmsg bus, akin to the handling of dynamic allocations for rpmsg
> +channels. For more information, refer to `rpmsg.txt`.
> diff --git a/Documentation/remoteproc/index.rst b/Documentation/remoteproc/index.rst
> new file mode 100644
> index 000000000000..631797f49b32
> --- /dev/null
> +++ b/Documentation/remoteproc/index.rst
> @@ -0,0 +1,27 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +========================================================================
> +remoteproc - remote processor subsystem in Linux(TM) kernel
> +========================================================================
> +
> +Authors:
> + - anish kumar <yesanishhere@gmail.com>
> +
> + remote processor subsystem is a way to manage the lifecycle of
> + a subsytem that is external to the Linux. The remoteproc framework
> + allows different platforms/architectures to control (power on,
> + load firmware, power off) those remote processors while abstracting
> + the hardware differences, so the entire driver doesn't need to be
> + duplicated.
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + core
> + rproc-api
> + rproc-kernel-api
> +
> +Mailing List
> +------------
> +To post a message, send an email to
> +linux-remoteproc@vger.kernel.org
> diff --git a/Documentation/remoteproc/rproc-api.rst b/Documentation/remoteproc/rproc-api.rst
> new file mode 100644
> index 000000000000..548d3658fc1c
> --- /dev/null
> +++ b/Documentation/remoteproc/rproc-api.rst
> @@ -0,0 +1,75 @@
> +==================================
> +The Linux Remoteproc userspace API
> +==================================
> +
> +Introduction
> +============
> +
> +A Remoteproc (rproc) is a subsystem for managing the lifecycle
> +of a processor that is connected to Linux.
> +
> +At times, userspace may need to check the state of the remote processor to
> +prevent other processes from using it. For instance, if the remote processor
> +is a DSP used for playback, there may be situations where the DSP is
> +undergoing recovery and cannot be used. In such cases, attempts to access the
> +DSP for playback should be blocked. The rproc framework provides sysfs APIs
> +to inform userspace of the processor's current status which should be utilised
> +to achieve the same.
> +
> +Additionally, there are scenarios where userspace applications need to explicitly
> +control the rproc. In these cases, rproc also offers the file descriptors.
> +
> +The simplest API
> +================
> +
> +Below set of api's can be used to start and stop the rproc
> +where 'X' refers to instance of associated remoteproc. There can be systems
> +where there are more than one rprocs such as multiple DSP's
> +connected to application processors running Linux.
> +::
> + echo start > /sys/class/remoteproc/remoteprocX/state
> + echo stop > /sys/class/remoteproc/remoteprocX/state
> +
> +To know the state of rproc:
> +
> +.. code-block::
> +
> + cat /sys/class/remoteproc/remoteprocX/state
> +
> +
> +To dynamically replace firmware, execute the following commands:
> +
> +.. code-block::
> +
> + echo stop > /sys/class/remoteproc/remoteprocX/state
> + echo -n <firmware_name> >
> + /sys/class/remoteproc/remoteprocX/firmware
> + echo start > /sys/class/remoteproc/remoteprocX/state
> +
> +To simulate a remote crash, execute:
> +
> +.. code-block::
> +
> + echo 1 > /sys/kernel/debug/remoteproc/remoteprocX/crash
> +
> +To get the trace logs, execute
> +
> +.. code-block::
> +
> + cat /sys/kernel/debug/remoteproc/remoteprocX/crashX
> +
> +where X will be 0 or 1 if there are 2 resources. Also, this
> +file will only exist if resources are defined in ELF firmware
> +file.
> +
> +The coredump feature can be disabled with the following command:
> +
> +.. code-block::
> +
> + echo disabled > /sys/kernel/debug/remoteproc/remoteprocX/coredump
> +
> +Userspace can also control start/stop of rproc by using a
> +remoteproc Character Device, it can open the open a file descriptor
> +and write `start` to initiate it, and `stop` to terminate it.
> +
> +[FIXME -- better explanations]
> diff --git a/Documentation/remoteproc/rproc-kernel-api.rst b/Documentation/remoteproc/rproc-kernel-api.rst
> new file mode 100644
> index 000000000000..8604f2b3e6b1
> --- /dev/null
> +++ b/Documentation/remoteproc/rproc-kernel-api.rst
> @@ -0,0 +1,239 @@
> +=====================================================
> +The Linux Remoteproc subsystem Driver Core kernel API
> +=====================================================
> +
> +anish kumar <yesanishhere@gmail.com>
> +
> +Introduction
> +------------
> +This document does not describe what a Remote processor subsystem
> +(RPROC) Driver or Device is. It also does not describe the API
> +which can be used by user space to communicate with a RPROC driver.
> +If you want to know this then please read the following
> +file: Documentation/remotproc/remoteproc-api.rst .
> +
> +So what does this document describe? It describes the API that can be used by
> +remote processor Drivers that want to use the remote processor Driver Core
> +Framework. This framework provides all interfacing towards user space so that
> +the same code does not have to be reproduced each time. This also means that
> +a remote processor driver then only needs to provide the different routines
> +(operations) that control the remote processor.
> +
> +The API
> +-------
> +Each remote processor driver that wants to use the remote processor Driver Core
> +must #include <linux/remoteproc.h> (you would have to do this anyway when
> +writing a rproc device driver). This include file contains following
> +register routine::
> +
> + int devm_rproc_add(struct device *dev, struct rproc *rproc)
> +
> +The devm_rproc_add routine registers a remote processor device.
> +The parameter of this routine is a pointer to a rproc device structure.
> +This routine returns zero on success and a negative errno code for failure.
> +
> +The rproc device structure looks like this::
> +
> + struct rproc {
> + struct list_head node;
> + struct iommu_domain *domain;
> + const char *name;
> + const char *firmware;
> + void *priv;
> + struct rproc_ops *ops;
> + struct device dev;
> + atomic_t power;
> + unsigned int state;
> + enum rproc_dump_mechanism dump_conf;
> + struct mutex lock;
> + struct dentry *dbg_dir;
> + struct list_head traces;
> + int num_traces;
> + struct list_head carveouts;
> + struct list_head mappings;
> + u64 bootaddr;
> + struct list_head rvdevs;
> + struct list_head subdevs;
> + struct idr notifyids;
> + int index;
> + struct work_struct crash_handler;
> + unsigned int crash_cnt;
> + bool recovery_disabled;
> + int max_notifyid;
> + struct resource_table *table_ptr;
> + struct resource_table *clean_table;
> + struct resource_table *cached_table;
> + size_t table_sz;
> + bool has_iommu;
> + bool auto_boot;
> + bool sysfs_read_only;
> + struct list_head dump_segments;
> + int nb_vdev;
> + u8 elf_class;
> + u16 elf_machine;
> + struct cdev cdev;
> + bool cdev_put_on_release;
> + DECLARE_BITMAP(features, RPROC_MAX_FEATURES);
> + };
> +
> +It contains following fields:
> +
> +* node: list node of this rproc object
> +* domain: iommu domain
> +* name: human readable name of the rproc
> +* firmware: name of firmware file to be loaded
> +* priv: private data which belongs to the platform-specific rproc module
> +* ops: platform-specific start/stop rproc handlers
> +* dev: virtual device for refcounting and common remoteproc behavior
> +* power: refcount of users who need this rproc powered up
> +* state: state of the device
> +* dump_conf: Currently selected coredump configuration
> +* lock: lock which protects concurrent manipulations of the rproc
> +* dbg_dir: debugfs directory of this rproc device
> +* traces: list of trace buffers
> +* num_traces: number of trace buffers
> +* carveouts: list of physically contiguous memory allocations
> +* mappings: list of iommu mappings we initiated, needed on shutdown
> +* bootaddr: address of first instruction to boot rproc with (optional)
> +* rvdevs: list of remote virtio devices
> +* subdevs: list of subdevices, to following the running state
> +* notifyids: idr for dynamically assigning rproc-wide unique notify ids
> +* index: index of this rproc device
> +* crash_handler: workqueue for handling a crash
> +* crash_cnt: crash counter
> +* recovery_disabled: flag that state if recovery was disabled
> +* max_notifyid: largest allocated notify id.
> +* table_ptr: pointer to the resource table in effect
> +* clean_table: copy of the resource table without modifications. Used
> +* when a remote processor is attached or detached from the core
> +* cached_table: copy of the resource table
> +* table_sz: size of @cached_table
> +* has_iommu: flag to indicate if remote processor is behind an MMU
> +* auto_boot: flag to indicate if remote processor should be auto-started
> +* sysfs_read_only: flag to make remoteproc sysfs files read only
> +* dump_segments: list of segments in the firmware
> +* nb_vdev: number of vdev currently handled by rproc
> +* elf_class: firmware ELF class
> +* elf_machine: firmware ELF machine
> +* cdev: character device of the rproc
> +* cdev_put_on_release: flag to indicate if remoteproc should be shutdown on @char_dev release
> +* features: indicate remoteproc features
> +
> +The list of rproc operations is defined as::
> +
> + struct rproc_ops {
> + int (*prepare)(struct rproc *rproc);
> + int (*unprepare)(struct rproc *rproc);
> + int (*start)(struct rproc *rproc);
> + int (*stop)(struct rproc *rproc);
> + int (*attach)(struct rproc *rproc);
> + int (*detach)(struct rproc *rproc);
> + void (*kick)(struct rproc *rproc, int vqid);
> + void * (*da_to_va)(struct rproc *rproc, u64 da, size_t len, bool *is_iomem);
> + int (*parse_fw)(struct rproc *rproc, const struct firmware *fw);
> + int (*handle_rsc)(struct rproc *rproc, u32 rsc_type, void *rsc,
> + int offset, int avail);
> + struct resource_table *(*find_loaded_rsc_table)(
> + struct rproc *rproc, const struct firmware *fw);
> + struct resource_table *(*get_loaded_rsc_table)(
> + struct rproc *rproc, size_t *size);
> + int (*load)(struct rproc *rproc, const struct firmware *fw);
> + int (*sanity_check)(struct rproc *rproc, const struct firmware *fw);
> + u64 (*get_boot_addr)(struct rproc *rproc, const struct firmware *fw);
> + unsigned long (*panic)(struct rproc *rproc);
> + void (*coredump)(struct rproc *rproc);
> + };
> +
> +Most of the operations are optional. Currently in the implementation
> +there are no mandatory operations, however from the practical standpoint
> +minimum ops are:
> +
> +* start: this is a pointer to the routine that starts the remote processor
> + device.
> + The routine needs a pointer to the remote processor device structure as a
> + parameter. It returns zero on success or a negative errno code for failure.
> +
> +* stop: with this routine the remote processor device is being stopped.
> +
> + The routine needs a pointer to the remote processor device structure as a
> + parameter. It returns zero on success or a negative errno code for failure.
> +
> +* da_to_va: this is the routine that needs to translate device address to
> + application processor virtual address that it can copy code to.
> +
> + The routine needs a pointer to the remote processor device structure as a
> + parameter. It returns zero on success or a negative errno code for failure.
> +
> + The routine provides the device address it finds in the ELF firmware and asks
> + the driver to convert that to virtual address.
> +
> +All other callbacks are optional in case of ELF provided firmware.
> +
> +* load: this is to load the firmware on to the remote device.
> +
> + The routine needs firmware file that it needs to load on to the remote processor.
> + If the driver overrides this callback then default ELF loader will not get used.
> + Otherwise default framework provided loader gets used.
> +
> + load = rproc_elf_load_segments;
> + parse_fw = rproc_elf_load_rsc_table;
> + find_loaded_rsc_table = rproc_elf_find_loaded_rsc_table;
> + sanity_check = rproc_elf_sanity_check;
> + get_boot_addr = rproc_elf_get_boot_addr;
> +
> +* parse_fw: this routing parses the provided firmware. In case of ELF format,
> + framework provided rproc_elf_load_rsc_table function can be used.
> +
> +* sanity_check: Check the format of the firmware.
> +
> +* coredump: If the driver prefers to manage coredumps independently, it can
> + implement its own coredump handling. However, the framework offers a default
> + implementation for the ELF format by assigning this callback to
> + rproc_coredump, unless the driver has overridden it.
> +
> +* get_boot_addr: In case the bootaddr defined in ELF firmware is different, driver
> + can use this callback to set a different boot address for remote processor to
> + starts its reset vector from.
> +
> +* find_loaded_rsc_table: this routine gets the loaded resource table from the firmware.
> +
> + resource table should have a section named (.resource_table) for the framework
> + to understand and interpret its content. Resource table is a way for remote
> + processor to ask for resources such as memory for dumping and logging. Look
> + at core documentation to know how to create the ELF section for the same.
> +
> +* get_loaded_rsc_table: Driver can customize passing the resource table by overriding
> + this callback. Framework doesn't provide any default implementation for the same.
> +
> +
> +The rproc_report_crash function allows you to report a crash when crash is
> +detected by the driver.
> +
> +::
> +
> + void rproc_report_crash(struct rproc *rproc, enum rproc_crash_type type);
> +
> +To add a subdev corresponding driver can call::
> +
> + void rproc_add_subdev(struct rproc *rproc, struct rproc_subdev *subdev);
> +
> +To remove a subdev, driver can call.
> +
> +::
> +
> + void rproc_remove_subdev(struct rproc *rproc, struct rproc_subdev *subdev);
> +
> +To work with ELF coredump below function can be called::
> +
> + void rproc_coredump_cleanup(struct rproc *rproc);
> + void rproc_coredump(struct rproc *rproc);
> + void rproc_coredump_using_sections(struct rproc *rproc);
> + int rproc_coredump_add_segment(struct rproc *rproc, dma_addr_t da, size_t size);
> + int rproc_coredump_add_custom_segment(struct rproc *rproc,
> + dma_addr_t da, size_t size,
> + void (*dumpfn)(struct rproc *rproc,
> + struct rproc_dump_segment *segment,
> + void *dest, size_t offset,
> + size_t size),
> +
> +Remember that coredump functions provided by the framework only works with ELF format.
> diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst
> index 77bae5e5328b..d2c2b75fade8 100644
> --- a/Documentation/staging/index.rst
> +++ b/Documentation/staging/index.rst
> @@ -9,7 +9,6 @@ Unsorted Documentation
> crc32
> lzo
> magic-number
> - remoteproc
> rpmsg
> speculation
> static-keys
> diff --git a/Documentation/staging/remoteproc.rst b/Documentation/staging/remoteproc.rst
> deleted file mode 100644
> index 348ee7e508ac..000000000000
> --- a/Documentation/staging/remoteproc.rst
> +++ /dev/null
> @@ -1,360 +0,0 @@
> -==========================
> -Remote Processor Framework
> -==========================
> -
> -Introduction
> -============
> -
> -Modern SoCs typically have heterogeneous remote processor devices in asymmetric
> -multiprocessing (AMP) configurations, which may be running different instances
> -of operating system, whether it's Linux or any other flavor of real-time OS.
> -
> -OMAP4, for example, has dual Cortex-A9, dual Cortex-M3 and a C64x+ DSP.
> -In a typical configuration, the dual cortex-A9 is running Linux in a SMP
> -configuration, and each of the other three cores (two M3 cores and a DSP)
> -is running its own instance of RTOS in an AMP configuration.
> -
> -The remoteproc framework allows different platforms/architectures to
> -control (power on, load firmware, power off) those remote processors while
> -abstracting the hardware differences, so the entire driver doesn't need to be
> -duplicated. In addition, this framework also adds rpmsg virtio devices
> -for remote processors that supports this kind of communication. This way,
> -platform-specific remoteproc drivers only need to provide a few low-level
> -handlers, and then all rpmsg drivers will then just work
> -(for more information about the virtio-based rpmsg bus and its drivers,
> -please read Documentation/staging/rpmsg.rst).
> -Registration of other types of virtio devices is now also possible. Firmwares
> -just need to publish what kind of virtio devices do they support, and then
> -remoteproc will add those devices. This makes it possible to reuse the
> -existing virtio drivers with remote processor backends at a minimal development
> -cost.
> -
> -User API
> -========
> -
> -::
> -
> - int rproc_boot(struct rproc *rproc)
> -
> -Boot a remote processor (i.e. load its firmware, power it on, ...).
> -
> -If the remote processor is already powered on, this function immediately
> -returns (successfully).
> -
> -Returns 0 on success, and an appropriate error value otherwise.
> -Note: to use this function you should already have a valid rproc
> -handle. There are several ways to achieve that cleanly (devres, pdata,
> -the way remoteproc_rpmsg.c does this, or, if this becomes prevalent, we
> -might also consider using dev_archdata for this).
> -
> -::
> -
> - int rproc_shutdown(struct rproc *rproc)
> -
> -Power off a remote processor (previously booted with rproc_boot()).
> -In case @rproc is still being used by an additional user(s), then
> -this function will just decrement the power refcount and exit,
> -without really powering off the device.
> -
> -Returns 0 on success, and an appropriate error value otherwise.
> -Every call to rproc_boot() must (eventually) be accompanied by a call
> -to rproc_shutdown(). Calling rproc_shutdown() redundantly is a bug.
> -
> -.. note::
> -
> - we're not decrementing the rproc's refcount, only the power refcount.
> - which means that the @rproc handle stays valid even after
> - rproc_shutdown() returns, and users can still use it with a subsequent
> - rproc_boot(), if needed.
> -
> -::
> -
> - struct rproc *rproc_get_by_phandle(phandle phandle)
> -
> -Find an rproc handle using a device tree phandle. Returns the rproc
> -handle on success, and NULL on failure. This function increments
> -the remote processor's refcount, so always use rproc_put() to
> -decrement it back once rproc isn't needed anymore.
> -
> -Typical usage
> -=============
> -
> -::
> -
> - #include <linux/remoteproc.h>
> -
> - /* in case we were given a valid 'rproc' handle */
> - int dummy_rproc_example(struct rproc *my_rproc)
> - {
> - int ret;
> -
> - /* let's power on and boot our remote processor */
> - ret = rproc_boot(my_rproc);
> - if (ret) {
> - /*
> - * something went wrong. handle it and leave.
> - */
> - }
> -
> - /*
> - * our remote processor is now powered on... give it some work
> - */
> -
> - /* let's shut it down now */
> - rproc_shutdown(my_rproc);
> - }
> -
> -API for implementors
> -====================
> -
> -::
> -
> - struct rproc *rproc_alloc(struct device *dev, const char *name,
> - const struct rproc_ops *ops,
> - const char *firmware, int len)
> -
> -Allocate a new remote processor handle, but don't register
> -it yet. Required parameters are the underlying device, the
> -name of this remote processor, platform-specific ops handlers,
> -the name of the firmware to boot this rproc with, and the
> -length of private data needed by the allocating rproc driver (in bytes).
> -
> -This function should be used by rproc implementations during
> -initialization of the remote processor.
> -
> -After creating an rproc handle using this function, and when ready,
> -implementations should then call rproc_add() to complete
> -the registration of the remote processor.
> -
> -On success, the new rproc is returned, and on failure, NULL.
> -
> -.. note::
> -
> - **never** directly deallocate @rproc, even if it was not registered
> - yet. Instead, when you need to unroll rproc_alloc(), use rproc_free().
> -
> -::
> -
> - void rproc_free(struct rproc *rproc)
> -
> -Free an rproc handle that was allocated by rproc_alloc.
> -
> -This function essentially unrolls rproc_alloc(), by decrementing the
> -rproc's refcount. It doesn't directly free rproc; that would happen
> -only if there are no other references to rproc and its refcount now
> -dropped to zero.
> -
> -::
> -
> - int rproc_add(struct rproc *rproc)
> -
> -Register @rproc with the remoteproc framework, after it has been
> -allocated with rproc_alloc().
> -
> -This is called by the platform-specific rproc implementation, whenever
> -a new remote processor device is probed.
> -
> -Returns 0 on success and an appropriate error code otherwise.
> -Note: this function initiates an asynchronous firmware loading
> -context, which will look for virtio devices supported by the rproc's
> -firmware.
> -
> -If found, those virtio devices will be created and added, so as a result
> -of registering this remote processor, additional virtio drivers might get
> -probed.
> -
> -::
> -
> - int rproc_del(struct rproc *rproc)
> -
> -Unroll rproc_add().
> -
> -This function should be called when the platform specific rproc
> -implementation decides to remove the rproc device. it should
> -_only_ be called if a previous invocation of rproc_add()
> -has completed successfully.
> -
> -After rproc_del() returns, @rproc is still valid, and its
> -last refcount should be decremented by calling rproc_free().
> -
> -Returns 0 on success and -EINVAL if @rproc isn't valid.
> -
> -::
> -
> - void rproc_report_crash(struct rproc *rproc, enum rproc_crash_type type)
> -
> -Report a crash in a remoteproc
> -
> -This function must be called every time a crash is detected by the
> -platform specific rproc implementation. This should not be called from a
> -non-remoteproc driver. This function can be called from atomic/interrupt
> -context.
> -
> -Implementation callbacks
> -========================
> -
> -These callbacks should be provided by platform-specific remoteproc
> -drivers::
> -
> - /**
> - * struct rproc_ops - platform-specific device handlers
> - * @start: power on the device and boot it
> - * @stop: power off the device
> - * @kick: kick a virtqueue (virtqueue id given as a parameter)
> - */
> - struct rproc_ops {
> - int (*start)(struct rproc *rproc);
> - int (*stop)(struct rproc *rproc);
> - void (*kick)(struct rproc *rproc, int vqid);
> - };
> -
> -Every remoteproc implementation should at least provide the ->start and ->stop
> -handlers. If rpmsg/virtio functionality is also desired, then the ->kick handler
> -should be provided as well.
> -
> -The ->start() handler takes an rproc handle and should then power on the
> -device and boot it (use rproc->priv to access platform-specific private data).
> -The boot address, in case needed, can be found in rproc->bootaddr (remoteproc
> -core puts there the ELF entry point).
> -On success, 0 should be returned, and on failure, an appropriate error code.
> -
> -The ->stop() handler takes an rproc handle and powers the device down.
> -On success, 0 is returned, and on failure, an appropriate error code.
> -
> -The ->kick() handler takes an rproc handle, and an index of a virtqueue
> -where new message was placed in. Implementations should interrupt the remote
> -processor and let it know it has pending messages. Notifying remote processors
> -the exact virtqueue index to look in is optional: it is easy (and not
> -too expensive) to go through the existing virtqueues and look for new buffers
> -in the used rings.
> -
> -Binary Firmware Structure
> -=========================
> -
> -At this point remoteproc supports ELF32 and ELF64 firmware binaries. However,
> -it is quite expected that other platforms/devices which we'd want to
> -support with this framework will be based on different binary formats.
> -
> -When those use cases show up, we will have to decouple the binary format
> -from the framework core, so we can support several binary formats without
> -duplicating common code.
> -
> -When the firmware is parsed, its various segments are loaded to memory
> -according to the specified device address (might be a physical address
> -if the remote processor is accessing memory directly).
> -
> -In addition to the standard ELF segments, most remote processors would
> -also include a special section which we call "the resource table".
> -
> -The resource table contains system resources that the remote processor
> -requires before it should be powered on, such as allocation of physically
> -contiguous memory, or iommu mapping of certain on-chip peripherals.
> -Remotecore will only power up the device after all the resource table's
> -requirement are met.
> -
> -In addition to system resources, the resource table may also contain
> -resource entries that publish the existence of supported features
> -or configurations by the remote processor, such as trace buffers and
> -supported virtio devices (and their configurations).
> -
> -The resource table begins with this header::
> -
> - /**
> - * struct resource_table - firmware resource table header
> - * @ver: version number
> - * @num: number of resource entries
> - * @reserved: reserved (must be zero)
> - * @offset: array of offsets pointing at the various resource entries
> - *
> - * The header of the resource table, as expressed by this structure,
> - * contains a version number (should we need to change this format in the
> - * future), the number of available resource entries, and their offsets
> - * in the table.
> - */
> - struct resource_table {
> - u32 ver;
> - u32 num;
> - u32 reserved[2];
> - u32 offset[0];
> - } __packed;
> -
> -Immediately following this header are the resource entries themselves,
> -each of which begins with the following resource entry header::
> -
> - /**
> - * struct fw_rsc_hdr - firmware resource entry header
> - * @type: resource type
> - * @data: resource data
> - *
> - * Every resource entry begins with a 'struct fw_rsc_hdr' header providing
> - * its @type. The content of the entry itself will immediately follow
> - * this header, and it should be parsed according to the resource type.
> - */
> - struct fw_rsc_hdr {
> - u32 type;
> - u8 data[0];
> - } __packed;
> -
> -Some resources entries are mere announcements, where the host is informed
> -of specific remoteproc configuration. Other entries require the host to
> -do something (e.g. allocate a system resource). Sometimes a negotiation
> -is expected, where the firmware requests a resource, and once allocated,
> -the host should provide back its details (e.g. address of an allocated
> -memory region).
> -
> -Here are the various resource types that are currently supported::
> -
> - /**
> - * enum fw_resource_type - types of resource entries
> - *
> - * @RSC_CARVEOUT: request for allocation of a physically contiguous
> - * memory region.
> - * @RSC_DEVMEM: request to iommu_map a memory-based peripheral.
> - * @RSC_TRACE: announces the availability of a trace buffer into which
> - * the remote processor will be writing logs.
> - * @RSC_VDEV: declare support for a virtio device, and serve as its
> - * virtio header.
> - * @RSC_LAST: just keep this one at the end
> - * @RSC_VENDOR_START: start of the vendor specific resource types range
> - * @RSC_VENDOR_END: end of the vendor specific resource types range
> - *
> - * Please note that these values are used as indices to the rproc_handle_rsc
> - * lookup table, so please keep them sane. Moreover, @RSC_LAST is used to
> - * check the validity of an index before the lookup table is accessed, so
> - * please update it as needed.
> - */
> - enum fw_resource_type {
> - RSC_CARVEOUT = 0,
> - RSC_DEVMEM = 1,
> - RSC_TRACE = 2,
> - RSC_VDEV = 3,
> - RSC_LAST = 4,
> - RSC_VENDOR_START = 128,
> - RSC_VENDOR_END = 512,
> - };
> -
> -For more details regarding a specific resource type, please see its
> -dedicated structure in include/linux/remoteproc.h.
> -
> -We also expect that platform-specific resource entries will show up
> -at some point. When that happens, we could easily add a new RSC_PLATFORM
> -type, and hand those resources to the platform-specific rproc driver to handle.
> -
> -Virtio and remoteproc
> -=====================
> -
> -The firmware should provide remoteproc information about virtio devices
> -that it supports, and their configurations: a RSC_VDEV resource entry
> -should specify the virtio device id (as in virtio_ids.h), virtio features,
> -virtio config space, vrings information, etc.
> -
> -When a new remote processor is registered, the remoteproc framework
> -will look for its resource table and will register the virtio devices
> -it supports. A firmware may support any number of virtio devices, and
> -of any type (a single remote processor can also easily support several
> -rpmsg virtio devices this way, if desired).
> -
> -Of course, RSC_VDEV resource entries are only good enough for static
> -allocation of virtio devices. Dynamic allocations will also be made possible
> -using the rpmsg bus (similar to how we already do dynamic allocations of
> -rpmsg channels; read more about it in rpmsg.txt).
> diff --git a/Documentation/staging/rpmsg.rst b/Documentation/staging/rpmsg.rst
> index 3713adaa1608..c1eb5343bf37 100644
> --- a/Documentation/staging/rpmsg.rst
> +++ b/Documentation/staging/rpmsg.rst
> @@ -5,7 +5,7 @@ Remote Processor Messaging (rpmsg) Framework
> .. note::
>
> This document describes the rpmsg bus and how to write rpmsg drivers.
> - To learn how to add rpmsg support for new platforms, check out remoteproc.txt
> + To learn how to add rpmsg support for new platforms, check out remoteproc
> (also a resident of Documentation/).
>
> Introduction
> --
> 2.39.3 (Apple Git-146)
>
>
Hi anish, kernel test robot noticed the following build warnings: [auto build test WARNING on remoteproc/rpmsg-next] [also build test WARNING on remoteproc/rproc-next lwn/docs-next linus/master v6.12-rc3 next-20241015] [If your patch is applied to the wrong git tree, kindly drop us a note. And when submitting patch, we suggest to use '--base' as documented in https://git-scm.com/docs/git-format-patch#_base_tree_information] url: https://github.com/intel-lab-lkp/linux/commits/anish-kumar/remoteproc-Documentation-upgrade-from-staging/20241015-105957 base: https://git.kernel.org/pub/scm/linux/kernel/git/remoteproc/linux.git rpmsg-next patch link: https://lore.kernel.org/r/20241015025831.65232-1-yesanishhere%40gmail.com patch subject: [PATCH] remoteproc: Documentation: upgrade from staging. reproduce: (https://download.01.org/0day-ci/archive/20241016/202410161444.jOKMsoGS-lkp@intel.com/reproduce) If you fix the issue in a separate patch/commit (i.e. not just a new version of the same patch/commit), kindly add following tags | Reported-by: kernel test robot <lkp@intel.com> | Closes: https://lore.kernel.org/oe-kbuild-all/202410161444.jOKMsoGS-lkp@intel.com/ All warnings (new ones prefixed by >>): Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`rt_link<../../networking/netlink_spec/rt_link>` Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`tc<../../networking/netlink_spec/tc>` Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`tc<../../networking/netlink_spec/tc>` Warning: Documentation/devicetree/bindings/regulator/siliconmitus,sm5703-regulator.yaml references a file that doesn't exist: Documentation/devicetree/bindings/mfd/siliconmitus,sm5703.yaml Warning: Documentation/hwmon/g762.rst references a file that doesn't exist: Documentation/devicetree/bindings/hwmon/g762.txt >> Warning: Documentation/remoteproc/rproc-kernel-api.rst references a file that doesn't exist: Documentation/remotproc/remoteproc-api.rst Warning: Documentation/userspace-api/netlink/index.rst references a file that doesn't exist: Documentation/networking/netlink_spec/index.rst Warning: Documentation/userspace-api/netlink/specs.rst references a file that doesn't exist: Documentation/networking/netlink_spec/index.rst Warning: MAINTAINERS references a file that doesn't exist: Documentation/devicetree/bindings/reserved-memory/qcom Warning: MAINTAINERS references a file that doesn't exist: Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt >> Warning: MAINTAINERS references a file that doesn't exist: Documentation/staging/remoteproc.rst Using alabaster theme -- 0-DAY CI Kernel Test Service https://github.com/intel/lkp-tests/wiki
© 2016 - 2024 Red Hat, Inc.