Commit d3b52e49 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Paolo Bonzini
Browse files

docs: kvm: convert devices/xive.txt to ReST 



- Use title markups;
- adjust indentation and add blank lines as needed;
- adjust tables to match ReST accepted formats;
- mark code blocks as such.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarPaolo Bonzini <pbonzini@redhat.com>
parent 5cccf379

Documentation/virt/kvm/devices/index.rst

+1 −0
Original line number Original line Diff line number Diff line
@@ -16,3 +16,4 @@ Devices 
   vfio

   vfio

   vm

   vm

   xics

   xics

   xive

Documentation/virt/kvm/devices/xive.txt→Documentation/virt/kvm/devices/xive.rst

+97 −55
Original line number Original line Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



===========================================================

POWER9 eXternal Interrupt Virtualization Engine (XIVE Gen1)

POWER9 eXternal Interrupt Virtualization Engine (XIVE Gen1)

==========================================================

===========================================================





Device types supported:

Device types supported:

  KVM_DEV_TYPE_XIVE     POWER9 XIVE Interrupt Controller generation 1

  - KVM_DEV_TYPE_XIVE     POWER9 XIVE Interrupt Controller generation 1





This device acts as a VM interrupt controller. It provides the KVM

This device acts as a VM interrupt controller. It provides the KVM

interface to configure the interrupt sources of a VM in the underlying

interface to configure the interrupt sources of a VM in the underlying
@@ -66,70 +69,98 @@ the legacy interrupt mode, referred as XICS (POWER7/8). 




1. KVM_DEV_XIVE_GRP_CTRL

1. KVM_DEV_XIVE_GRP_CTRL

     Provides global controls on the device

     Provides global controls on the device



  Attributes:

  Attributes:

    1.1 KVM_DEV_XIVE_RESET (write only)

    1.1 KVM_DEV_XIVE_RESET (write only)

    Resets the interrupt controller configuration for sources and event

    Resets the interrupt controller configuration for sources and event

    queues. To be used by kexec and kdump.

    queues. To be used by kexec and kdump.



    Errors: none

    Errors: none





    1.2 KVM_DEV_XIVE_EQ_SYNC (write only)

    1.2 KVM_DEV_XIVE_EQ_SYNC (write only)

    Sync all the sources and queues and mark the EQ pages dirty. This

    Sync all the sources and queues and mark the EQ pages dirty. This

    to make sure that a consistent memory state is captured when

    to make sure that a consistent memory state is captured when

    migrating the VM.

    migrating the VM.



    Errors: none

    Errors: none





    1.3 KVM_DEV_XIVE_NR_SERVERS (write only)

    1.3 KVM_DEV_XIVE_NR_SERVERS (write only)

    The kvm_device_attr.addr points to a __u32 value which is the number of

    The kvm_device_attr.addr points to a __u32 value which is the number of

    interrupt server numbers (ie, highest possible vcpu id plus one).

    interrupt server numbers (ie, highest possible vcpu id plus one).



    Errors:

    Errors:

      -EINVAL: Value greater than KVM_MAX_VCPU_ID.



      -EFAULT: Invalid user pointer for attr->addr.

      =======  ==========================================

      -EBUSY:  A vCPU is already connected to the device.

      -EINVAL  Value greater than KVM_MAX_VCPU_ID.

      -EFAULT  Invalid user pointer for attr->addr.

      -EBUSY   A vCPU is already connected to the device.

      =======  ==========================================





2. KVM_DEV_XIVE_GRP_SOURCE (write only)

2. KVM_DEV_XIVE_GRP_SOURCE (write only)

     Initializes a new source in the XIVE device and mask it.

     Initializes a new source in the XIVE device and mask it.



  Attributes:

  Attributes:

    Interrupt source number  (64-bit)

    Interrupt source number  (64-bit)

  The kvm_device_attr.addr points to a __u64 value:



  The kvm_device_attr.addr points to a __u64 value::



    bits:     | 63   ....  2 |   1   |   0

    bits:     | 63   ....  2 |   1   |   0

    values:   |    unused    | level | type

    values:   |    unused    | level | type



  - type:  0:MSI 1:LSI

  - type:  0:MSI 1:LSI

  - level: assertion level in case of an LSI.

  - level: assertion level in case of an LSI.



  Errors:

  Errors:

    -E2BIG:  Interrupt source number is out of range



    -ENOMEM: Could not create a new source block

    =======  ==========================================

    -EFAULT: Invalid user pointer for attr->addr.

    -E2BIG   Interrupt source number is out of range

    -ENXIO:  Could not allocate underlying HW interrupt

    -ENOMEM  Could not create a new source block

    -EFAULT  Invalid user pointer for attr->addr.

    -ENXIO   Could not allocate underlying HW interrupt

    =======  ==========================================





3. KVM_DEV_XIVE_GRP_SOURCE_CONFIG (write only)

3. KVM_DEV_XIVE_GRP_SOURCE_CONFIG (write only)

     Configures source targeting

     Configures source targeting



  Attributes:

  Attributes:

    Interrupt source number  (64-bit)

    Interrupt source number  (64-bit)

  The kvm_device_attr.addr points to a __u64 value:



  The kvm_device_attr.addr points to a __u64 value::



    bits:     | 63   ....  33 |  32  | 31 .. 3 |  2 .. 0

    bits:     | 63   ....  33 |  32  | 31 .. 3 |  2 .. 0

    values:   |    eisn       | mask |  server | priority

    values:   |    eisn       | mask |  server | priority



  - priority: 0-7 interrupt priority level

  - priority: 0-7 interrupt priority level

  - server: CPU number chosen to handle the interrupt

  - server: CPU number chosen to handle the interrupt

  - mask: mask flag (unused)

  - mask: mask flag (unused)

  - eisn: Effective Interrupt Source Number

  - eisn: Effective Interrupt Source Number



  Errors:

  Errors:

    -ENOENT: Unknown source number



    -EINVAL: Not initialized source number

    =======  =======================================================

    -EINVAL: Invalid priority

    -ENOENT  Unknown source number

    -EINVAL: Invalid CPU number.

    -EINVAL  Not initialized source number

    -EFAULT: Invalid user pointer for attr->addr.

    -EINVAL  Invalid priority

    -ENXIO:  CPU event queues not configured or configuration of the

    -EINVAL  Invalid CPU number.

    -EFAULT  Invalid user pointer for attr->addr.

    -ENXIO   CPU event queues not configured or configuration of the

	     underlying HW interrupt failed

	     underlying HW interrupt failed

    -EBUSY:  No CPU available to serve interrupt

    -EBUSY   No CPU available to serve interrupt

    =======  =======================================================





4. KVM_DEV_XIVE_GRP_EQ_CONFIG (read-write)

4. KVM_DEV_XIVE_GRP_EQ_CONFIG (read-write)

     Configures an event queue of a CPU

     Configures an event queue of a CPU



  Attributes:

  Attributes:

    EQ descriptor identifier (64-bit)

    EQ descriptor identifier (64-bit)

  The EQ descriptor identifier is a tuple (server, priority) :



  The EQ descriptor identifier is a tuple (server, priority)::



    bits:     | 63   ....  32 | 31 .. 3 |  2 .. 0

    bits:     | 63   ....  32 | 31 .. 3 |  2 .. 0

    values:   |    unused     |  server | priority

    values:   |    unused     |  server | priority

  The kvm_device_attr.addr points to :



  The kvm_device_attr.addr points to::



    struct kvm_ppc_xive_eq {

    struct kvm_ppc_xive_eq {

	__u32 flags;

	__u32 flags;

	__u32 qshift;

	__u32 qshift;
@@ -138,6 +169,7 @@ the legacy interrupt mode, referred as XICS (POWER7/8). 
	__u32 qindex;

	__u32 qindex;

	__u8  pad[40];

	__u8  pad[40];

    };

    };



  - flags: queue flags

  - flags: queue flags

      KVM_XIVE_EQ_ALWAYS_NOTIFY (required)

      KVM_XIVE_EQ_ALWAYS_NOTIFY (required)

	forces notification without using the coalescing mechanism

	forces notification without using the coalescing mechanism
@@ -147,22 +179,31 @@ the legacy interrupt mode, referred as XICS (POWER7/8). 
  - qtoggle: current queue toggle bit

  - qtoggle: current queue toggle bit

  - qindex: current queue index

  - qindex: current queue index

  - pad: reserved for future use

  - pad: reserved for future use



  Errors:

  Errors:

    -ENOENT: Invalid CPU number



    -EINVAL: Invalid priority

    =======  =========================================

    -EINVAL: Invalid flags

    -ENOENT  Invalid CPU number

    -EINVAL: Invalid queue size

    -EINVAL  Invalid priority

    -EINVAL: Invalid queue address

    -EINVAL  Invalid flags

    -EFAULT: Invalid user pointer for attr->addr.

    -EINVAL  Invalid queue size

    -EIO:    Configuration of the underlying HW failed

    -EINVAL  Invalid queue address

    -EFAULT  Invalid user pointer for attr->addr.

    -EIO     Configuration of the underlying HW failed

    =======  =========================================





5. KVM_DEV_XIVE_GRP_SOURCE_SYNC (write only)

5. KVM_DEV_XIVE_GRP_SOURCE_SYNC (write only)

     Synchronize the source to flush event notifications

     Synchronize the source to flush event notifications



  Attributes:

  Attributes:

    Interrupt source number  (64-bit)

    Interrupt source number  (64-bit)



  Errors:

  Errors:

    -ENOENT: Unknown source number



    -EINVAL: Not initialized source number

    =======  =============================

    -ENOENT  Unknown source number

    -EINVAL  Not initialized source number

    =======  =============================





* VCPU state

* VCPU state
@@ -175,7 +216,8 @@ the legacy interrupt mode, referred as XICS (POWER7/8). 
  as it synthesizes the priorities of the pending interrupts. We

  as it synthesizes the priorities of the pending interrupts. We

  capture a bit more to report debug information.

  capture a bit more to report debug information.





  KVM_REG_PPC_VP_STATE (2 * 64bits)

  KVM_REG_PPC_VP_STATE (2 * 64bits)::



    bits:     |  63  ....  32  |  31  ....  0  |

    bits:     |  63  ....  32  |  31  ....  0  |

    values:   |   TIMA word0   |   TIMA word1  |

    values:   |   TIMA word0   |   TIMA word1  |

    bits:     | 127       ..........       64  |

    bits:     | 127       ..........       64  |