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

[Jan Beulich <JBeulich@xxxxxxxx>]

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 / ?

> + *      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.

> + *      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.

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

"characters"

Jan
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel