Hi Peter/John,

There were several updates at kernel-doc upstream fixing bugs,
doing cleanups and a couple of improvements.

Better to keep QEMU in sync with such changes.

Worth mentioning that we did some changes on Linux at the
kernel-doc.py script itself, to avoid Kernel build to crash
with too old Python versions, as there docs build is a
separate target, and python >= 3.6 is a new requirement
there.

On kernel, if python < 3.6, it will simply ignore docs
build (emitting a warning).

I opted to not backport such changes, but if you prefer
doing that, I can do that on a v2.

---

For now, I opted to keep kernel-doc libraries at the same
directory as before - e.g. at scripts/lib/kdoc. On Linux,
we ended moving it to tools/lib/python/kdoc. It could make
sense to move it on QEMU too, as it makes a little bit
easier to keep things in sync.

What do you think?

Mauro Carvalho Chehab (1):
  kernel-doc.py: sync with upstream Kernel v6.19-rc4

 scripts/lib/kdoc/kdoc_files.py  |  11 +-
 scripts/lib/kdoc/kdoc_item.py   |   3 +-
 scripts/lib/kdoc/kdoc_output.py |  93 +++-
 scripts/lib/kdoc/kdoc_parser.py | 897 ++++++++++++++++----------------
 scripts/lib/kdoc/kdoc_re.py     |  24 +-
 5 files changed, 554 insertions(+), 474 deletions(-)

-- 
2.52.0

On Tue, 6 Jan 2026 at 16:38, Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> Hi Peter/John,
>
> There were several updates at kernel-doc upstream fixing bugs,
> doing cleanups and a couple of improvements.
>
> Better to keep QEMU in sync with such changes.
>
> Worth mentioning that we did some changes on Linux at the
> kernel-doc.py script itself, to avoid Kernel build to crash
> with too old Python versions, as there docs build is a
> separate target, and python >= 3.6 is a new requirement
> there.
>
> On kernel, if python < 3.6, it will simply ignore docs
> build (emitting a warning).
>
> I opted to not backport such changes, but if you prefer
> doing that, I can do that on a v2.
> ---
>
> For now, I opted to keep kernel-doc libraries at the same
> directory as before - e.g. at scripts/lib/kdoc. On Linux,
> we ended moving it to tools/lib/python/kdoc. It could make
> sense to move it on QEMU too, as it makes a little bit
> easier to keep things in sync.
>
> What do you think?

Hi; thanks for doing this backport. I checked that the output
with this patch applied is still the same as with the old
kernel-doc, and eyeballed the diffs between our kernel-doc
and the Linux version, to confirm that we have kept our two
minor QEMU-specific modifications and haven't missed anything
from Linux's version that we ought to have. So:

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

On your two questions:

(1) As Dan says, QEMU already enforces a new enough
Python version, so we don't need to handle 3.6. I think
the main thing driving a choice to backport or not those
changes would be simply keeping in sync with Linux's
version of the script so we don't diverge. We want to
make future re-syncing of the script as easy as possible.

(2) Regarding the location of the kernel-doc libraries:
we seem to have two things here, possibly in tension:
 - we don't want to gratuitously diverge from Linux
 - QEMU's directory hierarchy is not the kernel's

In particular, I'm not sure tools/ is where we would
naturally put python libraries used during the build
process. Maybe that would be python/ for us, but I defer
to John or another Python expert on that.

Hopefully this would not be a major divergence because it
would just be "our python path happens to be different
from the one the kernel uses, but the actual python code
just imports the modules by name and doesn't need to know
their specific path" ?

Personally I am OK with our taking this patch as-is
and dealing with the above questions (or not) as a
followon thing, if nobody has any objections to that
approach.

thanks
-- PMM

On Tue, Jan 13, 2026 at 11:44:51AM +0000, Peter Maydell wrote:
> On Tue, 6 Jan 2026 at 16:38, Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > Hi Peter/John,
> >
> > There were several updates at kernel-doc upstream fixing bugs,
> > doing cleanups and a couple of improvements.
> >
> > Better to keep QEMU in sync with such changes.
> >
> > Worth mentioning that we did some changes on Linux at the
> > kernel-doc.py script itself, to avoid Kernel build to crash
> > with too old Python versions, as there docs build is a
> > separate target, and python >= 3.6 is a new requirement
> > there.
> >
> > On kernel, if python < 3.6, it will simply ignore docs
> > build (emitting a warning).
> >
> > I opted to not backport such changes, but if you prefer
> > doing that, I can do that on a v2.
> > ---
> >
> > For now, I opted to keep kernel-doc libraries at the same
> > directory as before - e.g. at scripts/lib/kdoc. On Linux,
> > we ended moving it to tools/lib/python/kdoc. It could make
> > sense to move it on QEMU too, as it makes a little bit
> > easier to keep things in sync.
> >
> > What do you think?
> 
> Hi; thanks for doing this backport. I checked that the output
> with this patch applied is still the same as with the old
> kernel-doc, and eyeballed the diffs between our kernel-doc
> and the Linux version, to confirm that we have kept our two
> minor QEMU-specific modifications and haven't missed anything
> from Linux's version that we ought to have. So:
> 
> Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
> 
> On your two questions:
> 
> (1) As Dan says, QEMU already enforces a new enough
> Python version, so we don't need to handle 3.6. I think
> the main thing driving a choice to backport or not those
> changes would be simply keeping in sync with Linux's
> version of the script so we don't diverge. We want to
> make future re-syncing of the script as easy as possible.
> 
> (2) Regarding the location of the kernel-doc libraries:
> we seem to have two things here, possibly in tension:
>  - we don't want to gratuitously diverge from Linux
>  - QEMU's directory hierarchy is not the kernel's
> 
> In particular, I'm not sure tools/ is where we would
> naturally put python libraries used during the build
> process. Maybe that would be python/ for us, but I defer
> to John or another Python expert on that.

I tend to see the 'python' directory as being for stuff we formally
maintain as a python API for use by multiple internal consumers.

This is just a bunch of helper files exclusively for use by the kernel-doc
tool, and so the scripts/ directory is a decent fit for it, given that this
dir is for a collection of arbitary supporting tools & scripts.

As precedent, see the tracetool, which keeps all its helpers under
scripts/tracetool too.

TL;DR: I would not want to see a new top level tools/ directory
created, and don't think it fits in python/ either; scripts/ is
a fine home.

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

On Tue, Jan 13, 2026 at 7:09 AM Daniel P. Berrangé <berrange@redhat.com> wrote:
>
> On Tue, Jan 13, 2026 at 11:44:51AM +0000, Peter Maydell wrote:
> > On Tue, 6 Jan 2026 at 16:38, Mauro Carvalho Chehab
> > <mchehab+huawei@kernel.org> wrote:
> > >
> > > Hi Peter/John,
> > >
> > > There were several updates at kernel-doc upstream fixing bugs,
> > > doing cleanups and a couple of improvements.
> > >
> > > Better to keep QEMU in sync with such changes.
> > >
> > > Worth mentioning that we did some changes on Linux at the
> > > kernel-doc.py script itself, to avoid Kernel build to crash
> > > with too old Python versions, as there docs build is a
> > > separate target, and python >= 3.6 is a new requirement
> > > there.
> > >
> > > On kernel, if python < 3.6, it will simply ignore docs
> > > build (emitting a warning).
> > >
> > > I opted to not backport such changes, but if you prefer
> > > doing that, I can do that on a v2.
> > > ---
> > >
> > > For now, I opted to keep kernel-doc libraries at the same
> > > directory as before - e.g. at scripts/lib/kdoc. On Linux,
> > > we ended moving it to tools/lib/python/kdoc. It could make
> > > sense to move it on QEMU too, as it makes a little bit
> > > easier to keep things in sync.
> > >
> > > What do you think?
> >
> > Hi; thanks for doing this backport. I checked that the output
> > with this patch applied is still the same as with the old
> > kernel-doc, and eyeballed the diffs between our kernel-doc
> > and the Linux version, to confirm that we have kept our two
> > minor QEMU-specific modifications and haven't missed anything
> > from Linux's version that we ought to have. So:
> >
> > Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
> >
> > On your two questions:
> >
> > (1) As Dan says, QEMU already enforces a new enough
> > Python version, so we don't need to handle 3.6. I think
> > the main thing driving a choice to backport or not those
> > changes would be simply keeping in sync with Linux's
> > version of the script so we don't diverge. We want to
> > make future re-syncing of the script as easy as possible.
> >
> > (2) Regarding the location of the kernel-doc libraries:
> > we seem to have two things here, possibly in tension:
> >  - we don't want to gratuitously diverge from Linux
> >  - QEMU's directory hierarchy is not the kernel's
> >
> > In particular, I'm not sure tools/ is where we would
> > naturally put python libraries used during the build
> > process. Maybe that would be python/ for us, but I defer
> > to John or another Python expert on that.
>
> I tend to see the 'python' directory as being for stuff we formally
> maintain as a python API for use by multiple internal consumers.

I more or less agree with Dan - that is how it is currently arranged.

In the past, however, I have suggested moving certain other modules
that are bigger than a single file into python/ for the sake of being
able to maintain them more aggressively: i.e. I do not regularly check
for Python regression and compatibility issues for things under
scripts/, except for qapi, which is also something I proposed moving
to python/ before.

The current state of things is that I aggressively check and test these things:

- python/*
- scripts/qapi/
- docs/sphinx/qapi_domain.py
- docs/sphinx/qapidoc.py

Everything else is just "best effort" which generally means "I fix it
when I notice that it is broken". If it is not a multi-file module and
not necessary for configure+build to run, I think for now it is best
kept outside of python/.

>
> This is just a bunch of helper files exclusively for use by the kernel-doc
> tool, and so the scripts/ directory is a decent fit for it, given that this
> dir is for a collection of arbitary supporting tools & scripts.
>
> As precedent, see the tracetool, which keeps all its helpers under
> scripts/tracetool too.
>
> TL;DR: I would not want to see a new top level tools/ directory
> created, and don't think it fits in python/ either; scripts/ is
> a fine home.
>
> With regards,
> Daniel
> --
> |: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
> |: https://libvirt.org         -o-            https://fstop138.berrange.com :|
> |: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|
>

Em Tue, 13 Jan 2026 14:52:56 -0500
John Snow <jsnow@redhat.com> escreveu:

> On Tue, Jan 13, 2026 at 7:09 AM Daniel P. Berrangé <berrange@redhat.com> wrote:
> >
> > On Tue, Jan 13, 2026 at 11:44:51AM +0000, Peter Maydell wrote:  
> > > On Tue, 6 Jan 2026 at 16:38, Mauro Carvalho Chehab
> > > <mchehab+huawei@kernel.org> wrote:  
> > > >
> > > > Hi Peter/John,
> > > >
> > > > There were several updates at kernel-doc upstream fixing bugs,
> > > > doing cleanups and a couple of improvements.
> > > >
> > > > Better to keep QEMU in sync with such changes.
> > > >
> > > > Worth mentioning that we did some changes on Linux at the
> > > > kernel-doc.py script itself, to avoid Kernel build to crash
> > > > with too old Python versions, as there docs build is a
> > > > separate target, and python >= 3.6 is a new requirement
> > > > there.
> > > >
> > > > On kernel, if python < 3.6, it will simply ignore docs
> > > > build (emitting a warning).
> > > >
> > > > I opted to not backport such changes, but if you prefer
> > > > doing that, I can do that on a v2.
> > > > ---
> > > >
> > > > For now, I opted to keep kernel-doc libraries at the same
> > > > directory as before - e.g. at scripts/lib/kdoc. On Linux,
> > > > we ended moving it to tools/lib/python/kdoc. It could make
> > > > sense to move it on QEMU too, as it makes a little bit
> > > > easier to keep things in sync.
> > > >
> > > > What do you think?  
> > >
> > > Hi; thanks for doing this backport. I checked that the output
> > > with this patch applied is still the same as with the old
> > > kernel-doc, and eyeballed the diffs between our kernel-doc
> > > and the Linux version, to confirm that we have kept our two
> > > minor QEMU-specific modifications and haven't missed anything
> > > from Linux's version that we ought to have. So:
> > >
> > > Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
> > >
> > > On your two questions:
> > >
> > > (1) As Dan says, QEMU already enforces a new enough
> > > Python version, so we don't need to handle 3.6. I think
> > > the main thing driving a choice to backport or not those
> > > changes would be simply keeping in sync with Linux's
> > > version of the script so we don't diverge. We want to
> > > make future re-syncing of the script as easy as possible.
> > >
> > > (2) Regarding the location of the kernel-doc libraries:
> > > we seem to have two things here, possibly in tension:
> > >  - we don't want to gratuitously diverge from Linux
> > >  - QEMU's directory hierarchy is not the kernel's
> > >
> > > In particular, I'm not sure tools/ is where we would
> > > naturally put python libraries used during the build
> > > process. Maybe that would be python/ for us, but I defer
> > > to John or another Python expert on that.  
> >
> > I tend to see the 'python' directory as being for stuff we formally
> > maintain as a python API for use by multiple internal consumers.  
> 
> I more or less agree with Dan - that is how it is currently arranged.
> 
> In the past, however, I have suggested moving certain other modules
> that are bigger than a single file into python/ for the sake of being
> able to maintain them more aggressively: i.e. I do not regularly check
> for Python regression and compatibility issues for things under
> scripts/, except for qapi, which is also something I proposed moving
> to python/ before.
> 
> The current state of things is that I aggressively check and test these things:
> 
> - python/*
> - scripts/qapi/
> - docs/sphinx/qapi_domain.py
> - docs/sphinx/qapidoc.py

Giving my 2 cents here: at Linux Kernel, we're moving documentation
to tools/docs document because just scripts/ became too messy. Also,
having a directory specifically for python modules makes sense.
So, we just moved libraries to tools/python/lib. 

> Everything else is just "best effort" which generally means "I fix it
> when I notice that it is broken". If it is not a multi-file module and
> not necessary for configure+build to run, I think for now it is best
> kept outside of python/.

In the specific case of kernel-doc + modules this is required at build
time, if docs are enabled.

> > This is just a bunch of helper files exclusively for use by the kernel-doc
> > tool, and so the scripts/ directory is a decent fit for it, given that this
> > dir is for a collection of arbitary supporting tools & scripts.

Not quite: those files are the actual kernel-doc implementation.

The exec is just a shell to call them. At the Linux Kernel, we don't even
run kernel-doc exec anymore: they're called directly by the Sphinx 
kerneldoc extension. We use the exec just to allow us to run manually, 
as it can be helpful to see the ReST result when problems rise.

Right now on QEMU we're still running the exec, but this can change
some day.

> >
> > As precedent, see the tracetool, which keeps all its helpers under
> > scripts/tracetool too.
> >
> > TL;DR: I would not want to see a new top level tools/ directory
> > created, and don't think it fits in python/ either; scripts/ is
> > a fine home.
> >
> > With regards,
> > Daniel
> > --
> > |: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
> > |: https://libvirt.org         -o-            https://fstop138.berrange.com :|
> > |: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|
> >  
> 



Thanks,
Mauro

On Tue, 13 Jan 2026 at 12:09, Daniel P. Berrangé <berrange@redhat.com> wrote:
> TL;DR: I would not want to see a new top level tools/ directory
> created, and don't think it fits in python/ either; scripts/ is
> a fine home.

We do already have a tools/ directory, as it happens.
It has two things in it...

Personally I think tools/ ought to be for the set of
things that we build if you --enable-tools in configure
and which we document in docs/tools.
tools/i386/qemu-vmsr-helper.c fits in that idea of
what the directory is for. tools/ebpf/ does not, but
I don't know enough about what it's for to suggest
a better home for it.

We might at some point want to tidy up the qemu-io.c,
qemu-bridge-helper.c, etc that currently live in the
top level directory so they go in tools/ instead.

thanks
-- PMM

On Tue, Jan 13, 2026 at 01:04:48PM +0000, Peter Maydell wrote:
> On Tue, 13 Jan 2026 at 12:09, Daniel P. Berrangé <berrange@redhat.com> wrote:
> > TL;DR: I would not want to see a new top level tools/ directory
> > created, and don't think it fits in python/ either; scripts/ is
> > a fine home.
> 
> We do already have a tools/ directory, as it happens.
> It has two things in it...
> 
> Personally I think tools/ ought to be for the set of
> things that we build if you --enable-tools in configure
> and which we document in docs/tools.
> tools/i386/qemu-vmsr-helper.c fits in that idea of
> what the directory is for. tools/ebpf/ does not, but
> I don't know enough about what it's for to suggest
> a better home for it.

It is the source for the pre-generated ebpf/rss.bpf.skeleton.h file.
It should probably just live in epbf/.

Ideally we wwould build it by default, but GCC lacked a eBPF backend
and we didn't want a hard dep on clang for this.

> We might at some point want to tidy up the qemu-io.c,
> qemu-bridge-helper.c, etc that currently live in the
> top level directory so they go in tools/ instead.

Yes, that would be desirable.

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

On Tue, Jan 06, 2026 at 05:38:18PM +0100, Mauro Carvalho Chehab wrote:
> Hi Peter/John,
> 
> There were several updates at kernel-doc upstream fixing bugs,
> doing cleanups and a couple of improvements.
> 
> Better to keep QEMU in sync with such changes.
> 
> Worth mentioning that we did some changes on Linux at the
> kernel-doc.py script itself, to avoid Kernel build to crash
> with too old Python versions, as there docs build is a
> separate target, and python >= 3.6 is a new requirement
> there.
> 
> On kernel, if python < 3.6, it will simply ignore docs
> build (emitting a warning).
> 
> I opted to not backport such changes, but if you prefer
> doing that, I can do that on a v2.

QEMU mandates Python >= 3.9 (enforced by 'configure'), so there's no need
to worry about anything older than that.


With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|