docs: kvm: devices/arm-vgit-v3.txt to ReST

Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

kernel os linux

- Use title markups;
- change indent to match ReST syntax;
- use proper table markups;
- use literal block markups.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

authored by

Mauro Carvalho Chehab and committed by

Paolo Bonzini 6 years ago c0d1c8a0 d371c011

+87 -46

2 changed files

expand all

Documentation

virt

kvm

devices

arm-vgic-v3.rst

index.rst

+86 -46

Documentation/virt/kvm/devices/arm-vgic-v3.txt Documentation/virt/kvm/devices/arm-vgic-v3.rst

··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + ============================================================== 1 4 ARM Virtual Generic Interrupt Controller v3 and later (VGICv3) 2 5 ============================================================== 3 6 4 7 5 8 Device types supported: 6 - KVM_DEV_TYPE_ARM_VGIC_V3 ARM Generic Interrupt Controller v3.0 9 + - KVM_DEV_TYPE_ARM_VGIC_V3 ARM Generic Interrupt Controller v3.0 7 10 8 11 Only one VGIC instance may be instantiated through this API. The created VGIC 9 12 will act as the VM interrupt controller, requiring emulated user-space devices ··· 18 15 19 16 Groups: 20 17 KVM_DEV_ARM_VGIC_GRP_ADDR 21 - Attributes: 18 + Attributes: 19 + 22 20 KVM_VGIC_V3_ADDR_TYPE_DIST (rw, 64-bit) 23 21 Base address in the guest physical address space of the GICv3 distributor 24 22 register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V3. ··· 33 29 This address needs to be 64K aligned. 34 30 35 31 KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION (rw, 64-bit) 36 - The attribute data pointed to by kvm_device_attr.addr is a __u64 value: 37 - bits: | 63 .... 52 | 51 .... 16 | 15 - 12 |11 - 0 38 - values: | count | base | flags | index 32 + The attribute data pointed to by kvm_device_attr.addr is a __u64 value:: 33 + 34 + bits: | 63 .... 52 | 51 .... 16 | 15 - 12 |11 - 0 35 + values: | count | base | flags | index 36 + 39 37 - index encodes the unique redistributor region index 40 38 - flags: reserved for future use, currently 0 41 39 - base field encodes bits [51:16] of the guest physical base address 42 40 of the first redistributor in the region. 43 41 - count encodes the number of redistributors in the region. Must be 44 42 greater than 0. 43 + 45 44 There are two 64K pages for each redistributor in the region and 46 45 redistributors are laid out contiguously within the region. Regions 47 46 are filled with redistributors in the index order. The sum of all 48 47 region count fields must be greater than or equal to the number of 49 48 VCPUs. Redistributor regions must be registered in the incremental 50 49 index order, starting from index 0. 50 + 51 51 The characteristics of a specific redistributor region can be read 52 52 by presetting the index field in the attr data. 53 53 Only valid for KVM_DEV_TYPE_ARM_VGIC_V3. ··· 60 52 KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION attributes. 61 53 62 54 Errors: 63 - -E2BIG: Address outside of addressable IPA range 64 - -EINVAL: Incorrectly aligned address, bad redistributor region 55 + 56 + ======= ============================================================= 57 + -E2BIG Address outside of addressable IPA range 58 + -EINVAL Incorrectly aligned address, bad redistributor region 65 59 count/index, mixed redistributor region attribute usage 66 - -EEXIST: Address already configured 67 - -ENOENT: Attempt to read the characteristics of a non existing 60 + -EEXIST Address already configured 61 + -ENOENT Attempt to read the characteristics of a non existing 68 62 redistributor region 69 - -ENXIO: The group or attribute is unknown/unsupported for this device 63 + -ENXIO The group or attribute is unknown/unsupported for this device 70 64 or hardware support is missing. 71 - -EFAULT: Invalid user pointer for attr->addr. 65 + -EFAULT Invalid user pointer for attr->addr. 66 + ======= ============================================================= 72 67 73 68 74 - KVM_DEV_ARM_VGIC_GRP_DIST_REGS 75 - KVM_DEV_ARM_VGIC_GRP_REDIST_REGS 76 - Attributes: 77 - The attr field of kvm_device_attr encodes two values: 78 - bits: | 63 .... 32 | 31 .... 0 | 79 - values: | mpidr | offset | 69 + KVM_DEV_ARM_VGIC_GRP_DIST_REGS, KVM_DEV_ARM_VGIC_GRP_REDIST_REGS 70 + Attributes: 71 + 72 + The attr field of kvm_device_attr encodes two values:: 73 + 74 + bits: | 63 .... 32 | 31 .... 0 | 75 + values: | mpidr | offset | 80 76 81 77 All distributor regs are (rw, 32-bit) and kvm_device_attr.addr points to a 82 78 __u32 value. 64-bit registers must be accessed by separately accessing the ··· 105 93 redistributor is accessed. The mpidr is ignored for the distributor. 106 94 107 95 The mpidr encoding is based on the affinity information in the 108 - architecture defined MPIDR, and the field is encoded as follows: 96 + architecture defined MPIDR, and the field is encoded as follows:: 97 + 109 98 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | 110 99 | Aff3 | Aff2 | Aff1 | Aff0 | 111 100 ··· 161 148 ignored. 162 149 163 150 Errors: 164 - -ENXIO: Getting or setting this register is not yet supported 165 - -EBUSY: One or more VCPUs are running 151 + 152 + ====== ===================================================== 153 + -ENXIO Getting or setting this register is not yet supported 154 + -EBUSY One or more VCPUs are running 155 + ====== ===================================================== 166 156 167 157 168 158 KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS 169 - Attributes: 170 - The attr field of kvm_device_attr encodes two values: 171 - bits: | 63 .... 32 | 31 .... 16 | 15 .... 0 | 172 - values: | mpidr | RES | instr | 159 + Attributes: 160 + 161 + The attr field of kvm_device_attr encodes two values:: 162 + 163 + bits: | 63 .... 32 | 31 .... 16 | 15 .... 0 | 164 + values: | mpidr | RES | instr | 173 165 174 166 The mpidr field encodes the CPU ID based on the affinity information in the 175 - architecture defined MPIDR, and the field is encoded as follows: 167 + architecture defined MPIDR, and the field is encoded as follows:: 168 + 176 169 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | 177 170 | Aff3 | Aff2 | Aff1 | Aff0 | 178 171 179 172 The instr field encodes the system register to access based on the fields 180 173 defined in the A64 instruction set encoding for system register access 181 - (RES means the bits are reserved for future use and should be zero): 174 + (RES means the bits are reserved for future use and should be zero):: 182 175 183 176 | 15 ... 14 | 13 ... 11 | 10 ... 7 | 6 ... 3 | 2 ... 0 | 184 177 | Op 0 | Op1 | CRn | CRm | Op2 | ··· 197 178 198 179 CPU interface registers access is not implemented for AArch32 mode. 199 180 Error -ENXIO is returned when accessed in AArch32 mode. 181 + 200 182 Errors: 201 - -ENXIO: Getting or setting this register is not yet supported 202 - -EBUSY: VCPU is running 203 - -EINVAL: Invalid mpidr or register value supplied 183 + 184 + ======= ===================================================== 185 + -ENXIO Getting or setting this register is not yet supported 186 + -EBUSY VCPU is running 187 + -EINVAL Invalid mpidr or register value supplied 188 + ======= ===================================================== 204 189 205 190 206 191 KVM_DEV_ARM_VGIC_GRP_NR_IRQS 207 - Attributes: 192 + Attributes: 193 + 208 194 A value describing the number of interrupts (SGI, PPI and SPI) for 209 195 this GIC instance, ranging from 64 to 1024, in increments of 32. 210 196 211 197 kvm_device_attr.addr points to a __u32 value. 212 198 213 199 Errors: 214 - -EINVAL: Value set is out of the expected range 215 - -EBUSY: Value has already be set. 200 + 201 + ======= ====================================== 202 + -EINVAL Value set is out of the expected range 203 + -EBUSY Value has already be set. 204 + ======= ====================================== 216 205 217 206 218 207 KVM_DEV_ARM_VGIC_GRP_CTRL 219 - Attributes: 208 + Attributes: 209 + 220 210 KVM_DEV_ARM_VGIC_CTRL_INIT 221 211 request the initialization of the VGIC, no additional parameter in 222 212 kvm_device_attr.addr. ··· 233 205 save all LPI pending bits into guest RAM pending tables. 234 206 235 207 The first kB of the pending table is not altered by this operation. 208 + 236 209 Errors: 237 - -ENXIO: VGIC not properly configured as required prior to calling 238 - this attribute 239 - -ENODEV: no online VCPU 240 - -ENOMEM: memory shortage when allocating vgic internal data 241 - -EFAULT: Invalid guest ram access 242 - -EBUSY: One or more VCPUS are running 210 + 211 + ======= ======================================================== 212 + -ENXIO VGIC not properly configured as required prior to calling 213 + this attribute 214 + -ENODEV no online VCPU 215 + -ENOMEM memory shortage when allocating vgic internal data 216 + -EFAULT Invalid guest ram access 217 + -EBUSY One or more VCPUS are running 218 + ======= ======================================================== 243 219 244 220 245 221 KVM_DEV_ARM_VGIC_GRP_LEVEL_INFO 246 - Attributes: 247 - The attr field of kvm_device_attr encodes the following values: 248 - bits: | 63 .... 32 | 31 .... 10 | 9 .... 0 | 249 - values: | mpidr | info | vINTID | 222 + Attributes: 223 + 224 + The attr field of kvm_device_attr encodes the following values:: 225 + 226 + bits: | 63 .... 32 | 31 .... 10 | 9 .... 0 | 227 + values: | mpidr | info | vINTID | 250 228 251 229 The vINTID specifies which set of IRQs is reported on. 252 230 ··· 262 228 VGIC_LEVEL_INFO_LINE_LEVEL: 263 229 Get/Set the input level of the IRQ line for a set of 32 contiguously 264 230 numbered interrupts. 231 + 265 232 vINTID must be a multiple of 32. 266 233 267 234 kvm_device_attr.addr points to a __u32 value which will contain a ··· 278 243 reported with the same value regardless of the mpidr specified. 279 244 280 245 The mpidr field encodes the CPU ID based on the affinity information in the 281 - architecture defined MPIDR, and the field is encoded as follows: 246 + architecture defined MPIDR, and the field is encoded as follows:: 247 + 282 248 | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | 283 249 | Aff3 | Aff2 | Aff1 | Aff0 | 250 + 284 251 Errors: 285 - -EINVAL: vINTID is not multiple of 32 or 286 - info field is not VGIC_LEVEL_INFO_LINE_LEVEL 252 + 253 + ======= ============================================= 254 + -EINVAL vINTID is not multiple of 32 or info field is 255 + not VGIC_LEVEL_INFO_LINE_LEVEL 256 + ======= =============================================

Documentation/virt/kvm/devices/index.rst

··· 8 8 :maxdepth: 2 9 9 10 10 arm-vgic-its 11 + arm-vgic-v3