docs: fixup documentation

Fixup documentation. Signed-off-by: Klaus Jensen <[email protected]>
SamsungDS · Oct 26, 2023 · 88ddcd3 · 88ddcd3
1 parent 69f9b5e
commit 88ddcd3
Show file tree

Hide file tree

Showing 8 changed files with 51 additions and 13 deletions.
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -12,5 +12,6 @@ the library code.
 
    nvme/index
    pci/index
+   iommu/index
    vfio/index
    support/index
diff --git a/docs/api/iommu/context.rst b/docs/api/iommu/context.rst
@@ -0,0 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later or CC-BY-4.0
+
+IOMMU Context
+=============
+
+.. kernel-doc:: include/vfn/iommu/context.h
diff --git a/docs/api/iommu/dma.rst b/docs/api/iommu/dma.rst
@@ -0,0 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later or CC-BY-4.0
+
+DMA Mapping
+===========
+
+.. kernel-doc:: include/vfn/iommu/dma.h
diff --git a/docs/api/iommu/index.rst b/docs/api/iommu/index.rst
@@ -0,0 +1,14 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later or CC-BY-4.0
+
+=======
+ IOMMU
+=======
+
+This contains documentation mostly generated from kernel-doc-style comments in
+the library code.
+
+.. toctree::
+   :maxdepth: 1
+
+   context
+   dma
diff --git a/docs/api/vfio/container.rst b/docs/api/vfio/container.rst
diff --git a/docs/api/vfio/index.rst b/docs/api/vfio/index.rst
@@ -10,6 +10,5 @@ the library code.
 .. toctree::
    :maxdepth: 1
 
-   container
    device
    pci
diff --git a/include/vfn/iommu/context.h b/include/vfn/iommu/context.h
@@ -15,6 +15,14 @@
 
 #define __VFN_IOVA_MIN 0x10000
 
+/**
+ * get_iommu_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.
+ */
 struct iommu_ctx *get_iommu_context(const char *name);
 
 #endif /* LIBVFN_IOMMU_CONTEXT_H */
diff --git a/include/vfn/iommu/dma.h b/include/vfn/iommu/dma.h
@@ -16,8 +16,8 @@
 /**
  * enum iommu_map_flags - flags for DMA mapping
  * @IOMMU_MAP_FIXED_IOVA: If cleared, an appropriate IOVA will be allocated
- * @IOMMU_MAP_WRITABLE: DMA is allowed to write to this mapping
- * @IOMMU_MAP_READABLE: DMA is allowed to read from this mapping
+ * @IOMMU_MAP_NOWRITE: DMA is not allowed to write to this mapping
+ * @IOMMU_MAP_NOREAD: DMA is not allowed to read from this mapping
  */
 enum iommu_map_flags {
 	IOMMU_MAP_FIXED_IOVA = 1 << 0,
@@ -27,7 +27,7 @@ enum iommu_map_flags {
 
 /**
  * iommu_map_vaddr - map a virtual memory address to an I/O virtual address
- * @vfio: &struct vfio_container
+ * @ctx: &struct iommu_ctx
  * @vaddr: virtual memory address to map
  * @len: number of bytes to map
  * @iova: output parameter for mapped I/O virtual address
@@ -40,8 +40,9 @@ enum iommu_map_flags {
  * If @vaddr falls within an already mapped area, calculate the corresponding
  * iova instead.
  *
- * Note that the allocated IOVA can never be reused in the lifetime of the
- * process, so use this for mapping memory that will be reused.
+ * Note that, for the vfio backend, the allocated IOVA can never be reused in
+ * the lifetime of the process, so use this for mapping memory that will be
+ * reused.
  *
  * Return: ``0`` on success, ``-1`` on error and sets ``errno``.
  */
@@ -50,7 +51,7 @@ int iommu_map_vaddr(struct iommu_ctx *ctx, void *vaddr, size_t len, uint64_t *io
 
 /**
  * iommu_unmap_vaddr - unmap a virtual memory address in the IOMMU
- * @vfio: &struct vfio_container
+ * @ctx: &struct iommu_ctx
  * @vaddr: virtual memory address to unmap
  * @len: output parameter for length of mapping
  *
@@ -67,6 +68,15 @@ struct iova_range {
 	uint64_t end;
 };
 
+/**
+ * iommu_get_iova_ranges - get iova ranges
+ * @ctx: &struct iommu_ctx
+ * @ranges: output parameter
+ *
+ * Store the address of an array into @ranges and return the number of elements.
+ *
+ * Return: the number of elements in the array pointed to.
+ */
 int iommu_get_iova_ranges(struct iommu_ctx *ctx, struct iova_range **ranges);
 
 #endif /* LIBVFN_IOMMU_DMA_H */