Re: [net-next,09/10] documentation: networking: add shared devlink documentation

[Jakub Kicinski <kuba@kernel.org>]

This is an AI-generated review of your patch. The human sending this
email says "FYI"

For local reproduction steps see https://netdev-ai.bots.linux.dev/ai-local.html
---
documentation: networking: add shared devlink documentation

This commit adds documentation for shared devlink instances, which allow
multiple physical functions (PFs) on the same chip to share a devlink
instance for chip-wide operations.

> diff --git a/Documentation/networking/devlink/devlink-shared.rst b/Documentation/networking/devlink/devlink-shared.rst
> new file mode 100644
> index 000000000000..b2a1bd37564f
> --- /dev/null
> +++ b/Documentation/networking/devlink/devlink-shared.rst
> @@ -0,0 +1,89 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +============================
> +Devlink Shared Instances
> +============================

The underline length doesn't match the title. The title "Devlink Shared
Instances" is 25 characters, but the "====" lines are 28 characters. Should
these match?

> +
> +Overview
> +========
> +
> +Shared devlink instances allow multiple physical functions (PFs) on the same
> +chip to share an additional devlink instance for chip-wide operations. This
> +is implemented within individual drivers alongside the individual PF devlink
> +instances, not replacing them.

Should the documentation include a note here that shared devlink instances
are a workaround for legacy drivers, and that new drivers should have a
single devlink instance for the entire device?

This guidance appeared in multiple review discussions, particularly in the
V7 review where it was noted: "There needs to be a note here clearly
stating the the use of 'shared devlink instace' is a hack for legacy
drivers, and new drivers should have a single devlink instance for the
entire device. The fact that single instance is always preferred, and
*more correct* must be made very clear to the reader."

Without this context, readers might not understand when this feature is
appropriate to use versus when a single devlink instance would be more
correct.

> +
> +Multiple PFs may reside on the same physical chip, running a single firmware.
> +Some of the resources and configurations may be shared among these PFs. The
> +shared devlink instance provides an object to pin configuration knobs on.

[ ... ]

> diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
> index 35b12a2bfeba..f7ba7dcf477d 100644
> --- a/Documentation/networking/devlink/index.rst
> +++ b/Documentation/networking/devlink/index.rst
> @@ -68,6 +68,7 @@ general.
>     devlink-resource
>     devlink-selftests
>     devlink-trap
> +   devlink-shared
>
>  Driver-specific documentation
>  -----------------------------