Resource Table
Overview
The resource table is a key part of resource assignment of remoteproc life cycle management.
The table consists of a header detailing a version, number of resource entries and an array pointing at the offset location of each entry. Directly following the header are the resource entries themselves, each of which has a 32 bit type. These in remote context will likely be memory carveouts for locations of parts of the remote system and virtio device definitions.
Item |
Description |
|---|---|
ver |
RemoteProc version number |
num |
Number of resource entries following the header |
reserved |
Unused but should be set to zero until used |
offset |
Array of values pointing to the offset location of each resource entry |
resources |
Structures which define each of the resource entries (up to num count), at given offset, with each starting with a type (fw_resource_type) so the parser can correctly extract the information. |
The resource table is effectively a list of resource definitions, with each entry detailed by the corresponding resource structure, and the Remoteproc framework is responsible for configuring the relevant drivers and/or bare metal hardware.
The possible resource types are defined in the Remoteproc Header and detailed in the Resource Types section below.
Compatibility with Linux kernel
With Linux being a key full stack operating system in the embedded devices space, the resource table should maintain compatibility with that of Linux Remoteproc.
Evolution should be done in cooperation with Linux remoteproc community.
Related documentation can be found under the Linux kernel’s remoteproc documentation: Binary Firmware Structure.
Resource Types
Each of the resources in the Resource Table is defined by a type (fw_resource_type) and its corresponding structure.
-
enum fw_resource_type
Types of resource entries.
For more details regarding a specific resource type, please see its dedicated structure below.
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.
Values:
-
enumerator RSC_CARVEOUT
carveout resource
Request for allocation of a physically contiguous memory region.
-
enumerator RSC_DEVMEM
device memory resource
Request to iommu_map a memory-based peripheral.
-
enumerator RSC_TRACE
trace resource
Announces the availability of a trace buffer into which the remote remoteproc will be writing logs.
-
enumerator RSC_VDEV
virtio device resource
Declare support for a virtio device, and serve as its virtio header.
-
enumerator RSC_LAST
end of the generic resources
-
enumerator RSC_VENDOR_START
Start of the vendor specific resource types range.
-
enumerator RSC_VENDOR_END
End of the vendor specific resource types range.
-
enumerator RSC_CARVEOUT
Resource Structure Definitions
The following structures correspond to each of the Resource Types (fw_resource_type).
-
struct fw_rsc_carveout
Resource table physically contiguous memory request entry.
This resource entry requests the host to allocate a physically contiguous memory region.
These request entries should precede other firmware resource entries, as other entries might request placing other data objects inside these memory regions (e.g. data/code segments, trace resource entries, …).
Allocating memory this way helps utilizing the reserved physical memory (e.g. CMA) more efficiently, and also minimizes the number of TLB entries needed to map it (in case rproc is using an IOMMU). Reducing the TLB pressure is important; it may have a substantial impact on performance.
If the firmware is compiled with static addresses, then da should specify the expected device address of this memory region. If da is set to FW_RSC_ADDR_ANY, then the host will dynamically allocate it, and then overwrite da with the dynamically allocated address.
We will always use da to negotiate the device addresses, even if it isn’t using an IOMMU. In that case, though, it will obviously contain physical addresses.
Some remote remoteprocs need to know the allocated physical address even if they do use an IOMMU. This is needed, e.g., if they control hardware accelerators which access the physical memory directly (this is the case with OMAP4 for instance). In that case, the host will overwrite pa with the dynamically allocated physical address. Generally we don’t want to expose physical addresses if we don’t have to (remote remoteprocs are generally not trusted), so we might want to change this to happen only when explicitly required by the hardware.
-
struct fw_rsc_devmem
Resource table IOMMU mapping request entry.
This resource entry requests the host to IOMMU map a physically contiguous memory region. This is needed in case the remote remoteproc requires access to certain memory-based peripherals; never use it to access regular memory.
This is obviously only needed if the remote remoteproc is accessing memory via an IOMMU.
Note: at this point we just “trust” those devmem entries to contain valid physical addresses, but this isn’t safe and will be changed: eventually we want remoteproc implementations to provide us ranges of physical addresses the firmware is allowed to request, and not allow firmwares to request access to physical addresses that are outside those ranges.
-
struct fw_rsc_trace
Resource table trace buffer declaration entry.
This resource entry provides the host information about a trace buffer into which the remote remoteproc will write log messages.
After booting the remote remoteproc, the trace buffers are exposed to the user via debugfs entries (called trace0, trace1, etc..).
-
struct fw_rsc_vdev
Resource table virtio device entry.
This resource is a virtio device header: it provides information about the vdev, and is then used by the host and its peer remote remoteprocs to negotiate and share certain virtio properties.
By providing this resource entry, the firmware essentially asks remoteproc to statically allocate a vdev upon registration of the rproc (dynamic vdev allocation is not yet supported).
Note: unlike virtualization systems, the term ‘host’ here means the Linux side which is running remoteproc to control the remote remoteprocs. We use the name ‘gfeatures’ to comply with virtio’s terms, though there isn’t really any virtualized guest OS here: it’s the host which is responsible for negotiating the final features.
Note: immediately following this structure is the virtio config space for this vdev (which is specific to the vdev; for more info, read the virtio spec).
In addition to the predefined Resource Types vendors can define their own with types between RSC_VENDOR_START and RSC_VENDOR_END.
-
struct fw_rsc_vendor
Resource table remote processor vendor specific entry.
This resource entry tells the host the vendor specific resource required by the remote.
These request entries should precede other shared resource entries such as vdevs, vrings.