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

docs: kvm: devices/arm-vgic-its.txt to ReST format 



- Fix document title to match ReST format
- Convert the table to be properly recognized
- use proper markups for literal blocks
- Some indentation fixes to match ReST

While here, add an index for kvm devices.

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

Documentation/virt/kvm/devices/arm-vgic-its.txt→Documentation/virt/kvm/devices/arm-vgic-its.rst

+67 −39
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



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

ARM Virtual Interrupt Translation Service (ITS)

===============================================
@@ -12,22 +15,32 @@ There can be multiple ITS controllers per guest, each of them has to have 
a separate, non-overlapping MMIO region.





Groups:

Groups

======



KVM_DEV_ARM_VGIC_GRP_ADDR

-------------------------



  Attributes:

    KVM_VGIC_ITS_ADDR_TYPE (rw, 64-bit)

      Base address in the guest physical address space of the GICv3 ITS

      control register frame.

      This address needs to be 64K aligned and the region covers 128K.



  Errors:

    -E2BIG:  Address outside of addressable IPA range

    -EINVAL: Incorrectly aligned address

    -EEXIST: Address already configured

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

    -ENODEV: Incorrect attribute or the ITS is not supported.



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

    -E2BIG   Address outside of addressable IPA range

    -EINVAL  Incorrectly aligned address

    -EEXIST  Address already configured

    -EFAULT  Invalid user pointer for attr->addr.

    -ENODEV  Incorrect attribute or the ITS is not supported.

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





KVM_DEV_ARM_VGIC_GRP_CTRL

-------------------------



  Attributes:

    KVM_DEV_ARM_VGIC_CTRL_INIT

      request the initialization of the ITS, no additional parameter in
@@ -58,16 +71,21 @@ Groups: 
      "ITS Restore Sequence".



  Errors:

    -ENXIO:  ITS not properly configured as required prior to setting



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

     -ENXIO  ITS not properly configured as required prior to setting

             this attribute

    -ENOMEM: Memory shortage when allocating ITS internal data

    -EINVAL: Inconsistent restored data

    -EFAULT: Invalid guest ram access

    -EBUSY:  One or more VCPUS are running

    -EACCES: The virtual ITS is backed by a physical GICv4 ITS, and the

    -ENOMEM  Memory shortage when allocating ITS internal data

    -EINVAL  Inconsistent restored data

    -EFAULT  Invalid guest ram access

    -EBUSY   One or more VCPUS are running

    -EACCES  The virtual ITS is backed by a physical GICv4 ITS, and the

	     state is not available

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



KVM_DEV_ARM_VGIC_GRP_ITS_REGS

-----------------------------



  Attributes:

      The attr field of kvm_device_attr encodes the offset of the

      ITS register, relative to the ITS control frame base address
@@ -78,6 +96,7 @@ Groups: 
      be accessed with full length.



      Writes to read-only registers are ignored by the kernel except for:



      - GITS_CREADR. It must be restored otherwise commands in the queue

        will be re-executed after restoring CWRITER. GITS_CREADR must be

        restored before restoring the GITS_CTLR which is likely to enable the
@@ -91,23 +110,29 @@ Groups: 


      For other registers, getting or setting a register has the same

      effect as reading/writing the register on real hardware.



  Errors:

    -ENXIO: Offset does not correspond to any supported register

    -EFAULT: Invalid user pointer for attr->addr

    -EINVAL: Offset is not 64-bit aligned

    -EBUSY: one or more VCPUS are running



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

    -ENXIO   Offset does not correspond to any supported register

    -EFAULT  Invalid user pointer for attr->addr

    -EINVAL  Offset is not 64-bit aligned

    -EBUSY   one or more VCPUS are running

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



ITS Restore Sequence:

 -------------------------

---------------------



The following ordering must be followed when restoring the GIC and the ITS:



a) restore all guest memory and create vcpus

b) restore all redistributors

c) provide the ITS base address

   (KVM_DEV_ARM_VGIC_GRP_ADDR)

d) restore the ITS in the following order:



     1. Restore GITS_CBASER

   2. Restore all other GITS_ registers, except GITS_CTLR!

     2. Restore all other ``GITS_`` registers, except GITS_CTLR!

     3. Load the ITS table data (KVM_DEV_ARM_ITS_RESTORE_TABLES)

     4. Restore GITS_CTLR
@@ -125,12 +150,13 @@ Then vcpus can be started. 
 entries in the collection are listed in no particular order.

 All entries are 8 bytes.



 Device Table Entry (DTE):

 Device Table Entry (DTE)::



   bits:     | 63| 62 ... 49 | 48 ... 5 | 4 ... 0 |

   values:   | V |   next    | ITT_addr |  Size   |



 where;

 where:



 - V indicates whether the entry is valid. If not, other fields

   are not meaningful.

 - next: equals to 0 if this entry is the last one; otherwise it
@@ -140,24 +166,26 @@ Then vcpus can be started. 
 - Size specifies the supported number of bits for the EventID,

   minus one



 Collection Table Entry (CTE):

 Collection Table Entry (CTE)::



   bits:     | 63| 62 ..  52  | 51 ... 16 | 15  ...   0 |

   values:   | V |    RES0    |  RDBase   |    ICID     |



 where:



 - V indicates whether the entry is valid. If not, other fields are

   not meaningful.

 - RES0: reserved field with Should-Be-Zero-or-Preserved behavior.

 - RDBase is the PE number (GICR_TYPER.Processor_Number semantic),

 - ICID is the collection ID



 Interrupt Translation Entry (ITE):

 Interrupt Translation Entry (ITE)::



   bits:     | 63 ... 48 | 47 ... 16 | 15 ... 0 |

   values:   |    next   |   pINTID  |  ICID    |



 where:



 - next: equals to 0 if this entry is the last one; otherwise it corresponds

   to the EventID offset to the next ITE capped by 2^16 -1.

 - pINTID is the physical LPI ID; if zero, it means the entry is not valid

Documentation/virt/kvm/devices/index.rst

0 → 100644
+10 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



=======

Devices

=======



.. toctree::

   :maxdepth: 2



   arm-vgic-its

Documentation/virt/kvm/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -14,3 +14,4 @@ KVM 
   vcpu-requests



   arm/index

   devices/index