From 2ddf00d082533bcd2ed9903006961279bb87d3ea Mon Sep 17 00:00:00 2001 From: Tammy Leino Date: Thu, 5 Oct 2023 09:54:19 -0500 Subject: [PATCH] Doxygen updates for data structures Improved doxygen formatting and consistency for data structures. Signed-off-by: Tammy Leino --- Doxyfile | 2 +- lib/include/openamp/remoteproc.h | 327 ++++++++++-------- lib/include/openamp/remoteproc_loader.h | 43 +-- lib/include/openamp/remoteproc_virtio.h | 21 +- lib/include/openamp/rpmsg.h | 86 +++-- lib/include/openamp/rpmsg_rpc_client_server.h | 63 ++-- lib/include/openamp/rpmsg_virtio.h | 56 +-- lib/include/openamp/virtio.h | 56 +-- lib/include/openamp/virtio_mmio.h | 39 ++- lib/include/openamp/virtio_ring.h | 67 +++- lib/rpmsg/rpmsg_internal.h | 32 +- 11 files changed, 470 insertions(+), 322 deletions(-) diff --git a/Doxyfile b/Doxyfile index 2d1eefb48..aea772144 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1144,7 +1144,7 @@ FORTRAN_COMMENT_AFTER = 72 # also VERBATIM_HEADERS is set to NO. # The default value is: NO. -SOURCE_BROWSER = YES +SOURCE_BROWSER = NO # Setting the INLINE_SOURCES tag to YES will include the body of functions, # classes and enums directly into the documentation. diff --git a/lib/include/openamp/remoteproc.h b/lib/include/openamp/remoteproc.h index 1c5d240af..23f917861 100644 --- a/lib/include/openamp/remoteproc.h +++ b/lib/include/openamp/remoteproc.h @@ -25,19 +25,15 @@ extern "C" { #define RPROC_MAX_NAME_LEN 32 /** - * 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 + * @brief Resource table header * * A resource table is essentially a list of system resources required * by the remote remoteproc. It may also include configuration entries. * If needed, the remote remoteproc firmware should contain this table * as a dedicated ".resource_table" ELF section. * - * Some resources entries are mere announcements, where the host is informed - * of specific remoteproc configuration. Other entries require the host to + * Some resource entries are mere announcements, where the host is informed + * of specific remoteproc configurations. 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 @@ -49,28 +45,36 @@ extern "C" { * in the table. * * Immediately following this header are the resource entries themselves, - * each of which begins with a resource entry header (as described below). + * each of which begins with a resource entry header. */ METAL_PACKED_BEGIN struct resource_table { + /** Version number */ uint32_t ver; + + /** Number of resource entries */ uint32_t num; + + /** Reserved (must be zero) */ uint32_t reserved[2]; + + /** Array of offsets pointing at the various resource entries */ uint32_t offset[0]; } METAL_PACKED_END; /** - * struct fw_rsc_hdr - firmware resource entry header - * @type: resource type - * @data: resource data + * @brief Resource table entry header * - * Every resource entry begins with a 'struct fw_rsc_hdr' header providing - * its @type. The content of the entry itself will immediately follow + * Every resource entry begins with this firmware resource header providing + * its \ref type. The content of the entry itself will immediately follow * this header, and it should be parsed according to the resource type. */ METAL_PACKED_BEGIN struct fw_rsc_hdr { + /** Resource type matching the type field of the structure in \ref data */ uint32_t type; + + /** Resource data */ uint8_t data[0]; } METAL_PACKED_END; @@ -110,13 +114,7 @@ enum fw_resource_type { #define FW_RSC_U32_ADDR_ANY 0xFFFFFFFFUL /** - * struct fw_rsc_carveout - physically contiguous memory request - * @da: device address - * @pa: physical address - * @len: length (in bytes) - * @flags: iommu protection flags - * @reserved: reserved (must be zero) - * @name: human-readable name of the requested memory region + * @brief Resource table physically contiguous memory request entry * * This resource entry requests the host to allocate a physically contiguous * memory region. @@ -127,64 +125,61 @@ enum fw_resource_type { * * 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 + * 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 + * If the firmware is compiled with static addresses, then \ref da should specify + * the expected device address of this memory region. If \ref da is set to * FW_RSC_ADDR_ANY, then the host will dynamically allocate it, and then - * overwrite @da with the dynamically allocated address. + * overwrite \ref 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 + * We will always use \ref 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 needs to know the allocated physical address - * even if they do use an iommu. This is needed, e.g., if they control + * 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. + * overwrite \ref 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. - * - * @flags is used to provide IOMMU protection flags, and @name should - * (optionally) contain a human readable name of this carveout region - * (mainly for debugging purposes). */ METAL_PACKED_BEGIN struct fw_rsc_carveout { + /** Resource carveout has type 0 */ uint32_t type; + + /** Device address */ uint32_t da; + + /** Physical address */ uint32_t pa; + + /** Length in bytes */ uint32_t len; + + /** IOMMU protection flags */ uint32_t flags; + + /** Reserved (must be zero) */ uint32_t reserved; + + /** Optional human-readable name of the requested memory region used for debugging */ uint8_t name[RPROC_MAX_NAME_LEN]; } METAL_PACKED_END; /** - * struct fw_rsc_devmem - iommu mapping request - * @da: device address - * @pa: physical address - * @len: length (in bytes) - * @flags: iommu protection flags - * @reserved: reserved (must be zero) - * @name: human-readable name of the requested region to be mapped + * @brief Resource table IOMMU mapping request entry * - * This resource entry requests the host to iommu map a physically contiguous + * 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. - * - * @da should specify the required device address, @pa should specify - * the physical address we want to map, @len should specify the size of - * the mapping and @flags is the IOMMU protection flags. As always, @name may - * (optionally) contain a human readable name of this mapping (mainly for - * debugging purposes). + * 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 @@ -194,81 +189,89 @@ struct fw_rsc_carveout { */ METAL_PACKED_BEGIN struct fw_rsc_devmem { + /** IOMMU mapping request has type 1 */ uint32_t type; + + /** Device address */ uint32_t da; + + /** Physical address to map */ uint32_t pa; + + /** Length of the mapping in bytes */ uint32_t len; + + /** IOMMU protection flags */ uint32_t flags; + + /** Reserved (must be zero) */ uint32_t reserved; + + /** Optional human-readable name of the requested memory region used for debugging */ uint8_t name[RPROC_MAX_NAME_LEN]; } METAL_PACKED_END; /** - * struct fw_rsc_trace - trace buffer declaration - * @da: device address - * @len: length (in bytes) - * @reserved: reserved (must be zero) - * @name: human-readable name of the trace buffer + * @brief 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. * - * @da specifies the device address of the buffer, @len specifies - * its size, and @name may contain a human readable name of the trace buffer. - * * After booting the remote remoteproc, the trace buffers are exposed to the * user via debugfs entries (called trace0, trace1, etc..). */ METAL_PACKED_BEGIN struct fw_rsc_trace { + /** Trace buffer entry has type 2 */ uint32_t type; + + /** Device address of the buffer */ uint32_t da; + + /** Length of the buffer in bytes */ uint32_t len; + + /** Reserved (must be zero) */ uint32_t reserved; + + /** Optional human-readable name of the requested memory region used for debugging */ uint8_t name[RPROC_MAX_NAME_LEN]; } METAL_PACKED_END; /** - * struct fw_rsc_vdev_vring - vring descriptor entry - * @da: device address - * @align: the alignment between the consumer and producer parts of the vring - * @num: num of buffers supported by this vring (must be power of two) - * @notifyid is a unique rproc-wide notify index for this vring. This notify - * index is used when kicking a remote remoteproc, to let it know that this - * vring is triggered. - * @reserved: reserved (must be zero) + * @brief Resource table vring descriptor entry * * This descriptor is not a resource entry by itself; it is part of the - * vdev resource type (see below). - * - * Note that @da should either contain the device address where - * the remote remoteproc is expecting the vring, or indicate that - * dynamically allocation of the vring's device address is supported. + * \ref fw_rsc_vdev resource type. */ METAL_PACKED_BEGIN struct fw_rsc_vdev_vring { + /** + * The device address where the remoteproc is expecting the vring, or + * FW_RSC_U32_ADDR_ANY/FW_RSC_U64_ADDR_ANY to indicate that dynamic + * allocation of the vring's device address is supported + */ uint32_t da; + + /** The alignment between the consumer and producer parts of the vring */ uint32_t align; + + /** Number of buffers supported by this vring (must be power of two) */ uint32_t num; + + /** + * A unique rproc-wide notify index for this vring. This notify index is + * used when kicking a remote remoteproc, to let it know that this vring + * is triggered + */ uint32_t notifyid; + + /** Reserved (must be zero) */ uint32_t reserved; } METAL_PACKED_END; /** - * struct fw_rsc_vdev - virtio device header - * @id: virtio device id (as in virtio_ids.h) - * @notifyid is a unique rproc-wide notify index for this vdev. This notify - * index is used when kicking a remote remoteproc, to let it know that the - * status/features of this vdev have changes. - * @dfeatures specifies the virtio device features supported by the firmware - * @gfeatures is a place holder used by the host to write back the - * negotiated features that are supported by both sides. - * @config_len is the size of the virtio config space of this vdev. The config - * space lies in the resource table immediate after this vdev header. - * @status is a place holder where the host will indicate its virtio progress. - * @num_of_vrings indicates how many vrings are described in this vdev header - * @reserved: reserved (must be zero) - * @vring is an array of @num_of_vrings entries of 'struct fw_rsc_vdev_vring'. + * @brief 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 @@ -283,29 +286,56 @@ struct fw_rsc_vdev_vring { * 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. - * Yeah, it's a bit confusing. * * 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). the size of the config space is specified by @config_len. + * spec). */ METAL_PACKED_BEGIN struct fw_rsc_vdev { + /** Virtio device header has type 3 */ uint32_t type; + + /** Virtio device id (as in virtio_ids.h) */ uint32_t id; + + /** + * A unique rproc-wide notify index for this vdev. This notify index is + * used when kicking a remote remoteproc, to let it know that the + * status/features of this vdev have changes. + */ uint32_t notifyid; + + /** The virtio device features supported by the firmware */ uint32_t dfeatures; + + /** + * A place holder used by the host to write back the negotiated features + * that are supported by both sides + */ uint32_t gfeatures; + + /** + * The size of the virtio config space of this vdev. The config space lies + * in the resource table immediate after this vdev header + */ uint32_t config_len; + + /** A place holder where the host will indicate its virtio progress */ uint8_t status; + + /** Number of vrings described in this vdev header */ uint8_t num_of_vrings; + + /** Reserved (must be zero) */ uint8_t reserved[2]; + + /** An array of \ref num_of_vrings entries of \ref fw_rsc_vdev_vring */ struct fw_rsc_vdev_vring vring[0]; } METAL_PACKED_END; /** - * struct fw_rsc_vendor - remote processor vendor specific resource - * @len: length of the resource + * @brief Resource table remote processor vendor specific entry * * This resource entry tells the host the vendor specific resource * required by the remote. @@ -315,7 +345,10 @@ struct fw_rsc_vdev { */ METAL_PACKED_BEGIN struct fw_rsc_vendor { + /** Vendor specific resource type can be values 128-512 */ uint32_t type; + + /** Length of the resource */ uint32_t len; } METAL_PACKED_END; @@ -323,109 +356,125 @@ struct loader_ops; struct image_store_ops; struct remoteproc_ops; -/** - * struct remoteproc_mem - * - * This structure presents the memory used by the remote processor - * - * @da: device memory - * @pa: physical memory - * @size: size of the memory - * @io: pointer to the I/O region - * @node: list node - */ +/** @brief Memory used by the remote processor */ struct remoteproc_mem { + /** Device memory */ metal_phys_addr_t da; + + /** Physical memory */ metal_phys_addr_t pa; + + /** Size of the memory */ size_t size; + + /** Optional human-readable name of the memory region */ char name[RPROC_MAX_NAME_LEN]; + + /** Pointer to the I/O region */ struct metal_io_region *io; + + /** List node */ struct metal_list node; }; /** - * struct remoteproc + * @brief A remote processor instance * * This structure is maintained by the remoteproc to represent the remote * processor instance. This structure acts as a prime parameter to use * the remoteproc APIs. - * - * @bootaddr: boot address - * @loader: executable loader - * @lock: mutex lock - * @ops: remoteproc operations - * @rsc_table: pointer to resource table - * @rsc_len: length of resource table - * @rsc_io: metal I/O region of resource table - * @mems: remoteproc memories - * @vdevs: remoteproc virtio devices - * @bitmap: bitmap for notify IDs for remoteproc subdevices - * @state: remote processor state - * @priv: private data */ struct remoteproc { + /** Mutex lock */ metal_mutex_t lock; + + /** Pointer to the resource table */ void *rsc_table; + + /** Length of the resource table */ size_t rsc_len; + + /** Metal I/O region of the resource table */ struct metal_io_region *rsc_io; + + /** Remoteproc memories */ struct metal_list mems; + + /** Remoteproc virtio devices */ struct metal_list vdevs; + + /** Bitmap for notify IDs for remoteproc subdevices */ unsigned long bitmap; + + /** Remoteproc operations */ const struct remoteproc_ops *ops; + + /** Boot address */ metal_phys_addr_t bootaddr; + + /** Executable loader */ const struct loader_ops *loader; + + /** Remote processor state */ unsigned int state; + + /** Private data */ void *priv; }; /** - * struct remoteproc_ops - * - * remoteproc operations needs to be implemented by each remoteproc driver + * @brief Remoteproc operations to manage a remoteproc instance * - * @init: initialize the remoteproc instance - * @remove: remove the remoteproc instance - * @mmap: memory mapped the memory with physical address or destination - * address as input. - * @handle_rsc: handle the vendor specific resource - * @config: configure the remoteproc to make it ready to load and run - * executable - * @start: kick the remoteproc to run application - * @stop: stop the remoteproc from running application, the resource such as - * memory may not be off. - * @shutdown: shutdown the remoteproc and release its resources. - * @notify: notify the remote - * @get_mem: get remoteproc memory I/O region. + * Remoteproc operations need to be implemented by each remoteproc driver */ struct remoteproc_ops { + /** Initialize the remoteproc instance */ struct remoteproc *(*init)(struct remoteproc *rproc, const struct remoteproc_ops *ops, void *arg); + + /** Remove the remoteproc instance */ void (*remove)(struct remoteproc *rproc); + + /** Memory map the memory with physical address or destination address as input */ void *(*mmap)(struct remoteproc *rproc, metal_phys_addr_t *pa, metal_phys_addr_t *da, size_t size, unsigned int attribute, struct metal_io_region **io); + + /** Handle the vendor specific resource */ int (*handle_rsc)(struct remoteproc *rproc, void *rsc, size_t len); + + /** Configure the remoteproc to make it ready to load and run the executable */ int (*config)(struct remoteproc *rproc, void *data); + + /** Kick the remoteproc to run the application */ int (*start)(struct remoteproc *rproc); + + /** + * Stop the remoteproc from running the application, the resource such as + * memory may not be off + */ int (*stop)(struct remoteproc *rproc); + + /** Shutdown the remoteproc and release its resources */ int (*shutdown)(struct remoteproc *rproc); + + /** Notify the remote */ int (*notify)(struct remoteproc *rproc, uint32_t id); + /** - * get_mem - * - * get remoteproc memory I/O region by either name, virtual + * @brief Get remoteproc memory I/O region by either name, virtual * address, physical address or device address. * - * @rproc - pointer to remoteproc instance - * @name - memory name - * @pa - physical address - * @da - device address - * @va - virtual address - * @size - memory size - * @buf - pointer to remoteproc_mem struct object to store result + * @param rproc Pointer to remoteproc instance + * @param name Memory name + * @param pa Physical address + * @param da Device address + * @param va Virtual address + * @param size Memory size + * @param buf Pointer to remoteproc_mem struct object to store result * - * @returns remoteproc memory pointed by buf if success, otherwise NULL + * @return remoteproc memory pointed by buf if success, otherwise NULL */ struct remoteproc_mem *(*get_mem)(struct remoteproc *rproc, const char *name, diff --git a/lib/include/openamp/remoteproc_loader.h b/lib/include/openamp/remoteproc_loader.h index 14d371608..d928fcfce 100644 --- a/lib/include/openamp/remoteproc_loader.h +++ b/lib/include/openamp/remoteproc_loader.h @@ -54,50 +54,53 @@ extern "C" { /* Remoteproc loader reserved mask */ #define RPROC_LOADER_RESERVED_MASK 0x0F000000L -/** - * struct image_store_ops - user defined image store operations - * @open: user defined callback to open the "firmware" to prepare loading - * @close: user defined callback to close the "firmware" to clean up - * after loading - * @load: user defined callback to load the firmware contents to target - * memory or local memory - * @features: loader supported features. e.g. seek - */ +/** @brief User-defined image store operations */ struct image_store_ops { + /** User-defined callback to open the "firmware" to prepare loading */ int (*open)(void *store, const char *path, const void **img_data); + + /** User-defined callback to close the "firmware" to clean up after loading */ void (*close)(void *store); + + /** User-defined callback to load the firmware contents to target memory or local memory */ int (*load)(void *store, size_t offset, size_t size, const void **data, metal_phys_addr_t pa, struct metal_io_region *io, char is_blocking); + + /** Loader supported features. e.g. seek */ unsigned int features; }; -/** - * struct loader_ops - loader operations - * @load_header: define how to get the executable headers - * @load_data: define how to load the target data - * @locate_rsc_table: define how to get the resource table target address, - * offset to the ELF image file and size of the resource - * table. - * @release: define how to release the loader - * @get_entry: get entry address - * @get_load_state: get load state from the image information - */ +/** @brief Loader operations */ struct loader_ops { + /** Define how to get the executable headers */ int (*load_header)(const void *img_data, size_t offset, size_t len, void **img_info, int last_state, size_t *noffset, size_t *nlen); + + /** Define how to load the target data */ int (*load_data)(struct remoteproc *rproc, const void *img_data, size_t offset, size_t len, void **img_info, int last_load_state, metal_phys_addr_t *da, size_t *noffset, size_t *nlen, unsigned char *padding, size_t *nmemsize); + + /** + * Define how to get the resource table target address, offset to the ELF + * image file and size of the resource table + */ int (*locate_rsc_table)(void *img_info, metal_phys_addr_t *da, size_t *offset, size_t *size); + + /** Define how to release the loader */ void (*release)(void *img_info); + + /** Get entry address */ metal_phys_addr_t (*get_entry)(void *img_info); + + /** Get load state from the image information */ int (*get_load_state)(void *img_info); }; diff --git a/lib/include/openamp/remoteproc_virtio.h b/lib/include/openamp/remoteproc_virtio.h index ab06bb5a7..0b747cacc 100644 --- a/lib/include/openamp/remoteproc_virtio.h +++ b/lib/include/openamp/remoteproc_virtio.h @@ -39,21 +39,24 @@ extern "C" { /* define vdev notification function user should implement */ typedef int (*rpvdev_notify_func)(void *priv, uint32_t id); -/** - * struct remoteproc_virtio - * @priv pointer to private data - * @vdev_rsc address of vdev resource - * @vdev_rsc_io metal I/O region of vdev_info, can be NULL - * @notify notification function - * @vdev virtio device - * @node list node - */ +/** @brief Virtio structure for remoteproc instance */ struct remoteproc_virtio { + /** Pointer to private data */ void *priv; + + /** Address of vdev resource */ void *vdev_rsc; + + /** Metal I/O region of vdev_info, can be NULL */ struct metal_io_region *vdev_rsc_io; + + /** Notification function */ rpvdev_notify_func notify; + + /** Virtio device */ struct virtio_device vdev; + + /** List node */ struct metal_list node; }; diff --git a/lib/include/openamp/rpmsg.h b/lib/include/openamp/rpmsg.h index a39b2080e..9cf1e7444 100644 --- a/lib/include/openamp/rpmsg.h +++ b/lib/include/openamp/rpmsg.h @@ -55,76 +55,90 @@ typedef void (*rpmsg_ns_bind_cb)(struct rpmsg_device *rdev, const char *name, uint32_t dest); /** - * struct rpmsg_endpoint - binds a local rpmsg address to its user - * @name: name of the service supported - * @rdev: pointer to the rpmsg device - * @addr: local address of the endpoint - * @dest_addr: address of the default remote endpoint binded. - * @cb: user rx callback, return value of this callback is reserved - * for future use, for now, only allow RPMSG_SUCCESS as return value. - * @ns_unbind_cb: end point service unbind callback, called when remote - * ept is destroyed. - * @node: end point node. - * @priv: private data for the driver's use + * @brief Structure that binds a local RPMsg address to its user * - * In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as - * it binds an rpmsg address with an rx callback handler. + * In essence, an RPMsg endpoint represents a listener on the RPMsg bus, as + * it binds an RPMsg address with an rx callback handler. */ struct rpmsg_endpoint { + /** Name of the service supported */ char name[RPMSG_NAME_SIZE]; + + /** Pointer to the RPMsg device */ struct rpmsg_device *rdev; + + /** Local address of the endpoint */ uint32_t addr; + + /** Address of the default remote endpoint binded */ uint32_t dest_addr; + + /** + * User rx callback, return value of this callback is reserved for future + * use, for now, only allow RPMSG_SUCCESS as return value + */ rpmsg_ept_cb cb; + + /** Endpoint service unbind callback, called when remote ept is destroyed */ rpmsg_ns_unbind_cb ns_unbind_cb; + + /** Endpoint node */ struct metal_list node; + + /** Private data for the driver's use */ void *priv; }; -/** - * struct rpmsg_device_ops - RPMsg device operations - * @send_offchannel_raw: send RPMsg data - * @hold_rx_buffer: hold RPMsg RX buffer - * @release_rx_buffer: release RPMsg RX buffer - * @get_tx_payload_buffer: get RPMsg TX buffer - * @send_offchannel_nocopy: send RPMsg data without copy - * @release_tx_buffer: release RPMsg TX buffer - */ +/** @brief RPMsg device operations */ struct rpmsg_device_ops { + /** Send RPMsg data */ int (*send_offchannel_raw)(struct rpmsg_device *rdev, uint32_t src, uint32_t dst, const void *data, int len, int wait); + + /** Hold RPMsg RX buffer */ void (*hold_rx_buffer)(struct rpmsg_device *rdev, void *rxbuf); + + /** Release RPMsg RX buffer */ void (*release_rx_buffer)(struct rpmsg_device *rdev, void *rxbuf); + + /** Get RPMsg TX buffer */ void *(*get_tx_payload_buffer)(struct rpmsg_device *rdev, uint32_t *len, int wait); + + /** Send RPMsg data without copy */ int (*send_offchannel_nocopy)(struct rpmsg_device *rdev, uint32_t src, uint32_t dst, - const void *data, int len); + const void *data, int len); + + /** Release RPMsg TX buffer */ int (*release_tx_buffer)(struct rpmsg_device *rdev, void *txbuf); }; -/** - * struct rpmsg_device - representation of a RPMsg device - * @endpoints: list of endpoints - * @ns_ept: name service endpoint - * @bitmap: table endpoint address allocation. - * @lock: mutex lock for rpmsg management - * @ns_bind_cb: callback handler for name service announcement without local - * endpoints waiting to bind. - * @ns_unbind_cb: callback handler for name service announcement, called when - * remote ept is destroyed. - * @ops: RPMsg device operations - * @support_ns: create/destroy namespace message - */ +/** @brief Representation of a RPMsg device */ struct rpmsg_device { + /** List of endpoints */ struct metal_list endpoints; + + /** Name service endpoint */ struct rpmsg_endpoint ns_ept; + + /** Table endpoint address allocation */ unsigned long bitmap[metal_bitmap_longs(RPMSG_ADDR_BMP_SIZE)]; + + /** Mutex lock for RPMsg management */ metal_mutex_t lock; + + /** Callback handler for name service announcement without local epts waiting to bind */ rpmsg_ns_bind_cb ns_bind_cb; + + /** Callback handler for name service announcement, called when remote ept is destroyed */ rpmsg_ns_bind_cb ns_unbind_cb; + + /** RPMsg device operations */ struct rpmsg_device_ops ops; + + /** Create/destroy namespace message */ bool support_ns; }; diff --git a/lib/include/openamp/rpmsg_rpc_client_server.h b/lib/include/openamp/rpmsg_rpc_client_server.h index dfbc6c399..f9407849e 100644 --- a/lib/include/openamp/rpmsg_rpc_client_server.h +++ b/lib/include/openamp/rpmsg_rpc_client_server.h @@ -47,77 +47,70 @@ struct rpmsg_rpc_request { unsigned char params[MAX_BUF_LEN]; }; -/** - * struct rpmsg_rpc_answer - rpc request message - * - * @id: service id - * @status: status of rpc - * @params: answer params - * - */ +/** @brief RPC request message */ METAL_PACKED_BEGIN struct rpmsg_rpc_answer { + /** Service ID */ uint32_t id; + + /** Status of RPC */ int32_t status; + + /** Answer params */ unsigned char params[MAX_BUF_LEN]; } METAL_PACKED_END; -/** - * struct rpmsg_rpc_services - table for services - * - * @id: service id - * @cb_function: id callback - * - */ +/** @brief Table for services */ struct rpmsg_rpc_services { + /** Service ID */ uint32_t id; + + /** ID callback */ rpmsg_rpc_syscall_cb cb_function; }; -/** - * struct rpmsg_rpc_client_services - table for client services - * - * @id: service id - * @app_cb: id callback - * - */ +/** @brief Table for client services */ struct rpmsg_rpc_client_services { + /** Service ID */ uint32_t id; + + /** ID callback */ app_cb cb; }; /** - * struct rpmsg_rpc_svr - server remote procedure call data + * @brief Server remote procedure call data * * RPMsg RPC will send request to endpoint - * - * @ept: rpmsg_endpoint structure - * @services: service table - * @n_services: number of services - * */ struct rpmsg_rpc_svr { + /** RPMsg destination endpoint structure */ struct rpmsg_endpoint ept; + + /** Service table */ const struct rpmsg_rpc_services *services; + + /** Number of services */ unsigned int n_services; }; /** - * struct rpmsg_rpc_clt - client remote procedure call data + * @brief Client remote procedure call data * * RPMsg RPC will send request to remote and * wait for callback. - * - * @ept: rpmsg_endpoint structure - * @shutdown_cb: shutdown callback function - * @services: service table - * @n_services: number of services - * */ struct rpmsg_rpc_clt { + /** RPMsg endpoint associated with the call */ struct rpmsg_endpoint ept; + + /** Shutdown callback function */ rpmsg_rpc_shutdown_cb shutdown_cb; + + /** Service table */ const struct rpmsg_rpc_client_services *services; + + /** Number of services */ unsigned int n_services; }; diff --git a/lib/include/openamp/rpmsg_virtio.h b/lib/include/openamp/rpmsg_virtio.h index 6dfe905a1..aea2edf56 100644 --- a/lib/include/openamp/rpmsg_virtio.h +++ b/lib/include/openamp/rpmsg_virtio.h @@ -41,54 +41,62 @@ extern "C" { #define BUFFER_INVALIDATE(x, s) do { } while (0) #endif /* VIRTIO_CACHED_BUFFERS || VIRTIO_USE_DCACHE */ -/** - * struct rpmsg_virtio_shm_pool - shared memory pool used for rpmsg buffers - * @base: base address of the memory pool - * @avail: available memory size - * @size: total pool size - */ +/** @brief Shared memory pool used for RPMsg buffers */ struct rpmsg_virtio_shm_pool { + /** Base address of the memory pool */ void *base; + + /** Available memory size */ size_t avail; + + /** Total pool size */ size_t size; }; /** - * struct rpmsg_virtio_config - configuration of rpmsg device based on virtio + * @brief Configuration of RPMsg device based on virtio * - * This structure is used by the rpmsg virtio host to configure the virtiio + * This structure is used by the RPMsg virtio host to configure the virtiio * layer. - * - * @h2r_buf_size: the size of the buffer used to send data from host to remote - * @r2h_buf_size: the size of the buffer used to send data from remote to host - * @split_shpool: the flag that splitting share memory pool to TX and RX */ struct rpmsg_virtio_config { + /** The size of the buffer used to send data from host to remote */ uint32_t h2r_buf_size; + + /** The size of the buffer used to send data from remote to host */ uint32_t r2h_buf_size; + + /** The flag for splitting shared memory pool to TX and RX */ bool split_shpool; }; -/** - * struct rpmsg_virtio_device - representation of a rpmsg device based on virtio - * @rdev: rpmsg device, first property in the struct - * @config: structure containing virtio configuration - * @vdev: pointer to the virtio device - * @rvq: pointer to receive virtqueue - * @svq: pointer to send virtqueue - * @shbuf_io: pointer to the shared buffer I/O region - * @shpool: pointer to the shared buffers pool - * @reclaimer: Rpmsg buffer reclaimer that contains buffers released by - * the rpmsg_virtio_release_tx_buffer function. - */ +/** @brief Representation of a RPMsg device based on virtio */ struct rpmsg_virtio_device { + /** RPMsg device */ struct rpmsg_device rdev; + + /** Structure containing virtio configuration */ struct rpmsg_virtio_config config; + + /** Pointer to the virtio device */ struct virtio_device *vdev; + + /** Pointer to receive virtqueue */ struct virtqueue *rvq; + + /** Pointer to send virtqueue */ struct virtqueue *svq; + + /** Pointer to the shared buffer I/O region */ struct metal_io_region *shbuf_io; + + /** Pointer to the shared buffers pool */ struct rpmsg_virtio_shm_pool *shpool; + + /** + * RPMsg buffer reclaimer that contains buffers released by the + * \ref rpmsg_virtio_release_tx_buffer function + */ struct metal_list reclaimer; }; diff --git a/lib/include/openamp/virtio.h b/lib/include/openamp/virtio.h index b5e40b182..f0fcfc679 100644 --- a/lib/include/openamp/virtio.h +++ b/lib/include/openamp/virtio.h @@ -169,36 +169,48 @@ struct virtio_feature_desc { const char *vfd_str; }; -/** - * struct virtio_vring_info - * @vq virtio queue - * @info vring alloc info - * @notifyid vring notify id - * @io metal I/O region of the vring memory, can be NULL - */ +/** @brief Virtio vring data structure */ struct virtio_vring_info { + /** Virtio queue */ struct virtqueue *vq; + + /** Vring alloc info */ struct vring_alloc_info info; + + /** Vring notify id */ uint32_t notifyid; + + /** Metal I/O region of the vring memory, can be NULL */ struct metal_io_region *io; }; -/* - * Structure definition for virtio devices for use by the - * applications/drivers - */ - +/** @brief Structure definition for virtio devices for use by the applications/drivers */ struct virtio_device { - uint32_t notifyid; /**< unique position on the virtio bus */ - struct virtio_device_id id; /**< the device type identification - * (used to match it with a driver - */ - uint64_t features; /**< the features supported by both ends. */ - unsigned int role; /**< if it is virtio backend or front end. */ - virtio_dev_reset_cb reset_cb; /**< user registered device callback */ - const struct virtio_dispatch *func; /**< Virtio dispatch table */ - void *priv; /**< TODO: remove pointer to virtio_device private data */ - unsigned int vrings_num; /**< number of vrings */ + /** Unique position on the virtio bus */ + uint32_t notifyid; + + /** The device type identification used to match it with a driver */ + struct virtio_device_id id; + + /** The features supported by both ends. */ + uint64_t features; + + /** If it is virtio backend or front end. */ + unsigned int role; + + /** User-registered device callback */ + virtio_dev_reset_cb reset_cb; + + /** Virtio dispatch table */ + const struct virtio_dispatch *func; + + /** Private data */ + void *priv; + + /** Number of vrings */ + unsigned int vrings_num; + + /** Pointer to the virtio vring structure */ struct virtio_vring_info *vrings_info; }; diff --git a/lib/include/openamp/virtio_mmio.h b/lib/include/openamp/virtio_mmio.h index 64208973e..db678f6b5 100644 --- a/lib/include/openamp/virtio_mmio.h +++ b/lib/include/openamp/virtio_mmio.h @@ -128,37 +128,42 @@ extern "C" { /* Data buffer size for preallocated buffers before vring */ #define VIRTIO_MMIO_MAX_DATA_SIZE 128 -/** - * struct virtio_mmio_dev_mem: VIRTIO MMIO memory area - * @base memory region physical address - * @size memory region size - */ +/** @brief VIRTIO MMIO memory area */ struct virtio_mmio_dev_mem { + /** Memory region physical address */ void *base; + + /** Memory region size */ size_t size; }; -/** - * struct virtio_mmio_device: representation of a VIRTIO MMIO device - * @vdev base virtio device struct - * @cfg_io device configuration space metal_io_region - * @shm_io pre-shared memory space metal_io_region - * @shm_device shared memory device - * @cfg_mem VIRTIO device configuration space - * @shm_mem VIRTIO device pre-shared memory - * @device_mode VIRTIO_DEV_DRIVER or VIRTIO_DEV_DEVICE - * @irq interrupt number - * @user_data custom user data - */ +/** @brief A VIRTIO MMIO device */ struct virtio_mmio_device { + /** Base virtio device structure */ struct virtio_device vdev; + + /** Device configuration space metal_io_region */ struct metal_io_region *cfg_io; + + /** Pre-shared memory space metal_io_region */ struct metal_io_region *shm_io; + + /** Shared memory device */ struct metal_device shm_device; + + /** VIRTIO device configuration space */ struct virtio_mmio_dev_mem cfg_mem; + + /** VIRTIO device pre-shared memory */ struct virtio_mmio_dev_mem shm_mem; + + /** VIRTIO_DEV_DRIVER or VIRTIO_DEV_DEVICE */ unsigned int device_mode; + + /** Interrupt number */ unsigned int irq; + + /** Custom user data */ void *user_data; }; diff --git a/lib/include/openamp/virtio_ring.h b/lib/include/openamp/virtio_ring.h index af2dd434a..e3e93ae23 100644 --- a/lib/include/openamp/virtio_ring.h +++ b/lib/include/openamp/virtio_ring.h @@ -33,25 +33,49 @@ extern "C" { */ #define VRING_AVAIL_F_NO_INTERRUPT 1 -/* VirtIO ring descriptors: 16 bytes. - * These can chain together via "next". +/** + * @brief VirtIO ring descriptors. + * + * The descriptor table refers to the buffers the driver is using for the + * device. addr is a physical address, and the buffers can be chained via \ref next. + * Each descriptor describes a buffer which is read-only for the device + * (“device-readable”) or write-only for the device (“device-writable”), but a + * chain of descriptors can contain both device-readable and device-writable + * buffers. */ METAL_PACKED_BEGIN struct vring_desc { - /* Address (guest-physical). */ + /** Address (guest-physical) */ uint64_t addr; - /* Length. */ + + /** Length */ uint32_t len; - /* The flags as indicated above. */ + + /** Flags relevant to the descriptors */ uint16_t flags; - /* We chain unused descriptors via this, too. */ + + /** We chain unused descriptors via this, too */ uint16_t next; } METAL_PACKED_END; +/** + * @brief Used to offer buffers to the device. + * + * Each ring entry refers to the head of a descriptor chain. It is only + * written by the driver and read by the device. + */ METAL_PACKED_BEGIN struct vring_avail { + /** Flag which determines whether device notifications are required */ uint16_t flags; + + /** + * Indicates where the driver puts the next descriptor entry in the + * ring (modulo the queue size) + */ uint16_t idx; + + /** The ring of descriptors */ uint16_t ring[0]; } METAL_PACKED_END; @@ -67,18 +91,49 @@ struct vring_used_elem { uint32_t len; } METAL_PACKED_END; +/** + * @brief The device returns buffers to this structure when done with them + * + * The structure is only written to by the device, and read by the driver. + */ METAL_PACKED_BEGIN struct vring_used { + /** Flag which determines whether device notifications are required */ uint16_t flags; + + /** + * Indicates where the driver puts the next descriptor entry in the + * ring (modulo the queue size) + */ uint16_t idx; + + /** The ring of descriptors */ struct vring_used_elem ring[0]; } METAL_PACKED_END; +/** + * @brief The virtqueue layout structure + * + * Each virtqueue consists of; descriptor table, available ring, used ring, + * where each part is physically contiguous in guest memory. + * + * When the driver wants to send a buffer to the device, it fills in a slot in + * the descriptor table (or chains several together), and writes the descriptor + * index into the available ring. It then notifies the device. When the device + * has finished a buffer, it writes the descriptor index into the used ring, + * and sends an interrupt. + */ struct vring { + /** The number of descriptors in the virtqueue */ unsigned int num; + /** The actual descriptors, 16 bytes each */ struct vring_desc *desc; + + /** A ring of available descriptor heads with free-running index */ struct vring_avail *avail; + + /** A ring of used descriptor heads with free-running index */ struct vring_used *used; }; diff --git a/lib/rpmsg/rpmsg_internal.h b/lib/rpmsg/rpmsg_internal.h index ab6e0f294..6721ecf88 100644 --- a/lib/rpmsg/rpmsg_internal.h +++ b/lib/rpmsg/rpmsg_internal.h @@ -48,40 +48,46 @@ enum rpmsg_ns_flags { }; /** - * struct rpmsg_hdr - common header for all rpmsg messages - * @src: source address - * @dst: destination address - * @reserved: reserved for future use - * @len: length of payload (in bytes) - * @flags: message flags + * @brief Common header for all RPMsg messages * - * Every message sent(/received) on the rpmsg bus begins with this header. + * Every message sent(/received) on the RPMsg bus begins with this header. */ METAL_PACKED_BEGIN struct rpmsg_hdr { + /** Source address */ uint32_t src; + + /** Destination address */ uint32_t dst; + + /** Reserved for future use */ uint32_t reserved; + + /** Length of payload (in bytes) */ uint16_t len; + + /** Message flags */ uint16_t flags; } METAL_PACKED_END; /** - * struct rpmsg_ns_msg - dynamic name service announcement message - * @name: name of remote service that is published - * @addr: address of remote service that is published - * @flags: indicates whether service is created or destroyed + * @brief Dynamic name service announcement message * * This message is sent across to publish a new service, or announce * about its removal. When we receive these messages, an appropriate - * rpmsg channel (i.e device) is created/destroyed. In turn, the ->probe() - * or ->remove() handler of the appropriate rpmsg driver will be invoked + * RPMsg channel (i.e device) is created/destroyed. In turn, the ->probe() + * or ->remove() handler of the appropriate RPMsg driver will be invoked * (if/as-soon-as one is registered). */ METAL_PACKED_BEGIN struct rpmsg_ns_msg { + /** Name of the remote service that is being published */ char name[RPMSG_NAME_SIZE]; + + /** Endpoint address of the remote service that is being published */ uint32_t addr; + + /** Indicates whether service is created or destroyed */ uint32_t flags; } METAL_PACKED_END;