Author: scottl
Date: Fri Sep 11 19:45:26 2020
New Revision: 365641
URL: https://svnweb.freebsd.org/changeset/base/365641
Log:
Improve the documenation for bus_dma templates. Also add notes to
make it clear that filters may not work correctly and that their use
is deprecated.
MFC after: 3 days
Modified:
head/share/man/man9/bus_dma.9
Modified: head/share/man/man9/bus_dma.9
==============================================================================
--- head/share/man/man9/bus_dma.9 Fri Sep 11 18:09:49 2020
(r365640)
+++ head/share/man/man9/bus_dma.9 Fri Sep 11 19:45:26 2020
(r365641)
@@ -311,13 +311,13 @@ tag inheriting the restrictions of its parent.
This allows all devices along the path of DMA transactions
to contribute to the constraints of those transactions.
.It Vt bus_dma_template_t
-A template structure for creating a
+A template is a structure for creating a
.Fa bus_dma_tag_t
from a set of defaults.
Once initialized with
.Fn bus_dma_template_init ,
a driver can over-ride individual fields to suit its needs.
-The following fields have the indicated values:
+The following fields start with the indicated default values:
.Bd -literal
alignment 1
boundary 0
@@ -362,6 +362,8 @@ to
inclusive.
The filter function should return zero if any mapping in this range
can be accommodated by the device and non-zero otherwise.
+.Pp
+.Em Note: The use of filters is deprecated. Proper operation is not
guaranteed.
.It Vt bus_dma_segment_t
A machine-dependent type that describes individual
DMA segments.
@@ -614,6 +616,8 @@ and
cannot adequately describe the constraints of the device.
The filter function will be called for every machine page
that overlaps the exclusion window.
+.Pp
+.Em Note: The use of filters is deprecated. Proper operation is not
guaranteed.
.It Fa filtfuncarg
Argument passed to all calls to the filter function for this tag.
May be
@@ -691,22 +695,23 @@ on success.
.It Fn bus_dma_template_init "*template" "parent"
Initializes a
.Fa bus_dma_template_t
-structure and associates it with an optional
-.Fa parent .
-The
-.Fa parent
-argument may be NULL.
+structure. If the
+.Fa parent
+argument is non-NULL, values from this tag will be copied into the template,
+replacing any defaults.
.It Fn bus_dma_template_tag "*template" "*dmat"
Unpacks a template into a tag, and returns the tag via the
.Fa dmat .
All return values are identical to
.Fn bus_dma_tag_create .
+The template is not modified by this function, and can be reused and/or
+freed upon return.
.It Fn bus_dma_template_clone "*template" "dmat"
-Clones the fields from a tag to a template.
-This is useful for cloning tags when paired with
-.Fn bus_dma_template_tag .
-A template that is filled in as a clone does not need to be initialized
-first.
+Copies the fields from an existing tag to a template.
+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_dmamap_create "dmat" "flags" "*mapp"
Allocates and initializes a DMA map.
Arguments are as follows:
_______________________________________________
svn-src-head@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"
