Re: [Bridge] [Question] Any plan to write/update the bridge doc?
On Mon, Apr 24, 2023 at 02:28:00PM -0700, Jakub Kicinski wrote: > On Mon, 24 Apr 2023 17:25:08 +0800 Hangbin Liu wrote: > > Maybe someone already has asked. The only official Linux bridge document I > > got is a very ancient wiki page[1] or the ip link man page[2][3]. As there > > are > > many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel > > document about each parameter? The parameter showed in ip link page seems > > a little brief. > > > > I'd like to help do this work. But apparently neither my English nor my > > understanding of the code is good enough. Anyway, if you want, I can help > > write a draft version first and you (bridge maintainers) keep working on > > this. > > > > [1] https://wiki.linuxfoundation.org/networking/bridge > > [2] https://man7.org/linux/man-pages/man8/bridge.8.html > > [3] https://man7.org/linux/man-pages/man8/ip-link.8.html > > Sounds like we have 2 votes for the CLI man pages but I'd like to > register a vote for in-kernel documentation. > > I work at a large company so my perspective may differ but from what > I see: > > - users who want to call the kernel API should not have to look at >the CLI's man > - man pages use archaic and arcane markup, I'd like to know how many >people actually know how it works and how many copy / paste / look; >ReST is prevalent, simple and commonly understood +1 for the obscure man page syntax. I can only do copy/paste when update it.. > - in-kernel docs are rendered on the web as soon as they hit linux-next > - we can make sure documentation is provided with the kernel changes, >in an ideal world it doesn't matter but in practice the CLI support >may never happen (no to mention that iproute does not hold all CLI) Yes. I saw bpf code add the doc in the header file (include/uapi/linux/bpf.h) and generate to syscall page[1] or man page[2] directly. Another example is the statistics.rst document, which takes *struct rtnl_link_stats64* description drectly from the if_link.h. This should save a lot works to maintain another file in Documentation. Maybe we can strive in this direction? For example, we can just add descriptions for the enum in if_bridge.h and if_link.h when add new features. > > Obviously if Stephen and Ido prefer to document the bridge CLI that's > perfectly fine, it's their call :) For new sections of uAPI, however, > I personally find in-kernel docs superior. I understand the hard work to maintain docs in 3 different places with different syntax (ip-link, bridge, in-kernel). Since we will sync the uapi headers from kernel to iproute2. Can we use the similar way like kernel does in iproute2. i.e. Link the header file's description in a document and convert it to man page via rst2man? With this way we only need to maintain the doc in 1 place, the kernel uapi headers. NOTE: there may still need some adjustment in the iproute2 man page when add new arguments. [1] https://docs.kernel.org/userspace-api/ebpf/syscall.html [2] https://man7.org/linux/man-pages/man7/bpf-helpers.7.html [3] https://docs.kernel.org/networking/statistics.html Thanks Hangbin
Re: [Bridge] [Question] Any plan to write/update the bridge doc?
On Mon, 24 Apr 2023 14:28:00 -0700 Jakub Kicinski wrote: > On Mon, 24 Apr 2023 17:25:08 +0800 Hangbin Liu wrote: > > Maybe someone already has asked. The only official Linux bridge document I > > got is a very ancient wiki page[1] or the ip link man page[2][3]. As there > > are > > many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel > > document about each parameter? The parameter showed in ip link page seems > > a little brief. > > > > I'd like to help do this work. But apparently neither my English nor my > > understanding of the code is good enough. Anyway, if you want, I can help > > write a draft version first and you (bridge maintainers) keep working on > > this. > > > > [1] https://wiki.linuxfoundation.org/networking/bridge > > [2] https://man7.org/linux/man-pages/man8/bridge.8.html > > [3] https://man7.org/linux/man-pages/man8/ip-link.8.html > > Sounds like we have 2 votes for the CLI man pages but I'd like to > register a vote for in-kernel documentation. > > I work at a large company so my perspective may differ but from what > I see: > > - users who want to call the kernel API should not have to look at >the CLI's man Internal Kernel API's are not stable. So documentation is only the auto generated kernel docs. There is an effort to cover netlink API's with YAML. Bridge could/should be part of that. > - man pages use archaic and arcane markup, I'd like to know how many >people actually know how it works and how many copy / paste / look; >ReST is prevalent, simple and commonly understood Yes, but that is what distributions want. > - in-kernel docs are rendered on the web as soon as they hit linux-next > - we can make sure documentation is provided with the kernel changes, >in an ideal world it doesn't matter but in practice the CLI support >may never happen (no to mention that iproute does not hold all CLI) > > Obviously if Stephen and Ido prefer to document the bridge CLI that's > perfectly fine, it's their call :) For new sections of uAPI, however, > I personally find in-kernel docs superior. The in-kernel documents usually only cover the architecture and motivation. What/why/how... Not the user visible public API's.
Re: [Bridge] [Question] Any plan to write/update the bridge doc?
On Mon, 24 Apr 2023 17:25:08 +0800 Hangbin Liu wrote: > Maybe someone already has asked. The only official Linux bridge document I > got is a very ancient wiki page[1] or the ip link man page[2][3]. As there are > many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel > document about each parameter? The parameter showed in ip link page seems > a little brief. > > I'd like to help do this work. But apparently neither my English nor my > understanding of the code is good enough. Anyway, if you want, I can help > write a draft version first and you (bridge maintainers) keep working on this. > > [1] https://wiki.linuxfoundation.org/networking/bridge > [2] https://man7.org/linux/man-pages/man8/bridge.8.html > [3] https://man7.org/linux/man-pages/man8/ip-link.8.html Sounds like we have 2 votes for the CLI man pages but I'd like to register a vote for in-kernel documentation. I work at a large company so my perspective may differ but from what I see: - users who want to call the kernel API should not have to look at the CLI's man - man pages use archaic and arcane markup, I'd like to know how many people actually know how it works and how many copy / paste / look; ReST is prevalent, simple and commonly understood - in-kernel docs are rendered on the web as soon as they hit linux-next - we can make sure documentation is provided with the kernel changes, in an ideal world it doesn't matter but in practice the CLI support may never happen (no to mention that iproute does not hold all CLI) Obviously if Stephen and Ido prefer to document the bridge CLI that's perfectly fine, it's their call :) For new sections of uAPI, however, I personally find in-kernel docs superior.
Re: [Bridge] [Question] Any plan to write/update the bridge doc?
On Mon, 24 Apr 2023 18:46:53 +0300 Ido Schimmel wrote: > On Mon, Apr 24, 2023 at 05:25:08PM +0800, Hangbin Liu wrote: > > Hi, > > > > Maybe someone already has asked. The only official Linux bridge document I > > got is a very ancient wiki page[1] or the ip link man page[2][3]. As there > > are > > many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel > > document about each parameter? The parameter showed in ip link page seems > > a little brief. > > I suggest improving the man pages instead of adding kernel > documentation. The man pages are the most up to date resource and > therefore the one users probably refer to the most. Also, it's already > quite annoying to patch both "ip-link" and "bridge" man pages when > adding bridge port options. Adding a third document and making sure all > three resources are patched would be a nightmare... > > > > > I'd like to help do this work. But apparently neither my English nor my > > understanding of the code is good enough. Anyway, if you want, I can help > > write a draft version first and you (bridge maintainers) keep working on > > this. > > I can help reviewing man page patches if you want. I'm going to send > some soon. Will copy you. > > > > > [1] https://wiki.linuxfoundation.org/networking/bridge > > [2] https://man7.org/linux/man-pages/man8/bridge.8.html > > [3] https://man7.org/linux/man-pages/man8/ip-link.8.html > > > > Thanks > > Hangbin Yes, please update the iproute2 man pages. From there, I can make the old wiki just be a reference to them. And Michael will pickup the man7.org versions from the current iproute2. The iproute2 git tree is single source of current documentation please.
Re: [Bridge] [Question] Any plan to write/update the bridge doc?
On Mon, Apr 24, 2023 at 05:25:08PM +0800, Hangbin Liu wrote: > Hi, > > Maybe someone already has asked. The only official Linux bridge document I > got is a very ancient wiki page[1] or the ip link man page[2][3]. As there are > many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel > document about each parameter? The parameter showed in ip link page seems > a little brief. I suggest improving the man pages instead of adding kernel documentation. The man pages are the most up to date resource and therefore the one users probably refer to the most. Also, it's already quite annoying to patch both "ip-link" and "bridge" man pages when adding bridge port options. Adding a third document and making sure all three resources are patched would be a nightmare... > > I'd like to help do this work. But apparently neither my English nor my > understanding of the code is good enough. Anyway, if you want, I can help > write a draft version first and you (bridge maintainers) keep working on this. I can help reviewing man page patches if you want. I'm going to send some soon. Will copy you. > > [1] https://wiki.linuxfoundation.org/networking/bridge > [2] https://man7.org/linux/man-pages/man8/bridge.8.html > [3] https://man7.org/linux/man-pages/man8/ip-link.8.html > > Thanks > Hangbin
Re: [Bridge] [PATCH v2 net] net: bridge: switchdev: don't notify FDB entries with "master dynamic"
On Mon, Apr 24, 2023 at 15:26, Vladimir Oltean wrote: > > Obviously we have not reached the end of that plan, and net-next is closed > now. Seems to me that net-next is open. Maybe it will close soon.
Re: [Bridge] [PATCH v2 net] net: bridge: switchdev: don't notify FDB entries with "master dynamic"
On Mon, Apr 24, 2023 at 15:26, Vladimir Oltean wrote: > On Sun, Apr 23, 2023 at 10:47:15AM +0200, Hans Schultz wrote: >> I do not understand this patch. It seems to me that it basically blocks >> any future use of dynamic fdb entries from userspace towards drivers. >> >> I would have expected that something would be done in the DSA layer, >> where (switchcore) drivers would be able to set some flags to indicate >> which features are supported by the driver, including non-static >> fdb entries. But as the placement here is earlier in the datapath from >> userspace towards drivers it's not possible to do any such thing in the >> DSA layer wrt non-static fdb entries. > > As explained too many times already in the thread here: > https://patchwork.kernel.org/project/netdevbpf/patch/20230318141010.513424-3-net...@kapio-technology.com/ > the plan is: Ahh yes thanks, I see the comment you wrote on march the 27th.
Re: [Bridge] [PATCH v2 net] net: bridge: switchdev: don't notify FDB entries with "master dynamic"
On Sun, Apr 23, 2023 at 10:47:15AM +0200, Hans Schultz wrote:
> I do not understand this patch. It seems to me that it basically blocks
> any future use of dynamic fdb entries from userspace towards drivers.
>
> I would have expected that something would be done in the DSA layer,
> where (switchcore) drivers would be able to set some flags to indicate
> which features are supported by the driver, including non-static
> fdb entries. But as the placement here is earlier in the datapath from
> userspace towards drivers it's not possible to do any such thing in the
> DSA layer wrt non-static fdb entries.
As explained too many times already in the thread here:
https://patchwork.kernel.org/project/netdevbpf/patch/20230318141010.513424-3-net...@kapio-technology.com/
the plan is:
| Just like commit 6ab4c3117aec ("net: bridge: don't notify switchdev for
| local FDB addresses"), we could deny that for stable kernels, and add
| the correct interpretation of the flag in net-next.
Obviously we have not reached the end of that plan, and net-next is closed now.
[Bridge] [Question] Any plan to write/update the bridge doc?
Hi, Maybe someone already has asked. The only official Linux bridge document I got is a very ancient wiki page[1] or the ip link man page[2][3]. As there are many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel document about each parameter? The parameter showed in ip link page seems a little brief. I'd like to help do this work. But apparently neither my English nor my understanding of the code is good enough. Anyway, if you want, I can help write a draft version first and you (bridge maintainers) keep working on this. [1] https://wiki.linuxfoundation.org/networking/bridge [2] https://man7.org/linux/man-pages/man8/bridge.8.html [3] https://man7.org/linux/man-pages/man8/ip-link.8.html Thanks Hangbin
