Change rangeset parameters to "start, last" as proposed in [1],
and add documentation for public interface.
No functional changes.
[1] https://patchwork.kernel.org/comment/26251962/
Signed-off-by: Grygorii Strashko <grygorii_strashko@epam.com>
---
xen/include/xen/iocap.h | 134 +++++++++++++++++++++++++++++++++-------
1 file changed, 112 insertions(+), 22 deletions(-)
diff --git a/xen/include/xen/iocap.h b/xen/include/xen/iocap.h
index ffbc48b60fd5..8845949ab885 100644
--- a/xen/include/xen/iocap.h
+++ b/xen/include/xen/iocap.h
@@ -12,11 +12,21 @@
#include <asm/iocap.h>
#include <asm/p2m.h>
-static inline int iomem_permit_access(struct domain *d, unsigned long s,
- unsigned long e)
+/**
+ * @brief Gives domain permission to access IOMEM range
+ *
+ * @d: Domain to give IOMEM range access
+ * @start: IOMEM range start address, inclusive
+ * @last: IOMEM range last address, inclusive
+ *
+ * @retval 0 Is successful
+ * @retval -ENOMEM if memory allocation failed
+ */
+static inline int iomem_permit_access(struct domain *d, unsigned long start,
+ unsigned long last)
{
bool flush = cache_flush_permitted(d);
- int ret = rangeset_add_range(d->iomem_caps, s, e);
+ int ret = rangeset_add_range(d->iomem_caps, start, last);
if ( !ret && !is_iommu_enabled(d) && !flush )
/*
@@ -29,10 +39,20 @@ static inline int iomem_permit_access(struct domain *d, unsigned long s,
return ret;
}
-static inline int iomem_deny_access(struct domain *d, unsigned long s,
- unsigned long e)
+/**
+ * @brief Denies domain permission to access IOMEM range
+ *
+ * @d: Domain to deny IOMEM range access
+ * @start: IOMEM range start address, inclusive
+ * @last: IOMEM range last address, inclusive
+ *
+ * @retval 0 Is successful
+ * @retval -ENOMEM if memory allocation failed
+ */
+static inline int iomem_deny_access(struct domain *d, unsigned long start,
+ unsigned long last)
{
- int ret = rangeset_remove_range(d->iomem_caps, s, e);
+ int ret = rangeset_remove_range(d->iomem_caps, start, last);
if ( !ret && !is_iommu_enabled(d) && !cache_flush_permitted(d) )
/*
@@ -45,23 +65,93 @@ static inline int iomem_deny_access(struct domain *d, unsigned long s,
return ret;
}
-#define iomem_access_permitted(d, s, e) \
- rangeset_contains_range((d)->iomem_caps, s, e)
-
-#define irq_permit_access(d, i) \
- rangeset_add_singleton((d)->irq_caps, i)
-#define irq_deny_access(d, i) \
- rangeset_remove_singleton((d)->irq_caps, i)
-#define irqs_permit_access(d, s, e) \
- rangeset_add_range((d)->irq_caps, s, e)
-#define irqs_deny_access(d, s, e) \
- rangeset_remove_range((d)->irq_caps, s, e)
-#define irq_access_permitted(d, i) \
- rangeset_contains_singleton((d)->irq_caps, i)
-
-#define pirq_access_permitted(d, i) ({ \
+/**
+ * @brief Checks if domain has permissions to access IOMEM range
+ *
+ * @d: Domain to check IOMEM range access
+ * @start: IOMEM range start address, inclusive
+ * @last: IOMEM range last address, inclusive
+ *
+ * @retval true if access permitted
+ * @retval false if access denied
+ */
+#define iomem_access_permitted(d, start, last) \
+ rangeset_contains_range((d)->iomem_caps, start, last)
+
+/**
+ * @brief Gives domain permission to access IRQ
+ *
+ * @d: Domain to give IRQ access
+ * @irq: IRQ number
+ *
+ * @retval 0 Is successful
+ * @retval -ENOMEM if memory allocation failed
+ */
+#define irq_permit_access(d, irq) \
+ rangeset_add_singleton((d)->irq_caps, irq)
+
+/**
+ * @brief Denies domain permission to access IRQ
+ *
+ * @d: Domain to deny IRQ access
+ * @irq: IRQ number
+ *
+ * @retval 0 Is successful
+ * @retval -ENOMEM if memory allocation failed
+ */
+#define irq_deny_access(d, irq) \
+ rangeset_remove_singleton((d)->irq_caps, irq)
+
+/**
+ * @brief Gives domain permission to access IRQ range
+ *
+ * @d: Domain to give IRQ range access
+ * @start_irq: IRQ range start number, inclusive
+ * @last_irq: IRQ range last number, inclusive
+ *
+ * @retval 0 Is successful
+ * @retval -ENOMEM if memory allocation failed
+ */
+#define irqs_permit_access(d, start_irq, last_irq) \
+ rangeset_add_range((d)->irq_caps, start_irq, last_irq)
+
+/**
+ * @brief Denies domain permission to access IRQ range
+ *
+ * @d: Domain to deny IRQ range access
+ * @start_irq: IRQ range start number, inclusive
+ * @last_irq: IRQ range last number, inclusive
+ *
+ * @retval 0 Is successful
+ * @retval -ENOMEM if memory allocation failed
+ */
+#define irqs_deny_access(d, start_irq, last_irq) \
+ rangeset_remove_range((d)->irq_caps, start_irq, last_irq)
+
+/**
+ * @brief Checks if domain has permissions to access IRQ
+ *
+ * @d: Domain to check IRQ access
+ * @irq: IRQ number to check
+ *
+ * @retval true if access permitted
+ * @retval false if access denied
+ */
+#define irq_access_permitted(d, irq) \
+ rangeset_contains_singleton((d)->irq_caps, irq)
+
+/**
+ * @brief Checks if domain has permissions to access PIRQ
+ *
+ * @d: Domain to check PIRQ access
+ * @pirq: PIRQ number to check
+ *
+ * @retval IRQ number if access permitted
+ * @retval 0 if access denied
+ */
+#define pirq_access_permitted(d, pirq) ({ \
struct domain *d__ = (d); \
- int irq__ = domain_pirq_to_irq(d__, i); \
+ int irq__ = domain_pirq_to_irq(d__, pirq); \
irq__ > 0 && irq_access_permitted(d__, irq__) \
? irq__ : 0; \
})
--
2.34.1On 24.02.2025 12:38, Grygorii Strashko wrote:
> Change rangeset parameters to "start, last" as proposed in [1],
> and add documentation for public interface.
>
> No functional changes.
>
> [1] https://patchwork.kernel.org/comment/26251962/
> Signed-off-by: Grygorii Strashko <grygorii_strashko@epam.com>
To be honest, this is getting too verbose for my taste. I also don't think
title and description fit together: One says the main thing the patch does
is add doc, the other says the main thing is the parameter renaming. When
then there's at least one further parameter which is also renamed, despite
not fitting the description.
Jan
> --- a/xen/include/xen/iocap.h
> +++ b/xen/include/xen/iocap.h
> @@ -12,11 +12,21 @@
> #include <asm/iocap.h>
> #include <asm/p2m.h>
>
> -static inline int iomem_permit_access(struct domain *d, unsigned long s,
> - unsigned long e)
> +/**
> + * @brief Gives domain permission to access IOMEM range
> + *
> + * @d: Domain to give IOMEM range access
> + * @start: IOMEM range start address, inclusive
> + * @last: IOMEM range last address, inclusive
> + *
> + * @retval 0 Is successful
> + * @retval -ENOMEM if memory allocation failed
> + */
> +static inline int iomem_permit_access(struct domain *d, unsigned long start,
> + unsigned long last)
> {
> bool flush = cache_flush_permitted(d);
> - int ret = rangeset_add_range(d->iomem_caps, s, e);
> + int ret = rangeset_add_range(d->iomem_caps, start, last);
>
> if ( !ret && !is_iommu_enabled(d) && !flush )
> /*
> @@ -29,10 +39,20 @@ static inline int iomem_permit_access(struct domain *d, unsigned long s,
> return ret;
> }
>
> -static inline int iomem_deny_access(struct domain *d, unsigned long s,
> - unsigned long e)
> +/**
> + * @brief Denies domain permission to access IOMEM range
> + *
> + * @d: Domain to deny IOMEM range access
> + * @start: IOMEM range start address, inclusive
> + * @last: IOMEM range last address, inclusive
> + *
> + * @retval 0 Is successful
> + * @retval -ENOMEM if memory allocation failed
> + */
> +static inline int iomem_deny_access(struct domain *d, unsigned long start,
> + unsigned long last)
> {
> - int ret = rangeset_remove_range(d->iomem_caps, s, e);
> + int ret = rangeset_remove_range(d->iomem_caps, start, last);
>
> if ( !ret && !is_iommu_enabled(d) && !cache_flush_permitted(d) )
> /*
> @@ -45,23 +65,93 @@ static inline int iomem_deny_access(struct domain *d, unsigned long s,
> return ret;
> }
>
> -#define iomem_access_permitted(d, s, e) \
> - rangeset_contains_range((d)->iomem_caps, s, e)
> -
> -#define irq_permit_access(d, i) \
> - rangeset_add_singleton((d)->irq_caps, i)
> -#define irq_deny_access(d, i) \
> - rangeset_remove_singleton((d)->irq_caps, i)
> -#define irqs_permit_access(d, s, e) \
> - rangeset_add_range((d)->irq_caps, s, e)
> -#define irqs_deny_access(d, s, e) \
> - rangeset_remove_range((d)->irq_caps, s, e)
> -#define irq_access_permitted(d, i) \
> - rangeset_contains_singleton((d)->irq_caps, i)
> -
> -#define pirq_access_permitted(d, i) ({ \
> +/**
> + * @brief Checks if domain has permissions to access IOMEM range
> + *
> + * @d: Domain to check IOMEM range access
> + * @start: IOMEM range start address, inclusive
> + * @last: IOMEM range last address, inclusive
> + *
> + * @retval true if access permitted
> + * @retval false if access denied
> + */
> +#define iomem_access_permitted(d, start, last) \
> + rangeset_contains_range((d)->iomem_caps, start, last)
> +
> +/**
> + * @brief Gives domain permission to access IRQ
> + *
> + * @d: Domain to give IRQ access
> + * @irq: IRQ number
> + *
> + * @retval 0 Is successful
> + * @retval -ENOMEM if memory allocation failed
> + */
> +#define irq_permit_access(d, irq) \
> + rangeset_add_singleton((d)->irq_caps, irq)
> +
> +/**
> + * @brief Denies domain permission to access IRQ
> + *
> + * @d: Domain to deny IRQ access
> + * @irq: IRQ number
> + *
> + * @retval 0 Is successful
> + * @retval -ENOMEM if memory allocation failed
> + */
> +#define irq_deny_access(d, irq) \
> + rangeset_remove_singleton((d)->irq_caps, irq)
> +
> +/**
> + * @brief Gives domain permission to access IRQ range
> + *
> + * @d: Domain to give IRQ range access
> + * @start_irq: IRQ range start number, inclusive
> + * @last_irq: IRQ range last number, inclusive
> + *
> + * @retval 0 Is successful
> + * @retval -ENOMEM if memory allocation failed
> + */
> +#define irqs_permit_access(d, start_irq, last_irq) \
> + rangeset_add_range((d)->irq_caps, start_irq, last_irq)
> +
> +/**
> + * @brief Denies domain permission to access IRQ range
> + *
> + * @d: Domain to deny IRQ range access
> + * @start_irq: IRQ range start number, inclusive
> + * @last_irq: IRQ range last number, inclusive
> + *
> + * @retval 0 Is successful
> + * @retval -ENOMEM if memory allocation failed
> + */
> +#define irqs_deny_access(d, start_irq, last_irq) \
> + rangeset_remove_range((d)->irq_caps, start_irq, last_irq)
> +
> +/**
> + * @brief Checks if domain has permissions to access IRQ
> + *
> + * @d: Domain to check IRQ access
> + * @irq: IRQ number to check
> + *
> + * @retval true if access permitted
> + * @retval false if access denied
> + */
> +#define irq_access_permitted(d, irq) \
> + rangeset_contains_singleton((d)->irq_caps, irq)
> +
> +/**
> + * @brief Checks if domain has permissions to access PIRQ
> + *
> + * @d: Domain to check PIRQ access
> + * @pirq: PIRQ number to check
> + *
> + * @retval IRQ number if access permitted
> + * @retval 0 if access denied
> + */
> +#define pirq_access_permitted(d, pirq) ({ \
> struct domain *d__ = (d); \
> - int irq__ = domain_pirq_to_irq(d__, i); \
> + int irq__ = domain_pirq_to_irq(d__, pirq); \
> irq__ > 0 && irq_access_permitted(d__, irq__) \
> ? irq__ : 0; \
> })
Hi Jan, On 05.03.25 12:37, Jan Beulich wrote: > On 24.02.2025 12:38, Grygorii Strashko wrote: >> Change rangeset parameters to "start, last" as proposed in [1], >> and add documentation for public interface. >> >> No functional changes. >> >> [1] https://patchwork.kernel.org/comment/26251962/ >> Signed-off-by: Grygorii Strashko <grygorii_strashko@epam.com> > > To be honest, this is getting too verbose for my taste. I also don't think > title and description fit together: One says the main thing the patch does > is add doc, the other says the main thing is the parameter renaming. When > then there's at least one further parameter which is also renamed, despite > not fitting the description. > I can update subject and commit message and resend. Or you want me to drop some parts? [...] Thank you for your review. BR, -grygorii
On 11.03.2025 15:53, Grygorii Strashko wrote: > On 05.03.25 12:37, Jan Beulich wrote: >> On 24.02.2025 12:38, Grygorii Strashko wrote: >>> Change rangeset parameters to "start, last" as proposed in [1], >>> and add documentation for public interface. >>> >>> No functional changes. >>> >>> [1] https://patchwork.kernel.org/comment/26251962/ >>> Signed-off-by: Grygorii Strashko <grygorii_strashko@epam.com> >> >> To be honest, this is getting too verbose for my taste. I also don't think >> title and description fit together: One says the main thing the patch does >> is add doc, the other says the main thing is the parameter renaming. When >> then there's at least one further parameter which is also renamed, despite >> not fitting the description. > > I can update subject and commit message and resend. This would address the latter part of my comment, but ... > Or you want me to drop some parts? ... only this would address the former part. Jan
Hi Jan, On 11.03.25 17:35, Jan Beulich wrote: > On 11.03.2025 15:53, Grygorii Strashko wrote: >> On 05.03.25 12:37, Jan Beulich wrote: >>> On 24.02.2025 12:38, Grygorii Strashko wrote: >>>> Change rangeset parameters to "start, last" as proposed in [1], >>>> and add documentation for public interface. >>>> >>>> No functional changes. >>>> >>>> [1] https://patchwork.kernel.org/comment/26251962/ >>>> Signed-off-by: Grygorii Strashko <grygorii_strashko@epam.com> >>> >>> To be honest, this is getting too verbose for my taste. I also don't think >>> title and description fit together: One says the main thing the patch does >>> is add doc, the other says the main thing is the parameter renaming. When >>> then there's at least one further parameter which is also renamed, despite >>> not fitting the description. >> >> I can update subject and commit message and resend. > > This would address the latter part of my comment, but ... > >> Or you want me to drop some parts? > > ... only this would address the former part. I'm very sorry, but I feel very much confused about your above comment :( So I'd be appreciated if You can provide some clarification here. 1) you do not want API documentation at all? 2) you want API documentation, but only for some API? 3) you are not satisfied with documentation style? In case 3, how do you want it to be look like? Could you point on any .h or function in Xen, to inherit the doc style? Here I've followed doxygen style (like in xen/include/xen/vmap.h for example) Before proceeding I've checked CODING_STYLE and other headers as well and saw that there is no generic style for code documentation. Best regards, -grygorii
On 11.03.2025 17:11, Grygorii Strashko wrote: > > Hi Jan, > > On 11.03.25 17:35, Jan Beulich wrote: >> On 11.03.2025 15:53, Grygorii Strashko wrote: >>> On 05.03.25 12:37, Jan Beulich wrote: >>>> On 24.02.2025 12:38, Grygorii Strashko wrote: >>>>> Change rangeset parameters to "start, last" as proposed in [1], >>>>> and add documentation for public interface. >>>>> >>>>> No functional changes. >>>>> >>>>> [1] https://patchwork.kernel.org/comment/26251962/ >>>>> Signed-off-by: Grygorii Strashko <grygorii_strashko@epam.com> >>>> >>>> To be honest, this is getting too verbose for my taste. I also don't think >>>> title and description fit together: One says the main thing the patch does >>>> is add doc, the other says the main thing is the parameter renaming. When >>>> then there's at least one further parameter which is also renamed, despite >>>> not fitting the description. >>> >>> I can update subject and commit message and resend. >> >> This would address the latter part of my comment, but ... >> >>> Or you want me to drop some parts? >> >> ... only this would address the former part. > > I'm very sorry, but I feel very much confused about your above comment :( > > So I'd be appreciated if You can provide some clarification here. > > 1) you do not want API documentation at all? > 2) you want API documentation, but only for some API? > 3) you are not satisfied with documentation style? > > In case 3, how do you want it to be look like? Could you point on any .h or function in Xen, > to inherit the doc style? > > Here I've followed doxygen style (like in xen/include/xen/vmap.h for example) > Before proceeding I've checked CODING_STYLE and other headers as well and saw that > there is no generic style for code documentation. As said, my take is that this ends up too verbose. Personally I'm happy without any doc for these relatively simple interfaces. I could live with something lightweight. And if other maintainers think having this kind of extensive doc is useful, I also wouldn't veto this going in. But in the current shape I don#t think I'm willing to ack it. Jan
© 2016 - 2025 Red Hat, Inc.