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.
At this point, remoteproc supports ELF32 and ELF64 fitmware binary. However, other platforms and devices that we want to support with this framework are expected to be based on different binary formats.
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.
For these use cases, you need to separate the binary format from the framework core, so you can support several binary formats without duplicating common code.
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).
When parsing the firmware, various segments are loaded according to the unique device address (it could be a physical address if the remote processor has direct memory access to memory).
In addition to the standard ELF segments, most remote processors would also include a special section which we call "the resource table".
In addition to the standard ELF segment, many remote processors also include a special section called "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.
The resource table contains the system resources that the remote processor requests before powering it up. For example, securing a physically continuous memory area, iommu mapping for peripherals on the chip, etc. Remotecore powers on the device only after all resource table requests have been resolved.
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).
In addition to system resources, the resource table also contains a resource entry that exposes the existence of features and configurations supported by the remote processor. For example, trace buffer and supported virtio devices (and their configurations).
The resource table begins with this header::
The resource table starts from this header.
/**
* 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:Version number
* @num:Number of resource entries
* @reserved:Reservation(Please set to 0)
* @offset:An array of offsets showing each resource entries
*
* 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.
*
*The header of the resoruce table represented by this structure contains version information.
*A valid resource (required if this format changes in the future)
*It contains the number of entries, and their offsets in the table.
*
*/
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::
Immediately after this header comes the resource entry itself, each starting with the next resource entry header.
/**
* 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.
*
*Each resource entry is a struct fw provided by type_rsc_Start with the hdr header.
*The contents of the entry itself are immediately after this header.
*It is interpreted based on the 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).
Some resource entries are just announcements, and the host is notified of the specific remoteproc settings. For other entries, the host needs to do something (for example, reserve system resources). At times, negotiations anticipate the resources required by the firmware. Once assigned, the host must return its details (for example, the reserved memory region address).
Here are the various resource types that are currently supported::
The currently supported resource types are:
/**
* 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:Request to acquire contiguous physical memory regions
* @RSC_DEVMEM: memory-based peripheral iommu_map request
* @RSC_TRACE:Notification that trace buffer is enabled so that remote processor can write logs
* @RSC_VDEV:declare virtio device valid and provide as virtio header
* @RSC_LAST:Please place in the last position
* @RSC_VENDOR_START:Vendor-specific resource type Range start location
* @RSC_VENDOR_END:End position of vendor-specific resource type range
*
* 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.
*
*These values are rproc_handle_Used as index in rsc lookup table
*Please note in particular. And make sure it is correct.
*Also, RSC_LAST checks the validity of the index before accessing the lookup table
*It will be used to help you, please update as needed.
*
*/
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.
For more information on specific resource types, see Structures in 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.
We also expect to see platform-specific resource entries someday. In that case, you can easily add new RSC_PLATFORM types and pass those resources to the platform-specific rproc driver for processing.
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.
The firmware provides remoteproc with information about the virtio devices it supports and their settings. The RSC_VDEV resource entry must specify virtio device id (virtio_ids.h), virtio features, virtio config space, vrings information, and so on.
When a new remote processor is registered, the remoteproc framework will look for its resource table and will register the virtio devices it supports.
When a new remote processor is registered, the remoteproc framework looks up its resource table and registers the supporting virtio devices.
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).
The firmware supports several virtio devices and any type. (A single remote processor can easily support multiple rpmsg virtio devices in this way, if desired).
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).
Of course, the RSC_VDEV resource entry just needs to be statically assigned to the virtio device. You can also use the rpmsg bus with dynamic allocation. (It's the same as having already done the dynamic allocation of the rpmsg channel. Check rpmsg.txt).
Originally, it is a part of the Linux Kernel source code, so it will be treated as GPLv2 (recognition that it should be).
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