[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [PATCH] xen/iocap.h: add documentation


  • To: Grygorii Strashko <gragst.linux@xxxxxxxxx>
  • From: Jan Beulich <jbeulich@xxxxxxxx>
  • Date: Wed, 5 Mar 2025 11:37:36 +0100
  • Autocrypt: addr=jbeulich@xxxxxxxx; keydata= xsDiBFk3nEQRBADAEaSw6zC/EJkiwGPXbWtPxl2xCdSoeepS07jW8UgcHNurfHvUzogEq5xk hu507c3BarVjyWCJOylMNR98Yd8VqD9UfmX0Hb8/BrA+Hl6/DB/eqGptrf4BSRwcZQM32aZK 7Pj2XbGWIUrZrd70x1eAP9QE3P79Y2oLrsCgbZJfEwCgvz9JjGmQqQkRiTVzlZVCJYcyGGsD /0tbFCzD2h20ahe8rC1gbb3K3qk+LpBtvjBu1RY9drYk0NymiGbJWZgab6t1jM7sk2vuf0Py O9Hf9XBmK0uE9IgMaiCpc32XV9oASz6UJebwkX+zF2jG5I1BfnO9g7KlotcA/v5ClMjgo6Gl MDY4HxoSRu3i1cqqSDtVlt+AOVBJBACrZcnHAUSuCXBPy0jOlBhxPqRWv6ND4c9PH1xjQ3NP nxJuMBS8rnNg22uyfAgmBKNLpLgAGVRMZGaGoJObGf72s6TeIqKJo/LtggAS9qAUiuKVnygo 3wjfkS9A3DRO+SpU7JqWdsveeIQyeyEJ/8PTowmSQLakF+3fote9ybzd880fSmFuIEJldWxp Y2ggPGpiZXVsaWNoQHN1c2UuY29tPsJgBBMRAgAgBQJZN5xEAhsDBgsJCAcDAgQVAggDBBYC AwECHgECF4AACgkQoDSui/t3IH4J+wCfQ5jHdEjCRHj23O/5ttg9r9OIruwAn3103WUITZee e7Sbg12UgcQ5lv7SzsFNBFk3nEQQCACCuTjCjFOUdi5Nm244F+78kLghRcin/awv+IrTcIWF hUpSs1Y91iQQ7KItirz5uwCPlwejSJDQJLIS+QtJHaXDXeV6NI0Uef1hP20+y8qydDiVkv6l IreXjTb7DvksRgJNvCkWtYnlS3mYvQ9NzS9PhyALWbXnH6sIJd2O9lKS1Mrfq+y0IXCP10eS FFGg+Av3IQeFatkJAyju0PPthyTqxSI4lZYuJVPknzgaeuJv/2NccrPvmeDg6Coe7ZIeQ8Yj t0ARxu2xytAkkLCel1Lz1WLmwLstV30g80nkgZf/wr+/BXJW/oIvRlonUkxv+IbBM3dX2OV8 AmRv1ySWPTP7AAMFB/9PQK/VtlNUJvg8GXj9ootzrteGfVZVVT4XBJkfwBcpC/XcPzldjv+3 HYudvpdNK3lLujXeA5fLOH+Z/G9WBc5pFVSMocI71I8bT8lIAzreg0WvkWg5V2WZsUMlnDL9 mpwIGFhlbM3gfDMs7MPMu8YQRFVdUvtSpaAs8OFfGQ0ia3LGZcjA6Ik2+xcqscEJzNH+qh8V m5jjp28yZgaqTaRbg3M/+MTbMpicpZuqF4rnB0AQD12/3BNWDR6bmh+EkYSMcEIpQmBM51qM EKYTQGybRCjpnKHGOxG0rfFY1085mBDZCH5Kx0cl0HVJuQKC+dV2ZY5AqjcKwAxpE75MLFkr wkkEGBECAAkFAlk3nEQCGwwACgkQoDSui/t3IH7nnwCfcJWUDUFKdCsBH/E5d+0ZnMQi+G0A nAuWpQkjM1ASeQwSHEeAWPgskBQL
  • Cc: Stefano Stabellini <sstabellini@xxxxxxxxxx>, Julien Grall <julien@xxxxxxx>, Andrew Cooper <andrew.cooper3@xxxxxxxxxx>, Michal Orzel <michal.orzel@xxxxxxx>, Roger Pau Monne <roger.pau@xxxxxxxxxx>, Anthony PERARD <anthony.perard@xxxxxxxxxx>, Grygorii Strashko <grygorii_strashko@xxxxxxxx>, xen-devel@xxxxxxxxxxxxxxxxxxxx
  • Delivery-date: Wed, 05 Mar 2025 10:37:43 +0000
  • List-id: Xen developer discussion <xen-devel.lists.xenproject.org>

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@xxxxxxxx>

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;                                        \
>  })




 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.