docs: brush up documentation

Adjust documentation for new API. Signed-off-by: Klaus Jensen <[email protected]>
SamsungDS · Feb 9, 2024 · 9ad9873 · 9ad9873
1 parent c826e7e
commit 9ad9873
Show file tree

Hide file tree

Showing 21 changed files with 251 additions and 42 deletions.
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -10,8 +10,8 @@ the library code.
 .. toctree::
    :maxdepth: 1
 
+   iommu/index
    nvme/index
    pci/index
-   iommu/index
-   vfio/index
    support/index
+   vfio/index
diff --git a/docs/api/support/align.rst b/docs/api/support/align.rst
@@ -0,0 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later or CC-BY-4.0
+
+Alignment helpers
+=================
+
+.. kernel-doc:: include/vfn/support/align.h
diff --git a/docs/api/support/autoptr.rst b/docs/api/support/autoptr.rst
@@ -0,0 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later or CC-BY-4.0
+
+Glib-style auto pointer
+=======================
+
+.. kernel-doc:: include/vfn/support/autoptr.h
diff --git a/docs/api/support/barrier.rst b/docs/api/support/barrier.rst
@@ -0,0 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later or CC-BY-4.0
+
+Memory Barriers
+===============
+
+.. kernel-doc:: include/vfn/support/barrier.h
diff --git a/docs/api/support/index.rst b/docs/api/support/index.rst
@@ -10,11 +10,16 @@ the library code.
 .. toctree::
    :maxdepth: 1
 
+   align
    atomic
+   autoptr
+   barrier
    compiler
    endian
    io
    log
    mem
    mmio
-   trace
+   mutex
+   ticks
+   timer
diff --git a/docs/api/support/mutex.rst b/docs/api/support/mutex.rst
@@ -0,0 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later or CC-BY-4.0
+
+Autolockable Mutex
+==================
+
+.. kernel-doc:: include/vfn/support/mutex.h
diff --git a/docs/api/support/ticks.rst b/docs/api/support/ticks.rst
@@ -0,0 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later or CC-BY-4.0
+
+Timestamp Counter Helpers
+=========================
+
+.. kernel-doc:: include/vfn/support/ticks.h
diff --git a/docs/api/support/timer.rst b/docs/api/support/timer.rst
@@ -0,0 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later or CC-BY-4.0
+
+Timer Helpers
+=============
+
+.. kernel-doc:: include/vfn/support/timer.h
diff --git a/docs/api/support/trace.rst b/docs/api/support/trace.rst
diff --git a/include/vfn/iommu/context.h b/include/vfn/iommu/context.h
@@ -14,12 +14,12 @@
 #define LIBVFN_IOMMU_CONTEXT_H
 
 /**
- * iommu_get_context - create a new iommu context
- * @name: context identifier
+ * iommu_get_context - Create a new iommu context
+ * @name: Context identifier
  *
  * Create a new iommu context. The mechanism depends on the backend.
  *
- * Return: a new &struct iommu_ctx.
+ * Return: A new &struct iommu_ctx.
  */
 struct iommu_ctx *iommu_get_context(const char *name);
 

diff --git a/include/vfn/iommu/dma.h b/include/vfn/iommu/dma.h
@@ -14,7 +14,7 @@
 #define LIBVFN_IOMMU_DMA_H
 
 /**
- * enum iommu_map_flags - flags for DMA mapping
+ * enum iommu_map_flags - Flags for DMA mapping
  * @IOMMU_MAP_FIXED_IOVA: If cleared, an appropriate IOVA will be allocated
  * @IOMMU_MAP_EPHEMERAL: If set, the mapping is considered temporary
  * @IOMMU_MAP_NOWRITE: DMA is not allowed to write to this mapping
@@ -32,7 +32,7 @@ enum iommu_map_flags {
 };
 
 /**
- * iommu_map_vaddr - map a virtual memory address to an I/O virtual address
+ * iommu_map_vaddr - Map a virtual memory address to an I/O virtual address
  * @ctx: &struct iommu_ctx
  * @vaddr: virtual memory address to map
  * @len: number of bytes to map
@@ -55,7 +55,7 @@ int iommu_map_vaddr(struct iommu_ctx *ctx, void *vaddr, size_t len, uint64_t *io
 		    unsigned long flags);
 
 /**
- * iommu_unmap_vaddr - unmap a virtual memory address in the IOMMU
+ * iommu_unmap_vaddr - Unmap a virtual memory address in the IOMMU
  * @ctx: &struct iommu_ctx
  * @vaddr: virtual memory address to unmap
  * @len: output parameter for length of mapping
@@ -69,7 +69,7 @@ int iommu_map_vaddr(struct iommu_ctx *ctx, void *vaddr, size_t len, uint64_t *io
 int iommu_unmap_vaddr(struct iommu_ctx *ctx, void *vaddr, size_t *len);
 
 /**
- * iommu_unmap_all - unmap all virtual memory address in the IOMMU
+ * iommu_unmap_all - Unmap all virtual memory address in the IOMMU
  * @ctx: &struct iommu_ctx
  *
  * Remove all mappings.
@@ -86,7 +86,7 @@ struct iommu_iova_range {
 #endif
 
 /**
- * iommu_translate_vaddr - translate a virtual address into an iova
+ * iommu_translate_vaddr - Translate a virtual address into an iova
  * @ctx: &struct iommu_ctx
  * @vaddr: virtual memory address to translate
  * @iova: output parameter
@@ -99,7 +99,7 @@ struct iommu_iova_range {
 bool iommu_translate_vaddr(struct iommu_ctx *ctx, void *vaddr, uint64_t *iova);
 
 /**
- * iommu_get_iova_ranges - get iova ranges
+ * iommu_get_iova_ranges - Get iova ranges
  * @ctx: &struct iommu_ctx
  * @ranges: output parameter
  *

diff --git a/include/vfn/nvme/util.h b/include/vfn/nvme/util.h
@@ -22,7 +22,7 @@
 #define __mps_to_pagesize(mps) (1ULL << __mps_to_pageshift(mps))
 
 /**
- * nvme_crc64 - calculate NVMe CRC64
+ * nvme_crc64 - Calculate NVMe CRC64
  * @crc: starting value
  * @buffer: buffer to calculate CRC for
  * @len: length of buffer

diff --git a/include/vfn/pci/util.h b/include/vfn/pci/util.h
@@ -14,7 +14,7 @@
 #define LIBVFN_PCI_UTIL_H
 
 /**
- * pci_bind - bind a pci device to a driver
+ * pci_bind - Bind a pci device to a driver
  * @bdf: pci device identifier ("bus:device:function")
  * @driver: driver name
  *
@@ -26,7 +26,7 @@
 int pci_bind(const char *bdf, const char *driver);
 
 /**
- * pci_unbind - unbind a device from its current driver
+ * pci_unbind - Unbind a device from its current driver
  * @bdf: pci device identifier ("bus:device:function")
  *
  * Unbind the device identified by @bdf from its current driver.
@@ -37,7 +37,7 @@ int pci_bind(const char *bdf, const char *driver);
 int pci_unbind(const char *bdf);
 
 /**
- * pci_driver_new_id - add a new vendor/device id to the given driver
+ * pci_driver_new_id - Add a new vendor/device id to the given driver
  * @driver: kernel driver
  * @vid: vendor id
  * @did: device id
@@ -50,7 +50,7 @@ int pci_unbind(const char *bdf);
 int pci_driver_new_id(const char *driver, uint16_t vid, uint16_t did);
 
 /**
- * pci_driver_remove_id - remove a vendor/device id from the given driver
+ * pci_driver_remove_id - Remove a vendor/device id from the given driver
  * @driver: kernel driver
  * @vid: vendor id
  * @did: device id
@@ -63,7 +63,7 @@ int pci_driver_new_id(const char *driver, uint16_t vid, uint16_t did);
 int pci_driver_remove_id(const char *driver, uint16_t vid, uint16_t did);
 
 /**
- * pci_device_info_get_ull - get sysfs property
+ * pci_device_info_get_ull - Get sysfs property
  * @bdf: pci device identifier ("bus:device:function")
  * @prop: sysfs property
  * @v: output parameter
@@ -76,7 +76,7 @@ int pci_driver_remove_id(const char *driver, uint16_t vid, uint16_t did);
 int pci_device_info_get_ull(const char *bdf, const char *prop, unsigned long long *v);
 
 /**
- * pci_get_driver - get the name of the driver that the device is currently
+ * pci_get_driver - Get the name of the driver that the device is currently
  *                  bound to
  * @bdf: pci device identifier ("bus:device:function")
  *
@@ -88,7 +88,7 @@ int pci_device_info_get_ull(const char *bdf, const char *prop, unsigned long lon
 char *pci_get_driver(const char *bdf);
 
 /**
- * pci_get_iommu_group - get iommu group path
+ * pci_get_iommu_group - Get iommu group path
  * @bdf: pci device identifier ("bus:device:function")
  *
  * Get the iommu group path (/dev/vfio/N) of the device identified by @bdf.
@@ -98,7 +98,7 @@ char *pci_get_driver(const char *bdf);
 char *pci_get_iommu_group(const char *bdf);
 
 /**
- * pci_get_device_vfio_id - get vfio device id
+ * pci_get_device_vfio_id - Get vfio device id
  * @bdf: pci device identifier ("bus:device:function")
  *
  * Get the vfio device id (/sys/bus/pci/devices/%s/vfio-dev/vfio%d) of the

diff --git a/include/vfn/support/align.h b/include/vfn/support/align.h
@@ -13,12 +13,70 @@
 #ifndef LIBVFN_SUPPORT_ALIGN_H
 #define LIBVFN_SUPPORT_ALIGN_H
 
+/**
+ * ALIGN_UP - Align value up
+ * @x: value to be aligned
+ * @a: alignment
+ *
+ * Alignment must be a power of two.
+ *
+ * Return: Aligned value
+ */
 #define ALIGN_UP(x, a) (((x) + (a) - 1) & ~((a) - 1))
+
+/**
+ * ALIGN_DOWN - Align value down
+ * @x: value to be aligned
+ * @a: alignment
+ *
+ * Alignment must be a power of two.
+ *
+ * Return: Aligned value
+ */
 #define ALIGN_DOWN(x, a) ((x) & ~((a) - 1))
+
+/**
+ * ALIGNED - Check if value is aligned
+ * @x: value to be checked
+ * @a: alignment
+ *
+ * Alignment must be a power of two.
+ *
+ * Return: Boolean
+ */
 #define ALIGNED(x, a) (((x) & ((typeof(x))(a) - 1)) == 0)
 
+/**
+ * ROUND_DOWN - Round down to mutiple
+ * @x: value to be rounded
+ * @m: multiple
+ *
+ * Round value down to multiple. Safe when @m is not a power of 2.
+ *
+ * Return: Rounded value
+ */
 #define ROUND_DOWN(x, m) ((x) / (m) * (m))
+
+/**
+ * ROUND_UP - Round up to mutiple
+ * @x: value to be rounded
+ * @m: multiple
+ *
+ * Round value up to multiple. Safe when @m is not a power of 2.
+ *
+ * Return: Rounded value
+ */
 #define ROUND_UP(x, m) ROUND_DOWN((x) + (m) - 1, (m))
+
+/**
+ * ROUND - Round to mutiple
+ * @x: value to be rounded
+ * @m: multiple
+ *
+ * Round value to multiple (half to even). Safe when @m is not a power of 2.
+ *
+ * Return: Rounded value
+ */
 #define ROUND(x, m) \
 	({ \
 		typeof(x) ceil = ROUND_UP(x, m); \

diff --git a/include/vfn/support/atomic.h b/include/vfn/support/atomic.h
@@ -13,6 +13,10 @@
 #ifndef LIBVFN_SUPPORT_ATOMIC_H
 #define LIBVFN_SUPPORT_ATOMIC_H
 
+/**
+ * DOC: Atomic helpers
+ */
+
 /* sparse does not know about these gcc builtins */
 #ifdef __CHECKER__
 #define __atomic_load_n(ptr, memorder) (*(ptr))
@@ -32,18 +36,59 @@
 #define atomic_load_acquire(ptr) \
 	__atomic_load_n(ptr, __ATOMIC_ACQUIRE)
 
+/**
+ * atomic_store_release - Syntactic suger for __atomic_store_n
+ * @ptr: Pointer to value
+ * @val: Value
+ *
+ * Atomically store @val in @ptr with release semantics.
+ */
 #define atomic_store_release(ptr, val) \
 	__atomic_store_n(ptr, val, __ATOMIC_RELEASE)
 
+/**
+ * atomic_inc_fetch - Syntactic suger for __atomic_add_fetch
+ * @ptr: Pointer to value
+ *
+ * Atomically increment the value at @ptr and then fetch it with sequential
+ * consistency semantics.
+ *
+ * Return: The incremented value
+ */
 #define atomic_inc_fetch(ptr) \
 	__atomic_add_fetch(ptr, 1, __ATOMIC_SEQ_CST)
 
+/**
+ * atomic_dec_fetch - Syntactic suger for __atomic_sub_fetch
+ * @ptr: Pointer to value
+ *
+ * Atomically decrement the value at @ptr and then fetch it with sequential
+ * consistency semantics.
+ *
+ * Return: The decremented value
+ */
 #define atomic_dec_fetch(ptr) \
 	__atomic_sub_fetch(ptr, 1, __ATOMIC_SEQ_CST)
 
+/**
+ * atomic_inc - Syntactic suger for __atomic_fetch_add
+ * @ptr: Pointer to value
+ *
+ * Atomically increment the value at @ptr with sequential consistency semantics.
+ *
+ * Return: The previously stored value
+ */
 #define atomic_inc(ptr) \
 	((void) __atomic_fetch_add(ptr, 1, __ATOMIC_SEQ_CST))
 
+/**
+ * atomic_dec - Syntactic suger for __atomic_fetch_sub
+ * @ptr: Pointer to value
+ *
+ * Atomically decrement the value at @ptr with sequential consistency semantics.
+ *
+ * Return: The previously stored value
+ */
 #define atomic_dec(ptr) \
 	((void) __atomic_fetch_sub(ptr, 1, __ATOMIC_SEQ_CST))
 
@@ -54,6 +99,8 @@
  * @desired: Value that should be set
  *
  * Perform an atomic compare-and-exchange on @ptr.
+ *
+ * Return: Boolean, indicating if the CAS succeeded.
  */
 #define atomic_cmpxchg(ptr, expected, desired) \
 	__atomic_compare_exchange_n(ptr, &expected, desired, false, __ATOMIC_RELEASE, __ATOMIC_ACQUIRE)