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.

近年の一般的なSoCは、非対称マルチプロセッサ構成(asymmetric multi processing, AMP)として、heterogeneous remote processor device を有している。これは、Linux あるいはほかのreal-time OSといった異なるoperating systemのインスタンスを動かすことができる。

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.

例えば、OMAP4には、dual Cortex-A9, dia; Cortex-M3としてC64x+ DSPを有している。一般的な構成では、dual cortex-A9 はSMP構成でLinuxを動かし、残りの3つのコア(two M3 cores と DSP)では、AMP構成でそれぞれのRTOSのインスタンスを動かす。

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/rpmsg.txt).

remoteproc frameworkは、ハードウェアの違いを抽象化して、remote processorに対して異なるプラットフォーム/アーキテクチャに対して制御(電源投入、ファームウェア読み込み、電源切断）を、実現するものである。ドライバー全体を複製する必要はありません。更に、このframeworkではまた、この種類の通信をサポートする、remote processorとのrpmsg virtio device を追加します。このように、プラットフォーク特有のremoteproc driverは、わずかなlow-level handlerの提供のみをすればよく、そのあと、全てのrpmsg driverが正しく機能するでしょう（virtio-based rpmsg busとそのドライバに関する更なる情報については、Document/rpmsg.txtを参照してください)

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.

他の種類のvirtio deviceを登録することもまた可能です。Firmwareはそれらがサポートしているvirtio devicesの種類を公開するだけで、remoteprocはそれらのdeviceを追加します。これにより最小の開発コストによって、remote processor backendで既存のvirtio driverを再利用することができます。

User API

int rproc_boot(struct rproc *rproc)

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

remote processorの起動(例えば、firmwareのload, 電源投入)

If the remote processor is already powered on, this function immediately returns (successfully).

remote processorが既に電源投入されている場合、この関数は即座にreturnする（成功として）。

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

成功した場合、戻り値は0であり、そうでない場合には適切なエラー値が入る。

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

注意：この関数を使う場合、有効なrpoc handleを事前に用意する必要がある。それを綺麗に達成するには、いくつかの方法があります。(devres, pdata, このremoteproc_rpmsg.cを使う方法、流行った場合に、dev_archdataの使用を検討する事もできます）

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 this function will just decrement the power refcount and exit, without really powering off the device.

remote processorの電源切断(事前にrpoc_boot()で起動しておいたもの） prpocは既にほかのユーザーによって使われていた場合、この関数はpower refcountを減らして終了し、実際のデバイスの電源切断は行わない。

Every call to rproc_boot() must (eventually) be accompanied by a call to rproc_shutdown(). Calling rproc_shutdown() redundantly is a bug.

全てのrpoc_boot()の呼び出しには、（最終的には）rpoc_shutdown()への呼び出しを伴う必要があります。rpoc_shutdown()の不要な呼び出しはバグです。

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.

rprocのrefcountを減らすのではなく、power refcountのみを減らします。つまり、rpoc handleは、rpoc_shutdown()から戻った時点でも有効であり、ユーザーは必要に応じて後続のrppc_boot()で利用する事ができます。

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.

device tree phandleを使ってrpoc handleを探索します。成功した場合にはrpoc handleが、失敗したときにはNULLが帰ります。この関数はremote processorのrefcountを増化させます。rpocが不要となった場合には、rpoc_put()を使って減少させてください。

Typical usage

  #include <linux/remoteproc.h>

  /* in case we were given a valid 'rproc' handle */
  /* 有効な`rpoc` handleが得られているケースにおいて */
  int dummy_rproc_example(struct rproc *my_rproc)
  {
	int ret;

	/* let's power on and boot our remote processor */
    /* 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
	 */

    /*
     * remote processorは今、電源投入された、仕事を与えてください。
     */

	/* let's shut it down now */
    /* 電源切断 */
	rproc_shutdown(my_rproc);
  }

もともと、Linux Kernelのソースコードの一部なので、GPLv2扱いになる（はずの認識）。

https://www.kernel.org/doc/html/latest/index.html

Licensing documentation

The following describes the license of the Linux kernel source code (GPLv2), how to properly mark the license of individual files in the source tree, as well as links to the full license text.

https://www.kernel.org/doc/html/latest/process/license-rules.html#kernel-licensing