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: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>zero-colors
Mauro Carvalho Chehab
Jonathan Corbet
parent
ce0f95a501
commit
620b470bb4
|
|
@ -1,6 +1,9 @@
|
|||
==========================
|
||||
Remote Processor Framework
|
||||
==========================
|
||||
|
||||
1. Introduction
|
||||
Introduction
|
||||
============
|
||||
|
||||
Modern SoCs typically have heterogeneous remote processor devices in asymmetric
|
||||
multiprocessing (AMP) configurations, which may be running different instances
|
||||
|
|
@ -26,38 +29,56 @@ remoteproc will add those devices. This makes it possible to reuse the
|
|||
existing virtio drivers with remote processor backends at a minimal development
|
||||
cost.
|
||||
|
||||
2. User API
|
||||
User API
|
||||
========
|
||||
|
||||
::
|
||||
|
||||
int rproc_boot(struct rproc *rproc)
|
||||
- Boot a remote processor (i.e. load its firmware, power it on, ...).
|
||||
|
||||
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).
|
||||
|
||||
::
|
||||
|
||||
void rproc_shutdown(struct rproc *rproc)
|
||||
- Power off a remote processor (previously booted with rproc_boot()).
|
||||
|
||||
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.
|
||||
|
||||
Every call to rproc_boot() must (eventually) be accompanied by a call
|
||||
to rproc_shutdown(). Calling rproc_shutdown() redundantly is a bug.
|
||||
Notes:
|
||||
- we're not decrementing the rproc's refcount, only the power refcount.
|
||||
|
||||
.. 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
|
||||
|
||||
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
|
||||
Typical usage
|
||||
=============
|
||||
|
||||
::
|
||||
|
||||
#include <linux/remoteproc.h>
|
||||
|
||||
|
|
@ -82,12 +103,16 @@ int dummy_rproc_example(struct rproc *my_rproc)
|
|||
rproc_shutdown(my_rproc);
|
||||
}
|
||||
|
||||
4. API for implementors
|
||||
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
|
||||
|
||||
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
|
||||
|
|
@ -95,36 +120,54 @@ int dummy_rproc_example(struct rproc *my_rproc)
|
|||
|
||||
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
|
||||
.. 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.
|
||||
|
||||
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
|
||||
|
||||
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().
|
||||
|
||||
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()
|
||||
|
|
@ -135,17 +178,22 @@ int dummy_rproc_example(struct rproc *my_rproc)
|
|||
|
||||
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
|
||||
|
||||
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
|
||||
Implementation callbacks
|
||||
========================
|
||||
|
||||
These callbacks should be provided by platform-specific remoteproc
|
||||
drivers:
|
||||
drivers::
|
||||
|
||||
/**
|
||||
* struct rproc_ops - platform-specific device handlers
|
||||
|
|
@ -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
|
||||
in the used rings.
|
||||
|
||||
6. Binary Firmware Structure
|
||||
Binary Firmware Structure
|
||||
=========================
|
||||
|
||||
At this point remoteproc only supports ELF32 firmware binaries. However,
|
||||
it is quite expected that other platforms/devices which we'd want to
|
||||
|
|
@ -207,7 +256,7 @@ 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:
|
||||
The resource table begins with this header::
|
||||
|
||||
/**
|
||||
* struct resource_table - firmware resource table header
|
||||
|
|
@ -229,7 +278,7 @@ struct resource_table {
|
|||
} __packed;
|
||||
|
||||
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
|
||||
|
|
@ -252,7 +301,7 @@ 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:
|
||||
Here are the various resource types that are currently supported::
|
||||
|
||||
/**
|
||||
* enum fw_resource_type - types of resource entries
|
||||
|
|
@ -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
|
||||
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
|
||||
that it supports, and their configurations: a RSC_VDEV resource entry
|
||||
|
|
|
|||
Loading…
Reference in New Issue