On Wed, Jan 24, 2024 at 4:28 AM David Vernet <void@xxxxxxxxxxxxx> wrote: > > On Tue, Jan 23, 2024 at 11:27:15PM +0800, Yafang Shao wrote: > > This patch adds the document for the newly added cpumask iterator > > kfuncs. > > > > Signed-off-by: Yafang Shao <laoar.shao@xxxxxxxxx> > > --- > > Documentation/bpf/cpumasks.rst | 17 +++++++++++++++++ > > 1 file changed, 17 insertions(+) > > > > diff --git a/Documentation/bpf/cpumasks.rst b/Documentation/bpf/cpumasks.rst > > index b5d47a04da5d..523f377afc6e 100644 > > --- a/Documentation/bpf/cpumasks.rst > > +++ b/Documentation/bpf/cpumasks.rst > > @@ -372,6 +372,23 @@ used. > > .. _tools/testing/selftests/bpf/progs/cpumask_success.c: > > https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/bpf/progs/cpumask_success.c > > > > +3.3 cpumask iterator > > +-------------------- > > + > > +The cpumask iterator enables the iteration of percpu data, such as runqueues, > > +system_group_pcpu, and more. > > + > > +.. kernel-doc:: kernel/bpf/cpumask.c > > + :identifiers: bpf_iter_cpumask_new bpf_iter_cpumask_next > > + bpf_iter_cpumask_destroy > > Practically speaking I don't think documenting these kfuncs is going to > be super useful to most users. I expect we'd wrap this in a macro, just > like we do for bpf_for(), and I think it would be much more useful to a > reader to show how they can use such a macro with a full, self-contained > example rather than just embedding the doxygen comment here. Agree. > > > + > > +---- > > + > > +Some example usages of the cpumask iterator can be found in > > +`tools/testing/selftests/bpf/progs/test_cpumask_iter.c`_. > > + > > +.. _tools/testing/selftests/bpf/progs/test_cpumask_iter.c: > > + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/bpf/progs/test_cpumask_iter.c > > I know it's typical for BPF to link to selftests like this, but I > personally strongly prefer actual examples in the documentation. We have > examples elsewhere in this file, so can we please do the same here? will do it. -- Regards Yafang