From 3949e59414fccefadc50ae65650d676cc734048c Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 6 Feb 2013 21:27:24 +0100 Subject: 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 Reviewed-by: Eric Blake Signed-off-by: Anthony Liguori --- hmp-commands.hx | 37 +++++++++++++++++-------------------- 1 file changed, 17 insertions(+), 20 deletions(-) (limited to 'hmp-commands.hx') 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 -- cgit v1.2.3