aboutsummaryrefslogtreecommitdiff
path: root/hmp-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 /hmp-commands.hx
parent5c230105cdea8ac9338bd5b4485c6ae80ec1fa18 (diff)
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 'hmp-commands.hx')
-rw-r--r--hmp-commands.hx37
1 files changed, 17 insertions, 20 deletions
diff --git a/hmp-commands.hx b/hmp-commands.hx
index bdd48f3469..66ec716e03 100644
--- a/hmp-commands.hx
+++ b/hmp-commands.hx
@@ -841,40 +841,37 @@ Inject an NMI on the given CPU (x86 only).
ETEXI
{
- .name = "memchar_write",
+ .name = "ringbuf_write",
.args_type = "device:s,data:s",
.params = "device data",
- .help = "Provide writing interface for CirMemCharDriver. Write"
- "'data' to it.",
- .mhandler.cmd = hmp_memchar_write,
+ .help = "Write to a ring buffer character device",
+ .mhandler.cmd = hmp_ringbuf_write,
},
STEXI
-@item memchar_write @var{device} @var{data}
-@findex memchar_write
-Provide writing interface for CirMemCharDriver. Write @var{data}
-to char device 'memory'.
+@item ringbuf_write @var{device} @var{data}
+@findex ringbuf_write
+Write @var{data} to ring buffer character device @var{device}.
+@var{data} must be a UTF-8 string.
ETEXI
{
- .name = "memchar_read",
+ .name = "ringbuf_read",
.args_type = "device:s,size:i",
.params = "device size",
- .help = "Provide read interface for CirMemCharDriver. Read from"
- "it and return the data with size.",
- .mhandler.cmd = hmp_memchar_read,
+ .help = "Read from a ring buffer character device",
+ .mhandler.cmd = hmp_ringbuf_read,
},
STEXI
-@item memchar_read @var{device}
-@findex memchar_read
-Provide read interface for CirMemCharDriver. Read from char device
-'memory' and return the data.
-
-@var{size} is the size of data want to read from. 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.
+@item ringbuf_read @var{device}
+@findex ringbuf_read
+Read and print up to @var{size} bytes from ring buffer character
+device @var{device}.
+Bug: can screw up when the buffer contains invalid UTF-8 sequences,
+NUL characters, after the ring buffer lost data, and when reading
+stops because the size limit is reached.
ETEXI