[Qemu-devel] [PATCH v5 00/26] Add infrastructure for QIDL-based device serialization

[Michael Roth <mdroth@linux.vnet.ibm.com>]

These patches are based are origin/master, and can also be obtained from:

git://github.com/mdroth/qemu.git qidl-base-v5

Changes since v4:

 - Added QIDL_DECLARE_PUBLIC() and QIDL_IMPLEMENT_PUBLIC() to avoid
   duplicating generated code for declarations pulled in via public
   header files. QIDL_DECLARE_PUBLIC() defers the actual code generation
   to whatever file has the corresponding QIDL_IMPLEMENT_PUBLIC()
   directive, and instead only makes the appropriate declarations to
   access that code.
 - Pulled in Paolo's patch to add filename/line numbers to qidl
   lexer, and extended it to qidl parser as well.
 - Fixed build issue due to gcc-generated *.d files adding *.qidl.c
   dependency and causing issues due to us not having a corresponding
   rule to re-generate it when it's deleted (due to it being created in
   a qidl-generated/ subdir that make doesn't know how to match a
   rule to. Took work around it We no longer use qidl-generated/ subdirs.
 - Grouped serialization-specific annotations into a QIDL(serialize, ...)
   group to distinguish them from QIDL(properties, ...) and other annotation
   groups we might add in the future.
 - Added an optional/"no-op" q_standard serialization directive, mostly as
   a way to better document default qidl behavior when no explicit annotation
   is provided (avoided q_default to avoid any possible issues with reserved
   keywords in the underlying macro code).

Changes since v3:

 - Added documentation for array_capacity/array_size/embedded QAPI
   directives and improved existing docs. (Paolo)
     > qapi: Improve existing docs and document annotated QAPI types
 - Fix potential for unbalanced structures with visit_type_carray() in
   similar manner to type_list()/type_struct(). (Paolo)
 - Some comments in qapi_visit.py to clarify carray handling. (Paolo)
 - Avoid redundant re-definitions in qidl.h for -DQIDL_GEN (Paolo)
 - Added additional unit tests to exercise QAPI handling of
   array_capacity/array_size/embedded values for 'annotated' QAPI-defined
   types.
 - Added a to_json() method to OrderedDict() so that ordering is retained
   in the schemas that QIDL generates.
     > qapi: ordereddict, add to_json() method
 - *.qidl.schema QAPI schema files are now generated along-side *.qidl.c
   files when --enable-debug configure option is specified.
 - 2 additional patches to fix pre-existing QAPI issues triggered in testing:
     > qapi: QmpInputVisitor, don't re-allocate memory in start_struct
     > qapi: fix potential segfault for visit_type_size()

Changes since v2:

 - Documentations fix-ups and clarifications (Eric)
 - Moved annotations in front of variable names and documented this as
   the default (Paolo, Kevin)
 - Switched to q_* prefix instead of q<Capital> (Blue, Paolo, Anthony)
 - Switched to GPLv2+ licensing in QIDL lexer/parser
 - Minor clean-ups in unit tests

Changes since v1:

 - Simplified declaration format for QIDL-fied structures (Anthony, Blue)
 - Documentations fix-ups and clarifications (Eric, Peter)
 - Reduced build-time impact of QIDL by scanning for a QIDL_ENABLED()
   directive in .c files before running them through the
   the preprocessor and QIDL parser, and using a Makefile-set cflag
   to avoid declaring QIDL-related code/structures for files that don't
   include the directive.
 - Moved lexer functionality into a standalone lexer class, simplified
   interface to avoid the need to track offsets into the token stream.
 - Fixed an issue when deserializing a static array of structs using the
   new visit_type_carray() interfaces
 - Included a fix for a qom-fuse bug caused by multiple threads contending
   for QMP responses
 - Added brief descriptions of annotations to qidl.h
 - Minor clean-ups to the QIDL parser code

Changes since rfc v2:

 - Parser/Codegen fix-ups for cases encountered converting piix ide and usb.
 - Fixed license headers.
 - Stricter arg-checking for QIDL macros when passing to codegen.
 - Renamed QAPI visit_*_array interfaces to visit_*_carray to clarify that
   these are serialization routines for single-dimension C arrays.

These patches add infrastructure and unit tests for QIDL, which provides
a serialization framework for QEMU device structures by generating visitor
routines for device structs based on simple field annotations. Examples of
how this is done are included in patch 17, but, for brevity, a sample struct
such as this:

    typedef struct SerialDevice {
        SysBusDevice parent;

        uint8_t thr;            /* transmit holding register */
        uint8_t lsr;            /* line status register */
        uint8_t ier;            /* interrupt enable register */

        int int_pending;        /* whether we have a pending queued interrupt */
        CharDriverState *chr;   /* backend */
    } SerialDevice;

can now be made serializable with the following changes:

    typedef struct SerialDevice SerialDevice;

    QIDL_DECLARE(SerialDevice) {
        SysBusDevice parent;

        uint8_t thr;              /* transmit holding register */
        uint8_t lsr;              /* line status register */
        uint8_t ier;              /* interrupt enable register */

        int q_derived int_pending; /* whether we have a pending queued interrupt */
        CharDriverState q_immutable *chr; /* backend */
    };

To make use of generated visitor code, and .c file need only call the
QIDL_ENABLE() somewhere in the code body, which will then give it access to
visitor routines for any QIDL-ified device structures in that file, or included
from other files. These routines can then be used for
serialization/deserialization of the device state in a manner suitable for tasks
such as introspection/testing (generally via a r/w 'state' QOM property) or
migration.

The overall goal is to expose all migrateable device state in this manner so
that we can decouple serialization duties from savevm/VMState and convert them
into a stable, code-agnostic wire protocol, relying instead on intermediate
translation routines to handle the work of massaging serialized state into a
format suitable for the wire and vice-versa.

The following WIP branch contains the first set of QIDL conversions:

https://github.com/mdroth/qemu/commits/qidl

So far i440fx, pcibus, cirrus_vga, uhci, rtc, and isa/piix ide have been
converted, and I'm hoping to have most common PC devices converted over
within the next few weeks.

Please review. Comments/suggestions are very welcome.

 Makefile                                       |   27 +-
 QMP/qom-fuse                                   |   39 +-
 configure                                      |    1 +
 docs/qapi-code-gen.txt                         |  251 ++++++++++++-
 docs/qidl.txt                                  |  347 +++++++++++++++++
 hw/qdev-properties.h                           |  151 ++++++++
 hw/qdev.h                                      |  126 +------
 module.h                                       |    2 +
 qapi/Makefile.objs                             |    1 +
 qapi/misc-qapi-visit.c                         |   14 +
 qapi/qapi-visit-core.c                         |   31 +-
 qapi/qapi-visit-core.h                         |   11 +
 qapi/qmp-input-visitor.c                       |   32 +-
 qapi/qmp-output-visitor.c                      |   19 +
 qidl.h                                         |  149 ++++++++
 rules.mak                                      |   27 +-
 scripts/lexer.py                               |  325 ++++++++++++++++
 scripts/ordereddict.py                         |   51 +++
 scripts/qapi-visit.py                          |  364 ------------------
 scripts/qapi.py                                |   16 +-
 scripts/{qapi-commands.py => qapi_commands.py} |    8 +-
 scripts/{qapi-types.py => qapi_types.py}       |    2 +-
 scripts/qapi_visit.py                          |  481 ++++++++++++++++++++++++
 scripts/qidl.py                                |  291 ++++++++++++++
 scripts/qidl_parser.py                         |  295 +++++++++++++++
 tests/Makefile                                 |   20 +-
 tests/test-qidl-included.h                     |   25 ++
 tests/test-qidl-linked.c                       |  101 +++++
 tests/test-qidl-pub-linked.c                   |   18 +
 tests/test-qidl-pub-linked.h                   |   29 ++
 tests/test-qidl.c                              |  393 +++++++++++++++++++
 tests/test-qidl.h                              |   36 ++
 tests/test-qmp-input-visitor.c                 |    2 +-
 vl.c                                           |    1 +
 34 files changed, 3142 insertions(+), 544 deletions(-)