On Thu, 6 Feb 2025 20:13:28 -0400 Jason Gunthorpe <jgg@xxxxxxxxxx> wrote: > Document the purpose and rules for the fwctl subsystem. > > Link in kdocs to the doc tree. > > Nacked-by: Jakub Kicinski <kuba@xxxxxxxxxx> > Link: https://lore.kernel.org/r/20240603114250.5325279c@xxxxxxxxxx > Acked-by: Daniel Vetter <daniel.vetter@xxxxxxxx> > https://lore.kernel.org/r/ZrHY2Bds7oF7KRGz@phenom.ffwll.local > Reviewed-by: Jonathan Cameron <Jonathan.Cameron@xxxxxxxxxx> > Signed-off-by: Jason Gunthorpe <jgg@xxxxxxxxxx> A few tiny things inline. > --- > Documentation/userspace-api/fwctl/fwctl.rst | 285 ++++++++++++++++++++ > Documentation/userspace-api/fwctl/index.rst | 12 + > Documentation/userspace-api/index.rst | 1 + > MAINTAINERS | 2 +- > 4 files changed, 299 insertions(+), 1 deletion(-) > create mode 100644 Documentation/userspace-api/fwctl/fwctl.rst > create mode 100644 Documentation/userspace-api/fwctl/index.rst > > diff --git a/Documentation/userspace-api/fwctl/fwctl.rst b/Documentation/userspace-api/fwctl/fwctl.rst > new file mode 100644 > index 00000000000000..428f6f5bb9b4f9 > --- /dev/null > +++ b/Documentation/userspace-api/fwctl/fwctl.rst > @@ -0,0 +1,285 @@ > +Operations exposed through fwctl's non-taining interfaces should be fully > +sharable with other users of the device. For instance exposing a RPC through > +fwctl should never prevent a kernel subsystem from also concurrently using that > +same RPC or hardware unit down the road. In such cases fwctl will be less > +important than proper kernel subsystems that eventually emerge. Mistakes in this > +area resulting in clashes will be resolved in favour of a kernel implementation. > + > +fwctl User API > +============== > + > +.. kernel-doc:: include/uapi/fwctl/fwctl.h > +.. kernel-doc:: include/uapi/fwctl/mlx5.h Doesn't exist yet... I'm not sure if that actually causes a build issue or not but probably better to just slip this in later in the series. > +Development and debugging focused RPCs under more permissive scopes can have > +less stablitiy if the tools using them are only run under exceptional stability > +circumstances and not for every day use of the device. Debugging tools may even > +require exact version matching as they may require something similar to DWARF > +debug information from the FW binary. > + ... > diff --git a/MAINTAINERS b/MAINTAINERS > index 5f30adbe6c8521..319169f7cb7e1c 100644 > --- a/MAINTAINERS > +++ b/MAINTAINERS > @@ -9561,7 +9561,7 @@ FWCTL SUBSYSTEM > M: Jason Gunthorpe <jgg@xxxxxxxxxx> > M: Saeed Mahameed <saeedm@xxxxxxxxxx> > S: Maintained > -F: Documentation/userspace-api/fwctl.rst > +F: Documentation/userspace-api/fwctl/ Push back to patch 1 or introduce this here for the first time. > F: drivers/fwctl/ > F: include/linux/fwctl.h > F: include/uapi/fwctl/
