diff options
author | Markus Armbruster <armbru@redhat.com> | 2013-02-06 21:27:24 +0100 |
---|---|---|
committer | Anthony Liguori <aliguori@us.ibm.com> | 2013-02-06 16:35:19 -0600 |
commit | 3949e59414fccefadc50ae65650d676cc734048c (patch) | |
tree | bb6d54b1ce4491ec37c74d06cbf6e4aedefa54a9 /qmp-commands.hx | |
parent | 5c230105cdea8ac9338bd5b4485c6ae80ec1fa18 (diff) | |
download | qemu-3949e59414fccefadc50ae65650d676cc734048c.zip qemu-3949e59414fccefadc50ae65650d676cc734048c.tar.gz qemu-3949e59414fccefadc50ae65650d676cc734048c.tar.bz2 |
qemu-char: Saner naming of memchar stuff & doc fixes
New device, has never been released, so we can still improve things
without worrying about compatibility.
Naming is a mess. The code calls the device driver CirMemCharDriver,
the public API calls it "memory", "memchardev", or "memchar", and the
special commands are named like "memchar-FOO". "memory" is a
particularly unfortunate choice, because there's another character
device driver called MemoryDriver. Moreover, the device's distinctive
property is that it's a ring buffer, not that's in memory. Therefore:
* Rename CirMemCharDriver to RingBufCharDriver, and call the thing a
"ringbuf" in the API.
* Rename QMP and HMP commands from memchar-FOO to ringbuf-FOO.
* Rename device parameter from maxcapacity to size (simple words are
good for you).
* Clearly mark the parameter as optional in documentation.
* Fix error reporting so that chardev-add reports to current monitor,
not stderr.
* Replace cirmem in C identifiers by ringbuf.
* Rework documentation. Document the impact of our crappy UTF-8
handling on reading.
* QMP examples that even work.
I could split this up into multiple commits, but they'd change the
same documentation lines multiple times. Not worth it.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
Diffstat (limited to 'qmp-commands.hx')
-rw-r--r-- | qmp-commands.hx | 55 |
1 files changed, 29 insertions, 26 deletions
diff --git a/qmp-commands.hx b/qmp-commands.hx index 51ce2e6..799adea 100644 --- a/qmp-commands.hx +++ b/qmp-commands.hx @@ -466,30 +466,30 @@ Note: inject-nmi fails when the guest doesn't support injecting. EQMP { - .name = "memchar-write", + .name = "ringbuf-write", .args_type = "device:s,data:s,format:s?", - .mhandler.cmd_new = qmp_marshal_input_memchar_write, + .mhandler.cmd_new = qmp_marshal_input_ringbuf_write, }, SQMP -memchar-write +ringbuf-write ------------- -Provide writing interface for CirMemCharDriver. Write data to memory -char device. +Write to a ring buffer character device. Arguments: -- "device": the name of the char device, must be unique (json-string) -- "data": the source data write to memory (json-string) -- "format": the data format write to memory, default is - utf8. (json-string, optional) - - Possible values: "utf8", "base64" +- "device": ring buffer character device name (json-string) +- "data": data to write (json-string) +- "format": data format (json-string, optional) + - Possible values: "utf8" (default), "base64" + Bug: invalid base64 is currently not rejected. + Whitespace *is* invalid. Example: --> { "execute": "memchar-write", - "arguments": { "device": foo, +-> { "execute": "ringbuf-write", + "arguments": { "device": "foo", "data": "abcdefgh", "format": "utf8" } } <- { "return": {} } @@ -497,32 +497,35 @@ Example: EQMP { - .name = "memchar-read", + .name = "ringbuf-read", .args_type = "device:s,size:i,format:s?", - .mhandler.cmd_new = qmp_marshal_input_memchar_read, + .mhandler.cmd_new = qmp_marshal_input_ringbuf_read, }, SQMP -memchar-read +ringbuf-read ------------- -Provide read interface for CirMemCharDriver. Read from the char -device memory and return the data with size. +Read from a ring buffer character device. Arguments: -- "device": the name of the char device, must be unique (json-string) -- "size": the memory size wanted to read in bytes (refer to unencoded - size of the raw data), would adjust to the init size of the - memchar if the requested size is larger than it. (json-int) -- "format": the data format write to memchardev, default is - utf8. (json-string, optional) - - Possible values: "utf8", "base64" +- "device": ring buffer character device name (json-string) +- "size": how many bytes to read at most (json-int) + - Number of data bytes, not number of characters in encoded data +- "format": data format (json-string, optional) + - Possible values: "utf8" (default), "base64" + - Naturally, format "utf8" works only when the ring buffer + contains valid UTF-8 text. Invalid UTF-8 sequences get + replaced. Bug: replacement doesn't work. Bug: can screw + up on encountering NUL characters, after the ring buffer + lost data, and when reading stops because the size limit + is reached. Example: --> { "execute": "memchar-read", - "arguments": { "device": foo, +-> { "execute": "ringbuf-read", + "arguments": { "device": "foo", "size": 1000, "format": "utf8" } } <- {"return": "abcdefgh"} |