Message-ID: <9f34ffca-ed5c-39a0-ab18-4a81ab96df45@blackwall.org>
Date: Fri, 24 Nov 2023 14:59:31 +0200
From: Nikolay Aleksandrov <razor@...ckwall.org>
To: Hangbin Liu <liuhangbin@...il.com>, netdev@...r.kernel.org
Cc: "David S . Miller" <davem@...emloft.net>, David Ahern
 <dsahern@...nel.org>, Eric Dumazet <edumazet@...gle.com>,
 Jakub Kicinski <kuba@...nel.org>, Paolo Abeni <pabeni@...hat.com>,
 Ido Schimmel <idosch@...sch.org>, Roopa Prabhu <roopa@...dia.com>,
 Stephen Hemminger <stephen@...workplumber.org>,
 Florian Westphal <fw@...len.de>, Andrew Lunn <andrew@...n.ch>,
 Florian Fainelli <f.fainelli@...il.com>, Vladimir Oltean
 <olteanv@...il.com>, Jiri Pirko <jiri@...nulli.us>,
 Marc Muehlfeld <mmuehlfe@...hat.com>
Subject: Re: [PATCHv2 net-next 04/10] docs: bridge: Add kAPI/uAPI fields

On 11/23/23 15:45, Hangbin Liu wrote:
> The current bridge kernel doc is too old. It only pointed to the
> linuxfoundation wiki page which lacks of the new features.
> 
> Here let's start the new bridge document and put all the bridge info
> so new developers and users could catch up the last bridge status soon.
> 
> First, add kAPI/uAPI and FAQ fields. These 2 fields are only examples and
> more APIs need to be added in future.
> 
> Signed-off-by: Hangbin Liu <liuhangbin@...il.com>
> ---
>   Documentation/networking/bridge.rst | 84 +++++++++++++++++++++++++----
>   net/bridge/br_private.h             |  2 +
>   2 files changed, 76 insertions(+), 10 deletions(-)
> 

The title says add fields, but it also adds doc?
Perhaps split the last change into its own patch.
The rest looks good.

> diff --git a/Documentation/networking/bridge.rst b/Documentation/networking/bridge.rst
> index c859f3c1636e..84aae94f6598 100644
> --- a/Documentation/networking/bridge.rst
> +++ b/Documentation/networking/bridge.rst
> @@ -4,18 +4,82 @@
>   Ethernet Bridging
>   =================
>   
> -In order to use the Ethernet bridging functionality, you'll need the
> -userspace tools.
> +Introduction
> +============
>   
> -Documentation for Linux bridging is on:
> -   https://wiki.linuxfoundation.org/networking/bridge
> +A bridge is a way to connect multiple Ethernet segments together in a protocol
> +independent way. Packets are forwarded based on Layer 2 destination Ethernet
> +address, rather than IP address (like a router). Since forwarding is done
> +at Layer 2, all Layer 3 protocols can pass through a bridge transparently.
>   
> -The bridge-utilities are maintained at:
> -   git://git.kernel.org/pub/scm/linux/kernel/git/shemminger/bridge-utils.git
> +Bridge kAPI
> +===========
>   
> -Additionally, the iproute2 utilities can be used to configure
> -bridge devices.
> +Here are some core structures of bridge code.
>   
> -If you still have questions, don't hesitate to post to the mailing list
> -(more info https://lists.linux-foundation.org/mailman/listinfo/bridge).
> +.. kernel-doc:: net/bridge/br_private.h
> +   :identifiers: net_bridge_vlan
>   
> +Bridge uAPI
> +===========
> +
> +Modern Linux bridge uAPI is accessed via Netlink interface. You can find
> +below files where the bridge and bridge port netlink attributes are defined.
> +
> +Bridge netlink attributes
> +-------------------------
> +
> +.. kernel-doc:: include/uapi/linux/if_link.h
> +   :doc: Bridge enum definition
> +
> +Bridge port netlink attributes
> +------------------------------
> +
> +.. kernel-doc:: include/uapi/linux/if_link.h
> +   :doc: Bridge port enum definition
> +
> +Bridge sysfs
> +------------
> +
> +All sysfs attributes are also exported via the bridge netlink API.
> +You can find each attribute explanation based on the correspond netlink
> +attribute.
> +
> +NOTE: the sysfs interface is deprecated and should not be extended if new
> +options are added.
> +
> +.. kernel-doc:: net/bridge/br_sysfs_br.c
> +   :doc: Bridge sysfs attributes
> +
> +FAQ
> +===
> +
> +What does a bridge do?
> +----------------------
> +
> +A bridge transparently forwards traffic between multiple network interfaces.
> +In plain English this means that a bridge connects two or more physical
> +Ethernet networks, to form one larger (logical) Ethernet network.
> +
> +Is it L3 protocol independent?
> +------------------------------
> +
> +Yes. The bridge sees all frames, but it *uses* only L2 headers/information.
> +As such, the bridging functionality is protocol independent, and there should
> +be no trouble forwarding IPX, NetBEUI, IP, IPv6, etc.
> +
> +Contact Info
> +============
> +
> +The code is currently maintained by Roopa Prabhu <roopa@...dia.com> and
> +Nikolay Aleksandrov <razor@...ckwall.org>. Bridge bugs and enhancements
> +are discussed on the linux-netdev mailing list netdev@...r.kernel.org and
> +bridge@...ts.linux-foundation.org.
> +
> +The list is open to anyone interested: http://vger.kernel.org/vger-lists.html#netdev
> +
> +External Links
> +==============
> +
> +The old Documentation for Linux bridging is on:
> +https://wiki.linuxfoundation.org/networking/bridge
> diff --git a/net/bridge/br_private.h b/net/bridge/br_private.h
> index 6b7f36769d03..051ea81864ac 100644
> --- a/net/bridge/br_private.h
> +++ b/net/bridge/br_private.h
> @@ -186,6 +186,7 @@ enum {
>    * struct net_bridge_vlan - per-vlan entry
>    *
>    * @vnode: rhashtable member
> + * @tnode: rhashtable member
>    * @vid: VLAN id
>    * @flags: bridge vlan flags
>    * @priv_flags: private (in-kernel) bridge vlan flags
> @@ -196,6 +197,7 @@ enum {
>    * @refcnt: if MASTER flag set, this is bumped for each port referencing it
>    * @brvlan: if MASTER flag unset, this points to the global per-VLAN context
>    *          for this VLAN entry
> + * @tinfo: bridge tunnel info
>    * @br_mcast_ctx: if MASTER flag set, this is the global vlan multicast context
>    * @port_mcast_ctx: if MASTER flag unset, this is the per-port/vlan multicast
>    *                  context

Powered by blists - more mailing lists