[PATCH v2 0/2] QOM type names and QAPI

[Markus Armbruster <armbru@redhat.com>]

Based-on: <20210304100059.157158-1-armbru@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