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

[Alex Bennée]

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.

>
>> +
>> +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>

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro