qemu-e2k/docs
Markus Armbruster 44ea9d9be3 qapi: Start to elide redundant has_FOO in generated C
In QAPI, absent optional members are distinct from any present value.
We thus represent an optional schema member FOO as two C members: a
FOO with the member's type, and a bool has_FOO.  Likewise for function
arguments.

However, has_FOO is actually redundant for a pointer-valued FOO, which
can be null only when has_FOO is false, i.e. has_FOO == !!FOO.  Except
for arrays, where we a null FOO can also be a present empty array.

The redundant has_FOO are a nuisance to work with.  Improve the
generator to elide them.  Uses of has_FOO need to be replaced as
follows.

Tests of has_FOO become the equivalent comparison of FOO with null.
For brevity, this is commonly done by implicit conversion to bool.

Assignments to has_FOO get dropped.

Likewise for arguments to has_FOO parameters.

Beware: code may violate the invariant has_FOO == !!FOO before the
transformation, and get away with it.  The above transformation can
then break things.  Two cases:

* Absent: if code ignores FOO entirely when !has_FOO (except for
  freeing it if necessary), even non-null / uninitialized FOO works.
  Such code is known to exist.

* Present: if code ignores FOO entirely when has_FOO, even null FOO
  works.  Such code should not exist.

In both cases, replacing tests of has_FOO by FOO reverts their sense.
We have to fix the value of FOO then.

To facilitate review of the necessary updates to handwritten code, add
means to opt out of this change, and opt out for all QAPI schema
modules where the change requires updates to handwritten code.  The
next few commits will remove these opt-outs in reviewable chunks, then
drop the means to opt out.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Message-Id: <20221104160712.3005652-5-armbru@redhat.com>
2022-12-13 18:31:37 +01:00
..
_templates
about watchdog: remove -watchdog option 2022-09-29 11:40:28 +02:00
config
devel qapi: Start to elide redundant has_FOO in generated C 2022-12-13 18:31:37 +01:00
interop docs: add firmware feature flags 2022-10-12 11:02:44 +02:00
specs pci-ids: drop list of modern virtio devices 2022-10-12 12:01:11 +02:00
sphinx
sphinx-static
spin
system docs/system/s390x: Document the "loadparm" machine property 2022-11-16 10:15:26 +01:00
tools Fix some typos in documentation and comments 2022-11-05 20:35:45 +01:00
user linux-user: Remove the deprecated ppc64abi32 target 2022-02-09 13:29:38 +00:00
COLO-FT.txt
block-replication.txt
bypass-iommu.txt
colo-proxy.txt
conf.py sphinx: change default language to 'en' 2022-06-27 10:39:03 +01:00
defs.rst.inc
igd-assign.txt
image-fuzzer.txt
index.rst
memory-hotplug.txt
meson.build meson, configure: move --with-pkgversion, CONFIG_STAMP to meson 2022-05-07 07:46:58 +02:00
multi-thread-compression.txt
multiseat.txt
nvdimm.txt
pci_expander_bridge.txt
pcie.txt
pcie_pci_bridge.txt
pcie_sriov.txt docs: Replace Qemu -> QEMU 2022-04-26 12:38:44 +02:00
pvrdma.txt
qcow2-cache.txt
qdev-device-use.txt
qemu-option-trace.rst.inc
qemupciserial.inf
rdma.txt
spice-port-fqdn.txt
throttle.txt
u2f.txt
xbzrle.txt
xen-save-devices-state.txt