[Qemu-devel] QAPI enum naming rules (was: [for-4.0 PATCH v4 4/9] qapi: Define PCIe link speed and width properties)

[Markus Armbruster]

Eric Blake <address@hidden> writes:

> On 12/7/18 10:41 AM, Alex Williamson wrote:
>> Create properties to be able to define speeds and widths for PCIe
>> links.  The only tricky bit here is that our get and set callbacks
>> translate from the fixed QAPI automagic enums to those we define
>> in PCI code to represent the actual register segment value.
>>
>> Cc: Eric Blake <address@hidden>
>> Tested-by: Geoffrey McRae <address@hidden>
>> Reviewed-by: Markus Armbruster <address@hidden>
>> Signed-off-by: Alex Williamson <address@hidden>
[...]
>> +++ b/qapi/common.json
>> @@ -127,6 +127,48 @@
>>   { 'enum': 'OffAutoPCIBAR',
>>     'data': [ 'off', 'auto', 'bar0', 'bar1', 'bar2', 'bar3', 'bar4', 'bar5' 
>> ] }
>>   +##
>> +# @PCIELinkSpeed:
>> +#
>> +# An enumeration of PCIe link speeds in units of GT/s
>> +#
>> +# @2_5: 2.5GT/s
>> +#
>> +# @5: 5.0GT/s
>> +#
>> +# @8: 8.0GT/s
>> +#
>> +# @16: 16.0GT/s
>> +#
>> +# Since: 4.0
>> +##
>> +{ 'enum': 'PCIELinkSpeed',
>> +  'data': [ '2_5', '5', '8', '16' ] }
>
> QAPI enums are special-cased to allow starting with digits, thanks to
> QKeyCode.  I don't know if we are trying to avoid adding yet more of
> those, but the fact that you didn't have to whitelist them means that
> we are at least not forcibly limiting the use of leading digits in new
> enums.

Correct.  Enumeration values are a documented exception to the naming
rules:

    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.

We have naming rules for two reasons: (1) consistency and aesthetics,
and (2) a reasonably sane mapping to C identifiers.

Permitting both hyphen and underscore goes against (2).  The rules were
retrofitted after that horse had long bolted.  Same for the downstream
extension exception.

The enum value exception does not go against (2), because the mapping to
C identifiers prefixes the enum name.

(1) and (2) don't always pull in the same direction.  For instance, one
could argue that aesthetics favor '2.5' over '2_5'.  However, permitting
periods (everywhere or just in enum values) would go against (2),
because it creates new ways for the mapping to C identifiers to create
clashes.  We can certainly debate this.