Message-ID: <20230913092854.1027336-2-liuhangbin@gmail.com>
Date: Wed, 13 Sep 2023 17:28:53 +0800
From: Hangbin Liu <liuhangbin@...il.com>
To: 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>,
	Nikolay Aleksandrov <razor@...ckwall.org>,
	Roopa Prabhu <roopa@...dia.com>,
	Stephen Hemminger <stephen@...workplumber.org>,
	Hangbin Liu <liuhangbin@...il.com>
Subject: [RFC Draft PATCH net-next] Doc: update bridge doc

This is an example of bridge doc update. In this example I use the
sphinx identifier to insert the structure description in the doc.

I plan to copy all the iproute2 bridge related man docs first.
Please tell me if other doc I need to add.

Signed-off-by: Hangbin Liu <liuhangbin@...il.com>
---
 Documentation/networking/bridge.rst |  85 ++++++++++--
 include/uapi/linux/if_bridge.h      |  24 ++++
 include/uapi/linux/if_link.h        | 194 ++++++++++++++++++++++++++++
 3 files changed, 293 insertions(+), 10 deletions(-)

diff --git a/Documentation/networking/bridge.rst b/Documentation/networking/bridge.rst
index c859f3c1636e..7a877c304478 100644
--- a/Documentation/networking/bridge.rst
+++ b/Documentation/networking/bridge.rst
@@ -4,18 +4,83 @@
 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 two Ethernet segments together in a protocol
+independent way. Packets are forwarded based on Ethernet address, rather
+than IP address (like a router). Since forwarding is done at Layer 2, all
+protocols can go transparently through a bridge.
 
-The bridge-utilities are maintained at:
-   git://git.kernel.org/pub/scm/linux/kernel/git/shemminger/bridge-utils.git
+Bridge internals
+================
 
-Additionally, the iproute2 utilities can be used to configure
-bridge devices.
+.. kernel-doc:: include/uapi/linux/if_bridge.h
+   :identifiers: __bridge_info
 
-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:: include/uapi/linux/if_bridge.h
+   :identifiers: __port_info
+
+Bridge uAPI
+===========
+
+Bridge netlink attributes
+-------------------------
+
+.. kernel-doc:: include/uapi/linux/if_link.h
+   :doc: The bridge emum defination
+
+Bridge sysfs
+------------
+
+Most of them are same with netlink attributes. What about the read only
+parameters like gc_timer, tcn_timer? Should we doc them?
+
+STP
+===
+
+Multicast
+=========
+
+VLAN
+====
+
+Switchdev
+=========
+
+Netfilter
+=========
+
+FAQ
+===
+
+What does a bridge do?
+----------------------
+
+A bridge transparently relays traffic between multiple network interfaces.
+In plain English this means that a bridge connects two or more physical
+Ethernets together to form one bigger (logical) Ethernet.
+
+Is it protocol independent?
+---------------------------
+
+Yes. The bridge knows nothing about protocols, it only sees Ethernet frames.
+As such, the bridging functionality is protocol independent, and there should
+be no trouble relaying 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/include/uapi/linux/if_bridge.h b/include/uapi/linux/if_bridge.h
index f95326fce6bb..7e8ee14afc3a 100644
--- a/include/uapi/linux/if_bridge.h
+++ b/include/uapi/linux/if_bridge.h
@@ -52,6 +52,19 @@
 #define BR_STATE_FORWARDING 3
 #define BR_STATE_BLOCKING 4
 
+/**
+ * struct __bridge_info - the bridge information
+ *
+ * @designated_root: designated root
+ *
+ * @bridge_id: bridge id
+ *
+ * @root_path_cost: root path cost
+ *
+ * @max_age: max age
+ *
+ * @hello_time: hello time
+ */
 struct __bridge_info {
 	__u64 designated_root;
 	__u64 bridge_id;
@@ -74,6 +87,17 @@ struct __bridge_info {
 	__u32 gc_timer_value;
 };
 
+/**
+ * struct __port_info - the bridge port information
+ *
+ * @designated_root: designated root
+ *
+ * @designated_bridge: designated bridge
+ *
+ * @port_id: port id
+ *
+ * @designated_port: designated port
+ */
 struct __port_info {
 	__u64 designated_root;
 	__u64 designated_bridge;
diff --git a/include/uapi/linux/if_link.h b/include/uapi/linux/if_link.h
index ce3117df9cec..277855ccad1e 100644
--- a/include/uapi/linux/if_link.h
+++ b/include/uapi/linux/if_link.h
@@ -461,6 +461,200 @@ enum in6_addr_gen_mode {
 
 /* Bridge section */
 
+/**
+ * DOC: The bridge emum defination
+ *
+ * @IFLA_BR_FORWARD_DELAY:
+ *   set the forwarding delay in seconds, ie the time spent in LISTENING
+ *   state (before moving to LEARNING) and in LEARNING state (before moving
+ *   to FORWARDING). Only relevant if STP is enabled. Valid values are
+ *   between 2 and 30.
+ *
+ * @IFLA_BR_HELLO_TIME:
+ *   set the time in seconds between hello packets sent by the bridge,
+ *   when it is a root bridge or a designated bridges. Only relevant if
+ *   STP is enabled. Valid values are between 1 and 10.
+ *
+ * @IFLA_BR_MAX_AGE:
+ *   set the hello packet timeout, ie the time in seconds until another
+ *   bridge in the spanning tree is assumed to be dead, after reception of
+ *   its last hello message. Only relevant if STP is enabled. Valid values
+ *   are between 6 and 40.
+ *
+ * @IFLA_BR_AGEING_TIME:
+ *   configure the bridge's FDB entries ageing time, ie the number of
+ *   seconds a MAC address will be kept in the FDB after a packet has been
+ *   received from that address. after this time has passed, entries are
+ *   cleaned up.
+ *
+ * @IFLA_BR_STP_STATE:
+ *   turn spanning tree protocol on (*IFLA_BR_STP_STATE* > 0) or off
+ *   (*IFLA_BR_STP_STATE* == 0). for this bridge.
+ *
+ * @IFLA_BR_PRIORITY:
+ *   set this bridge's spanning tree priority, used during STP root bridge
+ *   election.  *IFLA_BR_PRIORITY* is a 16bit unsigned integer.
+ *
+ * @IFLA_BR_VLAN_FILTERING:
+ *   turn VLAN filtering on (*IFLA_BR_VLAN_FILTERING* > 0) or off
+ *   (*IFLA_BR_VLAN_FILTERING* == 0). When disabled, the bridge will not
+ *   consider the VLAN tag when handling packets.
+ *
+ * @IFLA_BR_VLAN_PROTOCOL:
+ *   set the protocol used for VLAN filtering.
+ *
+ * @IFLA_BR_GROUP_FWD_MASK:
+ *   set the group forward mask. This is the bitmask that is applied to
+ *   decide whether to forward incoming frames destined to link-local
+ *   addresses, ie addresses of the form 01:80:C2:00:00:0X (defaults to 0,
+ *   ie the bridge does not forward any linklocal frames coming on this port).
+ *
+ * @IFLA_BR_ROOT_ID:
+ *   Bridge root id.
+ *
+ * @IFLA_BR_BRIDGE_ID:
+ *   Bridge id.
+ *
+ * @IFLA_BR_ROOT_PORT:
+ *   Bridge root port.
+ *
+ * @IFLA_BR_ROOT_PATH_COST:
+ *   Bridge path cost.
+ *
+ * @IFLA_BR_TOPOLOGY_CHANGE:
+ *   Bridge topology change.
+ *
+ * @IFLA_BR_TOPOLOGY_CHANGE_DETECTED:
+ *   Bridge topology change detected.
+ *
+ * @IFLA_BR_HELLO_TIMER:
+ *   Bridge hello timer.
+ *
+ * @IFLA_BR_TCN_TIMER:
+ *   Bridge TCN timer.
+*
+ * @IFLA_BR_TOPOLOGY_CHANGE_TIMER:
+ *   Bridge topology change timer.
+ *
+ * @IFLA_BR_GC_TIMER:
+ *   Bridge gc timer.
+ *
+ * @IFLA_BR_GROUP_ADDR:
+ *   set the MAC address of the multicast group this bridge uses for STP.
+ *   The address must be a link-local address in standard Ethernet MAC address
+ *   format, ie an address of the form 01:80:C2:00:00:0X, with X in [0, 4..f].
+ *
+ * @IFLA_BR_FDB_FLUSH:
+ *   Bridge FDB flush.
+ *
+ * @IFLA_BR_MCAST_ROUTER:
+ *   set bridge's multicast router if IGMP snooping is enabled.
+ *   *IFLA_BR_MCAST_ROUTER* is an integer value having the following meaning:
+ *
+ *     * **0** - disabled.
+ *     * **1** - automatic (queried).
+ *     * **2** - permanently enabled.
+ *
+ * @IFLA_BR_MCAST_SNOOPING:
+ *   turn multicast snooping on (*IFLA_BR_MCAST_SNOOPING* > 0) or off
+ *   (*IFLA_BR_MCAST_SNOOPING* == 0).
+ *
+ * @IFLA_BR_MCAST_QUERY_USE_IFADDR:
+ *   whether to use the bridge's own IP address as source address for IGMP
+ *   queries (*IFLA_BR_MCAST_QUERY_USE_IFADDR* > 0) or the default of 0.0.0.0
+ *   (*IFLA_BR_MCAST_QUERY_USE_IFADDR* == 0).
+ *
+ * @IFLA_BR_MCAST_QUERIER:
+ *   enable (*IFLA_BR_MULTICAST_QUERIER* > 0) or disable
+ *   (*IFLA_BR_MULTICAST_QUERIER* == 0) IGMP querier, ie sending of multicast
+ *   queries by the bridge (default: disabled).
+ *
+ * @IFLA_BR_MCAST_HASH_ELASTICITY:
+ *   set multicast database hash elasticity, ie the maximum chain length in
+ *   the multicast hash table (defaults to 4).
+ *
+ * @IFLA_BR_MCAST_HASH_MAX:
+ *   set maximum size of multicast hash table (defaults to 512, value must
+ *   be a power of 2).
+ *
+ * @IFLA_BR_MCAST_LAST_MEMBER_CNT:
+ *   set multicast last member count, ie the number of queries the bridge
+ *   will send before stopping forwarding a multicast group after a "leave"
+ *   message has been received (defaults to 2).
+ *
+ * @IFLA_BR_MCAST_STARTUP_QUERY_CNT:
+ *   set the number of IGMP queries to send during startup phase (defaults
+ *   to 2).
+ *
+ * @IFLA_BR_MCAST_LAST_MEMBER_INTVL:
+ *   interval between queries to find remaining members of a group, after
+ *   a "leave" message is received.
+ *
+ * @IFLA_BR_MCAST_MEMBERSHIP_INTVL:
+ *   delay after which the bridge will leave a group, if no membership
+ *   reports for this group are received.
+ *
+ * @IFLA_BR_MCAST_QUERIER_INTVL:
+ *   interval between queries sent by other routers. if no queries are seen
+ *   after this delay has passed, the bridge will start to send its own
+ *   queries (as if **IFLA_BR_MCAST_QUERIER_INTVL** was enabled).
+ *
+ * @IFLA_BR_MCAST_QUERY_INTVL:
+ *   interval between queries sent by the bridge after the end of the
+ *   startup phase.
+ *
+ * @IFLA_BR_MCAST_QUERY_RESPONSE_INTVL:
+ *   set the Max Response Time/Maximum Response Delay for IGMP/MLD queries
+ *   sent by the bridge.
+ *
+ * @IFLA_BR_MCAST_STARTUP_QUERY_INTVL:
+ *   interval between queries in the startup phase.
+ *
+ * @IFLA_BR_NF_CALL_IPTABLES:
+ *   enable (*NF_CALL_IPTABLES* > 0) or disable (*NF_CALL_IPTABLES* == 0)
+ *   iptables hooks on the bridge.
+ *
+ * @IFLA_BR_NF_CALL_IP6TABLES:
+ *   enable (*NF_CALL_IP6TABLES* > 0) or disable (*NF_CALL_IP6TABLES* == 0)
+ *   ip6tables hooks on the bridge.
+ *
+ * @IFLA_BR_NF_CALL_ARPTABLES:
+ *   enable (*NF_CALL_ARPTABLES* > 0) or disable (*NF_CALL_ARPTABLES* == 0)
+ *   arptables hooks on the bridge.
+ *
+ * @IFLA_BR_VLAN_DEFAULT_PVID:
+ *   set the default PVID (native/untagged VLAN ID) for this bridge.
+ *
+ * @IFLA_BR_PAD:
+ *   Bridge attr PAD
+ *
+ * @IFLA_BR_VLAN_STATS_ENABLED:
+ *   enable (*IFLA_BR_VLAN_STATS_ENABLED* == 1) or disable
+ *   (*IFLA_BR_VLAN_STATS_ENABLED* == 0) per-VLAN stats accounting.
+ *
+ * @IFLA_BR_MCAST_STATS_ENABLED:
+ *   enable (*IFLA_BR_MCAST_STATS_ENABLED* > 0) or disable
+ *   (*IFLA_BR_MCAST_STATS_ENABLED* == 0) multicast (IGMP/MLD) stats
+ *   accounting.
+ *
+ * @IFLA_BR_MCAST_IGMP_VERSION:
+ *   set the IGMP version.
+ *
+ * @IFLA_BR_MCAST_MLD_VERSION:
+ *   set the MLD version.
+ *
+ * @IFLA_BR_VLAN_STATS_PER_PORT:
+ *   enable (*IFLA_BR_VLAN_STATS_PER_PORT* == 1) or disable
+ *   (*IFLA_BR_VLAN_STATS_PER_PORT* == 0) per-VLAN per-port stats accounting.
+ *   Can be changed only when there are no port VLANs configured.
+ *
+ * @IFLA_BR_MULTI_BOOLOPT:
+ *   Bridge multi bool options.
+ *
+ * @IFLA_BR_MCAST_QUERIER_STATE:
+ *   Bridge mcast querier state.
+ */
+
 enum {
 	IFLA_BR_UNSPEC,
 	IFLA_BR_FORWARD_DELAY,
-- 
2.41.0

Powered by blists - more mailing lists