Merge remote-tracking branch 'remotes/qmp-unstable/queue/qmp' into st…

…aging

* remotes/qmp-unstable/queue/qmp: (38 commits)
  Revert "qapi: Clean up superfluous null check in qapi_dealloc_type_str()"
  qapi: Document optional arguments' backwards compatibility
  qmp: use valid JSON in transaction example
  qmp: Don't use error_is_set() to suppress additional errors
  dump: Drop pointless error_is_set(), DumpState member errp
  qemu-option: Clean up fragile use of error_is_set()
  qga: Drop superfluous error_is_set()
  qga: Clean up fragile use of error_is_set()
  qapi: Clean up fragile use of error_is_set()
  tests/qapi-schema: Drop superfluous error_is_set()
  qapi: Drop redundant, unclean error_is_set()
  hmp: Guard against misuse of hmp_handle_error()
  qga: Use return values instead of error_is_set(errp)
  error: Consistently name Error ** objects errp, and not err
  qmp: Consistently name Error ** objects errp, and not err
  qga: Consistently name Error ** objects errp, and not err
  qmp hmp: Consistently name Error * objects err, and not errp
  pci-assign: assigned_initfn(): set monitor error in common error handler
  pci-assign: propagate errors from assign_intx()
  pci-assign: propagate errors from assign_device()
  ...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Makefile

@@ -238,23 +238,35 @@ qapi-py = $(SRC_PATH)/scripts/qapi.py $(SRC_PATH)/scripts/ordereddict.py
 
 qga/qapi-generated/qga-qapi-types.c qga/qapi-generated/qga-qapi-types.h :\
 $(SRC_PATH)/qga/qapi-schema.json $(SRC_PATH)/scripts/qapi-types.py $(qapi-py)
-	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-types.py $(gen-out-type) -o qga/qapi-generated -p "qga-" < $<, "  GEN   $@")
+	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-types.py \
+		$(gen-out-type) -o qga/qapi-generated -p "qga-" -i $<, \
+		"  GEN   $@")
 qga/qapi-generated/qga-qapi-visit.c qga/qapi-generated/qga-qapi-visit.h :\
 $(SRC_PATH)/qga/qapi-schema.json $(SRC_PATH)/scripts/qapi-visit.py $(qapi-py)
-	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-visit.py $(gen-out-type) -o qga/qapi-generated -p "qga-" < $<, "  GEN   $@")
+	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-visit.py \
+		$(gen-out-type) -o qga/qapi-generated -p "qga-" -i $<, \
+		"  GEN   $@")
 qga/qapi-generated/qga-qmp-commands.h qga/qapi-generated/qga-qmp-marshal.c :\
 $(SRC_PATH)/qga/qapi-schema.json $(SRC_PATH)/scripts/qapi-commands.py $(qapi-py)
-	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-commands.py $(gen-out-type) -o qga/qapi-generated -p "qga-" < $<, "  GEN   $@")
+	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-commands.py \
+		$(gen-out-type) -o qga/qapi-generated -p "qga-" -i $<, \
+		"  GEN   $@")
 
 qapi-types.c qapi-types.h :\
 $(SRC_PATH)/qapi-schema.json $(SRC_PATH)/scripts/qapi-types.py $(qapi-py)
-	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-types.py $(gen-out-type) -o "." -b < $<, "  GEN   $@")
+	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-types.py \
+		$(gen-out-type) -o "." -b -i $<, \
+		"  GEN   $@")
 qapi-visit.c qapi-visit.h :\
 $(SRC_PATH)/qapi-schema.json $(SRC_PATH)/scripts/qapi-visit.py $(qapi-py)
-	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-visit.py $(gen-out-type) -o "." -b < $<, "  GEN   $@")
+	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-visit.py \
+		$(gen-out-type) -o "." -b -i $<, \
+		"  GEN   $@")
 qmp-commands.h qmp-marshal.c :\
 $(SRC_PATH)/qapi-schema.json $(SRC_PATH)/scripts/qapi-commands.py $(qapi-py)
-	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-commands.py $(gen-out-type) -m -o "." < $<, "  GEN   $@")
+	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-commands.py \
+		$(gen-out-type) -o "." -m -i $<, \
+		"  GEN   $@")
 
 QGALIB_GEN=$(addprefix qga/qapi-generated/, qga-qapi-types.h qga-qapi-visit.h qga-qmp-commands.h)
 $(qga-obj-y) qemu-ga.o: $(QGALIB_GEN)

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
@@ -49,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
@@ -221,7 +256,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 +326,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 */
 

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;
     }
 

dump.c

@@ -86,7 +86,6 @@ typedef struct DumpState {
     bool has_filter;
     int64_t begin;
     int64_t length;
-    Error **errp;
 
     uint8_t *note_buf;          /* buffer for notes */
     size_t note_buf_offset;     /* the writing place in note_buf */
@@ -1570,7 +1569,6 @@ static int dump_init(DumpState *s, int fd, bool has_format,
         nr_cpus++;
     }
 
-    s->errp = errp;
     s->fd = fd;
     s->has_filter = has_filter;
     s->begin = begin;
@@ -1780,11 +1778,11 @@ void qmp_dump_guest_memory(bool paging, const char *file, bool has_begin,
     }
 
     if (has_format && format != DUMP_GUEST_MEMORY_FORMAT_ELF) {
-        if (create_kdump_vmcore(s) < 0 && !error_is_set(s->errp)) {
+        if (create_kdump_vmcore(s) < 0) {
             error_set(errp, QERR_IO_ERROR);
         }
     } else {
-        if (create_vmcore(s) < 0 && !error_is_set(s->errp)) {
+        if (create_vmcore(s) < 0) {
             error_set(errp, QERR_IO_ERROR);
         }
     }