Skip to content

Commit df8d9de

Browse files
dhower-qcdhower-qc
authored
schema: add array form of description (#598)
* schema: add array form of description Adds an array form of "description" fields that enables tagged statements. In this first cut, statements can be tagged as: - normative or non-normative. - conditional, using an IDL function to evaluate the condition * schema: add id field to array form of descriptions IDs should never change, even if the underlying text changes
1 parent 5cb2bd9 commit df8d9de

File tree

7 files changed

+307
-154
lines changed

7 files changed

+307
-154
lines changed

‎arch/csr/hstatus.yaml

+139-112
Original file line numberDiff line numberDiff line change
@@ -15,30 +15,33 @@ description: |
1515
definedBy: H
1616
fields:
1717
VSXL:
18+
long_name: VS-mode XLen
1819
location: 33-32
1920
base: 64
20-
description: |
21-
*VS-mode XLen*
22-
23-
[when,"VSXLEN == 3264"]
24-
--
25-
Determines the effective XLEN in VS-mode. Valid values are:
26-
27-
[separator="!"]
28-
!===
29-
! Value ! VSXLEN
30-
31-
! 0 ! 32
32-
! 1 ! 64
33-
!===
34-
35-
--
36-
37-
[when,"VSXLEN = 32"]
38-
Because the implementation only supports a single VSXLEN == 32, this field is read-only-0.
39-
40-
[when,"VSXLEN = 64"]
41-
Because the implementation only supports a single VSXLEN == 64, this field is read-only-1.
21+
description:
22+
- id: csr-hstatus-vsxl-values
23+
normative: false
24+
text: |
25+
Determines the effective XLEN in VS-mode. Valid values are:
26+
27+
[separator="!"]
28+
!===
29+
! Value ! VSXLEN
30+
31+
! 0 ! 32
32+
! 1 ! 64
33+
!===
34+
when(): return VSXLEN == 3264;
35+
- id: csr-hstatus-vsxl-rv32
36+
normative: false
37+
text: |
38+
Because the implementation only supports a single VSXLEN == 32, this field is read-only-0.
39+
when(): return VSXLEN == 32;
40+
- id: csr-hstatus-vsxl-rv64
41+
normative: false
42+
text: |
43+
Because the implementation only supports a single VSXLEN == 64, this field is read-only-1.
44+
when(): return VSXLEN == 64;
4245

4346
type(): |
4447
if ((VSXLEN == 32) || (VSXLEN == 64)) {
@@ -69,69 +72,77 @@ fields:
6972
}
7073
VTSR:
7174
location: 22
72-
description: |
73-
*Virtual Trap SRET*
74-
75-
When `hstatus.VTSR` is set, executing the `sret` instruction in VS-mode
76-
raises a `Virtual Instruction` exception.
77-
78-
When `hstatus.VTSR` is clear, an `sret` instruction in VS-mode returns control
79-
to the mode stored in `vsstatus.SPP`.
75+
long_name: Virtual Trap SRET
76+
description:
77+
- id: csr-hstatus-vtsr-behavior
78+
normative: false
79+
text: |
80+
When `hstatus.VTSR` is set, executing the `sret` instruction in VS-mode
81+
raises a `Virtual Instruction` exception.
82+
83+
When `hstatus.VTSR` is clear, an `sret` instruction in VS-mode returns control
84+
to the mode stored in `vsstatus.SPP`.
8085
type: RW
8186
reset_value: UNDEFINED_LEGAL
8287
VTW:
8388
location: 21
84-
description: |
85-
*Virtual Trap WFI*
86-
87-
When `hstatus.VTW` is set, a `wfi` instruction executed in VS-mode raises
88-
a `Virtual Instruction` exception after waiting an implementation-defined
89-
amount of time (which can be 0).
90-
91-
When both `hstatus.VTW` and `mstatus.TW` are clear, a `wfi` instruction
92-
executes in VS-mode without a timeout period.
93-
94-
The `wfi` instruction is also affected by `mstatus.TW`, as shown below:
95-
96-
[separator="!",%autowidth,%footer]
97-
!===
98-
.2+! [.rotate]#`mstatus.TW`# .2+! [.rotate]#`hstatus.VTW`# 4+^.>! `wfi` behavior
99-
h! HS-mode h! U-mode h! VS-mode h! VU-mode
100-
101-
! 0 ! 0 ! Wait ! Trap (I) ! Wait ! Trap (V)
102-
! 0 ! 1 ! Wait ! Trap (I) ! Trap (V) ! Trap (V)
103-
! 1 ! - ! Trap (I) ! Trap (I) ! Trap (I) ! Trap (I)
104-
105-
6+! Trap (I) - Trap with `Illegal Instruction` code +
106-
Trap (V) - Trap with `Virtual Instruction` code
107-
!===
89+
long_name: Virtual Trap WFI
90+
description:
91+
- id: csr-hstatus-vtw-behavior
92+
normative: false
93+
text: |
94+
When `hstatus.VTW` is set, a `wfi` instruction executed in VS-mode raises
95+
a `Virtual Instruction` exception after waiting an implementation-defined
96+
amount of time (which can be 0).
97+
98+
When both `hstatus.VTW` and `mstatus.TW` are clear, a `wfi` instruction
99+
executes in VS-mode without a timeout period.
100+
101+
The `wfi` instruction is also affected by `mstatus.TW`, as shown below:
102+
103+
[separator="!",%autowidth,%footer]
104+
!===
105+
.2+! [.rotate]#`mstatus.TW`# .2+! [.rotate]#`hstatus.VTW`# 4+^.>! `wfi` behavior
106+
h! HS-mode h! U-mode h! VS-mode h! VU-mode
107+
108+
! 0 ! 0 ! Wait ! Trap (I) ! Wait ! Trap (V)
109+
! 0 ! 1 ! Wait ! Trap (I) ! Trap (V) ! Trap (V)
110+
! 1 ! - ! Trap (I) ! Trap (I) ! Trap (I) ! Trap (I)
111+
112+
6+! Trap (I) - Trap with `Illegal Instruction` code +
113+
Trap (V) - Trap with `Virtual Instruction` code
114+
!===
108115
type: RW
109116
reset_value: UNDEFINED_LEGAL
110117
VTVM:
111118
location: 20
112-
description: |
113-
*Virtual Trap Virtual Memory*
114-
115-
When set, a 'Virtual Instruction` trap occurs when executing an `sfence.vma`, `sinval.vma`,
116-
or an explicit CSR access of the `satp` (really `vsatp`) register when in VS-mode.
119+
long_name: Virtual Trap Virtual Memory
120+
description:
121+
- id: csr-hstatus-vtvm-behavior
122+
normative: false
123+
text: |
124+
When set, a 'Virtual Instruction` trap occurs when executing an `sfence.vma`, `sinval.vma`,
125+
or an explicit CSR access of the `satp` (really `vsatp`) register when in VS-mode.
117126
118-
When clear, the instructions execute as normal in VS-mode.
127+
When clear, the instructions execute as normal in VS-mode.
119128
120-
Notably, `hstatus.VTVM` does *not* cause `hfence.vvma`, `sfence.w.inval`, or `sfence.inval.ir` to trap.
129+
Notably, `hstatus.VTVM` does *not* cause `hfence.vvma`, `sfence.w.inval`, or `sfence.inval.ir` to trap.
121130
122-
`mstatus.TVM` does not affect the VS-mode instructions controlled by `hstatus.TVTM`.
131+
`mstatus.TVM` does not affect the VS-mode instructions controlled by `hstatus.TVTM`.
123132
type: RW
124133
reset_value: UNDEFINED_LEGAL
125134
VGEIN:
126135
location: 17-12
127-
description: |
128-
*Virtual Guest External Interrupt Number*
136+
long_name: Virtual Guest External Interrupt Number
137+
description:
138+
- id: csr-hstatus-vgein-behavior
139+
normative: false
140+
text: |
141+
Selects the guest external interrupt source for VS-level external interrupts.
129142
130-
Selects the guest external interrupt source for VS-level external interrupts.
143+
When `hstatus.VGEIN` == 0, no external interrupt source is selected.
131144
132-
When `hstatus.VGEIN` == 0, no external interrupt source is selected.
133-
134-
When `hstatus.VGEIN` != 0, it selects which bit of `hgeip` is currently active in VS-mode.
145+
When `hstatus.VGEIN` != 0, it selects which bit of `hgeip` is currently active in VS-mode.
135146
136147
type(): |
137148
# if NUM_EXTERNAL_GUEST_INTERRUPTS+1 is 63 (because indexing in `hgeip` starts at 1),
@@ -153,77 +164,93 @@ fields:
153164
}
154165
HU:
155166
location: 9
156-
description: |
157-
*Hypervisor in U-mode*
158-
159-
When set, the hypervisor load/store instructions (`hlv`, `hlvx`, and `hsv`) can be
160-
executed in U-mode.
161-
162-
When clear, the hypervisor load/store instructions cause an `Illegal Instruction` trap.
167+
long_name: Hypervisor in U-mode
168+
description:
169+
- id: csr-hstatus-hu-behavior
170+
normative: false
171+
text: |
172+
When set, the hypervisor load/store instructions (`hlv`, `hlvx`, and `hsv`) can be
173+
executed in U-mode.
174+
175+
When clear, the hypervisor load/store instructions cause an `Illegal Instruction` trap.
163176
type: RW
164177
reset_value: UNDEFINED_LEGAL
165178
SPVP:
166179
location: 8
167-
description: |
168-
*Supervisor Previous Virtual Privilege*
180+
long_name: Supervisor Previous Virtual Privilege
181+
description:
182+
- id: csr-hstatus-spvp-behavior
183+
normative: false
184+
text: |
185+
Written by hardware:
169186
170-
Written by hardware:
187+
* When taking a trap into HS-mode from VS-mode or VU-mode, `hstatus.SPVP` is written with the nominal privilege mode
171188
172-
* When taking a trap into HS-mode from VS-mode or VU-mode, `hstatus.SPVP` is written with the nominal privilege mode
189+
Notably, unlike its analog `mstatus.SPP`, `hstatus.SPVP` is *not* cleared when returning from a trap.
173190
174-
Notably, unlike its analog `mstatus.SPP`, `hstatus.SPVP` is *not* cleared when returning from a trap.
191+
Can also be written by software without immediate side-effect.
175192
176-
Can also be written by software without immediate side-effect.
193+
Affects execution by:
177194
178-
Affects execution by:
179-
180-
* Controls the effective privilege level applied to the hypervisor load/store instructions, `hlv`, `hlvx`, and `hsv`.
195+
* Controls the effective privilege level applied to the hypervisor load/store instructions, `hlv`, `hlvx`, and `hsv`.
181196
type: RW
182197
reset_value: UNDEFINED_LEGAL
183198
SPV:
184199
location: 7
185-
description: |
186-
*Supervisor Previous Virtualization Mode*
187-
188-
Written by hardware:
200+
long_name: Supervisor Previous Virtualization Mode
201+
description:
202+
- id: csr-hstatus-spv-behavior
203+
normative: false
204+
text: |
205+
Written by hardware:
189206
190-
* On a trap into HS-mode, hardware writes 1 when the prior mode was VS-mode or VU-mode, and 0 otherwise.
207+
* On a trap into HS-mode, hardware writes 1 when the prior mode was VS-mode or VU-mode, and 0 otherwise.
191208
192-
Can also be written by software without immediate side-effect.
209+
Can also be written by software without immediate side-effect.
193210
194-
Affects execution by:
211+
Affects execution by:
195212
196-
* When an `sret` instruction in executed in HS-mode or M-mode,
197-
control returns to VS-mode or VU-mode (as selected by `mstatus.SPP`) when
198-
`hstatus.SPV` is 1 and to HS-mode or U-mode otherwise.
213+
* When an `sret` instruction in executed in HS-mode or M-mode,
214+
control returns to VS-mode or VU-mode (as selected by `mstatus.SPP`) when
215+
`hstatus.SPV` is 1 and to HS-mode or U-mode otherwise.
199216
type: RW
200217
reset_value: UNDEFINED_LEGAL
201218
GVA:
202219
location: 6
203-
description: |
204-
*Guest Virtual Address*
205-
206-
Written by hardware whenever a trap is taken into HS-mode:
220+
long_name: Guest Virtual Address
221+
description:
222+
- id: csr-hstatus-gva-behavior
223+
normative: false
224+
text: |
225+
Written by hardware whenever a trap is taken into HS-mode:
207226
208-
* Writes 1 when a trap causes a guest virtual address to be written into `stval` (`Breakpoint`, `* Address Misaligned`, `* Access Fault`, `* Page Fault`, or `* Guest-Page Fault`).
209-
* Writes 0 otherwise
227+
* Writes 1 when a trap causes a guest virtual address to be written into `stval` (`Breakpoint`, `* Address Misaligned`, `* Access Fault`, `* Page Fault`, or `* Guest-Page Fault`).
228+
* Writes 0 otherwise
210229
211-
Does not affect execution.
230+
Does not affect execution.
212231
type: RW
213232
reset_value: UNDEFINED_LEGAL
214233
VSBE:
215234
location: 5
216-
description: |
217-
*VS-mode Big Endian*
218-
219-
Controls the endianness of data VS-mode (0 = little, 1 = big).
220-
Instructions are always little endian, regardless of the data setting.
221-
222-
[when,"VS_MODE_ENDIANESS == little"]
223-
Since the CPU does not support big endian in VS-mode, this is hardwired to 0.
224-
225-
[when,"VS_MODE_ENDIANESS == bit"]
226-
Since the CPU does not support little endian in VS-mode, this is hardwired to 1.
235+
long_name: VS-mode Big Endian
236+
description:
237+
- id: csr-hstatus-vgein-behavior
238+
normative: false
239+
text: |
240+
Controls the endianness of data VS-mode (0 = little, 1 = big).
241+
Instructions are always little endian, regardless of the data setting.
242+
243+
- id: csr-hstatus-vgein-little-endian
244+
normative: false
245+
text: |
246+
Since the CPU does not support big endian in VS-mode, this is hardwired to 0.
247+
when(): return VS_MODE_ENDIANESS == "little";
248+
249+
- id: csr-hstatus-vgein-big-endian
250+
normative: false
251+
text: |
252+
Since the CPU does not support little endian in VS-mode, this is hardwired to 1.
253+
when(): return VS_MODE_ENDIANESS == "big";
227254
type(): |
228255
if (VS_MODE_ENDIANESS == "dynamic") {
229256
# mode is mutable

‎arch/csr/mie.yaml

+1-2
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,7 @@ address: 0x304
88
priv_mode: M
99
length: MXLEN
1010
definedBy: Sm
11-
description:
12-
$copy: "mip.yaml#/description"
11+
description: "mip.yaml#/description"
1312
fields:
1413
SSIE:
1514
location: 1

‎lib/arch_obj_models/csr_field.rb

+8
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,14 @@ def initialize(parent_csr, field_name, field_data)
2929
@parent = parent_csr
3030
end
3131

32+
# CSR fields are defined in their parent CSR YAML file
33+
def __source = @parent.__source
34+
35+
# CSR field data starts at fields: NAME: with the YAML
36+
def source_line(*path)
37+
super("fields", name, *path)
38+
end
39+
3240
# For a full config, whether or not the field is implemented
3341
# For a partial config, whether or the it is possible for the field to be implemented
3442
#

0 commit comments

Comments
 (0)