[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Xen-devel] [PATCH v2 3/4] xen/public: Document HYPERCALL_console_io()


On 08/08/2019 15:03, Jan Beulich wrote:
On 05.08.2019 15:29, Julien Grall wrote:
Currently, OS developpers will have to look at Xen code in order to know
the parameters of an hypercall and how it is meant to work.

This is not a trivial task as you may need to have a deep understanding
of Xen internal.

This patch attempts to document the behavior of HYPERCALL_console_io() to
help OS developer.

Signed-off-by: Julien Grall <julien.grall@xxxxxxx>

Acked-by: Jan Beulich <jbeulich@xxxxxxxx>
with a couple of nits:

--- a/xen/include/public/xen.h
+++ b/xen/include/public/xen.h
@@ -486,7 +486,29 @@ DEFINE_XEN_GUEST_HANDLE(mmuext_op_t);
   /* ` } */
- * Commands to HYPERVISOR_console_io().
+ * ` int
+ * ` HYPERVISOR_console_io(unsigned int cmd,
+ * `                       unsigned int count,
+ * `                       char buffer[]);
+ *
+ * @cmd: Command (see below)
+ * @count: Size of the buffer to read/write
+ * @buffer: Pointer in the guest memory
+ *
+ * List of commands:
+ *
+ *  * CONSOLEIO_write: Write the buffer on Xen console.

s/ on / to / ?

I am not entirely sure. Looking online [1] "on" would make sense here.

But I am not a native english speaker. @George, @Ian, @Andrew, any opinions?

+ *      For the hardware domain, all the characters in the buffer will
+ *      be written. Characters will be printed to directly to the

The first "to" looks to be unwanted.

Yes, I have dropped it.

+ *      console.
+ *      For all the other domains, only the printable characters will be
+ *      written. Characters may be buffered until a newline (i.e '\n') is
+ *      found.
+ *      @return 0 on success, otherwise return an error code.
+ *  * CONSOLEIO_read: Attempts to read up @count characters from Xen console.

"... up to @count ..."

+ *      The maximum buffer size (i.e @count) supported is 2GB.

"i.e." or "ie" are the two common forms I'm aware of.

Yes, I must have made up that one. I will use the i.e. form.

+ *      @return the number of character read on success, otherwise return



Thank you for the ack. I will wait for the on/to discussion to settle before committing.


[1] https://idioms.thefreedictionary.com/write+on

Julien Grall

Xen-devel mailing list



Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.