[PATCH net-next] docs: net: document guidance of implementing the SR-IOV NDOs

[PATCH net-next] docs: net: document guidance of implementing the SR-IOV NDOs

[Jakub Kicinski]

New drivers were prevented from adding ndo_set_vf_* callbacks
over the last few years. This was expected to result in broader
switchdev adoption, but seems to have had little effect.

Based on recent netdev meeting there is broad support for allowing
adding those ops.

There is a problem with the current API supporting a limited number
of VFs (100+, which is less than some modern HW supports).
We can try to solve it by adding similar functionality on devlink
ports, but that'd be another API variation to maintain.
So a netlink attribute reshuffling is a more likely outcome.

Document the guidance, make it clear that the API is frozen.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
CC: corbet@lwn.net
CC: linux-doc@vger.kernel.org
---
 Documentation/networking/index.rst |  1 +
 Documentation/networking/sriov.rst | 25 +++++++++++++++++++++++++
 2 files changed, 26 insertions(+)
 create mode 100644 Documentation/networking/sriov.rst

diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index a6443851a142..b4b2a002f183 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -105,6 +105,7 @@ Refer to :ref:`netdev-FAQ` for a guide on netdev development process specifics.
    seg6-sysctl
    skbuff
    smc-sysctl
+   sriov
    statistics
    strparser
    switchdev
diff --git a/Documentation/networking/sriov.rst b/Documentation/networking/sriov.rst
new file mode 100644
index 000000000000..652ffb501e6b
--- /dev/null
+++ b/Documentation/networking/sriov.rst
@@ -0,0 +1,25 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+NIC SR-IOV APIs
+===============
+
+Modern NICs are strongly encouraged to focus on implementing the ``switchdev``
+model (see :ref:`switchdev`) to configure forwarding and security of SR-IOV
+functionality.
+
+Legacy API
+==========
+
+The old SR-IOV API is implemented in ``rtnetlink`` Netlink family as part of
+the ``RTM_GETLINK`` and ``RTM_SETLINK`` commands. On the driver side
+it consists of a number of ``ndo_set_vf_*`` and ``ndo_get_vf_*`` callbacks.
+
+Since the legacy APIs does not integrate well with the rest of the stack
+the API is considered frozen, no new functionality or extensions
+will be accepted. New drivers should not implement the uncommon callbacks,
+namely the following callbacks are off limits:
+
+ - ``ndo_get_vf_port``
+ - ``ndo_set_vf_port``
+ - ``ndo_set_vf_rss_query_en``
-- 
2.45.2

Re: [PATCH net-next] docs: net: document guidance of implementing the SR-IOV NDOs

[Randy Dunlap]

Hi Jakub,

some nit editing below:

On 6/18/24 12:28 PM, Jakub Kicinski wrote:
> New drivers were prevented from adding ndo_set_vf_* callbacks
> over the last few years. This was expected to result in broader
> switchdev adoption, but seems to have had little effect.
> 
> Based on recent netdev meeting there is broad support for allowing
> adding those ops.
> 
> There is a problem with the current API supporting a limited number
> of VFs (100+, which is less than some modern HW supports).
> We can try to solve it by adding similar functionality on devlink
> ports, but that'd be another API variation to maintain.
> So a netlink attribute reshuffling is a more likely outcome.
> 
> Document the guidance, make it clear that the API is frozen.
> 
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
> ---
> CC: corbet@lwn.net
> CC: linux-doc@vger.kernel.org
> ---
>  Documentation/networking/index.rst |  1 +
>  Documentation/networking/sriov.rst | 25 +++++++++++++++++++++++++
>  2 files changed, 26 insertions(+)
>  create mode 100644 Documentation/networking/sriov.rst
> 
> diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
> index a6443851a142..b4b2a002f183 100644
> --- a/Documentation/networking/index.rst
> +++ b/Documentation/networking/index.rst
> @@ -105,6 +105,7 @@ Refer to :ref:`netdev-FAQ` for a guide on netdev development process specifics.
>     seg6-sysctl
>     skbuff
>     smc-sysctl
> +   sriov
>     statistics
>     strparser
>     switchdev
> diff --git a/Documentation/networking/sriov.rst b/Documentation/networking/sriov.rst
> new file mode 100644
> index 000000000000..652ffb501e6b
> --- /dev/null
> +++ b/Documentation/networking/sriov.rst
> @@ -0,0 +1,25 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============
> +NIC SR-IOV APIs
> +===============
> +
> +Modern NICs are strongly encouraged to focus on implementing the ``switchdev``
> +model (see :ref:`switchdev`) to configure forwarding and security of SR-IOV
> +functionality.
> +
> +Legacy API
> +==========
> +
> +The old SR-IOV API is implemented in ``rtnetlink`` Netlink family as part of
> +the ``RTM_GETLINK`` and ``RTM_SETLINK`` commands. On the driver side
> +it consists of a number of ``ndo_set_vf_*`` and ``ndo_get_vf_*`` callbacks.
> +
> +Since the legacy APIs does not integrate well with the rest of the stack

                         do not

> +the API is considered frozen, no new functionality or extensions

                         frozen; no

> +will be accepted. New drivers should not implement the uncommon callbacks,

                                                                   callbacks;

> +namely the following callbacks are off limits:
> +
> + - ``ndo_get_vf_port``
> + - ``ndo_set_vf_port``
> + - ``ndo_set_vf_rss_query_en``

-- 
~Randy

RE: [EXTERNAL] [PATCH net-next] docs: net: document guidance of implementing the SR-IOV NDOs

[Sunil Kovvuri Goutham]

>-----Original Message-----
>From: Jakub Kicinski <kuba@kernel.org>
>Sent: Wednesday, June 19, 2024 12:58 AM
>To: davem@davemloft.net
>Cc: netdev@vger.kernel.org; edumazet@google.com; pabeni@redhat.com; netdev-
>driver-reviewers@vger.kernel.org; Jakub Kicinski <kuba@kernel.org>;
>corbet@lwn.net; linux-doc@vger.kernel.org
>Subject: [PATCH net-next] docs: net: document guidance of
>implementing the SR-IOV NDOs
>
>New drivers were prevented from adding ndo_set_vf_* callbacks over the last few
>years. This was expected to result in broader switchdev adoption, but seems to
>have had little effect. Based on recent netdev meeting there is broad support for
>allowing adding those ops.
>
>There is a problem with the current API supporting a limited number of VFs (100+,
>which is less than some modern HW supports).
>We can try to solve it by adding similar functionality on devlink ports, but that'd be
>another API variation to maintain.
>So a netlink attribute reshuffling is a more likely outcome.
>
>Document the guidance, make it clear that the API is frozen.
>
>Signed-off-by: Jakub Kicinski <kuba@kernel.org>
>---
>CC: corbet@lwn.net
>CC: linux-doc@vger.kernel.org
>---
> Documentation/networking/index.rst |  1 +  Documentation/networking/sriov.rst
>| 25 +++++++++++++++++++++++++
> 2 files changed, 26 insertions(+)
> create mode 100644 Documentation/networking/sriov.rst
>
>diff --git a/Documentation/networking/index.rst
>b/Documentation/networking/index.rst
>index a6443851a142..b4b2a002f183 100644
>--- a/Documentation/networking/index.rst
>+++ b/Documentation/networking/index.rst
>@@ -105,6 +105,7 @@ Refer to :ref:`netdev-FAQ` for a guide on netdev
>development process specifics.
>    seg6-sysctl
>    skbuff
>    smc-sysctl
>+   sriov
>    statistics
>    strparser
>    switchdev
>diff --git a/Documentation/networking/sriov.rst
>b/Documentation/networking/sriov.rst
>new file mode 100644
>index 000000000000..652ffb501e6b
>--- /dev/null
>+++ b/Documentation/networking/sriov.rst
>@@ -0,0 +1,25 @@
>+.. SPDX-License-Identifier: GPL-2.0
>+
>+===============
>+NIC SR-IOV APIs
>+===============
>+
>+Modern NICs are strongly encouraged to focus on implementing the
>+``switchdev`` model (see :ref:`switchdev`) to configure forwarding and
>+security of SR-IOV functionality.
>+
>+Legacy API
>+==========
>+
>+The old SR-IOV API is implemented in ``rtnetlink`` Netlink family as
>+part of the ``RTM_GETLINK`` and ``RTM_SETLINK`` commands. On the driver
>+side it consists of a number of ``ndo_set_vf_*`` and ``ndo_get_vf_*`` callbacks.
>+
>+Since the legacy APIs does not integrate well with the rest of the
>+stack the API is considered frozen, no new functionality or extensions
>+will be accepted. New drivers should not implement the uncommon
>+callbacks, namely the following callbacks are off limits:
>+
>+ - ``ndo_get_vf_port``
>+ - ``ndo_set_vf_port``
>+ - ``ndo_set_vf_rss_query_en``
>--
>2.45.2
>

Does this mean 
ndo_set_vf_mac
ndo_set_vf_vlan
etc
will be allowed for new drivers ?

Thanks,
Sunil.

Re: [EXTERNAL] [PATCH net-next] docs: net: document guidance of implementing the SR-IOV NDOs

[Jakub Kicinski]

On Wed, 19 Jun 2024 16:37:02 +0000 Sunil Kovvuri Goutham wrote:
> Does this mean 
> ndo_set_vf_mac
> ndo_set_vf_vlan
> etc
> will be allowed for new drivers ?

Yup!