busdma: Prevent the use of filters with bus_dma_tag_create()

[mhorne]

Summary

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 IMO
this is the appropriate step for the lifetime of 15, without actually
breaking the driver API.

I have no real stake in what happens here, nor do I know the whole
history behind the filter functionality. I am trying to clear out some
of my local clean-up branches, and this change enables the removal of a
fair amount of unused complexity across the various busdma
implementations.

[mhorne]

Fix a typo.

[emaste]

d58ff30aca2abfe6ae31e1bc48424be8b48a9ef6 - "filters may not work correctly"
I'm not really familiar with the issue, but this seems reasonable to me.

If you wanted to be thorough you could start with printing a warning in this case and MFC that to stable/14, making it EINVAL in main?

[mhorne]

In D42852#977394, @emaste wrote:

d58ff30aca2abfe6ae31e1bc48424be8b48a9ef6 - "filters may not work correctly"
I'm not really familiar with the issue, but this seems reasonable to me.

Thanks, I meant to include that hash in the commit message. FWIW, by code inspection filters do appear to work correctly today, but as I note they are unused in the tree.

If you wanted to be thorough you could start with printing a warning in this case and MFC that to stable/14, making it EINVAL in main?

Good suggestion, I'll keep this as-is for the moment but can handle this in due time.

[imp]

Maybe we need a new function to replace bus_dma_tag_create ? Maybe make it into a varargs macro that calls _ bus_dma_tag_create when the filtargs aren't present, or _bus_dma_tag_create_legacy when they are... Though we may also be able to use macro magic to ensure they are are identical to NULL at compile time (the former I know we can do, the latter I'm not so sure about).

Warnings in 14 and gone in 15 is great. I doubt anybody will see a warning. IIRC, when Scott made this announcement, they'd already been dead for a number of years since we'd removed the only driver that needed them many, many years ago.

[jhb]

We can certainly do macro magic to make it pass NULL, NULL if a macro with fewer args is used and that macro can even be MFC'd to enable cross-branch API compatibility and then kill it in main. That's what I did when axeing the devclass arg to DRIVER_MODULE.

[mhorne]

In D42852#977579, @jhb wrote:

We can certainly do macro magic to make it pass NULL, NULL if a macro with fewer args is used and that macro can even be MFC'd to enable cross-branch API compatibility and then kill it in main. That's what I did when axeing the devclass arg to DRIVER_MODULE.

Sounds good. For me this is a stretch goal that I can handle eventually, but not immediately.