Re: [PATCH RFC 0/1] QOM type names and QAPI

[Markus Armbruster]

Markus Armbruster <armbru@redhat.com> writes:

> 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
> will become a problem when we
>
> * Switch from QemuOpts to keyval_parse()
>
>   QOM type names must not contain special characters, unless we
>   introduce more quoting.  Which we shouldn't, because the value of
>   special characters in names is negligible compared to the hassle of
>   having to quote them.
>
> * QAPIfy (the compile-time static parts of) QOM
>
>   QOM type names become QAPI enum values.  They must conform to QAPI
>   naming rules.
>
> Adopting QAPI naming rules for QOM type names takes care of both.
>
> Let's review the existing offenders.
>
> 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 some 550 type names containing '.'.  QAPI's naming rules
>    could be relaxed to accept '.', but keyval_parse()'s can't.

Thinko: keyval_parse() copes.  QOM type names occur as *value*, not as
key.

One more thing on 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.

>    Aside: I wish keyval_parse() would use '/' instead of '.', but it's
>    designed to be compatible to the block layer's existing use of
>    dotted keys (shoehorned into QemuOpts).
>
> 3. We have six type names containing '+'.  Four of them also contain
>    '.'.  Naming rules could be relaxed to accept '+'.  I'm not sure
>    it's worthwhile.
>
> 4. We have 19 names starting with a digit.  Three of them also contain
>    '.'.  Leading digit is okay as QAPI enum, not okay as
>    keyval_parse() key fragment.  We can either rename these types, or
>    make keyval_parse() a bit less strict.
>
> Of the type names containing '.' or '+'[**], 293 are CPUs, 107 are
> machines, and 150 are something else.  48 of them can be plugged with
> -device, all s390x or spapr CPUs.
>
> Can we get rid of '.'?
>
> I figure we could keep old names as deprecated aliases if we care.
> Perhaps just the ones that can be plugged with -device.
>
>
> [*] 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.
>
> [**] They are:
>     603e_v1.1-powerpc-cpu
[...]