netdev - Re: [RFC PATCHv3 net-next 04/10] docs: bridge: Add kAPI/uAPI fields

Open Source and information security mailing list archives

Date: Sat, 11 Nov 2023 19:07:33 +0000
From: Simon Horman <horms@...nel.org>
To: Hangbin Liu <liuhangbin@...il.com>
Cc: netdev@...r.kernel.org, "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>,
	Nikolay Aleksandrov <razor@...ckwall.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>
Subject: Re: [RFC PATCHv3 net-next 04/10] docs: bridge: Add kAPI/uAPI fields

On Fri, Nov 10, 2023 at 06:15:41PM +0800, 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 fileds are only examples and
> more APIs need to be added in future.
> 
> Signed-off-by: Hangbin Liu <liuhangbin@...il.com>
> ---
>  Documentation/networking/bridge.rst | 83 +++++++++++++++++++++++++----
>  1 file changed, 73 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/networking/bridge.rst b/Documentation/networking/bridge.rst
> index c859f3c1636e..d06c51960f45 100644
> --- a/Documentation/networking/bridge.rst
> +++ b/Documentation/networking/bridge.rst
> @@ -4,18 +4,81 @@
>  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

nit: Building htmldocs reports:

 ./net/bridge/br_private.h:240: warning: Function parameter or member 'tnode' not described in 'net_bridge_vlan'
 ./net/bridge/br_private.h:240: warning: Function parameter or member 'tinfo' not described in 'net_bridge_vlan'

...

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives