aboutsummaryrefslogtreecommitdiff
path: root/qmp-commands.hx
diff options
context:
space:
mode:
authorMarkus Armbruster <armbru@redhat.com>2013-02-06 21:27:24 +0100
committerAnthony Liguori <aliguori@us.ibm.com>2013-02-06 16:35:19 -0600
commit3949e59414fccefadc50ae65650d676cc734048c (patch)
treebb6d54b1ce4491ec37c74d06cbf6e4aedefa54a9 /qmp-commands.hx
parent5c230105cdea8ac9338bd5b4485c6ae80ec1fa18 (diff)
downloadqemu-arm-3949e59414fccefadc50ae65650d676cc734048c.tar.gz
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.hx55
1 files changed, 29 insertions, 26 deletions
diff --git a/qmp-commands.hx b/qmp-commands.hx
index 51ce2e6b41..799adea1b7 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"}