motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-08-02 07:13:54 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

qemu-char: Saner naming of memchar stuff & doc fixes

Browse source 
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>
This commit is contained in:
Markus Armbruster 2013-02-06 21:27:24 +01:00 • committed by Anthony Liguori
parent 5c230105cd
commit 3949e59414
7 changed files with 122 additions and 107 deletions
Download patch file Download diff file Expand all files Collapse all files

37
hmp-commands.hx
View file

@ -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