diff --git a/docs/api/index.rst b/docs/api/index.rst index 0320fb9d..fa66c89c 100644 --- 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 new file mode 100644 index 00000000..080e38e0 --- /dev/null +++ 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 new file mode 100644 index 00000000..c974c731 --- /dev/null +++ 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 new file mode 100644 index 00000000..fa168779 --- /dev/null +++ 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 index cb3d0b18..f3f1fb21 100644 --- 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 new file mode 100644 index 00000000..b1bbc337 --- /dev/null +++ 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 new file mode 100644 index 00000000..0459601c --- /dev/null +++ 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 new file mode 100644 index 00000000..5426121d --- /dev/null +++ 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 deleted file mode 100644 index ad0acd00..00000000 --- a/docs/api/support/trace.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0-or-later or CC-BY-4.0 - -Tracing -======= - -.. kernel-doc:: include/vfn/trace.h diff --git a/include/vfn/iommu/context.h b/include/vfn/iommu/context.h index 4189edae..8656252c 100644 --- 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 index 67de46be..d6abc809 100644 --- 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 index 88b343b7..044629de 100644 --- 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 index 02231274..17397dce 100644 --- 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 index 7c4b14a0..24d1886f 100644 --- 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 index d4797b71..025cf0fa 100644 --- 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) diff --git a/include/vfn/support/autoptr.h b/include/vfn/support/autoptr.h index 05906749..fd0977db 100644 --- a/include/vfn/support/autoptr.h +++ b/include/vfn/support/autoptr.h @@ -13,8 +13,8 @@ #ifndef LIBVFN_SUPPORT_AUTOPTR_H #define LIBVFN_SUPPORT_AUTOPTR_H -/* - * glib-style auto pointer +/** + * DOC: glib-style auto pointer * * The __autoptr() provides a general way of "cleaning up" when going out of * scope. Inspired by glib, but simplified a lot (at the expence of @@ -24,6 +24,14 @@ #define __AUTOPTR_CLEANUP(t) __autoptr_cleanup_##t #define __AUTOPTR_T(t) __autoptr_##t +/** + * DEFINE_AUTOPTR - Defines the appropriate cleanup function for a pointer type + * @t: type name + * @cleanup: function to be called to cleanup type + * + * Defines a function ``__autoptr_cleanup_##t`` that will call @cleanup when + * invoked. + */ #define DEFINE_AUTOPTR(t, cleanup) \ typedef t *__AUTOPTR_T(t); \ \ @@ -33,6 +41,14 @@ (cleanup)(*p); \ } +/** + * __autoptr - Helper to declare a pointer variable with automatic cleanup + * @t: type name + * + * Declares a pointer that is cleaned up when the variable goes out of scope. + * How to clean up the type must have been previously declared using + * DEFINE_AUTOPTR(). + */ #define __autoptr(t) __attribute__((cleanup(__AUTOPTR_CLEANUP(t)))) __AUTOPTR_T(t) #endif /* LIBVFN_SUPPORT_AUTOPTR_H */ diff --git a/include/vfn/support/barrier.h b/include/vfn/support/barrier.h index a399055f..c8052dd3 100644 --- a/include/vfn/support/barrier.h +++ b/include/vfn/support/barrier.h @@ -13,6 +13,18 @@ #ifndef LIBVFN_SUPPORT_BARRIER_H #define LIBVFN_SUPPORT_BARRIER_H +/** + * DOC: Memory barrier helpers + * + * Defines the usual ``rmb()``, ``wmb()``, ``mb()`` and ``dma_rmb()`` + * architecture specific memory barriers. + */ + +/** + * barrier - Compiler barrier + * + * Inserts a compiler barrier. + */ #define barrier() asm volatile("" ::: "memory") #if defined(__aarch64__) diff --git a/include/vfn/support/endian.h b/include/vfn/support/endian.h index b4b501de..02e3bee4 100644 --- a/include/vfn/support/endian.h +++ b/include/vfn/support/endian.h @@ -139,10 +139,10 @@ static inline beint32_t cpu_to_be32(uint32_t native) } /** - * cpu_to_be16 - convert a uint16_t value to big endian. - * @native: value to convert + * cpu_to_be16 - Convert a uint16_t value to big endian. + * @native: Value to convert * - * Return: big endian integer + * Return: Big endian integer */ static inline beint16_t cpu_to_be16(uint16_t native) { @@ -150,10 +150,10 @@ static inline beint16_t cpu_to_be16(uint16_t native) } /** - * be64_to_cpu - convert a big-endian uint64_t value - * @be_val: big-endian value to convert + * be64_to_cpu - Convert a big-endian uint64_t value + * @be_val: Big-endian value to convert * - * Return: host endian integer + * Return: Host endian integer */ static inline uint64_t be64_to_cpu(beint64_t be_val) { @@ -161,10 +161,10 @@ static inline uint64_t be64_to_cpu(beint64_t be_val) } /** - * be32_to_cpu - convert a big-endian uint32_t value - * @be_val: big-endian value to convert + * be32_to_cpu - Convert a big-endian uint32_t value + * @be_val: Big-endian value to convert * - * Return: host endian integer + * Return: Host endian integer */ static inline uint32_t be32_to_cpu(beint32_t be_val) { @@ -172,16 +172,25 @@ static inline uint32_t be32_to_cpu(beint32_t be_val) } /** - * be16_to_cpu - convert a big-endian uint16_t value - * @be_val: big-endian value to convert + * be16_to_cpu - Convert a big-endian uint16_t value + * @be_val: Big-endian value to convert * - * Return: host endian integer + * Return: Host endian integer */ static inline uint16_t be16_to_cpu(beint16_t be_val) { return BE16_TO_CPU(be_val); } +/** + * put_unaligned_be48 - Store 48 bits of v into p as big endian + * @v: Value + * @p: Pointer to memory + * + * Store the lower 48 bits of @v into @p, forming a big endian value. + * + * Note: @p MUST be at least 6 bytes. + */ static inline void put_unaligned_be48(const uint64_t v, uint8_t *p) { p[0] = (uint8_t)(v >> 40); @@ -192,6 +201,17 @@ static inline void put_unaligned_be48(const uint64_t v, uint8_t *p) p[5] = (uint8_t)(v); } +/** + * get_unaligned_be48 - Get 48 bit big endian value from @p + * @p: Pointer to memory + * + * Load the 48 bits at @p, converting from big into host endian. + * + * Note: @p MUST be at least 6 bytes. + * + * Return: Host endian integer + */ + static inline uint64_t get_unaligned_be48(const uint8_t *p) { uint64_t v = 0; diff --git a/include/vfn/support/mutex.h b/include/vfn/support/mutex.h index c476925a..3b84af26 100644 --- a/include/vfn/support/mutex.h +++ b/include/vfn/support/mutex.h @@ -14,7 +14,7 @@ #define LIBVFN_SUPPORT_MUTEX_H /* - * Autolockable mutex + * DOC: Autolockable mutex * * Define a __autolock() macro that will lock the given mutex as well as ensure * that it is unlocked when going out of scope. This is inspired by the @@ -36,6 +36,12 @@ static inline void __mutex_auto_unlock(pthread_mutex_t *mutex) DEFINE_AUTOPTR(pthread_mutex_t, __mutex_auto_unlock) +/** + * __autolock - autolock mutex + * @x: pointer to pthread mutex + * + * Lock the mutex and unlock it automatically when going out of scope. + */ #define __autolock(x) \ __autoptr(pthread_mutex_t) \ glue(autolock, __COUNTER__) __attribute__((__unused__)) = __mutex_auto_lock(x) diff --git a/include/vfn/support/ticks.h b/include/vfn/support/ticks.h index d5720eee..547be223 100644 --- a/include/vfn/support/ticks.h +++ b/include/vfn/support/ticks.h @@ -13,6 +13,10 @@ #ifndef LIBVFN_SUPPORT_TICKS_H #define LIBVFN_SUPPORT_TICKS_H +/** + * DOC: Helpers for architecture specific timestamp counters + */ + #if defined(__x86_64__) # include #elif defined(__aarch64__) @@ -23,6 +27,11 @@ extern uint64_t __vfn_ticks_freq; +/** + * get_ticks - get ticks + * + * Return: value of architecture specific timestamp counter + */ static inline uint64_t get_ticks(void) { return get_ticks_arch(); diff --git a/include/vfn/support/timer.h b/include/vfn/support/timer.h index 517dfb91..b905209a 100644 --- a/include/vfn/support/timer.h +++ b/include/vfn/support/timer.h @@ -17,6 +17,12 @@ #define US_PER_SEC 1000000 #define MS_PER_SEC 1000 +/** + * __usleep - sleep through interrupts + * @usec: number of milliseconds to sleep + * + * If interrupted, continue. + */ void __usleep(useconds_t usec); #endif /* LIBVFN_SUPPORT_TIMER_H */