docs: kvm: devices/arm-vgic-its.txt to ReST format (d371c011) · Commits · 戴 / test

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

Admin message