Remote Processor Framework (3/3)

https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/Documentation/remoteproc.txt

# Remote Processor Framework

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

この時点で、remoteprocはELF32とELF64 fitmware binaryをサポートしています。しかし、このフレームワークでサポートしたい他のプラットフォームやデバイスでは、異なるbinary formatに基づいていることが予想されます。

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

これらのユースケースに対しては、framework coreからbinary formatを切り離す必要があるため、共通コードを複製することなくいくつかのbinary format をサポートできます。

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

firmwareをparseしたとき、特有のデバイスのアドレスに従って、様々なsegmentがloadされます（remote processorがmemoryに直接メモリアクセスしている場合には、物理アドレスである可能性もあります）。

> In addition to the standard ELF segments, most remote processors would also include a special section which we call "the resource table".

標準的なELF segmentに加えて、多くのremote processorは"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.

resource tableには、remote processorが電源投入する前に要求するシステムリソースが含まれています。例えば、物理的な連続するメモリ領域の確保や、チップ上のペリフェラルに向けたiommu mapping等。Remotecoreは、resource tableの要求がすべて解決した後にだけ、デバイスの電源を投入します。

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

システムリソースに加えて、resource tableには、remote processorによってサポートされている機能や構成の存在を公開する、resource entryも含まれています。例えば、trace bufferやサポートされているvirtio device(さらにその構成）。

> The resource table begins with this header::

resource tableは、このヘッダから開始されます。


```c
  /**
   * 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
   * 
   * @ver: バージョンナンバー
   * @num: resource entriesの個数
   * @reserved: 予約 (0 にしてください )
   * @offset: 各resource entriesを示すoffsetの配列
   *
   * 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.
   * 
   * この構造体が表現する、resoruce tableのヘッダーには、バージョン情報
   * （将来的にこのフォーマットが変更した場合に必要となる）、有効なresource
   * entriesの個数、そしてtable内でのそれらのoffsetが含まれます。
   * 
   */
  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::

このヘッダーの直後にはリソースエントリー自体が次ぐ来ます、それぞれが次のresource entry headerから開始します。


```c
 /**
   * 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.
   *
   * それぞれのresource entryは、typeが提供する struct fw_rsc_hdr headerから開始します。　
   * entry 自身のcontentsは、このヘッダ―のすぐあとにあります。
   * それは、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).

resource entryは単なるアナウンスのものもあり、hostには特有のremoteproc設定が通知されます。他のエントリーでは、ホストが何かしらをする必要があります（例えば、system resourceの確保）。時として、ネゴシエーションによって、ファームウェアが要求するリソースが予想されます。割り当てられたら、hostはその詳細を返す必要があります（例えば、確保したmemory regionのアドレス等）。

> Here are the various resource types that are currently supported::

現時点でサポートしているresource typesの種別は以下です。

```c
  /**
   * 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
   *
   * @RSC_CARVEOUT:   連続した物理メモリリージョンの獲得の要求
   * @RSC_DEVMEM:     memory-basedペリフェラルのiommu_mapの要求
   * @RSC_TRACE:      remote processorがログを書き込めるtrace bufferが有効である通知
   * @RSC_VDEV:       virtio device有効を宣言し、virtio headerとして提供
   * @RSC_LAST:       最後の位置に配置してください
   * @RSC_VENDOR_START:	ベンダー特有のresource type範囲の開始位置
   * @RSC_VENDOR_END:	ベンダー特有のresource type範囲の終了位置
   *
   * 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.
   *
   * これらの値が、rproc_handle_rsc loopup tableへのindexとして利用される
   * ことに注意してください。そして、それが正しくあるようにしてください。
   * また、RSC_LASTは、lookup tableへアクセスする前にindexの有効性を確認
   * するために利用されます、必要に応じて更新してください。
   *
   */
  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.

特有のresource typeに関する詳細については、 include/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.

また、platform固有のresource entriesがいつか表示されることも期待しています。 その場合、簡単に新しいRSC_PLATFORMタイプを追加し、それらのリソースをplatform固有固有のrprocドライバに渡して処理することができます。

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

firmwareは、remoteprocに、サポートしているvirtio deviceに関する情報と、それらの設定について提供をします。RSC_VDEV resource entryは、virtio device id(virtio_ids.h）、virtio features, virtio config space, vrings informationなどを指定する必要があります。

> When a new remote processor is registered, the remoteproc framework will look for its resource table and will register the virtio devices it supports.

新しいremote processorが登録されたら、remoteproc frameworkはそのresource tableを検索し、サポートしているvirtio deviceを登録します。

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

firmwareは、いくつかのvirtio deviceと任意のタイプをサポートします。（単一のremote processorが、必要に応じて、この方法で複数のrpmsg virtio deviceを容易にサポートすることもできます）。

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

もちろん、RSC_VDEV resource entryは、ただvirtio deviceの静的な割り当てのみでも十分です。動的な割り当てによって、rpmsg busを用いることもできます。(rpmsg channelの動的割り当てをすでに行っているのと同じです。rpmsg.txtを確認してください）。

---
もともと、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