On Wed, Feb 17, 2021 at 5:55 AM Toke Høiland-Jørgensen <toke@xxxxxxxxxx> wrote: > > Joe Stringer <joe@xxxxxxxxxxx> writes: > > Given the relative success of the process around bpf-helpers(7) to > > encourage developers to document their user-facing changes, in this > > patch series I explore applying this technique to bpf(2) as well. > > Unfortunately, even with bpf(2) being so out-of-date, there is still a > > lot of content to convert over. In particular, I've identified at least > > the following aspects of the bpf syscall which could individually be > > generated from separate documentation in the header: > > * BPF syscall commands > > * BPF map types > > * BPF program types > > * BPF attachment points > > Does this also include program subtypes (AKA expected_attach_type?) I seem to have left my lawyerly "including, but not limited to..." language at home today ;-) . Of course, I can add that to the list. > > At this point I'd like to put this out for comments. In my mind, the > > ideal eventuation of this work would be to extend kernel UAPI headers > > such that each of the categories I had listed above (commands, maps, > > progs, hooks) have dedicated documentation in the kernel tree, and that > > developers must update the comments in the headers to document the APIs > > prior to patch acceptance, and that we could auto-generate the latest > > version of the bpf(2) manual pages based on a few static description > > sections combined with the dynamically-generated output from the header. > > I like the approach, and I don't think it's too onerous to require > updates to the documentation everywhere like we (as you note) already do > for helpers. > > So with that, please feel free to add my enthusiastic: > > Acked-by: Toke Høiland-Jørgensen <toke@xxxxxxxxxx> Thanks Toke.
