[Xen-devel,00/10,v2] pl011 emulation support in Xen

PL011 emulation for guests in Xen
===================================
Linaro has published VM System specification for ARM Processors, which
provides a set of guidelines for both guest OS and hypervisor implementations, 
such that building OS images according to these guidelines guarantees
that those images can also run on hypervisors compliant with this specification.

One of the spec requirements is that the hypervisor must provide an
emulated PL011 UART as a serial console which meets the minimum requirements in 
SBSA UART as defined in appendix B of the following ARM Server Base Architecture Document:

https://static.docs.arm.com/den0029/a/Server_Base_System_Architecture_v3_1_ARM_DEN_0029A.pdf.

This feature allows the Xen guests to use SBSA compliant pl011 UART as 
as a console. 

Note that SBSA pl011 UART is a subset of full featured ARM pl011 UART and
supports only a subset of registers as mentioned below. It does not support
rx/tx DMA.

Currently, Xen supports paravirtualized (aka PV console) and an emulated serial 
consoles. This feature will expose an emulated SBSA pl011 UART console to the
guest, which a user can access using xenconsole.

The device tree passed to the guest VM will contain the pl011 MMIO address 
range and an irq for receiving rx/tx pl011 interrupts. The device tree format 
is specified in Documentation/devicetree/bindings/serial/arm_sbsa_uart.txt.

The Xen hypervisor will expose two types of interfaces to the backend and domU. 

The interface exposed to domU will be an emulated pl011 UART by emulating the 
access to the following pl011 registers by the guest.

- Data register (DR)            - RW
- Raw interrupt status register (RIS)   - RO
- Masked interrupt status register (MIS)- RO
- Interrupt Mask (IMSC)         - RW
- Interrupt Clear (ICR)         - WO

It will also inject the pl011 interrupts to the guest in the following 
conditions:

- incoming data in the rx buffer for the guest
- there is space in the tx buffer for the guest to write more data

The interface exposed to the backend will be the same PV console interface, 
which minimizes the changes required in xenconsole to support a new pl011 console.

This interface has rx and tx ring buffers and an event channel for 
sending/receiving events from the backend. 

So essentially Xen handles the data on behalf of domU and the backend. Any data 
written by domU is captured by Xen and written to the TX (OUT) ring buffer 
and a pl011 event is raised to the backend to read the TX ring buffer.
 
Similarly on reciving a pl011 event, Xen injects an interrupt to guest to
indicate there is data available in the RX (IN) ring buffer.

Note that the pl011 UART state is completely captured in the set of registers 
mentioned above and this state is updated everytime there is an event from 
the backend or there is register read/write access from domU. 

For example, if domU has masked the rx interrupt in the IMSC register, then Xen 
will not inject an interrupt to guest and will just update the RIS register. 
Once the interrupt is unmasked by guest, the interrupt will be delivered to the 
guest.

Changes summary:

Xen Hypervisor
===============

1. Add emulation code to emulate read/write access to pl011 registers and pl011 
   interrupts:
    - It emulates DR read/write by reading and writing from/to the IN and 
      OUT ring buffers and raising an event to dom0 when there is data in 
      the OUT ring buffer and injecting an interrupt to the guest when there 
      is data in the IN ring buffer.
    - Other registers are related to interrupt management and essentially 
      control when interrupts are delivered to the guest.

2. Add two new domctl API to set and get pfn and evtchn respectively
    - Allocate a new event channel for sending/receiving events from Xen 
      and return to the toolstack.
    - Map the PFN allocted by the toolstack to be used as IN/OUT ring 
      buffers.

3. Enable vpl011 emulation for a domain based on a libxl option passed during 
   domain creation.

Toolstack
==========

1. Create a sbsa uart DT node in the guest device tree. It uses a fixed
   vpl011 SPI IRQ number and MMIO address.

2. Allocate a new PFN and pass it on to Xen though a hvm call to be used 
   as the IN/OUT ring buffers.

3. Add two new keys to the xen store
    - Allocate a PFN to be used as IN/OUT ring buffer by xenconsoled 
    - Read new event channel from Xen using a hvm call to be used by 
      xenconsoled for sending/receiving events.

Xenconsoled
============

1. Split the domain structure to support multiple consoles.

2. Modify different APIs such as buffer_append() etc. to operate on the 
   console structure.
   
3. Modfications in domain_create_ring(): 
    - Bind to the vpl011 event channel obtained from the xen store as a new
      parameter
    - Map the PFN to its address space to be used as IN/OUT ring buffers. 
      It obtains the PFN from the xen store as a new parameter

4. Modifications in handle_ring_read() to handle both PV and VUART
   events.

The vpl011 changes available at the following repo:

url: ssh://git@git.linaro.org:/people/bhupinder.thakur/xen.git
branch: vpl011_v2

Bhupinder Thakur (10):
  xen/arm: vpl011: Add pl011 uart emulation in Xen
  xen/arm: vpl011: Add new vuart domctl interface to setup pfn and
    evtchn
  xen/arm: vpl011: Enable pl011 emulation for a guest domain in Xen
  xen/arm: vpl011: Add support for vuart in libxl
  xen/arm: vpl011: Allocate a new PFN in the toolstack for vuart
  xen/arm: vpl011: Add vuart ring-buf and evtchn to xenstore
  xen/arm: vpl011: Add support for vuart in xenconsole
  xen/arm: vpl011: Add a new vuart console type to xenconsole client
  xen/arm: vpl011: Add a pl011 uart DT node in the guest device tree
  xen/arm: vpl011: Update documentation for vuart console support

 docs/man/xl.cfg.pod.5.in         |   8 +
 docs/misc/console.txt            |  14 +-
 tools/console/client/main.c      |   8 +-
 tools/console/daemon/io.c        | 514 +++++++++++++++++++++++++++------------
 tools/libxc/include/xc_dom.h     |   2 +
 tools/libxc/include/xenctrl.h    |  26 ++
 tools/libxc/xc_dom_arm.c         |   7 +-
 tools/libxc/xc_dom_boot.c        |   2 +
 tools/libxc/xc_domain.c          |  39 +++
 tools/libxl/libxl.h              |   6 +
 tools/libxl/libxl_arm.c          |  54 +++-
 tools/libxl/libxl_console.c      |  10 +
 tools/libxl/libxl_create.c       |  10 +
 tools/libxl/libxl_dom.c          |   4 +
 tools/libxl/libxl_internal.h     |   4 +
 tools/libxl/libxl_types.idl      |   2 +
 tools/xl/xl_console.c            |   4 +-
 tools/xl/xl_parse.c              |   3 +
 xen/arch/arm/Kconfig             |   5 +
 xen/arch/arm/Makefile            |   1 +
 xen/arch/arm/domain.c            |   6 +
 xen/arch/arm/domctl.c            |  20 ++
 xen/arch/arm/vpl011.c            | 340 ++++++++++++++++++++++++++
 xen/arch/x86/domctl.c            |   4 +
 xen/common/domctl.c              |   3 +
 xen/include/asm-arm/domain.h     |   3 +
 xen/include/asm-arm/pl011-uart.h |   2 +
 xen/include/public/arch-arm.h    |   8 +
 xen/include/public/domctl.h      |  13 +
 xen/include/xen/sched.h          |   4 +
 xen/include/xen/vpl011.h         |  74 ++++++
 31 files changed, 1045 insertions(+), 155 deletions(-)
 create mode 100644 xen/arch/arm/vpl011.c
 create mode 100644 xen/include/xen/vpl011.h

On Fri, Apr 28, 2017 at 09:31:14PM +0530, Bhupinder Thakur wrote:
> 
> url: ssh://git@git.linaro.org:/people/bhupinder.thakur/xen.git

I'm not sure if a ssh:// url is helpful...