tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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: 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
d371c011
263a19ff
+81
-42
+70
-42
Documentation/virt/kvm/devices/arm-vgic-its.txt
Documentation/virt/kvm/devices/arm-vgic-its.rst
+70
-42
Documentation/virt/kvm/devices/arm-vgic-its.txt
Documentation/virt/kvm/devices/arm-vgic-its.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
===============================================
1
4
ARM Virtual Interrupt Translation Service (ITS)
2
5
===============================================
3
6
···
15
12
a separate, non-overlapping MMIO region.
16
13
17
14
18
-
Groups:
19
-
KVM_DEV_ARM_VGIC_GRP_ADDR
15
+
Groups
16
+
======
17
+
18
+
KVM_DEV_ARM_VGIC_GRP_ADDR
19
+
-------------------------
20
+
20
21
Attributes:
21
22
KVM_VGIC_ITS_ADDR_TYPE (rw, 64-bit)
22
23
Base address in the guest physical address space of the GICv3 ITS
23
24
control register frame.
24
25
This address needs to be 64K aligned and the region covers 128K.
26
+
25
27
Errors:
26
-
-E2BIG: Address outside of addressable IPA range
27
-
-EINVAL: Incorrectly aligned address
28
-
-EEXIST: Address already configured
29
-
-EFAULT: Invalid user pointer for attr->addr.
30
-
-ENODEV: Incorrect attribute or the ITS is not supported.
28
+
29
+
======= =================================================
30
+
-E2BIG Address outside of addressable IPA range
31
+
-EINVAL Incorrectly aligned address
32
+
-EEXIST Address already configured
33
+
-EFAULT Invalid user pointer for attr->addr.
34
+
-ENODEV Incorrect attribute or the ITS is not supported.
35
+
======= =================================================
31
36
32
37
33
-
KVM_DEV_ARM_VGIC_GRP_CTRL
38
+
KVM_DEV_ARM_VGIC_GRP_CTRL
39
+
-------------------------
40
+
34
41
Attributes:
35
42
KVM_DEV_ARM_VGIC_CTRL_INIT
36
43
request the initialization of the ITS, no additional parameter in
···
71
58
"ITS Restore Sequence".
72
59
73
60
Errors:
74
-
-ENXIO: ITS not properly configured as required prior to setting
75
-
this attribute
76
-
-ENOMEM: Memory shortage when allocating ITS internal data
77
-
-EINVAL: Inconsistent restored data
78
-
-EFAULT: Invalid guest ram access
79
-
-EBUSY: One or more VCPUS are running
80
-
-EACCES: The virtual ITS is backed by a physical GICv4 ITS, and the
81
-
state is not available
82
61
83
-
KVM_DEV_ARM_VGIC_GRP_ITS_REGS
62
+
======= ==========================================================
63
+
-ENXIO ITS not properly configured as required prior to setting
64
+
this attribute
65
+
-ENOMEM Memory shortage when allocating ITS internal data
66
+
-EINVAL Inconsistent restored data
67
+
-EFAULT Invalid guest ram access
68
+
-EBUSY One or more VCPUS are running
69
+
-EACCES The virtual ITS is backed by a physical GICv4 ITS, and the
70
+
state is not available
71
+
======= ==========================================================
72
+
73
+
KVM_DEV_ARM_VGIC_GRP_ITS_REGS
74
+
-----------------------------
75
+
84
76
Attributes:
85
77
The attr field of kvm_device_attr encodes the offset of the
86
78
ITS register, relative to the ITS control frame base address
···
96
78
be accessed with full length.
97
79
98
80
Writes to read-only registers are ignored by the kernel except for:
81
+
99
82
- GITS_CREADR. It must be restored otherwise commands in the queue
100
83
will be re-executed after restoring CWRITER. GITS_CREADR must be
101
84
restored before restoring the GITS_CTLR which is likely to enable the
···
110
91
111
92
For other registers, getting or setting a register has the same
112
93
effect as reading/writing the register on real hardware.
113
-
Errors:
114
-
-ENXIO: Offset does not correspond to any supported register
115
-
-EFAULT: Invalid user pointer for attr->addr
116
-
-EINVAL: Offset is not 64-bit aligned
117
-
-EBUSY: one or more VCPUS are running
118
94
119
-
ITS Restore Sequence:
120
-
-------------------------
95
+
Errors:
96
+
97
+
======= ====================================================
98
+
-ENXIO Offset does not correspond to any supported register
99
+
-EFAULT Invalid user pointer for attr->addr
100
+
-EINVAL Offset is not 64-bit aligned
101
+
-EBUSY one or more VCPUS are running
102
+
======= ====================================================
103
+
104
+
ITS Restore Sequence:
105
+
---------------------
121
106
122
107
The following ordering must be followed when restoring the GIC and the ITS:
108
+
123
109
a) restore all guest memory and create vcpus
124
110
b) restore all redistributors
125
111
c) provide the ITS base address
126
112
(KVM_DEV_ARM_VGIC_GRP_ADDR)
127
113
d) restore the ITS in the following order:
128
-
1. Restore GITS_CBASER
129
-
2. Restore all other GITS_ registers, except GITS_CTLR!
130
-
3. Load the ITS table data (KVM_DEV_ARM_ITS_RESTORE_TABLES)
131
-
4. Restore GITS_CTLR
114
+
115
+
1. Restore GITS_CBASER
116
+
2. Restore all other ``GITS_`` registers, except GITS_CTLR!
117
+
3. Load the ITS table data (KVM_DEV_ARM_ITS_RESTORE_TABLES)
118
+
4. Restore GITS_CTLR
132
119
133
120
Then vcpus can be started.
134
121
135
-
ITS Table ABI REV0:
136
-
-------------------
122
+
ITS Table ABI REV0:
123
+
-------------------
137
124
138
125
Revision 0 of the ABI only supports the features of a virtual GICv3, and does
139
126
not support a virtual GICv4 with support for direct injection of virtual
···
150
125
entries in the collection are listed in no particular order.
151
126
All entries are 8 bytes.
152
127
153
-
Device Table Entry (DTE):
128
+
Device Table Entry (DTE)::
154
129
155
-
bits: | 63| 62 ... 49 | 48 ... 5 | 4 ... 0 |
156
-
values: | V | next | ITT_addr | Size |
130
+
bits: | 63| 62 ... 49 | 48 ... 5 | 4 ... 0 |
131
+
values: | V | next | ITT_addr | Size |
157
132
158
-
where;
133
+
where:
134
+
159
135
- V indicates whether the entry is valid. If not, other fields
160
136
are not meaningful.
161
137
- next: equals to 0 if this entry is the last one; otherwise it
···
166
140
- Size specifies the supported number of bits for the EventID,
167
141
minus one
168
142
169
-
Collection Table Entry (CTE):
143
+
Collection Table Entry (CTE)::
170
144
171
-
bits: | 63| 62 .. 52 | 51 ... 16 | 15 ... 0 |
172
-
values: | V | RES0 | RDBase | ICID |
145
+
bits: | 63| 62 .. 52 | 51 ... 16 | 15 ... 0 |
146
+
values: | V | RES0 | RDBase | ICID |
173
147
174
148
where:
149
+
175
150
- V indicates whether the entry is valid. If not, other fields are
176
151
not meaningful.
177
152
- RES0: reserved field with Should-Be-Zero-or-Preserved behavior.
178
153
- RDBase is the PE number (GICR_TYPER.Processor_Number semantic),
179
154
- ICID is the collection ID
180
155
181
-
Interrupt Translation Entry (ITE):
156
+
Interrupt Translation Entry (ITE)::
182
157
183
-
bits: | 63 ... 48 | 47 ... 16 | 15 ... 0 |
184
-
values: | next | pINTID | ICID |
158
+
bits: | 63 ... 48 | 47 ... 16 | 15 ... 0 |
159
+
values: | next | pINTID | ICID |
185
160
186
161
where:
162
+
187
163
- next: equals to 0 if this entry is the last one; otherwise it corresponds
188
164
to the EventID offset to the next ITE capped by 2^16 -1.
189
165
- pINTID is the physical LPI ID; if zero, it means the entry is not valid
190
166
and other fields are not meaningful.
191
167
- ICID is the collection ID
192
168
193
-
ITS Reset State:
194
-
----------------
169
+
ITS Reset State:
170
+
----------------
195
171
196
172
RESET returns the ITS to the same state that it was when first created and
197
173
initialized. When the RESET command returns, the following things are
+10
Documentation/virt/kvm/devices/index.rst
+10
Documentation/virt/kvm/devices/index.rst