Commit 620b470b authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet

remoteproc.txt: standardize document format

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- mark document and section titles;
- adjust identation;
- mark literal blocks
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent ce0f95a5
==========================
Remote Processor Framework Remote Processor Framework
==========================
1. Introduction Introduction
============
Modern SoCs typically have heterogeneous remote processor devices in asymmetric Modern SoCs typically have heterogeneous remote processor devices in asymmetric
multiprocessing (AMP) configurations, which may be running different instances multiprocessing (AMP) configurations, which may be running different instances
...@@ -26,44 +29,62 @@ remoteproc will add those devices. This makes it possible to reuse the ...@@ -26,44 +29,62 @@ remoteproc will add those devices. This makes it possible to reuse the
existing virtio drivers with remote processor backends at a minimal development existing virtio drivers with remote processor backends at a minimal development
cost. cost.
2. User API User API
========
::
int rproc_boot(struct rproc *rproc) 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 Boot a remote processor (i.e. load its firmware, power it on, ...).
returns (successfully).
Returns 0 on success, and an appropriate error value otherwise. If the remote processor is already powered on, this function immediately
Note: to use this function you should already have a valid rproc returns (successfully).
handle. There are several ways to achieve that cleanly (devres, pdata,
the way remoteproc_rpmsg.c does this, or, if this becomes prevalent, we Returns 0 on success, and an appropriate error value otherwise.
might also consider using dev_archdata for this). 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).
::
void rproc_shutdown(struct rproc *rproc) void 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 Power off a remote processor (previously booted with rproc_boot()).
this function will just decrement the power refcount and exit, In case @rproc is still being used by an additional user(s), then
without really powering off the device. this function will just decrement the power refcount and exit,
Every call to rproc_boot() must (eventually) be accompanied by a call without really powering off the device.
to rproc_shutdown(). Calling rproc_shutdown() redundantly is a bug.
Notes: Every call to rproc_boot() must (eventually) be accompanied by a call
- we're not decrementing the rproc's refcount, only the power refcount. to rproc_shutdown(). Calling rproc_shutdown() redundantly is a bug.
which means that the @rproc handle stays valid even after
rproc_shutdown() returns, and users can still use it with a subsequent .. note::
rproc_boot(), if needed.
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) 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.
3. Typical usage 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 */ #include <linux/remoteproc.h>
int dummy_rproc_example(struct rproc *my_rproc)
{ /* in case we were given a valid 'rproc' handle */
int dummy_rproc_example(struct rproc *my_rproc)
{
int ret; int ret;
/* let's power on and boot our remote processor */ /* let's power on and boot our remote processor */
...@@ -80,84 +101,111 @@ int dummy_rproc_example(struct rproc *my_rproc) ...@@ -80,84 +101,111 @@ int dummy_rproc_example(struct rproc *my_rproc)
/* let's shut it down now */ /* let's shut it down now */
rproc_shutdown(my_rproc); rproc_shutdown(my_rproc);
} }
API for implementors
====================
4. API for implementors ::
struct rproc *rproc_alloc(struct device *dev, const char *name, struct rproc *rproc_alloc(struct device *dev, const char *name,
const struct rproc_ops *ops, const struct rproc_ops *ops,
const char *firmware, int len) const char *firmware, int len)
- Allocate a new remote processor handle, but don't register
it yet. Required parameters are the underlying device, the Allocate a new remote processor handle, but don't register
name of this remote processor, platform-specific ops handlers, it yet. Required parameters are the underlying device, the
the name of the firmware to boot this rproc with, and the name of this remote processor, platform-specific ops handlers,
length of private data needed by the allocating rproc driver (in bytes). 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. This function should be used by rproc implementations during
After creating an rproc handle using this function, and when ready, initialization of the remote processor.
implementations should then call rproc_add() to complete
the registration of the remote processor. After creating an rproc handle using this function, and when ready,
On success, the new rproc is returned, and on failure, NULL. implementations should then call rproc_add() to complete
the registration of the remote processor.
Note: _never_ directly deallocate @rproc, even if it was not registered
yet. Instead, when you need to unroll rproc_alloc(), use rproc_free(). 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) 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 Free an rproc handle that was allocated by rproc_alloc.
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 This function essentially unrolls rproc_alloc(), by decrementing the
dropped to zero. 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) int rproc_add(struct rproc *rproc)
- Register @rproc with the remoteproc framework, after it has been
allocated with rproc_alloc(). Register @rproc with the remoteproc framework, after it has been
This is called by the platform-specific rproc implementation, whenever allocated with rproc_alloc().
a new remote processor device is probed.
Returns 0 on success and an appropriate error code otherwise. This is called by the platform-specific rproc implementation, whenever
Note: this function initiates an asynchronous firmware loading a new remote processor device is probed.
context, which will look for virtio devices supported by the rproc's
firmware. Returns 0 on success and an appropriate error code otherwise.
If found, those virtio devices will be created and added, so as a result Note: this function initiates an asynchronous firmware loading
of registering this remote processor, additional virtio drivers might get context, which will look for virtio devices supported by the rproc's
probed. 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) 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 Unroll rproc_add().
last refcount should be decremented by calling rproc_free().
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.
Returns 0 on success and -EINVAL if @rproc isn't valid. 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) 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.
5. Implementation callbacks 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 These callbacks should be provided by platform-specific remoteproc
drivers: drivers::
/** /**
* struct rproc_ops - platform-specific device handlers * struct rproc_ops - platform-specific device handlers
* @start: power on the device and boot it * @start: power on the device and boot it
* @stop: power off the device * @stop: power off the device
* @kick: kick a virtqueue (virtqueue id given as a parameter) * @kick: kick a virtqueue (virtqueue id given as a parameter)
*/ */
struct rproc_ops { struct rproc_ops {
int (*start)(struct rproc *rproc); int (*start)(struct rproc *rproc);
int (*stop)(struct rproc *rproc); int (*stop)(struct rproc *rproc);
void (*kick)(struct rproc *rproc, int vqid); void (*kick)(struct rproc *rproc, int vqid);
}; };
Every remoteproc implementation should at least provide the ->start and ->stop Every remoteproc implementation should at least provide the ->start and ->stop
handlers. If rpmsg/virtio functionality is also desired, then the ->kick handler handlers. If rpmsg/virtio functionality is also desired, then the ->kick handler
...@@ -179,7 +227,8 @@ the exact virtqueue index to look in is optional: it is easy (and not ...@@ -179,7 +227,8 @@ 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 too expensive) to go through the existing virtqueues and look for new buffers
in the used rings. in the used rings.
6. Binary Firmware Structure Binary Firmware Structure
=========================
At this point remoteproc only supports ELF32 firmware binaries. However, At this point remoteproc only supports ELF32 firmware binaries. However,
it is quite expected that other platforms/devices which we'd want to it is quite expected that other platforms/devices which we'd want to
...@@ -207,43 +256,43 @@ resource entries that publish the existence of supported features ...@@ -207,43 +256,43 @@ resource entries that publish the existence of supported features
or configurations by the remote processor, such as trace buffers and or configurations by the remote processor, such as trace buffers and
supported virtio devices (and their configurations). supported virtio devices (and their configurations).
The resource table begins with this header: The resource table begins with this header::
/** /**
* struct resource_table - firmware resource table header * struct resource_table - firmware resource table header
* @ver: version number * @ver: version number
* @num: number of resource entries * @num: number of resource entries
* @reserved: reserved (must be zero) * @reserved: reserved (must be zero)
* @offset: array of offsets pointing at the various resource entries * @offset: array of offsets pointing at the various resource entries
* *
* The header of the resource table, as expressed by this structure, * The header of the resource table, as expressed by this structure,
* contains a version number (should we need to change this format in the * contains a version number (should we need to change this format in the
* future), the number of available resource entries, and their offsets * future), the number of available resource entries, and their offsets
* in the table. * in the table.
*/ */
struct resource_table { struct resource_table {
u32 ver; u32 ver;
u32 num; u32 num;
u32 reserved[2]; u32 reserved[2];
u32 offset[0]; u32 offset[0];
} __packed; } __packed;
Immediately following this header are the resource entries themselves, Immediately following this header are the resource entries themselves,
each of which begins with the following resource entry header: each of which begins with the following resource entry header::
/** /**
* struct fw_rsc_hdr - firmware resource entry header * struct fw_rsc_hdr - firmware resource entry header
* @type: resource type * @type: resource type
* @data: resource data * @data: resource data
* *
* Every resource entry begins with a 'struct fw_rsc_hdr' header providing * Every resource entry begins with a 'struct fw_rsc_hdr' header providing
* its @type. The content of the entry itself will immediately follow * its @type. The content of the entry itself will immediately follow
* this header, and it should be parsed according to the resource type. * this header, and it should be parsed according to the resource type.
*/ */
struct fw_rsc_hdr { struct fw_rsc_hdr {
u32 type; u32 type;
u8 data[0]; u8 data[0];
} __packed; } __packed;
Some resources entries are mere announcements, where the host is informed Some resources entries are mere announcements, where the host is informed
of specific remoteproc configuration. Other entries require the host to of specific remoteproc configuration. Other entries require the host to
...@@ -252,32 +301,32 @@ is expected, where the firmware requests a resource, and once allocated, ...@@ -252,32 +301,32 @@ is expected, where the firmware requests a resource, and once allocated,
the host should provide back its details (e.g. address of an allocated the host should provide back its details (e.g. address of an allocated
memory region). memory region).
Here are the various resource types that are currently supported: Here are the various resource types that are currently supported::
/** /**
* enum fw_resource_type - types of resource entries * enum fw_resource_type - types of resource entries
* *
* @RSC_CARVEOUT: request for allocation of a physically contiguous * @RSC_CARVEOUT: request for allocation of a physically contiguous
* memory region. * memory region.
* @RSC_DEVMEM: request to iommu_map a memory-based peripheral. * @RSC_DEVMEM: request to iommu_map a memory-based peripheral.
* @RSC_TRACE: announces the availability of a trace buffer into which * @RSC_TRACE: announces the availability of a trace buffer into which
* the remote processor will be writing logs. * the remote processor will be writing logs.
* @RSC_VDEV: declare support for a virtio device, and serve as its * @RSC_VDEV: declare support for a virtio device, and serve as its
* virtio header. * virtio header.
* @RSC_LAST: just keep this one at the end * @RSC_LAST: just keep this one at the end
* *
* Please note that these values are used as indices to the rproc_handle_rsc * 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 * 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 * check the validity of an index before the lookup table is accessed, so
* please update it as needed. * please update it as needed.
*/ */
enum fw_resource_type { enum fw_resource_type {
RSC_CARVEOUT = 0, RSC_CARVEOUT = 0,
RSC_DEVMEM = 1, RSC_DEVMEM = 1,
RSC_TRACE = 2, RSC_TRACE = 2,
RSC_VDEV = 3, RSC_VDEV = 3,
RSC_LAST = 4, RSC_LAST = 4,
}; };
For more details regarding a specific resource type, please see its For more details regarding a specific resource type, please see its
dedicated structure in include/linux/remoteproc.h. dedicated structure in include/linux/remoteproc.h.
...@@ -286,7 +335,8 @@ We also expect that platform-specific resource entries will show up ...@@ -286,7 +335,8 @@ 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 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. type, and hand those resources to the platform-specific rproc driver to handle.
7. Virtio and remoteproc Virtio and remoteproc
=====================
The firmware should provide remoteproc information about virtio devices The firmware should provide remoteproc information about virtio devices
that it supports, and their configurations: a RSC_VDEV resource entry that it supports, and their configurations: a RSC_VDEV resource entry
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment