include/exec/memory.h | 52 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 42 insertions(+), 10 deletions(-)
Convert the existing documentation comments of
IOMMUMemoryRegionClass to kernel-doc format so their contents
will appear in the API reference at docs/devel/memory.html.
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
include/exec/memory.h | 52 ++++++++++++++++++++++++++++++++++---------
1 file changed, 42 insertions(+), 10 deletions(-)
diff --git a/include/exec/memory.h b/include/exec/memory.h
index f1bb2a7df5..c01475a4e9 100644
--- a/include/exec/memory.h
+++ b/include/exec/memory.h
@@ -211,7 +211,7 @@ enum IOMMUMemoryRegionAttr {
IOMMU_ATTR_SPAPR_TCE_FD
};
-/*
+/**
* IOMMUMemoryRegionClass:
*
* All IOMMU implementations need to subclass TYPE_IOMMU_MEMORY_REGION
@@ -228,8 +228,11 @@ enum IOMMUMemoryRegionAttr {
* attributes and the output TLB entry depends on the transaction
* attributes, we represent this using IOMMU indexes. Each index
* selects a particular translation table that the IOMMU has:
+ *
* @attrs_to_index returns the IOMMU index for a set of transaction attributes
+ *
* @translate takes an input address and an IOMMU index
+ *
* and the mapping returned can only depend on the input address and the
* IOMMU index.
*
@@ -238,10 +241,13 @@ enum IOMMUMemoryRegionAttr {
* for secure transactions and one for non-secure transactions.
*/
struct IOMMUMemoryRegionClass {
- /* private */
+ /* private: */
MemoryRegionClass parent_class;
- /*
+ /* public: */
+ /**
+ * @translate:
+ *
* Return a TLB entry that contains a given address.
*
* The IOMMUAccessFlags indicated via @flag are optional and may
@@ -262,26 +268,38 @@ struct IOMMUMemoryRegionClass {
* information when the IOMMU mapping changes.
*
* @iommu: the IOMMUMemoryRegion
+ *
* @hwaddr: address to be translated within the memory region
- * @flag: requested access permissions
+ *
+ * @flag: requested access permission
+ *
* @iommu_idx: IOMMU index for the translation
*/
IOMMUTLBEntry (*translate)(IOMMUMemoryRegion *iommu, hwaddr addr,
IOMMUAccessFlags flag, int iommu_idx);
- /* Returns minimum supported page size in bytes.
+ /**
+ * @get_min_page_size:
+ *
+ * Returns minimum supported page size in bytes.
+ *
* If this method is not provided then the minimum is assumed to
* be TARGET_PAGE_SIZE.
*
* @iommu: the IOMMUMemoryRegion
*/
uint64_t (*get_min_page_size)(IOMMUMemoryRegion *iommu);
- /* Called when IOMMU Notifier flag changes (ie when the set of
+ /**
+ * @notify_flag_changed:
+ *
+ * Called when IOMMU Notifier flag changes (ie when the set of
* events which IOMMU users are requesting notification for changes).
* Optional method -- need not be provided if the IOMMU does not
* need to know exactly which events must be notified.
*
* @iommu: the IOMMUMemoryRegion
+ *
* @old_flags: events which previously needed to be notified
+ *
* @new_flags: events which now need to be notified
*
* Returns 0 on success, or a negative errno; in particular
@@ -293,7 +311,10 @@ struct IOMMUMemoryRegionClass {
IOMMUNotifierFlag old_flags,
IOMMUNotifierFlag new_flags,
Error **errp);
- /* Called to handle memory_region_iommu_replay().
+ /**
+ * @replay:
+ *
+ * Called to handle memory_region_iommu_replay().
*
* The default implementation of memory_region_iommu_replay() is to
* call the IOMMU translate method for every page in the address space
@@ -310,7 +331,10 @@ struct IOMMUMemoryRegionClass {
*/
void (*replay)(IOMMUMemoryRegion *iommu, IOMMUNotifier *notifier);
- /* Get IOMMU misc attributes. This is an optional method that
+ /**
+ * @get_attr:
+ *
+ * Get IOMMU misc attributes. This is an optional method that
* can be used to allow users of the IOMMU to get implementation-specific
* information. The IOMMU implements this method to handle calls
* by IOMMU users to memory_region_iommu_get_attr() by filling in
@@ -319,7 +343,9 @@ struct IOMMUMemoryRegionClass {
* memory_region_iommu_get_attr() will always return -EINVAL.
*
* @iommu: the IOMMUMemoryRegion
+ *
* @attr: attribute being queried
+ *
* @data: memory to fill in with the attribute data
*
* Returns 0 on success, or a negative errno; in particular
@@ -328,7 +354,10 @@ struct IOMMUMemoryRegionClass {
int (*get_attr)(IOMMUMemoryRegion *iommu, enum IOMMUMemoryRegionAttr attr,
void *data);
- /* Return the IOMMU index to use for a given set of transaction attributes.
+ /**
+ * @attrs_to_index:
+ *
+ * Return the IOMMU index to use for a given set of transaction attributes.
*
* Optional method: if an IOMMU only supports a single IOMMU index then
* the default implementation of memory_region_iommu_attrs_to_index()
@@ -341,7 +370,10 @@ struct IOMMUMemoryRegionClass {
*/
int (*attrs_to_index)(IOMMUMemoryRegion *iommu, MemTxAttrs attrs);
- /* Return the number of IOMMU indexes this IOMMU supports.
+ /**
+ * @num_indexes:
+ *
+ * Return the number of IOMMU indexes this IOMMU supports.
*
* Optional method: if this method is not provided, then
* memory_region_iommu_num_indexes() will return 1, indicating that
--
2.26.2
On 08/09/20 22:11, Eduardo Habkost wrote: > Convert the existing documentation comments of > IOMMUMemoryRegionClass to kernel-doc format so their contents > will appear in the API reference at docs/devel/memory.html. > > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com> > --- > include/exec/memory.h | 52 ++++++++++++++++++++++++++++++++++--------- > 1 file changed, 42 insertions(+), 10 deletions(-) > > diff --git a/include/exec/memory.h b/include/exec/memory.h > index f1bb2a7df5..c01475a4e9 100644 > --- a/include/exec/memory.h > +++ b/include/exec/memory.h > @@ -211,7 +211,7 @@ enum IOMMUMemoryRegionAttr { > IOMMU_ATTR_SPAPR_TCE_FD > }; > > -/* > +/** > * IOMMUMemoryRegionClass: > * > * All IOMMU implementations need to subclass TYPE_IOMMU_MEMORY_REGION > @@ -228,8 +228,11 @@ enum IOMMUMemoryRegionAttr { > * attributes and the output TLB entry depends on the transaction > * attributes, we represent this using IOMMU indexes. Each index > * selects a particular translation table that the IOMMU has: > + * > * @attrs_to_index returns the IOMMU index for a set of transaction attributes > + * > * @translate takes an input address and an IOMMU index > + * > * and the mapping returned can only depend on the input address and the > * IOMMU index. > * > @@ -238,10 +241,13 @@ enum IOMMUMemoryRegionAttr { > * for secure transactions and one for non-secure transactions. > */ > struct IOMMUMemoryRegionClass { > - /* private */ > + /* private: */ > MemoryRegionClass parent_class; > > - /* > + /* public: */ > + /** > + * @translate: > + * > * Return a TLB entry that contains a given address. > * > * The IOMMUAccessFlags indicated via @flag are optional and may > @@ -262,26 +268,38 @@ struct IOMMUMemoryRegionClass { > * information when the IOMMU mapping changes. > * > * @iommu: the IOMMUMemoryRegion > + * > * @hwaddr: address to be translated within the memory region > - * @flag: requested access permissions > + * > + * @flag: requested access permission > + * > * @iommu_idx: IOMMU index for the translation > */ > IOMMUTLBEntry (*translate)(IOMMUMemoryRegion *iommu, hwaddr addr, > IOMMUAccessFlags flag, int iommu_idx); > - /* Returns minimum supported page size in bytes. > + /** > + * @get_min_page_size: > + * > + * Returns minimum supported page size in bytes. > + * > * If this method is not provided then the minimum is assumed to > * be TARGET_PAGE_SIZE. > * > * @iommu: the IOMMUMemoryRegion > */ > uint64_t (*get_min_page_size)(IOMMUMemoryRegion *iommu); > - /* Called when IOMMU Notifier flag changes (ie when the set of > + /** > + * @notify_flag_changed: > + * > + * Called when IOMMU Notifier flag changes (ie when the set of > * events which IOMMU users are requesting notification for changes). > * Optional method -- need not be provided if the IOMMU does not > * need to know exactly which events must be notified. > * > * @iommu: the IOMMUMemoryRegion > + * > * @old_flags: events which previously needed to be notified > + * > * @new_flags: events which now need to be notified > * > * Returns 0 on success, or a negative errno; in particular > @@ -293,7 +311,10 @@ struct IOMMUMemoryRegionClass { > IOMMUNotifierFlag old_flags, > IOMMUNotifierFlag new_flags, > Error **errp); > - /* Called to handle memory_region_iommu_replay(). > + /** > + * @replay: > + * > + * Called to handle memory_region_iommu_replay(). > * > * The default implementation of memory_region_iommu_replay() is to > * call the IOMMU translate method for every page in the address space > @@ -310,7 +331,10 @@ struct IOMMUMemoryRegionClass { > */ > void (*replay)(IOMMUMemoryRegion *iommu, IOMMUNotifier *notifier); > > - /* Get IOMMU misc attributes. This is an optional method that > + /** > + * @get_attr: > + * > + * Get IOMMU misc attributes. This is an optional method that > * can be used to allow users of the IOMMU to get implementation-specific > * information. The IOMMU implements this method to handle calls > * by IOMMU users to memory_region_iommu_get_attr() by filling in > @@ -319,7 +343,9 @@ struct IOMMUMemoryRegionClass { > * memory_region_iommu_get_attr() will always return -EINVAL. > * > * @iommu: the IOMMUMemoryRegion > + * > * @attr: attribute being queried > + * > * @data: memory to fill in with the attribute data > * > * Returns 0 on success, or a negative errno; in particular > @@ -328,7 +354,10 @@ struct IOMMUMemoryRegionClass { > int (*get_attr)(IOMMUMemoryRegion *iommu, enum IOMMUMemoryRegionAttr attr, > void *data); > > - /* Return the IOMMU index to use for a given set of transaction attributes. > + /** > + * @attrs_to_index: > + * > + * Return the IOMMU index to use for a given set of transaction attributes. > * > * Optional method: if an IOMMU only supports a single IOMMU index then > * the default implementation of memory_region_iommu_attrs_to_index() > @@ -341,7 +370,10 @@ struct IOMMUMemoryRegionClass { > */ > int (*attrs_to_index)(IOMMUMemoryRegion *iommu, MemTxAttrs attrs); > > - /* Return the number of IOMMU indexes this IOMMU supports. > + /** > + * @num_indexes: > + * > + * Return the number of IOMMU indexes this IOMMU supports. > * > * Optional method: if this method is not provided, then > * memory_region_iommu_num_indexes() will return 1, indicating that > Queued, thanks. Paolo
On 9/8/20 10:11 PM, Eduardo Habkost wrote: > Convert the existing documentation comments of > IOMMUMemoryRegionClass to kernel-doc format so their contents > will appear in the API reference at docs/devel/memory.html. > > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> > --- > include/exec/memory.h | 52 ++++++++++++++++++++++++++++++++++--------- > 1 file changed, 42 insertions(+), 10 deletions(-) > > diff --git a/include/exec/memory.h b/include/exec/memory.h > index f1bb2a7df5..c01475a4e9 100644 > --- a/include/exec/memory.h > +++ b/include/exec/memory.h > @@ -211,7 +211,7 @@ enum IOMMUMemoryRegionAttr { > IOMMU_ATTR_SPAPR_TCE_FD > }; > > -/* > +/** > * IOMMUMemoryRegionClass: > * > * All IOMMU implementations need to subclass TYPE_IOMMU_MEMORY_REGION > @@ -228,8 +228,11 @@ enum IOMMUMemoryRegionAttr { > * attributes and the output TLB entry depends on the transaction > * attributes, we represent this using IOMMU indexes. Each index > * selects a particular translation table that the IOMMU has: > + * > * @attrs_to_index returns the IOMMU index for a set of transaction attributes > + * > * @translate takes an input address and an IOMMU index > + * > * and the mapping returned can only depend on the input address and the > * IOMMU index. > * > @@ -238,10 +241,13 @@ enum IOMMUMemoryRegionAttr { > * for secure transactions and one for non-secure transactions. > */ > struct IOMMUMemoryRegionClass { > - /* private */ > + /* private: */ > MemoryRegionClass parent_class; > > - /* > + /* public: */ > + /** > + * @translate: > + * > * Return a TLB entry that contains a given address. > * > * The IOMMUAccessFlags indicated via @flag are optional and may > @@ -262,26 +268,38 @@ struct IOMMUMemoryRegionClass { > * information when the IOMMU mapping changes. > * > * @iommu: the IOMMUMemoryRegion > + * > * @hwaddr: address to be translated within the memory region > - * @flag: requested access permissions > + * > + * @flag: requested access permission > + * > * @iommu_idx: IOMMU index for the translation > */ > IOMMUTLBEntry (*translate)(IOMMUMemoryRegion *iommu, hwaddr addr, > IOMMUAccessFlags flag, int iommu_idx); > - /* Returns minimum supported page size in bytes. > + /** > + * @get_min_page_size: > + * > + * Returns minimum supported page size in bytes. > + * > * If this method is not provided then the minimum is assumed to > * be TARGET_PAGE_SIZE. > * > * @iommu: the IOMMUMemoryRegion > */ > uint64_t (*get_min_page_size)(IOMMUMemoryRegion *iommu); > - /* Called when IOMMU Notifier flag changes (ie when the set of > + /** > + * @notify_flag_changed: > + * > + * Called when IOMMU Notifier flag changes (ie when the set of > * events which IOMMU users are requesting notification for changes). > * Optional method -- need not be provided if the IOMMU does not > * need to know exactly which events must be notified. > * > * @iommu: the IOMMUMemoryRegion > + * > * @old_flags: events which previously needed to be notified > + * > * @new_flags: events which now need to be notified > * > * Returns 0 on success, or a negative errno; in particular > @@ -293,7 +311,10 @@ struct IOMMUMemoryRegionClass { > IOMMUNotifierFlag old_flags, > IOMMUNotifierFlag new_flags, > Error **errp); > - /* Called to handle memory_region_iommu_replay(). > + /** > + * @replay: > + * > + * Called to handle memory_region_iommu_replay(). > * > * The default implementation of memory_region_iommu_replay() is to > * call the IOMMU translate method for every page in the address space > @@ -310,7 +331,10 @@ struct IOMMUMemoryRegionClass { > */ > void (*replay)(IOMMUMemoryRegion *iommu, IOMMUNotifier *notifier); > > - /* Get IOMMU misc attributes. This is an optional method that > + /** > + * @get_attr: > + * > + * Get IOMMU misc attributes. This is an optional method that > * can be used to allow users of the IOMMU to get implementation-specific > * information. The IOMMU implements this method to handle calls > * by IOMMU users to memory_region_iommu_get_attr() by filling in > @@ -319,7 +343,9 @@ struct IOMMUMemoryRegionClass { > * memory_region_iommu_get_attr() will always return -EINVAL. > * > * @iommu: the IOMMUMemoryRegion > + * > * @attr: attribute being queried > + * > * @data: memory to fill in with the attribute data > * > * Returns 0 on success, or a negative errno; in particular > @@ -328,7 +354,10 @@ struct IOMMUMemoryRegionClass { > int (*get_attr)(IOMMUMemoryRegion *iommu, enum IOMMUMemoryRegionAttr attr, > void *data); > > - /* Return the IOMMU index to use for a given set of transaction attributes. > + /** > + * @attrs_to_index: > + * > + * Return the IOMMU index to use for a given set of transaction attributes. > * > * Optional method: if an IOMMU only supports a single IOMMU index then > * the default implementation of memory_region_iommu_attrs_to_index() > @@ -341,7 +370,10 @@ struct IOMMUMemoryRegionClass { > */ > int (*attrs_to_index)(IOMMUMemoryRegion *iommu, MemTxAttrs attrs); > > - /* Return the number of IOMMU indexes this IOMMU supports. > + /** > + * @num_indexes: > + * > + * Return the number of IOMMU indexes this IOMMU supports. > * > * Optional method: if this method is not provided, then > * memory_region_iommu_num_indexes() will return 1, indicating that >
© 2016 - 2024 Red Hat, Inc.