mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/qapi-code-gen.txt: Clarify naming rules

Browse Source 
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Kevin Wolf <kwolf@redhat.com>
Message-Id: <1488317230-26248-24-git-send-email-armbru@redhat.com>
This commit is contained in:
Markus Armbruster 2017-02-28 22:27:09 +01:00
parent 31478f26ab
commit 79f7598164
1 changed files with 39 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
docs/qapi-code-gen.txt
View File

@ -216,33 +216,38 @@ single-dimension array of that type; multi-dimension arrays are not
directly supported (although an array of a complex struct that
contains an array member is possible).
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.
Names beginning with 'q_' are reserved for the generator, which uses
them for munging QMP names that resemble C keywords or other
problematic strings. For example, a member named "default" in qapi
becomes "q_default" in the generated C code.
Types, commands, and events share a common namespace. Therefore,
generally speaking, type definitions should always use CamelCase for
user-defined type names, while built-in types are lowercase. Type
definitions should not end in 'Kind', as this namespace is used for
creating implicit C enums for visiting union types, or in 'List', as
this namespace is used for creating array types. Command names,
and member names within a type, should be all lower case with words
separated by a hyphen. However, some existing older commands and
complex types use underscore; when extending such expressions,
consistency is preferred over blindly avoiding underscore. Event
names should be ALL_CAPS with words separated by underscore. Member
names cannot start with 'has-' or 'has_', as this is reserved for
tracking optional members.
user-defined type names, while built-in types are lowercase.
Type names ending with 'Kind' or 'List' are reserved for the
generator, which uses them for implicit union enums and array types,
respectively.
Command names, and member names within a type, should be all lower
case with words separated by a hyphen. However, some existing older
commands and complex types use underscore; when extending such
expressions, consistency is preferred over blindly avoiding
underscore.
Event names should be ALL_CAPS with words separated by underscore.
Member names starting with 'has-' or 'has_' are reserved for the
generator, which uses them for tracking optional members.
Any name (command, event, type, member, or enum value) beginning with
"x-" is marked experimental, and may be withdrawn or changed
incompatibly in a future release. All names must begin with a letter,
and contain only ASCII letters, digits, dash, and underscore. There
are two exceptions: enum values may start with a digit, and any
extensions added by downstream vendors should start with a prefix
matching "__RFQDN_" (for the reverse-fully-qualified-domain-name of
the vendor), even if the rest of the name uses dash (example:
__com.redhat_drive-mirror). Names beginning with 'q_' are reserved
for the generator: QMP names that resemble C keywords or other
problematic strings will be munged in C to use this prefix. For
example, a member named "default" in qapi becomes "q_default" in the
generated C code.
incompatibly in a future release.
In the rest of this document, usage lines are given for each
expression type, with literal strings written in lower case and
@ -643,6 +648,18 @@ any non-empty complex type (struct, union, or alternate), and a
pointer to that QAPI type is passed as a single argument.
=== Downstream extensions ===
QAPI schema names that are externally visible, say in the Client JSON
Protocol, need to be managed with care. Names starting with a
downstream prefix of the form __RFQDN_ are reserved for the downstream
who controls the valid, reverse fully qualified domain name RFQDN.
RFQDN may only contain ASCII letters, digits, hyphen and period.
Example: Red Hat, Inc. controls redhat.com, and may therefore add a
downstream command __com.redhat_drive-mirror.
== Client JSON Protocol introspection ==
Clients of a Client JSON Protocol commonly need to figure out what