Re: [PATCH 6/7] docs: add a glossary

[Pierrick Bouvier]

On 12/3/24 10:10, Alex Bennée wrote:
> Peter Maydell <peter.maydell@linaro.org> writes:
>
> > On Mon, 18 Nov 2024 at 17:24, Pierrick Bouvier
> > <pierrick.bouvier@linaro.org> wrote:
> > > Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
> > > ---
> > >   docs/devel/control-flow-integrity.rst |   2 +
> > >   docs/devel/multi-thread-tcg.rst       |   2 +
> > >   docs/glossary/index.rst               | 238 ++++++++++++++++++++++++++
> > >   docs/index.rst                        |   1 +
> > >   docs/system/arm/virt.rst              |   2 +
> > >   docs/system/images.rst                |   2 +
> > >   docs/tools/qemu-nbd.rst               |   2 +
> > >   7 files changed, 249 insertions(+)
> > >   create mode 100644 docs/glossary/index.rst
> >
> > I think this is a good idea; we've had at least one bug
> > report from a user pointing out that we had a term in
> > our docs which we didn't define ("block driver"):
> > https://gitlab.com/qemu-project/qemu/-/issues/2611
> > I have some comments on specific entries below.
> >
> > > diff --git a/docs/devel/control-flow-integrity.rst 
> > > b/docs/devel/control-flow-integrity.rst
> > > index e6b73a4fe1a..3d5702fa4cc 100644
> > > --- a/docs/devel/control-flow-integrity.rst
> <snip>
> > > +
> > > +Device
> > > +------
> > > +
> > > +QEMU is able to emulate a CPU, and all the hardware interacting with it,
> > > +including many devices. When QEMU runs a virtual machine using a hardware-based
> > > +accelerator, it is responsible for emulating, using software, all devices.
> >
> > This definition doesn't actually define what a device is :-)
>
> Also we can xref to:
>
>    https://qemu.readthedocs.io/en/v9.1.0/system/device-emulation.html
>
> where we go into a bit more detail about what a device, bus, frontend
> and backend are.

Good point, I'll add it.

> > > +
> > > +EDK2
> > > +----
> > > +
> > > +EDK2, as known as `TianoCore <https://www.tianocore.org/>`_, is an open source
> > > +implementation of UEFI standard. It's ran by QEMU to support UEFI for virtual
> > > +machines.
> >
> > Replace last sentence with
> > "QEMU virtual machines that boot a UEFI BIOS usually use EDK2."
> > ?
> <snip>