Based-on: <20210304100059.157158-1-arm...@redhat.com>
Note: to apply it on master instead, replace one more "SUNW,fdtwo" by
"sun-fdtwo" in hw/block/fdc.c.
QAPI has naming rules. docs/devel/qapi-code-gen.txt:
=== Naming rules and reserved names ===
All names must begin with a letter, and contain only ASCII letters,
digits, hyphen, and underscore. There are two exceptions: enum values
may start with a digit, and names that are downstream extensions (see
section Downstream extensions) start with underscore.
[More on reserved names, upper vs. lower case, '-' vs. '_'...]
The generator enforces the rules.
Naming rules help in at least three ways:
1. They help with keeping names in interfaces consistent and
predictable.
2. They make avoiding collisions with the users' names in the
generator simpler.
3. They enable quote-less, evolvable syntax.
For instance, keyval_parse() syntax consists of names, values, and
special characters ',', '=', '.'
Since names cannot contain special characters, there is no need for
quoting[*]. Simple.
Values are unrestricted, but only ',' is special there. We quote
it by doubling.
Together, we get exactly the same quoting as in QemuOpts. This is
a feature.
If we ever decice to extend key syntax, we have plenty of special
characters to choose from. This is also a feature.
Both features rely on naming rules.
QOM has no naming rules whatsoever. Actual names aren't nearly as bad
as they could be. Still, there are plenty of "funny" names. This may
become a problem when we
* Switch from QemuOpts to keyval_parse()
Compared to QemuOpts, keyval_parse() restricts *keys*, but not
*values*.
"Funny" type names occuring as values are no worse than before:
quoting issues, described below.
Type names occuring in keys must be valid QAPI names. Should be
avoidable.
* QAPIfy (the compile-time static parts of) QOM
QOM type names become QAPI enum values. They must conform to QAPI
enum naming rules.
Let's review the existing offenders in the qemu-system-FOO:
1. We have a few type names containing ',', and one containing ' '.
The former require QemuOpts / keyval quoting (double the comma),
the latter requires shell quoting. There is no excuse for making
our users remember and do such crap. PATCH 1 eliminates it.
2. We have six type names containing '+', and two containing ':':
Sun-UltraSparc-IIIi+-sparc64-cpu
Sun-UltraSparc-IV+-sparc64-cpu
power5+_v2.1-powerpc64-cpu
power5+_v2.1-spapr-cpu-core
power7+_v2.1-powerpc64-cpu
power7+_v2.1-spapr-cpu-core
qemu:iommu-memory-region
qemu:memory-region
Naming rules could be relaxed to accept '+' and ':'. I'm doubt
this is worthwhile.
PATCH 2 renames the ones with ':'.
I'm leaving the ones with '+' alone for now.
3. We have some 550 type names containing '.'.
QAPI's (enum) naming rules could be relaxed to accept '.'.
keyval_parse()'s can't. Irrelevant, as long as type names only
occur as values, not as keys.
4. We have some 450 names starting with a digit. Roughly half of them
also contain '.'.
Leading digit is okay as QAPI enum, not okay as keyval_parse() key
fragment. Irrelevant, as long as type names only occur as
*values*, not as *keys*.
5. We generate type names of the form T::I, where T is a type name,
and I is the name of one of its interfaces.
I hope these are just for internal use.
One more thing on relaxing QAPI naming rules. QAPI names get mapped
to (parts of) C identifiers. These mappings are not injective. The
basic mapping is simple: replace characters other than letters and
digits by '_'.
This means names distinct QAPI names can clash in C. Fairly harmless
when the only "other" characters are '-' and '_'. The more "others" we
permit, the more likely confusing clashes become. Not a show stopper,
"merely" an issue of ergonomics.
v2:
* No longer RFC
* Cover letter:
- Consider difference between between keys and values in
keyval_parse()
- Differentiate more clearly between general QAPI naming rules and
QAPI enum naming rules
- List the types containing '+'
- Cover types containing ':'
- Drop "Can we get rid of '.'?" [Peter Maydell]
- Drop the idea to rename types starting with digits
- Cover "T::I" types generated for interfaces
- Cover ergonomics of relaxing QAPI naming rules
* PATCH 1: Rename SUNW,FOO to sun-FOO [Mark Cave-Ayland]
* PATCH 2: New
[*] Paolo's "[PATCH 04/25] keyval: accept escaped commas in implied
option" provides for comma-quoting. I'm ignoring it here for brevity.
I assure you it doesn't weaken my argument.
Markus Armbruster (2):
hw: Replace anti-social QOM type names
memory: Drop "qemu:" prefix from QOM memory region type names
include/exec/memory.h | 4 ++--
include/hw/arm/armv7m.h | 2 +-
include/hw/arm/fsl-imx25.h | 2 +-
include/hw/arm/fsl-imx31.h | 2 +-
include/hw/arm/fsl-imx6.h | 2 +-
include/hw/arm/fsl-imx6ul.h | 2 +-
include/hw/arm/fsl-imx7.h | 2 +-
include/hw/arm/xlnx-zynqmp.h | 2 +-
include/hw/cris/etraxfs.h | 2 +-
include/hw/i386/ich9.h | 2 +-
include/hw/misc/grlib_ahb_apb_pnp.h | 4 ++--
include/hw/misc/zynq-xadc.h | 2 +-
include/hw/register.h | 2 +-
include/hw/sparc/grlib.h | 6 +++---
hw/arm/xilinx_zynq.c | 2 +-
hw/audio/cs4231.c | 2 +-
hw/block/fdc.c | 4 ++--
hw/char/etraxfs_ser.c | 2 +-
hw/cris/axis_dev88.c | 6 +++---
hw/display/tcx.c | 2 +-
hw/intc/etraxfs_pic.c | 2 +-
hw/microblaze/xlnx-zynqmp-pmu.c | 2 +-
hw/misc/zynq_slcr.c | 2 +-
hw/sparc/sun4m.c | 12 ++++++------
hw/timer/etraxfs_timer.c | 2 +-
softmmu/vl.c | 2 +-
tests/vmstate-static-checker-data/dump1.json | 4 ++--
tests/vmstate-static-checker-data/dump2.json | 4 ++--
28 files changed, 42 insertions(+), 42 deletions(-)
--
2.26.2
