@@ -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@nvidia.com> and
+Nikolay Aleksandrov <razor@blackwall.org>. Bridge bugs and enhancements
+are discussed on the linux-netdev mailing list netdev@vger.kernel.org and
+bridge@lists.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
@@ -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;
@@ -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,
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@gmail.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(-)