From e18eb7b14ebc42494a9dafc7e2b3127a09c734e9 Mon Sep 17 00:00:00 2001
From: Scott Long <scottl@FreeBSD.org>
Date: Mon, 14 Sep 2020 06:26:36 +0000
Subject: [PATCH] Update bus_dma.9 for the expanded template API.  Add some
 clarifying language about the operation of parent tags in templates.

---
 share/man/man9/bus_dma.9 | 51 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 46 insertions(+), 5 deletions(-)

diff --git a/share/man/man9/bus_dma.9 b/share/man/man9/bus_dma.9
index 8ee3d399306e..dacc88acee35 100644
--- a/share/man/man9/bus_dma.9
+++ b/share/man/man9/bus_dma.9
@@ -63,6 +63,8 @@
 .Nm bus_dma_template_init ,
 .Nm bus_dma_template_tag ,
 .Nm bus_dma_template_clone ,
+.Nm bus_dma_template_fill,
+.Nm BUS_DMA_TEMPLATE_FILL,
 .Nm bus_dmamap_create ,
 .Nm bus_dmamap_destroy ,
 .Nm bus_dmamap_load ,
@@ -90,19 +92,29 @@
 .Fn bus_dma_tag_destroy "bus_dma_tag_t dmat"
 .Ft void
 .Fo bus_dma_template_init
-.Fa "bus_dma_template_t template"
+.Fa "bus_dma_template_t *template"
 .Fa "bus_dma_tag_t parent"
 .Fc
 .Ft int
 .Fo bus_dma_template_tag
-.Fa "bus_dma_template_t template"
+.Fa "bus_dma_template_t *template"
 .Fa "bus_dma_tag_t *dmat"
 .Fc
 .Ft void
 .Fo bus_dma_template_clone
-.Fa "bus_dma_template_t template"
+.Fa "bus_dma_template_t *template"
 .Fa "bus_dma_tag_t dmat"
 .Fc
+.Ft void
+.Fo bus_dma_template_fill
+.Fa "bus_dma_template_t *template"
+.Fa "bus_dma_param_t params[]"
+.Fa "u_int count"
+.Fc
+.Fo BUS_DMA_TEMPLATE_FILL
+.Fa "bus_dma_template_t *template"
+.Fa "bus_dma_param_t param ..."
+.Fc
 .Ft int
 .Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp"
 .Ft int
@@ -697,8 +709,12 @@ Initializes a
 .Fa bus_dma_template_t
 structure.  If the
 .Fa parent 
-argument is non-NULL, values from this tag will be copied into the template,
-replacing any defaults.
+argument is non-NULL, this parent tag is associated with the template and
+will be compiled into the dma tag that is later created.  The values
+of the parent are not copied into the template.  During tag creation in
+.Fn bus_dma_tag_template ,
+any parameters from the parent tag that are more restrictive than what is
+in the provided template will overwrite what goes into the new tag.
 .It Fn bus_dma_template_tag "*template" "*dmat"
 Unpacks a template into a tag, and returns the tag via the
 .Fa dmat .
@@ -712,6 +728,31 @@ The template does not need to be initialized first.  All of its fields will
 be overwritten by the values contained in the tag.  When paired with
 .Fn bus_dma_template_tag ,
 this function is useful for creating copies of tags.
+.It Fn bus_dma_template_fill "*template" "params[]" "count"
+Fills in the selected fields of the template with the keyed values from the
+.Fa params
+array.  This is not meant to be called directly, use
+.Fn BUS_DMA_TEMPLATE_FILL
+instead.
+.It Fn BUS_DMA_TEMPLATE_FILL "*template" "param ..."
+Fills in the selected fields of the template with a variable number of
+key-value parameters.  The macros listed below take an argument of the
+specified type and encapsulate it into a key-value structure that is directly
+usable as a parameter argument.  Muliple parameters may be provided at once.
+.Bd -literal
+	BD_PARENT()	void *
+	BD_ALIGNMENT()	uintmax_t
+	BD_BOUNDARY()	uintmax_t
+	BD_LOWADDR()	vm_paddr_t
+	BD_HIGHADDR()	vm_paddr_t
+	BD_MAXSIZE()	uintmax_t
+	BD_NSEGMENTS()	uintmax_t
+	BD_MAXSEGSIZE()	uintmax_t
+	BD_FLAGS()	uintmax_t
+	BD_LOCKFUNC()	void *
+	BD_LOCKFUNCARG() void *
+.Ed
+.Pp
 .It Fn bus_dmamap_create "dmat" "flags" "*mapp"
 Allocates and initializes a DMA map.
 Arguments are as follows: