From 33aaad529e7391a9ddc73682415e900950553200 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Llu=C3=ADs=20Vilanova?= Date: Fri, 2 May 2014 15:52:35 +0200 Subject: qapi: Use an explicit input file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use an explicit input file on the command-line instead of reading from standard input. It also outputs the proper file name when there's an error. Signed-off-by: Lluís Vilanova Reviewed-by: Eric Blake Reviewed-by: Markus Armbruster Signed-off-by: Luiz Capitulino --- docs/qapi-code-gen.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt index d78921f..63b03cf 100644 --- a/docs/qapi-code-gen.txt +++ b/docs/qapi-code-gen.txt @@ -221,7 +221,7 @@ created code. Example: mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-types.py \ - --output-dir="qapi-generated" --prefix="example-" < example-schema.json + --output-dir="qapi-generated" --prefix="example-" --input-file=example-schema.json mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.c /* AUTOMATICALLY GENERATED, DO NOT MODIFY */ @@ -291,7 +291,7 @@ $(prefix)qapi-visit.h: declarations for previously mentioned visitor Example: mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-visit.py \ - --output-dir="qapi-generated" --prefix="example-" < example-schema.json + --output-dir="qapi-generated" --prefix="example-" --input-file=example-schema.json mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.c /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */ -- cgit v1.1 From a719a27c824ea5e70f5bf6f3c8d13a8c1d6b1bfe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Llu=C3=ADs=20Vilanova?= Date: Wed, 7 May 2014 20:46:15 +0200 Subject: qapi: Add a primitive to include other files from a QAPI schema file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The primitive uses JSON syntax, and include paths are relative to the file using the directive: { 'include': 'path/to/file.json' } Signed-off-by: Lluís Vilanova Reviewed-by: Eric Blake Reviewed-by: Markus Armbruster Signed-off-by: Luiz Capitulino --- docs/qapi-code-gen.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs') diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt index 63b03cf..051d109 100644 --- a/docs/qapi-code-gen.txt +++ b/docs/qapi-code-gen.txt @@ -40,6 +40,17 @@ enumeration types and union types. Generally speaking, types definitions should always use CamelCase for the type names. Command names should be all lower case with words separated by a hyphen. + +=== Includes === + +The QAPI schema definitions can be modularized using the 'include' directive: + + { 'include': 'path/to/file.json'} + +The directive is evaluated recursively, and include paths are relative to the +file using the directive. + + === Complex types === A complex type is a dictionary containing a single key whose value is a -- cgit v1.1 From e940f543ae7606819c9083fdb524e5b85914f032 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 2 May 2014 13:26:29 +0200 Subject: qmp hmp: Consistently name Error * objects err, and not errp Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Signed-off-by: Luiz Capitulino --- docs/writing-qmp-commands.txt | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/writing-qmp-commands.txt b/docs/writing-qmp-commands.txt index 3930a9b..4d86c24 100644 --- a/docs/writing-qmp-commands.txt +++ b/docs/writing-qmp-commands.txt @@ -308,12 +308,12 @@ Here's the implementation of the "hello-world" HMP command: void hmp_hello_world(Monitor *mon, const QDict *qdict) { const char *message = qdict_get_try_str(qdict, "message"); - Error *errp = NULL; + Error *err = NULL; - qmp_hello_world(!!message, message, &errp); - if (errp) { - monitor_printf(mon, "%s\n", error_get_pretty(errp)); - error_free(errp); + qmp_hello_world(!!message, message, &err); + if (err) { + monitor_printf(mon, "%s\n", error_get_pretty(err)); + error_free(err); return; } } @@ -328,7 +328,7 @@ There are three important points to be noticed: 2. hmp_hello_world() performs error checking. In this example we just print the error description to the user, but we could do more, like taking different actions depending on the error qmp_hello_world() returns -3. The "errp" variable must be initialized to NULL before performing the +3. The "err" variable must be initialized to NULL before performing the QMP call There's one last step to actually make the command available to monitor users, @@ -480,12 +480,12 @@ Here's the HMP counterpart of the query-alarm-clock command: void hmp_info_alarm_clock(Monitor *mon) { QemuAlarmClock *clock; - Error *errp = NULL; + Error *err = NULL; - clock = qmp_query_alarm_clock(&errp); - if (errp) { + clock = qmp_query_alarm_clock(&err); + if (err) { monitor_printf(mon, "Could not query alarm clock information\n"); - error_free(errp); + error_free(err); return; } @@ -631,12 +631,12 @@ has to traverse the list, it's shown below for reference: void hmp_info_alarm_methods(Monitor *mon) { TimerAlarmMethodList *method_list, *method; - Error *errp = NULL; + Error *err = NULL; - method_list = qmp_query_alarm_methods(&errp); - if (errp) { + method_list = qmp_query_alarm_methods(&err); + if (err) { monitor_printf(mon, "Could not query alarm methods\n"); - error_free(errp); + error_free(err); return; } -- cgit v1.1 From cc1626556d264c867a07ebe8672fa06b208e209a Mon Sep 17 00:00:00 2001 From: Eric Blake Date: Wed, 7 May 2014 09:57:41 +0800 Subject: qapi: Document optional arguments' backwards compatibility Signed-off-by: Eric Blake Signed-off-by: Fam Zheng Signed-off-by: Luiz Capitulino --- docs/qapi-code-gen.txt | 32 ++++++++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt index 051d109..26312d8 100644 --- a/docs/qapi-code-gen.txt +++ b/docs/qapi-code-gen.txt @@ -60,10 +60,34 @@ example of a complex type is: { 'type': 'MyType', 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } } -The use of '*' as a prefix to the name means the member is optional. Optional -members should always be added to the end of the dictionary to preserve -backwards compatibility. - +The use of '*' as a prefix to the name means the member is optional. + +The default initialization value of an optional argument should not be changed +between versions of QEMU unless the new default maintains backward +compatibility to the user-visible behavior of the old default. + +With proper documentation, this policy still allows some flexibility; for +example, documenting that a default of 0 picks an optimal buffer size allows +one release to declare the optimal size at 512 while another release declares +the optimal size at 4096 - the user-visible behavior is not the bytes used by +the buffer, but the fact that the buffer was optimal size. + +On input structures (only mentioned in the 'data' side of a command), changing +from mandatory to optional is safe (older clients will supply the option, and +newer clients can benefit from the default); changing from optional to +mandatory is backwards incompatible (older clients may be omitting the option, +and must continue to work). + +On output structures (only mentioned in the 'returns' side of a command), +changing from mandatory to optional is in general unsafe (older clients may be +expecting the field, and could crash if it is missing), although it can be done +if the only way that the optional argument will be omitted is when it is +triggered by the presence of a new input flag to the command that older clients +don't know to send. Changing from optional to mandatory is safe. + +A structure that is used in both input and output of various commands +must consider the backwards compatibility constraints of both directions +of use. A complex type definition can specify another complex type as its base. In this case, the fields of the base type are included as top-level fields -- cgit v1.1