busdma: Prevent the use of filters with bus_dma_tag_create()

A deprecation notice was added to the bus_dma(9) man page by scottl@ in
September 2020 discouraging the use of filter functions. I've performed
an attentive check of all callers in the tree and everything that exists
today passes NULL for both filtfunc and filtarg. Thus, we should start
returning EINVAL if these arguments are non-NULL to prevent new usages
from popping up. Update the man page to be more clear about this.

The deprecation notice is present since at least 13.0-RELEASE, so this
is the appropriate step for the lifetime of 15, without actually
breaking the driver API. Stable branches will emit a warning instead.

This change enables the removal of a fair amount of unused complexity
across the various busdma implementations.

Reviewed by:	jhb
MFC after:	never
Sponsored by:	The FreeBSD Foundation
Differential Revision:	https://reviews.freebsd.org/D42852

share/man/man9/bus_dma.9

@@ -373,7 +373,7 @@ 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.
+.Em Note: The use of filters is no longer supported and will result in an error.
 .It Vt bus_dma_segment_t
 A machine-dependent type that describes individual
 DMA segments.
@@ -611,26 +611,10 @@ This area of
 is used to bounce requests that would otherwise conflict with
 the exclusion window.
 .It Fa filtfunc
-Optional filter function (may be
-.Dv NULL )
-to be called for any attempt to
-map memory into the window described by
-.Fa lowaddr
-and
-.Fa highaddr .
-A filter function is only required when the single window described
-by
-.Fa lowaddr
-and
-.Fa highaddr
-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.
+Formerly the optional filter function; must be
+.Dv NULL .
 .It Fa filtfuncarg
-Argument passed to all calls to the filter function for this tag.
-May be
+Must be
 .Dv NULL .
 .It Fa maxsize
 Maximum size, in bytes, of the sum of all segment lengths in a given
@@ -689,6 +673,14 @@ Returns
 .Er ENOMEM
 if sufficient memory is not available for tag creation
 or allocating mapping resources.
+Returns
+.Er EINVAL
+if either
+.Fa filtfunc
+or
+.Fa filtarg
+arguments are not
+.Dv NULL .
 .It Fn bus_dma_tag_destroy "dmat"
 Deallocate the DMA tag
 .Fa dmat

sys/arm/arm/busdma_machdep.c

@@ -398,6 +398,10 @@ bus_dma_tag_create(bus_dma_tag_t parent, bus_size_t alignment,
 	/* Return a NULL tag on failure */
 	*dmat = NULL;
 
+	/* Filters are no longer supported. */
+	if (filter != NULL || filterarg != NULL)
+		return (EINVAL);
+
 	newtag = (bus_dma_tag_t)malloc(sizeof(*newtag), M_BUSDMA,
 	    M_ZERO | M_NOWAIT);
 	if (newtag == NULL) {

sys/arm64/arm64/busdma_machdep.c

@@ -164,6 +164,10 @@ bus_dma_tag_create(bus_dma_tag_t parent, bus_size_t alignment,
 	struct bus_dma_tag_common *tc;
 	int error;
 
+	/* Filters are no longer supported. */
+	if (filter != NULL || filterarg != NULL)
+		return (EINVAL);
+
 	if (parent == NULL) {
 		error = bus_dma_bounce_impl.tag_create(parent, alignment,
 		    boundary, lowaddr, highaddr, filter, filterarg, maxsize,

sys/powerpc/powerpc/busdma_machdep.c

@@ -168,6 +168,10 @@ bus_dma_tag_create(bus_dma_tag_t parent, bus_size_t alignment,
 		return (EINVAL);
 	}
 
+	/* Filters are no longer supported. */
+	if (filter != NULL || filterarg != NULL)
+		return (EINVAL);
+
 	/* Return a NULL tag on failure */
 	*dmat = NULL;
 

sys/riscv/riscv/busdma_machdep.c

@@ -161,6 +161,10 @@ bus_dma_tag_create(bus_dma_tag_t parent, bus_size_t alignment,
 	struct bus_dma_tag_common *tc;
 	int error;
 
+	/* Filters are no longer supported. */
+	if (filter != NULL || filterarg != NULL)
+		return (EINVAL);
+
 	if (parent == NULL) {
 		error = bus_dma_bounce_impl.tag_create(parent, alignment,
 		    boundary, lowaddr, highaddr, filter, filterarg, maxsize,

sys/x86/x86/busdma_machdep.c

@@ -184,6 +184,10 @@ bus_dma_tag_create(bus_dma_tag_t parent, bus_size_t alignment,
 	struct bus_dma_tag_common *tc;
 	int error;
 
+	/* Filters are no longer supported. */
+	if (filter != NULL || filterarg != NULL)
+		return (EINVAL);
+
 	if (parent == NULL) {
 		error = bus_dma_bounce_impl.tag_create(parent, alignment,
 		    boundary, lowaddr, highaddr, filter, filterarg, maxsize,