Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

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

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

Documentation/remoteproc.txt

+189 −139
Original line number Original line Diff line number Diff line 
==========================

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,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

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, ...).



Boot a remote processor (i.e. load its firmware, power it on, ...).



If the remote processor is already powered on, this function immediately

If the remote processor is already powered on, this function immediately

returns (successfully).

returns (successfully).



Returns 0 on success, and an appropriate error value otherwise.

Returns 0 on success, and an appropriate error value otherwise.

Note: to use this function you should already have a valid rproc

Note: to use this function you should already have a valid rproc

handle. There are several ways to achieve that cleanly (devres, pdata,

handle. There are several ways to achieve that cleanly (devres, pdata,

the way remoteproc_rpmsg.c does this, or, if this becomes prevalent, we

the way remoteproc_rpmsg.c does this, or, if this becomes prevalent, we

might also consider using dev_archdata for this).

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()).



Power off a remote processor (previously booted with rproc_boot()).

In case @rproc is still being used by an additional user(s), then

In case @rproc is still being used by an additional user(s), then

this function will just decrement the power refcount and exit,

this function will just decrement the power refcount and exit,

without really powering off the device.

without really powering off the device.



Every call to rproc_boot() must (eventually) be accompanied by a call

Every call to rproc_boot() must (eventually) be accompanied by a call

to rproc_shutdown(). Calling rproc_shutdown() redundantly is a bug.

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

  which means that the @rproc handle stays valid even after

  rproc_shutdown() returns, and users can still use it with a subsequent

  rproc_shutdown() returns, and users can still use it with a subsequent

  rproc_boot(), if needed.

  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



Find an rproc handle using a device tree phandle. Returns the rproc

handle on success, and NULL on failure. This function increments

handle on success, and NULL on failure. This function increments

the remote processor's refcount, so always use rproc_put() to

the remote processor's refcount, so always use rproc_put() to

decrement it back once rproc isn't needed anymore.

decrement it back once rproc isn't needed anymore.





3. Typical usage

Typical usage

=============



::





  #include <linux/remoteproc.h>

  #include <linux/remoteproc.h>
@@ -82,12 +103,16 @@ int dummy_rproc_example(struct rproc *my_rproc) 
	rproc_shutdown(my_rproc);

	rproc_shutdown(my_rproc);

  }

  }





4. API for implementors

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



Allocate a new remote processor handle, but don't register

it yet. Required parameters are the underlying device, the

it yet. Required parameters are the underlying device, the

name of this remote processor, platform-specific ops handlers,

name of this remote processor, platform-specific ops handlers,

the name of the firmware to boot this rproc with, and the

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

This function should be used by rproc implementations during

initialization of the remote processor.

initialization of the remote processor.



After creating an rproc handle using this function, and when ready,

After creating an rproc handle using this function, and when ready,

implementations should then call rproc_add() to complete

implementations should then call rproc_add() to complete

the registration of the remote processor.

the registration of the remote processor.



On success, the new rproc is returned, and on failure, NULL.

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().

  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.



Free an rproc handle that was allocated by rproc_alloc.



This function essentially unrolls rproc_alloc(), by decrementing the

This function essentially unrolls rproc_alloc(), by decrementing the

rproc's refcount. It doesn't directly free rproc; that would happen

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

only if there are no other references to rproc and its refcount now

dropped to zero.

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



Register @rproc with the remoteproc framework, after it has been

allocated with rproc_alloc().

allocated with rproc_alloc().



This is called by the platform-specific rproc implementation, whenever

This is called by the platform-specific rproc implementation, whenever

a new remote processor device is probed.

a new remote processor device is probed.



Returns 0 on success and an appropriate error code otherwise.

Returns 0 on success and an appropriate error code otherwise.

Note: this function initiates an asynchronous firmware loading

Note: this function initiates an asynchronous firmware loading

context, which will look for virtio devices supported by the rproc's

context, which will look for virtio devices supported by the rproc's

firmware.

firmware.



If found, those virtio devices will be created and added, so as a result

If found, those virtio devices will be created and added, so as a result

of registering this remote processor, additional virtio drivers might get

of registering this remote processor, additional virtio drivers might get

probed.

probed.





::



  int rproc_del(struct rproc *rproc)

  int rproc_del(struct rproc *rproc)

    - Unroll rproc_add().



Unroll rproc_add().



This function should be called when the platform specific rproc

This function should be called when the platform specific rproc

implementation decides to remove the rproc device. it should

implementation decides to remove the rproc device. it should

_only_ be called if a previous invocation of rproc_add()

_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.

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



Report a crash in a remoteproc



This function must be called every time a crash is detected by the

This function must be called every time a crash is detected by the

platform specific rproc implementation. This should not be called from a

platform specific rproc implementation. This should not be called from a

non-remoteproc driver. This function can be called from atomic/interrupt

non-remoteproc driver. This function can be called from atomic/interrupt

context.

context.





5. Implementation callbacks

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
@@ -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,7 +256,7 @@ 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
@@ -229,7 +278,7 @@ struct resource_table { 
  } __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
@@ -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

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
@@ -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