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

[Pierrick Bouvier <pierrick.bouvier@linaro.org>]

On 12/5/24 07:23, Peter Maydell wrote:
> On Tue, 3 Dec 2024 at 20:32, Pierrick Bouvier
> <pierrick.bouvier@linaro.org> wrote:
>>
>> On 12/3/24 09:37, Peter Maydell wrote:
>>> 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.
>>>
>>
>> And people can be free to add new entries later. However, we should
>> resist the temptation to add too many details. It should stay simple and
>> understandable, even if not all technical nuances are not represented.
>>
>>>> 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
>>>> +++ b/docs/devel/control-flow-integrity.rst
>>>> @@ -1,3 +1,5 @@
>>>> +.. _cfi:
>>>> +
>>>>    ============================
>>>>    Control-Flow Integrity (CFI)
>>>>    ============================
>>>> diff --git a/docs/devel/multi-thread-tcg.rst b/docs/devel/multi-thread-tcg.rst
>>>> index d706c27ea74..7fd0a07633d 100644
>>>> --- a/docs/devel/multi-thread-tcg.rst
>>>> +++ b/docs/devel/multi-thread-tcg.rst
>>>> @@ -4,6 +4,8 @@
>>>>      This work is licensed under the terms of the GNU GPL, version 2 or
>>>>      later. See the COPYING file in the top-level directory.
>>>>
>>>> +.. _mttcg:
>>>> +
>>>>    ==================
>>>>    Multi-threaded TCG
>>>>    ==================
>>>> diff --git a/docs/glossary/index.rst b/docs/glossary/index.rst
>>>> new file mode 100644
>>>> index 00000000000..a2d4f3eae16
>>>> --- /dev/null
>>>> +++ b/docs/glossary/index.rst
>>>
>>> I guess it makes sense to give this its own subdir, since we want
>>> it to come at the end of the manual. The other option would be
>>> to put it directly into docs/.
>>>
>>
>>   From your comment, it's not clear for me if it's ok as it is, or if you
>> want a change.
>> Can you elaborate on that?
> 
> It means I'm not sure. We end up with a subdirectory with only
> one file in it and where there's no expectation we'd ever want
> to add any more files to it. On the other hand it does keep it
> out of the docs/ top level directory, which currently has a
> fair amount of cruft awaiting cleanup.
> 
> I guess on balance I would make this docs/glossary.rst,
> unless you anticipate wanting to split this into multiple
> files or have something else in docs/glossary/ later.
> 
>>>> @@ -0,0 +1,238 @@
>>>> +.. _Glossary:
>>>> +
>>>> +--------
>>>> +Glossary
>>>> +--------
>>>> +
>>>> +This section of the manual presents *simply* acronyms and terms QEMU developers
>>>> +use.
>>>
>>> What's "simply" intended to mean here?
>>>
>>
>> "in a straightforward or plain manner".
>> I can remove this word if you think it does not serve any purpose.
> 
> You could phrase it as "presents brief definitions of acronyms
> and terms", I think.
> 
>>>> +QEMU system defines board models for various architectures. It's a description
>>>> +of a SoC (system-on-chip) with various devices pre-configured, and can be
>>>> +selected with the option ``-machine`` of qemu-system.
>>>
>>> SoCs are not the same as boards.
>>>
>>> We could say something like:
>>>
>>> QEMU's system emulation models many different types of hardware.
>>> A machine model (sometimes called a board model) is the model
>>> of a complete virtual system with RAM, one or more CPUs, and
>>> various devices.
>>>
>>> We could also put in a link to
>>> https://www.qemu.org/docs/master/system/targets.html
>>> which is where we document what our machine types are.
>>>
>>
>> How do you distinguish a SoC and cpu? Is a SoC cpu + devices?
>> Isn't a board/machine a set of SoC + devices attached?
> 
> An SoC is a "system on chip". To quote wikipedia's definition:
> 
> "A system on a chip or system-on-chip is an integrated circuit that
> integrates most or all components of a computer or electronic system.
> These components usually include an on-chip central processing unit
> (CPU), memory interfaces, input/output devices and interfaces, and
> secondary storage interfaces, often alongside other components such
> as radio modems and a graphics processing unit (GPU) – all on a
> single substrate or microchip."
> 
> An SoC always contains a CPU, but it will have a lot more
> than that built into it too. And the SoC only has "most"
> of the system components, so the whole machine will be
> an SoC plus some other things.
> 
> Generally a board/machine that uses an SoC will have on it:
>   * an SoC
>   * the actual memory
>   * perhaps one or two extra devices external to the SoC
>   * connectors for things like serial ports, SD cards, etc
>     (which generally wire up to SoC pins)
>   * a crystal or similar to act as the main clock source
> 
> So if you look at a photo of a development board that uses
> an SoC, there will be one large chip which is the SoC,
> some RAM chips, a bunch of connectors and one or two smaller
> chips. Not every device will be inside the SoC, but
> generally almost all of them are.
> 
> QEMU's machine models for this kind of board match the
> organization of the hardware; looking at hw/arm/sabrelite.c
> which is a machine model you can see that it has:
>   * an instance of the fsl-imx6 SoC device object
>   * the main memory
>   * some NOR flash memory
>   * some configuration and wiring up of things
> 
> And the SoC itself is in hw/arm/fsl-imx6.c, and is a
> QOM device object that creates and wires up the CPUs,
> UARTs, USB controller, and various other devices that
> this particular SoC includes. In this case we only have
> one board model using this SoC, but for some SoCs we
> have several board models that all use the same SoC
> but wire up different external devices to it.
> 
> Some of our machine models are models of systems that
> don't use an SoC at all. This is rare in the Arm world,
> but for instance the SPARC machines like the SS-5 are
> like that -- the real hardware had a discrete CPU chip
> and a bunch of devices in their own chips on the
> motherboard, and QEMU's model of that hardware has
> a machine model which directly creates the CPU and
> the various devices. (And some of our older machine
> models are models of hardware that *does* have an SoC
> but where we didn't model that level of abstraction,
> so they directly create devices in the machine model
> that really ought to be inside an SoC object.
> hw/arm/stellaris.c is one example of that.)
> 

Thanks for the answer on this.
My specific implicit question was: do we have boards with cpu only (and 
not a SoC), which you answered.

>>>> +
>>>> +Block
>>>> +-----
>>>> +
>>>> +Block drivers are the available `disk formats <block-drivers>` available, and
>>>> +block devices `(see Block device section on options page)<sec_005finvocation>`
>>>> +are using them to implement disks for a virtual machine.
>>>
>>> Block drivers aren't just disk formats; there are some filter
>>> drivers too. Somebody on the block side could probably
>>> provide a better definition here.
>>>
>>
>> I'm open to a more exact definition. The two terms (drivers and devices)
>> seem to overlap on some parts, so I came up with this trivial definition.
> 
> Yeah, the driver vs device split is a good one (basically
> the device is the front-end visible to the guest, and the
> driver is the back-end that provides it with storage
> via an abstracted API). The nit I'm picking here is that
> not every block driver is there to provide support for
> an on-host disk format.
> 
>>>> +
>>>> +CFI
>>>> +---
>>>> +
>>>> +Control Flow Integrity is a hardening technique used to prevent exploits
>>>> +targeting QEMU by detecting unexpected branches during execution. QEMU `actively
>>>> +supports<cfi>` being compiled with CFI enabled.
>>>> +
>>>> +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 :-)
>>>
>>
>> Indeed :)
>> Should we explain what is a computer device?
>> The goal was just to say that QEMU can emulate hardware interacting with
>> the cpu, which could be a possible definition. So people can associate
>> that QEMU devices are nothing else than a "normal" computer device.
> 
> We could say, perhaps:
> 
> In QEMU, a device is a piece of hardware visible to the guest.
> Examples include UARTs, PCI controllers, PCI cards, VGA controllers,
> and many more.
> 
> 
> 
>>>> +
>>>> +Hypervisor
>>>> +----------
>>>> +
>>>> +The formal definition of an hypervisor is a program than can be used to manage a
>>>> +virtual machine. QEMU itself is an hypervisor.
>>>
>>> "a hypervisor". QEMU isn't really a hypervisor, though...
>>>
>>
>> It's a shortcut, and I'm open to change it. It brings an interesting
>> question though.
>>
>> Technically, QEMU interacts with hypervisor APIs built in various OSes.
>> On the other hand, when we use TCG, it's an emulator instead.
>>
>> But as you can't use KVM/hvf/whpx by itself, how do you name the program
>> interacting with it, and emulating the rest of the VM?
>>
>> The correct word is probably "virtualizer", but from searching on
>> Internet, it seems that "vmm" and "virtualizer" are considered the same
>> as an "hypervisor". The difference is subtle, and maybe we have an
>> opportunity here to clarify it.
> 
> 
>>>> +Patchwork
>>>> +---------
>>>> +
>>>> +`Patchwork <https://patchew.org/QEMU/>`_ is a website that tracks
>>>> +patches on the Mailing List.
>>>
>>> Patchwork and patchew are different systems. Patchew's URL is
>>> https://patchew.org/QEMU/
>>>
>>> (There is a patchwork instance that tracks qemu-devel patches,
>>> at https://patchwork.kernel.org/project/qemu-devel/list/ , but
>>> I'm not aware of any developers that are actively using it, so
>>> I don't think it merits being mentioned in the glossary.)
>>>
>>
>> I've been confused by that, and just thought it was two different
>> instances (fork me if you can) of the "same" thing.
>> How would you define patchew?
>> When we say patchwork, do we implicitely mean patchew?
> 
> No. patchwork is patchwork, and patchew is patchew -- these
> are entirely different pieces of software that happen to do
> similar jobs.
> 
>> if I understand currently, patchew is what we want to mention in our
>> doc? (and mention it's not associated to patchwork).
> 
> We don't use patchwork, so we don't need to mention it anywhere.
> 
>>>> +Once a series is reviewed and accepted by a subsystem maintainer, it will be
>>>> +included in a PR (Pull Request) that the project maintainer will merge into QEMU
>>>> +main branch, after running tests.
>>>
>>> I think we could probably also usefully say
>>>
>>> "The QEMU project doesn't currently expect most developers to
>>> directly submit pull requests."
>>>
>>> just to flag up that our development model isn't like the
>>> currently-popular github/gitlab one where a PR is how you
>>> send contributions.
>>>
>>
>> This is interesting.
>>
>> For the majority of developers nowadays, a PR is a GitHub/GitLab PR.
>> Despite the fact we use the original PR meaning (in git terms), it's
>> probably confusing when new comers hear pull request.
>>
>>>> +
>>>> +QCOW
>>>> +----
>>>> +
>>>> +QEMU Copy On Write is a disk format developed by QEMU. It provides transparent
>>>> +compression, automatic extension, and many other advantages over a raw image.
>>>
>>> We want to be a bit careful here, because the "qcow" format
>>> is not something we recommend for new use -- "qcow2" is what
>>> you actually want.
>>>
>>> https://www.qemu.org/docs/master/system/qemu-block-drivers.html#cmdoption-image-formats-arg-qcow2
>>>
>>
>> Sounds good.
>>
>> For my personal knowledge: during this work I discovered that we had
>> qcow3. From what I understood, it seems to be included in what we called
>> qcow2 today. Is that correct?
> 
> I have no idea -- you'd need to ask somebody who works on the
> block layer
> 
> thanks
> -- PMM

Thanks for all the suggestions, I'll integrate those in next version.