diff options
Diffstat (limited to 'docs/devel/qapi-code-gen.txt')
| -rw-r--r-- | docs/devel/qapi-code-gen.txt | 124 |
1 files changed, 59 insertions, 65 deletions
diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 5900b39b91..25b7180a18 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -647,7 +647,7 @@ name an event 'MAX', since the generator also produces a C enumeration of all event names with a generated _MAX value at the end. When 'data' is also specified, additional info will be included in the event, with similar semantics to a 'struct' expression. Finally there -will be C API generated in qapi-event.h; when called by QEMU code, a +will be C API generated in qapi-events.h; when called by QEMU code, a message with timestamp will be emitted on the wire. An example event is: @@ -899,12 +899,13 @@ the names of built-in types. Clients should examine member == Code generation == -Schemas are fed into five scripts to generate all the code/files that, -paired with the core QAPI libraries, comprise everything required to -take JSON commands read in by a Client JSON Protocol server, unmarshal -the arguments into the underlying C types, call into the corresponding -C function, map the response back to a Client JSON Protocol response -to be returned to the user, and introspect the commands. +The QAPI code generator qapi-gen.py generates code and documentation +from the schema. Together with the core QAPI libraries, this code +provides everything required to take JSON commands read in by a Client +JSON Protocol server, unmarshal the arguments into the underlying C +types, call into the corresponding C function, map the response back +to a Client JSON Protocol response to be returned to the user, and +introspect the commands. As an example, we'll use the following schema, which describes a single complex user-defined type, along with command which takes a @@ -922,18 +923,23 @@ qmp_my_command(); everything else is produced by the generator. { 'event': 'MY_EVENT' } +We run qapi-gen.py like this: + + $ python scripts/qapi-gen.py --output-dir="qapi-generated" \ + --prefix="example-" example-schema.json + For a more thorough look at generated code, the testsuite includes tests/qapi-schema/qapi-schema-tests.json that covers more examples of what the generator will accept, and compiles the resulting C code as part of 'make check-unit'. -=== scripts/qapi-types.py === +=== Code generated for QAPI types === -Used to generate the C types defined by a schema, along with -supporting code. The following files are created: +The following files are created: $(prefix)qapi-types.h - C types corresponding to types defined in - the schema you pass in + the schema + $(prefix)qapi-types.c - Cleanup functions for the above C types The $(prefix) is an optional parameter used as a namespace to keep the @@ -943,8 +949,6 @@ created code. Example: - $ python scripts/qapi-types.py --output-dir="qapi-generated" \ - --prefix="example-" example-schema.json $ cat qapi-generated/example-qapi-types.h [Uninteresting stuff omitted...] @@ -1008,28 +1012,26 @@ Example: visit_free(v); } -=== scripts/qapi-visit.py === +=== Code generated for visiting QAPI types === -Used to generate the visitor functions used to walk through and -convert between a native QAPI C data structure and some other format -(such as QObject); the generated functions are named visit_type_FOO() -and visit_type_FOO_members(). +These are the visitor functions used to walk through and convert +between a native QAPI C data structure and some other format (such as +QObject); the generated functions are named visit_type_FOO() and +visit_type_FOO_members(). The following files are generated: -$(prefix)qapi-visit.c: visitor function for a particular C type, used +$(prefix)qapi-visit.c: Visitor function for a particular C type, used to automagically convert QObjects into the corresponding C type and vice-versa, as well as for deallocating memory for an existing C type -$(prefix)qapi-visit.h: declarations for previously mentioned visitor +$(prefix)qapi-visit.h: Declarations for previously mentioned visitor functions Example: - $ python scripts/qapi-visit.py --output-dir="qapi-generated" - --prefix="example-" example-schema.json $ cat qapi-generated/example-qapi-visit.h [Uninteresting stuff omitted...] @@ -1137,31 +1139,23 @@ Example: error_propagate(errp, err); } -=== scripts/qapi-commands.py === +=== Code generated for commands === + +These are the marshaling/dispatch functions for the commands defined +in the schema. The generated code provides qmp_marshal_COMMAND(), and +declares qmp_COMMAND() that the user must implement. -Used to generate the marshaling/dispatch functions for the commands -defined in the schema. The generated code implements -qmp_marshal_COMMAND() (registered automatically), and declares -qmp_COMMAND() that the user must implement. The following files are -generated: +The following files are generated: -$(prefix)qmp-marshal.c: command marshal/dispatch functions for each - QMP command defined in the schema. Functions - generated by qapi-visit.py are used to - convert QObjects received from the wire into - function parameters, and uses the same - visitor functions to convert native C return - values to QObjects from transmission back - over the wire. +$(prefix)qapi-commands.c: Command marshal/dispatch functions for each + QMP command defined in the schema -$(prefix)qmp-commands.h: Function prototypes for the QMP commands - specified in the schema. +$(prefix)qapi-commands.h: Function prototypes for the QMP commands + specified in the schema Example: - $ python scripts/qapi-commands.py --output-dir="qapi-generated" - --prefix="example-" example-schema.json - $ cat qapi-generated/example-qmp-commands.h + $ cat qapi-generated/example-qapi-commands.h [Uninteresting stuff omitted...] #ifndef EXAMPLE_QMP_COMMANDS_H @@ -1176,7 +1170,7 @@ Example: void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp); #endif - $ cat qapi-generated/example-qmp-marshal.c + $ cat qapi-generated/example-qapi-commands.c [Uninteresting stuff omitted...] static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, QObject **ret_out, Error **errp) @@ -1242,21 +1236,21 @@ Example: qmp_marshal_my_command, QCO_NO_OPTIONS); } -=== scripts/qapi-event.py === +=== Code generated for events === -Used to generate the event-related C code defined by a schema, with -implementations for qapi_event_send_FOO(). The following files are -created: +This is the code related to events defined in the schema, providing +qapi_event_send_EVENT(). -$(prefix)qapi-event.h - Function prototypes for each event type, plus an +The following files are created: + +$(prefix)qapi-events.h - Function prototypes for each event type, plus an enumeration of all event names -$(prefix)qapi-event.c - Implementation of functions to send an event + +$(prefix)qapi-events.c - Implementation of functions to send an event Example: - $ python scripts/qapi-event.py --output-dir="qapi-generated" - --prefix="example-" example-schema.json - $ cat qapi-generated/example-qapi-event.h + $ cat qapi-generated/example-qapi-events.h [Uninteresting stuff omitted...] #ifndef EXAMPLE_QAPI_EVENT_H @@ -1279,7 +1273,7 @@ Example: extern const char *const example_QAPIEvent_lookup[]; #endif - $ cat qapi-generated/example-qapi-event.c + $ cat qapi-generated/example-qapi-events.c [Uninteresting stuff omitted...] void qapi_event_send_my_event(Error **errp) @@ -1301,25 +1295,25 @@ Example: QDECREF(qmp); } - const char *const example_QAPIEvent_lookup[] = { - [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT", - [EXAMPLE_QAPI_EVENT__MAX] = NULL, + const QEnumLookup example_QAPIEvent_lookup = { + .array = (const char *const[]) { + [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT", + }, + .size = EXAMPLE_QAPI_EVENT__MAX }; -=== scripts/qapi-introspect.py === +=== Code generated for introspection === + +The following files are created: -Used to generate the introspection C code for a schema. The following -files are created: +$(prefix)qapi-introspect.c - Defines a string holding a JSON + description of the schema -$(prefix)qmp-introspect.c - Defines a string holding a JSON - description of the schema. -$(prefix)qmp-introspect.h - Declares the above string. +$(prefix)qapi-introspect.h - Declares the above string Example: - $ python scripts/qapi-introspect.py --output-dir="qapi-generated" - --prefix="example-" example-schema.json - $ cat qapi-generated/example-qmp-introspect.h + $ cat qapi-generated/example-qapi-introspect.h [Uninteresting stuff omitted...] #ifndef EXAMPLE_QMP_INTROSPECT_H @@ -1328,7 +1322,7 @@ Example: extern const char example_qmp_schema_json[]; #endif - $ cat qapi-generated/example-qmp-introspect.c + $ cat qapi-generated/example-qapi-introspect.c [Uninteresting stuff omitted...] const char example_qmp_schema_json[] = "[" |