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

[Julien Grall <julien.grall@xxxxxxx>]

Hi,

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
> "characters"
Fixed.

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

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

--
Julien Grall

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