| Message ID | 20231117093145.1563511-2-liuhangbin@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | Doc: update bridge doc | expand |
On Fri, 17 Nov 2023 17:31:36 +0800 Hangbin Liu wrote: > Add document for IFLA_BR enum so we can use it in > Documentation/networking/bridge.rst. Did you consider writing a YAML spec instead? It's unlikely to be usable today with YNL due to all the classic netlink vs genetlink differences, but Breno is working on rendering the specs in documentation: https://lore.kernel.org/all/20231113202936.242308-1-leitao@debian.org/ so in terms of just documenting attributes it may be good enough. It may possibly be nice to have that documentation folder as "one stop shop" for all of netlink? Absolutely no strong preference on my side, just wanted to make sure you're aware of that work.
On Fri, Nov 17, 2023 at 05:31:36PM +0800, Hangbin Liu wrote: > + * @IFLA_BR_MAX_AGE > + * The hello packet timeout, is the time until another bridge in the No comma between subject and predicate. > + * spanning tree is assumed to be dead, after reception of its last hello > + * message. Only relevant if STP is enabled. > + * > + * The valid values are between (6 * USER_HZ) and (40 * USER_HZ). > + * The default value is (20 * USER_HZ). > + * > + * @IFLA_BR_GROUP_FWD_MASK > + * The group forward mask. This is the bitmask that is applied to > + * decide whether to forward incoming frames destined to link-local > + * addresses. The addresses of the form is 01:80:C2:00:00:0X, which > + * means the bridge does not forward any link-local frames coming on > + * this port). > + * > + * The default value is 0. I'm confused by this description, I believe some of the wording is misplaced. Maybe: The group forwarding mask. This is the bitmask that is applied to decide whether to forward incoming frames destined to link-local addresses (of the form 01:80:C2:00:00:0X). The default value is 0, which means the bridge does not forward any link-local frames coming on this port. > + * @IFLA_BR_VLAN_DEFAULT_PVID > + * The default PVID (native/untagged VLAN ID) for this bridge. I don't think that "native VLAN" is a good description of this. The native VLAN should be the only egress-untagged VLAN of a port. I would say "VLAN ID applied to untagged and priority-tagged incoming packets". > + * > + * The default value is 1. I would also mention that the special value of 0 makes all ports of this bridge not have a PVID by default, which means that they will not accept VLAN-untagged traffic.
On Sun, Nov 19, 2023 at 06:46:25PM +0200, Vladimir Oltean wrote: > On Fri, Nov 17, 2023 at 05:31:36PM +0800, Hangbin Liu wrote: > > + * @IFLA_BR_MAX_AGE > > + * The hello packet timeout, is the time until another bridge in the > > No comma between subject and predicate. > > > + * spanning tree is assumed to be dead, after reception of its last hello > > + * message. Only relevant if STP is enabled. > > + * > > + * The valid values are between (6 * USER_HZ) and (40 * USER_HZ). > > + * The default value is (20 * USER_HZ). > > + * > > + * @IFLA_BR_GROUP_FWD_MASK > > + * The group forward mask. This is the bitmask that is applied to > > + * decide whether to forward incoming frames destined to link-local > > + * addresses. The addresses of the form is 01:80:C2:00:00:0X, which > > + * means the bridge does not forward any link-local frames coming on > > + * this port). > > + * > > + * The default value is 0. Where was the default value of 0 derived from? br_handle_frame() seems to handle 01-80-C2-00-00-00 using is used for BPDUs. 01-80-C2-00-00-01 is explicitly dropped, since its Pause, which i doubt you want to forward. LLDP has some level of processing. Should the default value reflect this? Andrew
On Sun, Nov 19, 2023 at 06:46:25PM +0200, Vladimir Oltean wrote: > On Fri, Nov 17, 2023 at 05:31:36PM +0800, Hangbin Liu wrote: > > + * @IFLA_BR_MAX_AGE > > + * The hello packet timeout, is the time until another bridge in the > > No comma between subject and predicate. > > > + * spanning tree is assumed to be dead, after reception of its last hello > > + * message. Only relevant if STP is enabled. > > + * > > + * The valid values are between (6 * USER_HZ) and (40 * USER_HZ). > > + * The default value is (20 * USER_HZ). > > + * > > + * @IFLA_BR_GROUP_FWD_MASK > > + * The group forward mask. This is the bitmask that is applied to > > + * decide whether to forward incoming frames destined to link-local > > + * addresses. The addresses of the form is 01:80:C2:00:00:0X, which > > + * means the bridge does not forward any link-local frames coming on > > + * this port). > > + * > > + * The default value is 0. > > I'm confused by this description, I believe some of the wording is > misplaced. Maybe: > > The group forwarding mask. This is the bitmask that is applied to > decide whether to forward incoming frames destined to link-local > addresses (of the form 01:80:C2:00:00:0X). > > The default value is 0, which means the bridge does not forward any > link-local frames coming on this port. > > > + * @IFLA_BR_VLAN_DEFAULT_PVID > > + * The default PVID (native/untagged VLAN ID) for this bridge. > > I don't think that "native VLAN" is a good description of this. > The native VLAN should be the only egress-untagged VLAN of a port. > > I would say "VLAN ID applied to untagged and priority-tagged incoming > packets". > > > + * > > + * The default value is 1. > > I would also mention that the special value of 0 makes all ports of > this bridge not have a PVID by default, which means that they will > not accept VLAN-untagged traffic. Thanks for the comments. I will update it in next version. Hangbin
On Sun, Nov 19, 2023 at 07:21:25PM +0100, Andrew Lunn wrote: > > > + * @IFLA_BR_GROUP_FWD_MASK > > > + * The group forward mask. This is the bitmask that is applied to > > > + * decide whether to forward incoming frames destined to link-local > > > + * addresses. The addresses of the form is 01:80:C2:00:00:0X, which > > > + * means the bridge does not forward any link-local frames coming on > > > + * this port). > > > + * > > > + * The default value is 0. > > Where was the default value of 0 derived from? I doc it as 0 because I saw in br_dev_setup() br->stp_enabled = BR_NO_STP; br->group_fwd_mask = BR_GROUPFWD_DEFAULT; br->group_fwd_mask_required = BR_GROUPFWD_DEFAULT; and #define BR_GROUPFWD_DEFAULT 0 Thanks Hangbin > > br_handle_frame() seems to handle 01-80-C2-00-00-00 using is used for > BPDUs. 01-80-C2-00-00-01 is explicitly dropped, since its Pause, which > i doubt you want to forward. LLDP has some level of processing. > > Should the default value reflect this? > > Andrew
On Sat, Nov 18, 2023 at 09:45:25AM -0800, Jakub Kicinski wrote: > On Fri, 17 Nov 2023 17:31:36 +0800 Hangbin Liu wrote: > > Add document for IFLA_BR enum so we can use it in > > Documentation/networking/bridge.rst. > > Did you consider writing a YAML spec instead? > > It's unlikely to be usable today with YNL due to all the classic > netlink vs genetlink differences, but Breno is working on rendering > the specs in documentation: > > https://lore.kernel.org/all/20231113202936.242308-1-leitao@debian.org/ > > so in terms of just documenting attributes it may be good enough. > It may possibly be nice to have that documentation folder as "one > stop shop" for all of netlink? Thanks for this info. Will the YAML spec be build by the document team? I'd prefer all the doc shows in https://www.kernel.org/doc/html/latest/ so users could find the doc easily. It would be good if there is an example in Documentation/netlink/specs/ (when the patch applied) so I can take as a reference :) Thanks Hangbin > > Absolutely no strong preference on my side, just wanted to make > sure you're aware of that work.
On Tue, 21 Nov 2023 11:28:30 +0800 Hangbin Liu wrote: > Thanks for this info. Will the YAML spec be build by the document team? > I'd prefer all the doc shows in https://www.kernel.org/doc/html/latest/ > so users could find the doc easily. That's the plan, it will render under ${base}/networking/netlink_spec/ > It would be good if there is an example in Documentation/netlink/specs/ (when > the patch applied) so I can take as a reference :) All the operations, attributes etc in the spec accept a "doc" property. The html output is just a rendering of those doc strings. So the existing specs are already kind of examples, although they don't have doc strings in very many places so the output looks a bit empty :(
On Tue, Nov 21, 2023 at 08:21:27AM -0800, Jakub Kicinski wrote: > On Tue, 21 Nov 2023 11:28:30 +0800 Hangbin Liu wrote: > > Thanks for this info. Will the YAML spec be build by the document team? > > I'd prefer all the doc shows in https://www.kernel.org/doc/html/latest/ > > so users could find the doc easily. > > That's the plan, it will render under ${base}/networking/netlink_spec/ > > > It would be good if there is an example in Documentation/netlink/specs/ (when > > the patch applied) so I can take as a reference :) > > All the operations, attributes etc in the spec accept a "doc" property. > The html output is just a rendering of those doc strings. > So the existing specs are already kind of examples, although they don't > have doc strings in very many places so the output looks a bit empty :( Thanks, I will investigate how to convert the bridge yaml. But next week I will be in vacation. So I may post another patch after vacation. Regards Hangbin
diff --git a/include/uapi/linux/if_link.h b/include/uapi/linux/if_link.h index 8181ef23a7a2..8debf1c62a6d 100644 --- a/include/uapi/linux/if_link.h +++ b/include/uapi/linux/if_link.h @@ -461,6 +461,284 @@ enum in6_addr_gen_mode { /* Bridge section */ +/** + * DOC: Bridge enum definition + * + * please *note* that the timer values in the following section are expected + * in clock_t format, which is seconds multiplied by USER_HZ (generally + * defined as 100). + * + * @IFLA_BR_FORWARD_DELAY + * The bridge forwarding delay is the time spent in LISTENING state + * (before moving to LEARNING) and in LEARNING state (before moving + * to FORWARDING). Only relevant if STP is enabled. + * + * The valid values are between (2 * USER_HZ) and (30 * USER_HZ). + * The default value is (15 * USER_HZ). + * + * @IFLA_BR_HELLO_TIME + * The time between hello packets sent by the bridge, when it is a root + * bridge or a designated bridge. Only relevant if STP is enabled. + * + * The valid values are between (1 * USER_HZ) and (10 * USER_HZ). + * The default value is (2 * USER_HZ). + * + * @IFLA_BR_MAX_AGE + * The hello packet timeout, is the time 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. + * + * The valid values are between (6 * USER_HZ) and (40 * USER_HZ). + * The default value is (20 * USER_HZ). + * + * @IFLA_BR_AGEING_TIME + * Configure the bridge's FDB entries aging time. It is the time 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. + * Allow values outside the 802.1 standard specification for special cases: + * + * * 0 - entry never ages (all permanent) + * * 1 - entry disappears (no persistence) + * + * The default value is (300 * USER_HZ). + * + * @IFLA_BR_STP_STATE + * Turn spanning tree protocol on (*IFLA_BR_STP_STATE* > 0) or off + * (*IFLA_BR_STP_STATE* == 0) for this bridge. + * + * The default value is 0 (disabled). + * + * @IFLA_BR_PRIORITY + * set this bridge's spanning tree priority, used during STP root bridge + * election. + * + * The valid values are between 0 and 65535. + * + * @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. + * + * The default value is 0 (disabled). + * + * @IFLA_BR_VLAN_PROTOCOL + * Set the protocol used for VLAN filtering. + * + * The valid values are 0x8100(802.1Q) or 0x88A8(802.1AD). The default value + * is 0x8100(802.1Q). + * + * @IFLA_BR_GROUP_FWD_MASK + * The group forward mask. This is the bitmask that is applied to + * decide whether to forward incoming frames destined to link-local + * addresses. The addresses of the form is 01:80:C2:00:00:0X, which + * means the bridge does not forward any link-local frames coming on + * this port). + * + * The default value is 0. + * + * @IFLA_BR_ROOT_ID + * The bridge root id, read only. + * + * @IFLA_BR_BRIDGE_ID + * The bridge id, read only. + * + * @IFLA_BR_ROOT_PORT + * The bridge root port, read only. + * + * @IFLA_BR_ROOT_PATH_COST + * The bridge root path cost, read only. + * + * @IFLA_BR_TOPOLOGY_CHANGE + * The bridge topology change, read only. + * + * @IFLA_BR_TOPOLOGY_CHANGE_DETECTED + * The bridge topology change detected, read only. + * + * @IFLA_BR_HELLO_TIMER + * The bridge hello timer, read only. + * + * @IFLA_BR_TCN_TIMER + * The bridge tcn timer, read only. + * + * @IFLA_BR_TOPOLOGY_CHANGE_TIMER + * The bridge topology change timer, read only. + * + * @IFLA_BR_GC_TIMER + * The bridge gc timer, read only. + * + * @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. It is an address of the form 01:80:C2:00:00:0X, with X in [0, 4..f]. + * + * The default value is 0. + * + * @IFLA_BR_FDB_FLUSH + * Flush bridge's fdb dynamic entries. + * + * @IFLA_BR_MCAST_ROUTER + * Set bridge's multicast router if IGMP snooping is enabled. + * The valid values are: + * + * * 0 - disabled. + * * 1 - automatic (queried). + * * 2 - permanently enabled. + * + * The default value is 1. + * + * @IFLA_BR_MCAST_SNOOPING + * Turn multicast snooping on (*IFLA_BR_MCAST_SNOOPING* > 0) or off + * (*IFLA_BR_MCAST_SNOOPING* == 0). + * + * The default value is 1. + * + * @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). + * + * The default value is 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. + * + * The default value is 0 (disabled). + * + * @IFLA_BR_MCAST_HASH_ELASTICITY + * Set multicast database hash elasticity, It is the maximum chain length in + * the multicast hash table. This attribute is *deprecated* and the value + * is always 16. + * + * @IFLA_BR_MCAST_HASH_MAX + * Set maximum size of the multicast hash table + * + * The default value is 4096, the value must be a power of 2. + * + * @IFLA_BR_MCAST_LAST_MEMBER_CNT + * The Last Member Query Count is the number of Group-Specific Queries + * sent before the router assumes there are no local members. The Last + * Member Query Count is also the number of Group-and-Source-Specific + * Queries sent before the router assumes there are no listeners for a + * particular source. + * + * The default value is 2. + * + * @IFLA_BR_MCAST_STARTUP_QUERY_CNT + * The Startup Query Count is the number of Queries sent out on startup, + * separated by the Startup Query Interval. + * + * The default value is 2. + * + * @IFLA_BR_MCAST_LAST_MEMBER_INTVL + * The Last Member Query Interval is the Max Response Time inserted into + * Group-Specific Queries sent in response to Leave Group messages, and + * is also the amount of time between Group-Specific Query messages. + * + * The default value is (1 * USER_HZ). + * + * @IFLA_BR_MCAST_MEMBERSHIP_INTVL + * The interval after which the bridge will leave a group, if no membership + * reports for this group are received. + * + * The default value is (260 * USER_HZ). + * + * @IFLA_BR_MCAST_QUERIER_INTVL + * The 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). + * + * The default value is (255 * USER_HZ). + * + * @IFLA_BR_MCAST_QUERY_INTVL + * The Query Interval is the interval between General Queries sent by + * the Querier. + * + * The default value is (125 * USER_HZ). The minimum value is (1 * USER_HZ). + * + * @IFLA_BR_MCAST_QUERY_RESPONSE_INTVL + * The Max Response Time used to calculate the Max Resp Code inserted + * into the periodic General Queries. + * + * The default value is (10 * USER_HZ). + * + * @IFLA_BR_MCAST_STARTUP_QUERY_INTVL + * The interval between queries in the startup phase. + * + * The default value is (125 * USER_HZ) / 4. The minimum value is (1 * USER_HZ). + * + * @IFLA_BR_NF_CALL_IPTABLES + * Enable (*NF_CALL_IPTABLES* > 0) or disable (*NF_CALL_IPTABLES* == 0) + * iptables hooks on the bridge. + * + * The default value is 0 (disabled). + * + * @IFLA_BR_NF_CALL_IP6TABLES + * Enable (*NF_CALL_IP6TABLES* > 0) or disable (*NF_CALL_IP6TABLES* == 0) + * ip6tables hooks on the bridge. + * + * The default value is 0 (disabled). + * + * @IFLA_BR_NF_CALL_ARPTABLES + * Enable (*NF_CALL_ARPTABLES* > 0) or disable (*NF_CALL_ARPTABLES* == 0) + * arptables hooks on the bridge. + * + * The default value is 0 (disabled). + * + * @IFLA_BR_VLAN_DEFAULT_PVID + * The default PVID (native/untagged VLAN ID) for this bridge. + * + * The default value is 1. + * + * @IFLA_BR_PAD + * Bridge attribute padding type for netlink message. + * + * @IFLA_BR_VLAN_STATS_ENABLED + * Enable (*IFLA_BR_VLAN_STATS_ENABLED* == 1) or disable + * (*IFLA_BR_VLAN_STATS_ENABLED* == 0) per-VLAN stats accounting. + * + * The default value is 0 (disabled). + * + * @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. + * + * The default value is 0 (disabled). + * + * @IFLA_BR_MCAST_IGMP_VERSION + * Set the IGMP version. + * + * The valid values are 2 and 3. The default value is 2. + * + * @IFLA_BR_MCAST_MLD_VERSION + * Set the MLD version. + * + * The valid values are 1 and 2. The default value is 1. + * + * @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. + * + * The default value is 0 (disabled). + * + * @IFLA_BR_MULTI_BOOLOPT + * The multi_boolopt is used to control new boolean options to avoid adding + * new netlink attributes. + * + * @IFLA_BR_MCAST_QUERIER_STATE + * Bridge mcast querier states, read only. + * + * @IFLA_BR_FDB_N_LEARNED + * The number of dynamically learned FDB entries for the current bridge, + * read only. + * + * @IFLA_BR_FDB_MAX_LEARNED + * Set the number of max dynamically learned FDB entries for the current + * bridge. + */ enum { IFLA_BR_UNSPEC, IFLA_BR_FORWARD_DELAY,
Add document for IFLA_BR enum so we can use it in Documentation/networking/bridge.rst. Signed-off-by: Hangbin Liu <liuhangbin@gmail.com> --- include/uapi/linux/if_link.h | 278 +++++++++++++++++++++++++++++++++++ 1 file changed, 278 insertions(+)