git: 7cb028deff6f - main - busdma: Prevent the use of filters with bus_dma_tag_create()

The branch main has been updated by mhorne:

URL: https://cgit.FreeBSD.org/src/commit/?id=7cb028deff6f46fbefa99f4f19882c69fd7cb883

commit 7cb028deff6f46fbefa99f4f19882c69fd7cb883
Author:     Mitchell Horne <mhorne@FreeBSD.org>
AuthorDate: 2023-12-06 23:07:31 +0000
Commit:     Mitchell Horne <mhorne@FreeBSD.org>
CommitDate: 2023-12-06 23:10:25 +0000

    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             | 32 ++++++++++++--------------------
 sys/arm/arm/busdma_machdep.c         |  4 ++++
 sys/arm64/arm64/busdma_machdep.c     |  4 ++++
 sys/powerpc/powerpc/busdma_machdep.c |  4 ++++
 sys/riscv/riscv/busdma_machdep.c     |  4 ++++
 sys/x86/x86/busdma_machdep.c         |  4 ++++
 6 files changed, 32 insertions(+), 20 deletions(-)

diff --git a/share/man/man9/bus_dma.9 b/share/man/man9/bus_dma.9
index 832ddb4daa22..b644eeb2a476 100644
--- a/share/man/man9/bus_dma.9
+++ b/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
diff --git a/sys/arm/arm/busdma_machdep.c b/sys/arm/arm/busdma_machdep.c
index aa6aa76234cb..282a8ccea690 100644
--- a/sys/arm/arm/busdma_machdep.c
+++ b/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) {
diff --git a/sys/arm64/arm64/busdma_machdep.c b/sys/arm64/arm64/busdma_machdep.c
index 9f1137636ca7..0c1550267ae6 100644
--- a/sys/arm64/arm64/busdma_machdep.c
+++ b/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,
diff --git a/sys/powerpc/powerpc/busdma_machdep.c b/sys/powerpc/powerpc/busdma_machdep.c
index 21828e422d50..c1717140181e 100644
--- a/sys/powerpc/powerpc/busdma_machdep.c
+++ b/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;
 
diff --git a/sys/riscv/riscv/busdma_machdep.c b/sys/riscv/riscv/busdma_machdep.c
index 711717661908..712aad4cb5c4 100644
--- a/sys/riscv/riscv/busdma_machdep.c
+++ b/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,
diff --git a/sys/x86/x86/busdma_machdep.c b/sys/x86/x86/busdma_machdep.c
index 0e72b09684cc..40afcee0651e 100644
--- a/sys/x86/x86/busdma_machdep.c
+++ b/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,