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