diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/devel/migration.rst | 15 | ||||
| -rw-r--r-- | docs/devel/qapi-code-gen.txt | 140 | ||||
| -rw-r--r-- | docs/generic-loader.txt | 20 | ||||
| -rw-r--r-- | docs/interop/live-block-operations.rst | 4 | ||||
| -rw-r--r-- | docs/interop/qmp-spec.txt | 42 | ||||
| -rw-r--r-- | docs/nvdimm.txt | 22 | ||||
| -rw-r--r-- | docs/usb2.txt | 4 | ||||
| -rw-r--r-- | docs/virtio-balloon-stats.txt | 6 |
8 files changed, 181 insertions, 72 deletions
diff --git a/docs/devel/migration.rst b/docs/devel/migration.rst index 6ed3fce061..687570754d 100644 --- a/docs/devel/migration.rst +++ b/docs/devel/migration.rst @@ -240,10 +240,13 @@ should succeed even with the data missing. To support this the subsection can be connected to a device property and from there to a versioned machine type. -One important note is that the post_load() function is called "after" -loading all subsections, because a newer subsection could change same -value that it uses. A flag, and the combination of pre_load and post_load -can be used to detect whether a subsection was loaded, and to +The 'pre_load' and 'post_load' functions on subsections are only +called if the subsection is loaded. + +One important note is that the outer post_load() function is called "after" +loading all subsections, because a newer subsection could change the same +value that it uses. A flag, and the combination of outer pre_load and +post_load can be used to detect whether a subsection was loaded, and to fall back on default behaviour when the subsection isn't present. Example: @@ -315,8 +318,8 @@ For example: the property to false. c) Add a static bool support_foo function that tests the property. d) Add a subsection with a .needed set to the support_foo function - e) (potentially) Add a pre_load that sets up a default value for 'foo' - to be used if the subsection isn't loaded. + e) (potentially) Add an outer pre_load that sets up a default value + for 'foo' to be used if the subsection isn't loaded. Now that subsection will not be generated when using an older machine type and the migration stream will be accepted by older diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index c2e11465f0..53eaf01f34 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -1035,7 +1035,7 @@ Example: #ifndef EXAMPLE_QAPI_TYPES_H #define EXAMPLE_QAPI_TYPES_H -[Built-in types omitted...] + #include "qapi/qapi-builtin-types.h" typedef struct UserDefOne UserDefOne; @@ -1062,7 +1062,7 @@ Example: UserDefOneList *arg1; }; - #endif + #endif /* EXAMPLE_QAPI_TYPES_H */ $ cat qapi-generated/example-qapi-types.c [Uninteresting stuff omitted...] @@ -1092,6 +1092,8 @@ Example: visit_free(v); } +[Uninteresting stuff omitted...] + === Code generated for visiting QAPI types === These are the visitor functions used to walk through and convert @@ -1118,7 +1120,9 @@ Example: #ifndef EXAMPLE_QAPI_VISIT_H #define EXAMPLE_QAPI_VISIT_H -[Visitors for built-in types omitted...] + #include "qapi/qapi-builtin-visit.h" + #include "example-qapi-types.h" + void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp); void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp); @@ -1126,7 +1130,7 @@ Example: void visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp); - #endif + #endif /* EXAMPLE_QAPI_VISIT_H */ $ cat qapi-generated/example-qapi-visit.c [Uninteresting stuff omitted...] @@ -1219,6 +1223,8 @@ Example: error_propagate(errp, err); } +[Uninteresting stuff omitted...] + === Code generated for commands === These are the marshaling/dispatch functions for the commands defined @@ -1238,18 +1244,17 @@ Example: $ cat qapi-generated/example-qapi-commands.h [Uninteresting stuff omitted...] - #ifndef EXAMPLE_QMP_COMMANDS_H - #define EXAMPLE_QMP_COMMANDS_H + #ifndef EXAMPLE_QAPI_COMMANDS_H + #define EXAMPLE_QAPI_COMMANDS_H #include "example-qapi-types.h" - #include "qapi/qmp/qdict.h" #include "qapi/qmp/dispatch.h" - void example_qmp_init_marshal(QmpCommandList *cmds); UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp); void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp); + void example_qmp_init_marshal(QmpCommandList *cmds); - #endif + #endif /* EXAMPLE_QAPI_COMMANDS_H */ $ cat qapi-generated/example-qapi-commands.c [Uninteresting stuff omitted...] @@ -1316,6 +1321,8 @@ Example: qmp_marshal_my_command, QCO_NO_OPTIONS); } +[Uninteresting stuff omitted...] + === Code generated for events === This is the code related to events defined in the schema, providing @@ -1333,14 +1340,14 @@ Example: $ cat qapi-generated/example-qapi-events.h [Uninteresting stuff omitted...] - #ifndef EXAMPLE_QAPI_EVENT_H - #define EXAMPLE_QAPI_EVENT_H + #ifndef EXAMPLE_QAPI_EVENTS_H + #define EXAMPLE_QAPI_EVENTS_H - #include "qapi/qmp/qdict.h" + #include "qapi/util.h" #include "example-qapi-types.h" - void qapi_event_send_my_event(Error **errp); + void qapi_event_send_my_event(void); typedef enum example_QAPIEvent { EXAMPLE_QAPI_EVENT_MY_EVENT = 0, @@ -1348,18 +1355,17 @@ Example: } example_QAPIEvent; #define example_QAPIEvent_str(val) \ - qapi_enum_lookup(example_QAPIEvent_lookup, (val)) + qapi_enum_lookup(&example_QAPIEvent_lookup, (val)) - extern const char *const example_QAPIEvent_lookup[]; + extern const QEnumLookup example_QAPIEvent_lookup; - #endif + #endif /* EXAMPLE_QAPI_EVENTS_H */ $ cat qapi-generated/example-qapi-events.c [Uninteresting stuff omitted...] - void qapi_event_send_my_event(Error **errp) + void qapi_event_send_my_event(void) { QDict *qmp; - Error *err = NULL; QMPEventFuncEmit emit; emit = qmp_event_get_func_emit(); @@ -1369,9 +1375,8 @@ Example: qmp = qmp_event_build_dict("MY_EVENT"); - emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp, &err); + emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp); - error_propagate(errp, err); qobject_unref(qmp); } @@ -1382,6 +1387,8 @@ Example: .size = EXAMPLE_QAPI_EVENT__MAX }; +[Uninteresting stuff omitted...] + === Code generated for introspection === The following files are created: @@ -1396,30 +1403,93 @@ Example: $ cat qapi-generated/example-qapi-introspect.h [Uninteresting stuff omitted...] - #ifndef EXAMPLE_QMP_INTROSPECT_H - #define EXAMPLE_QMP_INTROSPECT_H + #ifndef EXAMPLE_QAPI_INTROSPECT_H + #define EXAMPLE_QAPI_INTROSPECT_H - extern const QLitObject qmp_schema_qlit; + #include "qapi/qmp/qlit.h" - #endif + extern const QLitObject example_qmp_schema_qlit; + + #endif /* EXAMPLE_QAPI_INTROSPECT_H */ $ cat qapi-generated/example-qapi-introspect.c [Uninteresting stuff omitted...] const QLitObject example_qmp_schema_qlit = QLIT_QLIST(((QLitObject[]) { QLIT_QDICT(((QLitDictEntry[]) { - { "arg-type", QLIT_QSTR("0") }, - { "meta-type", QLIT_QSTR("event") }, - { "name", QLIT_QSTR("Event") }, - { } + { "arg-type", QLIT_QSTR("0"), }, + { "meta-type", QLIT_QSTR("command"), }, + { "name", QLIT_QSTR("my-command"), }, + { "ret-type", QLIT_QSTR("1"), }, + {} })), QLIT_QDICT(((QLitDictEntry[]) { + { "arg-type", QLIT_QSTR("2"), }, + { "meta-type", QLIT_QSTR("event"), }, + { "name", QLIT_QSTR("MY_EVENT"), }, + {} + })), + /* "0" = q_obj_my-command-arg */ + QLIT_QDICT(((QLitDictEntry[]) { + { "members", QLIT_QLIST(((QLitObject[]) { + QLIT_QDICT(((QLitDictEntry[]) { + { "name", QLIT_QSTR("arg1"), }, + { "type", QLIT_QSTR("[1]"), }, + {} + })), + {} + })), }, + { "meta-type", QLIT_QSTR("object"), }, + { "name", QLIT_QSTR("0"), }, + {} + })), + /* "1" = UserDefOne */ + QLIT_QDICT(((QLitDictEntry[]) { { "members", QLIT_QLIST(((QLitObject[]) { - { } - })) }, - { "meta-type", QLIT_QSTR("object") }, - { "name", QLIT_QSTR("0") }, - { } + QLIT_QDICT(((QLitDictEntry[]) { + { "name", QLIT_QSTR("integer"), }, + { "type", QLIT_QSTR("int"), }, + {} + })), + QLIT_QDICT(((QLitDictEntry[]) { + { "default", QLIT_QNULL, }, + { "name", QLIT_QSTR("string"), }, + { "type", QLIT_QSTR("str"), }, + {} + })), + {} + })), }, + { "meta-type", QLIT_QSTR("object"), }, + { "name", QLIT_QSTR("1"), }, + {} })), - ... - { } + /* "2" = q_empty */ + QLIT_QDICT(((QLitDictEntry[]) { + { "members", QLIT_QLIST(((QLitObject[]) { + {} + })), }, + { "meta-type", QLIT_QSTR("object"), }, + { "name", QLIT_QSTR("2"), }, + {} + })), + QLIT_QDICT(((QLitDictEntry[]) { + { "element-type", QLIT_QSTR("1"), }, + { "meta-type", QLIT_QSTR("array"), }, + { "name", QLIT_QSTR("[1]"), }, + {} + })), + QLIT_QDICT(((QLitDictEntry[]) { + { "json-type", QLIT_QSTR("int"), }, + { "meta-type", QLIT_QSTR("builtin"), }, + { "name", QLIT_QSTR("int"), }, + {} + })), + QLIT_QDICT(((QLitDictEntry[]) { + { "json-type", QLIT_QSTR("string"), }, + { "meta-type", QLIT_QSTR("builtin"), }, + { "name", QLIT_QSTR("str"), }, + {} + })), + {} })); + +[Uninteresting stuff omitted...] diff --git a/docs/generic-loader.txt b/docs/generic-loader.txt index 31bbcd42f6..a9603a2af7 100644 --- a/docs/generic-loader.txt +++ b/docs/generic-loader.txt @@ -56,25 +56,25 @@ An example of setting CPU 0's PC to 0x8000 is: Loading Files ------------- -The loader device also allows files to be loaded into memory. It can load raw -files and ELF executable files. Raw files are loaded verbatim. ELF executable -files are loaded by an ELF loader. The syntax is shown below: +The loader device also allows files to be loaded into memory. It can load ELF, +U-Boot, and Intel HEX executable formats as well as raw images. The syntax is +shown below: -device loader,file=<file>[,addr=<addr>][,cpu-num=<cpu-num>][,force-raw=<raw>] <file> - A file to be loaded into memory - <addr> - The addr in memory that the file should be loaded. This is - ignored if you are using an ELF (unless force-raw is true). - This is required if you aren't loading an ELF. + <addr> - The memory address where the file should be loaded. This is + required for raw images and ignored for non-raw files. <cpu-num> - This specifies the CPU that should be used. This is an optional argument and will cause the CPU's PC to be set to - where the image is stored or in the case of an ELF file to - the value in the header. This option should only be used - for the boot image. + the memory address where the raw file is loaded or the entry + point specified in the executable format header. This option + should only be used for the boot image. This will also cause the image to be written to the specified CPU's address space. If not specified, the default is CPU 0. <force-raw> - Setting force-raw=on forces the file to be treated as a raw - image. This can be used to load ELF files as if they were raw. + image. This can be used to load supported executable formats + as if they were raw. All values are parsed using the standard QemuOps parsing. This allows the user to specify any values in any format supported. By default the values diff --git a/docs/interop/live-block-operations.rst b/docs/interop/live-block-operations.rst index 734252bc80..48afdc7927 100644 --- a/docs/interop/live-block-operations.rst +++ b/docs/interop/live-block-operations.rst @@ -129,7 +129,7 @@ To show some example invocations of command-line, we will use the following invocation of QEMU, with a QMP server running over UNIX socket:: - $ ./x86_64-softmmu/qemu-system-x86_64 -display none -nodefconfig \ + $ ./x86_64-softmmu/qemu-system-x86_64 -display none -no-user-config \ -M q35 -nodefaults -m 512 \ -blockdev node-name=node-A,driver=qcow2,file.driver=file,file.node-name=file,file.filename=./a.qcow2 \ -device virtio-blk,drive=node-A,id=virtio0 \ @@ -694,7 +694,7 @@ instance, with the following invocation. (As noted earlier, for simplicity's sake, the destination QEMU is started on the same host, but it could be located elsewhere):: - $ ./x86_64-softmmu/qemu-system-x86_64 -display none -nodefconfig \ + $ ./x86_64-softmmu/qemu-system-x86_64 -display none -no-user-config \ -M q35 -nodefaults -m 512 \ -blockdev node-name=node-TargetDisk,driver=qcow2,file.driver=file,file.node-name=file,file.filename=./target-disk.qcow2 \ -device virtio-blk,drive=node-TargetDisk,id=virtio0 \ diff --git a/docs/interop/qmp-spec.txt b/docs/interop/qmp-spec.txt index 1566b8ae5e..8f7da0245d 100644 --- a/docs/interop/qmp-spec.txt +++ b/docs/interop/qmp-spec.txt @@ -20,9 +20,9 @@ operating system. 2. Protocol Specification ========================= -This section details the protocol format. For the purpose of this document -"Client" is any application which is using QMP to communicate with QEMU and -"Server" is QEMU itself. +This section details the protocol format. For the purpose of this +document, "Server" is either QEMU or the QEMU Guest Agent, and +"Client" is any application communicating with it via QMP. JSON data structures, when mentioned in this document, are always in the following format: @@ -34,9 +34,8 @@ by the JSON standard: http://www.ietf.org/rfc/rfc7159.txt -The protocol is always encoded in UTF-8 except for synchronization -bytes (documented below); although thanks to json-string escape -sequences, the server will reply using only the strict ASCII subset. +The server expects its input to be encoded in UTF-8, and sends its +output encoded in ASCII. For convenience, json-object members mentioned in this document will be in a certain order. However, in real protocol usage they can be in @@ -215,16 +214,31 @@ Some events are rate-limited to at most one per second. If additional dropped, and the last one is delayed. "Similar" normally means same event type. See qmp-events.txt for details. -2.6 QGA Synchronization +2.6 Forcing the JSON parser into known-good state +------------------------------------------------- + +Incomplete or invalid input can leave the server's JSON parser in a +state where it can't parse additional commands. To get it back into +known-good state, the client should provoke a lexical error. + +The cleanest way to do that is sending an ASCII control character +other than '\t' (horizontal tab), '\r' (carriage return), or '\n' (new +line). + +Sadly, older versions of QEMU can fail to flag this as an error. If a +client needs to deal with them, it should send a 0xFF byte. + +2.7 QGA Synchronization ----------------------- -When using QGA, an additional synchronization feature is built into -the protocol. If the Client sends a raw 0xFF sentinel byte (not valid -JSON), then the Server will reset its state and discard all pending -data prior to the sentinel. Conversely, if the Client makes use of -the 'guest-sync-delimited' command, the Server will send a raw 0xFF -sentinel byte prior to its response, to aid the Client in discarding -any data prior to the sentinel. +When a client connects to QGA over a transport lacking proper +connection semantics such as virtio-serial, QGA may have read partial +input from a previous client. The client needs to force QGA's parser +into known-good state using the previous section's technique. +Moreover, the client may receive output a previous client didn't read. +To help with skipping that output, QGA provides the +'guest-sync-delimited' command. Refer to its documentation for +details. 3. QMP Examples diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt index 24b443b655..5f158a6170 100644 --- a/docs/nvdimm.txt +++ b/docs/nvdimm.txt @@ -173,3 +173,25 @@ There are currently two valid values for this option: the NVDIMMs in the event of power loss. This implies that the platform also supports flushing dirty data through the memory controller on power loss. + +If the vNVDIMM backend is in host persistent memory that can be accessed in +SNIA NVM Programming Model [1] (e.g., Intel NVDIMM), it's suggested to set +the 'pmem' option of memory-backend-file to 'on'. When 'pmem' is 'on' and QEMU +is built with libpmem [2] support (configured with --enable-libpmem), QEMU +will take necessary operations to guarantee the persistence of its own writes +to the vNVDIMM backend(e.g., in vNVDIMM label emulation and live migration). +If 'pmem' is 'on' while there is no libpmem support, qemu will exit and report +a "lack of libpmem support" message to ensure the persistence is available. +For example, if we want to ensure the persistence for some backend file, +use the QEMU command line: + + -object memory-backend-file,id=nv_mem,mem-path=/XXX/yyy,size=4G,pmem=on + +References +---------- + +[1] NVM Programming Model (NPM) + Version 1.2 + https://www.snia.org/sites/default/files/technical_work/final/NVMProgrammingModel_v1.2.pdf +[2] Persistent Memory Development Kit (PMDK), formerly known as NVML project, home page: + http://pmem.io/pmdk/ diff --git a/docs/usb2.txt b/docs/usb2.txt index f63c8d9465..172614d3a7 100644 --- a/docs/usb2.txt +++ b/docs/usb2.txt @@ -94,8 +94,8 @@ physical port addressing First you can (for all USB devices) specify the physical port where the device will show up in the guest. This can be done using the -"port" property. UHCI has two root ports (1,2). EHCI has four root -ports (1-4), the emulated (1.1) USB hub has eight ports. +"port" property. UHCI has two root ports (1,2). EHCI has six root +ports (1-6), the emulated (1.1) USB hub has eight ports. Plugging a tablet into UHCI port 1 works like this: diff --git a/docs/virtio-balloon-stats.txt b/docs/virtio-balloon-stats.txt index 9985e1dffc..1732cc8c8a 100644 --- a/docs/virtio-balloon-stats.txt +++ b/docs/virtio-balloon-stats.txt @@ -61,9 +61,9 @@ It's also important to note the following: respond to the request the timer will never be re-armed, which has the same effect as disabling polling -Here are a few examples. QEMU is started with '-balloon virtio', which -generates '/machine/peripheral-anon/device[1]' as the QOM path for the -balloon device. +Here are a few examples. QEMU is started with '-device virtio-balloon', +which generates '/machine/peripheral-anon/device[1]' as the QOM path for +the balloon device. Enable polling with 2 seconds interval: |