[PATCH] xen/iocap.h: add documentation

[Grygorii Strashko <gragst.linux@xxxxxxxxx>]

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>
---
 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.1