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 --- qapi-schema.json | 47 +++++++++++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 18 deletions(-) (limited to 'qapi-schema.json') diff --git a/qapi-schema.json b/qapi-schema.json index 6f6379151f..736f881b75 100644 --- a/qapi-schema.json +++ b/qapi-schema.json @@ -329,9 +329,9 @@ # # An enumeration of data format. # -# @utf8: The data format is 'utf8'. +# @utf8: Data is a UTF-8 string (RFC 3629) # -# @base64: The data format is 'base64'. +# @base64: Data is Base64 encoded binary (RFC 3548) # # Since: 1.4 ## @@ -339,44 +339,55 @@ 'data': [ 'utf8', 'base64' ] } ## -# @memchar-write: +# @ringbuf-write: # -# Provide writing interface for memchardev. Write data to char -# device 'memory'. +# Write to a ring buffer character device. # -# @device: the name of the memory char device. +# @device: the ring buffer character device name # -# @data: the source data write to memchar. +# @data: data to write # -# @format: #optional the format of the data write to chardev 'memory', -# by default is 'utf8'. +# @format: #optional data encoding (default 'utf8'). +# - base64: data must be base64 encoded text. Its binary +# decoding gets written. +# Bug: invalid base64 is currently not rejected. +# Whitespace *is* invalid. +# - utf8: data's UTF-8 encoding is written +# - data itself is always Unicode regardless of format, like +# any other string. # # Returns: Nothing on success # # Since: 1.4 ## -{ 'command': 'memchar-write', +{ 'command': 'ringbuf-write', 'data': {'device': 'str', 'data': 'str', '*format': 'DataFormat'} } ## -# @memchar-read: +# @ringbuf-read: # -# Provide read interface for memchardev. Read from the char -# device 'memory' and return the data. +# Read from a ring buffer character device. # -# @device: the name of the memory char device. +# @device: the ring buffer character device name # -# @size: the size to read in bytes. +# @size: how many bytes to read at most # -# @format: #optional the format of the data want to read from -# memchardev, by default is 'utf8'. +# @format: #optional data encoding (default 'utf8'). +# - base64: the data read is returned in base64 encoding. +# - utf8: the data read is interpreted as UTF-8. +# 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. +# - The return value is always Unicode regardless of format, +# like any other string. # # Returns: data read from the device # # Since: 1.4 ## -{ 'command': 'memchar-read', +{ 'command': 'ringbuf-read', 'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'}, 'returns': 'str' } -- cgit v1.2.1