Re: [Xen-devel] [PATCH 25/25 v6] xen/arm: vpl011: Update documentation for vuart console support

[Julien Grall <julien.grall@xxxxxxx>]

Hi Bhupinder,

Sorry I am jumping a bit late in the discussion here.

On 17/07/17 14:06, Bhupinder Thakur wrote:
> 1. Update documentation for a new vuart option added.
> 2. Update documentation about SPI irq reserved for vuart.
>
> Signed-off-by: Bhupinder Thakur <bhupinder.thakur@xxxxxxxxxx>
> Reviewed-by: Stefano Stabellini <sstabellini@xxxxxxxxxx>
> Acked-by: Wei Liu <wei.liu2@xxxxxxxxxx>
> ---
> CC: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
> CC: Wei Liu <wei.liu2@xxxxxxxxxx>
> CC: Stefano Stabellini <sstabellini@xxxxxxxxxx>
> CC: Julien Grall <julien.grall@xxxxxxx>
>
> Changes since v4:
> - Minor change to rename "pl011" to "sbsa_uart". Since it is a minor change I 
> have
>   retained the reviewed-by and acked-by tags.
>
>  docs/man/xl.cfg.pod.5.in |  9 +++++++++
>  docs/misc/console.txt    | 44 +++++++++++++++++++++++++++++++++-----------
>  2 files changed, 42 insertions(+), 11 deletions(-)
>
> diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in
> index 79cb2ea..75f9169 100644
> --- a/docs/man/xl.cfg.pod.5.in
> +++ b/docs/man/xl.cfg.pod.5.in
> @@ -1105,6 +1105,15 @@ Allow a guest to access specific physical IRQs.
>  It is recommended to only use this option for trusted VMs under
>  administrator's control.
>
> +If the virtual uart is enabled then irq 32 is reserved for it.  By
> +default, it is disabled. If the user specifies the following option in
> +the VM config file then the vuart gets enabled. Today, only the
> +"sbsa_uart" model is supported.
> +
> +vuart = "sbsa_uart"
> +
> +Currently vuart console is available only for ARM64.
vuart console is available for both AArch32 and AArch64.

Furthermore, it looks a bit odd you describe how to use vuart in irqs 
option. You want to describe it in a separate section:
=item B<vuart="uart">

See how we did with gic_version. You also want to place this in the 
alphabetical order and probably in the ARM section if it is only 
supported by ARM today.
> +
>  =item B<max_event_channels=N>
>
>  Limit the guest to using at most N event channels (PV interrupts).
> diff --git a/docs/misc/console.txt b/docs/misc/console.txt
> index 16da805..d081acc 100644
> --- a/docs/misc/console.txt
> +++ b/docs/misc/console.txt
> @@ -19,7 +19,20 @@ The first PV console path in xenstore remains:
>
>  /local/domain/$DOMID/console
>
> -the other PV consoles follow the conventional xenstore device path and
> +The virtual UART console path in xenstore is defined as:
> +
> +/local/domain/$DOMID/vuart/0
> +
> +The vuart console provides access to a virtual SBSA UART on ARM64 systems.
> +To enable vuart the following line has to be added to the guest configuration
> +file:
> +
> +vuart = "sbsa_uart"
> +
> +In Linux you can select the virtual SBSA UART by using the "ttyAMA0"
> +console instead of "hvc0".
> +
> +The other PV consoles follow the conventional xenstore device path and
>  live in:
>
>  /local/domain/$DOMID/device/console/$DEVID.
> @@ -61,6 +74,14 @@ output = pty
>  The backend will write the pty device name to the "tty" node in the
>  console frontend.
>
> +For the PV console the tty node is added at
> +
> +/local/domain/$DOMID/console/tty
> +
> +For the virtual UART console the tty node is added at
> +
> +/local/domain/$DOMID/vuart/0/tty
> +
>  If the toolstack wants a listening Unix domain socket to be created at path
>  <path>, a connection accepted and data proxied to the console, it will write:
>
> @@ -79,8 +100,8 @@ For example:
>  ioemu
>
>  The supported values are only xenconsoled or ioemu; xenconsoled has
> -several limitations: it can only be used for the first PV console and it
> -can only connect to a pty.
> +several limitations: it can only be used for the first PV or virtual UART
> +console and it can only connect to a pty.
>
>  Emulated serials are provided by qemu-dm only to hvm guests; the number
>  of emulated serials depends on how many "-serial" command line options
> @@ -90,14 +111,15 @@ xenstore in the following path:
>
>  /local/domain/$DOMID/serial/$SERIAL_NUM/tty
>
> -xenconsole is the tool to connect to a PV console or an emulated serial
> -that has a pty as output. Xenconsole takes a domid as parameter plus an
> -optional console type (pv for PV consoles or serial for emulated
> -serials) and console number. Depending on the type and console
> -number, xenconsole will look for the tty node in different xenstore
> -paths, as described above.  If the user doesn't specify the console type
> -xenconsole will try to guess: if the guest is a pv guest it defaults to
> -PV console, if the guest is an hvm guest it defaults to emulated serial.
> +xenconsole is the tool to connect to a PV or virtual UART console or an
> +emulated serial that has a pty as output. Xenconsole takes a domid as
> +parameter plus an optional console type (pv for PV consoles, vuart for
> +virtual UART or serial for emulated serials) and console number.
> +Depending on the type and console number, xenconsole will look for the tty
> +node in different xenstore paths, as described above.  If the user doesn't
> +specify the console type xenconsole will try to guess: if the guest is a pv
> +guest it defaults to PV console, if the guest is an hvm guest it defaults to
> +emulated serial.
>
>  By default xl creates a pv console for hvm guests, plus an emulated
>  serial if the user specified 'serial = "pty"' in the VM config file.
Cheers,

--
Julien Grall

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
https://lists.xen.org/xen-devel