Skip to content

Commit a83d966

Browse files
neverlandizKatherine HsuKatherine Hsudhower-qc
authored
Add CSR Definitions for Trigger Module Registers (#524)
This PR addresses Issue #81 by adding the missing CSR definitions for the following trigger module registers: - tselect - tdata1 - tdata2 - tdata3 - scontext - mcontext - hcontext --------- Signed-off-by: Katherine Hsu <[email protected]> Co-authored-by: Katherine Hsu <[email protected]> Co-authored-by: Katherine Hsu <[email protected]> Co-authored-by: Derek Hower <[email protected]>
1 parent 8485dbc commit a83d966

File tree

9 files changed

+394
-6
lines changed

9 files changed

+394
-6
lines changed

‎spec/std/isa/csr/hcontext.yaml‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Copyright (c) Katherine Hsu
2+
# SPDX-License-Identifier: BSD-3-Clause-Clear
3+
4+
# yaml-language-server: $schema=../../../schemas/csr_schema.json
5+
6+
$schema: "csr_schema.json#"
7+
kind: csr
8+
name: hcontext
9+
long_name: Hypervisor Context
10+
address: 0x6A8
11+
priv_mode: S
12+
length: XLEN
13+
writable: true
14+
description: |
15+
This optional register may be implemented only if the H extension is implemented.
16+
If it is implemented, `mcontext` must also be implemented.
17+
18+
This register is only accessible in HS-Mode, M-mode and Debug Mode. If Smstateen is implemented,
19+
then accessibility of in HS-Mode is controlled by `mstateen0[57]`.
20+
21+
This register is an alias of the `mcontext` register, providing access to the HCONTEXT field from HS-Mode.
22+
23+
definedBy:
24+
allOf:
25+
- Sdtrig
26+
- H
27+
fields:
28+
HCONTEXT:
29+
alias: mcontext.HCONTEXT
30+
location: 13-0
31+
type: RW
32+
description: |
33+
Alias of `mcontext.HCONTEXT`.
34+
reset_value: 0
35+
sw_write(csr_value): |
36+
# check if mstateen0 is implemented
37+
if (implemented?(ExtensionName::Smstateen) && CSR[mstateen0].CONTEXT != 0) {
38+
unimplemented_csr($encoding);
39+
}
40+
41+
# check if HCONTEXT is available
42+
if (!HCONTEXT_AVAILABLE) {
43+
unimplemented_csr($encoding);
44+
}
45+
46+
# enforce width of HCONTEXT
47+
Bits<14> hcontext_value = csr_value.HCONTEXT & ((14'1 << DBG_HCONTEXT_WIDTH) - 1);
48+
# forward the write to mcontext.HCONTEXT
49+
CSR[mcontext].HCONTEXT = hcontext_value;
50+
return CSR[mcontext].HCONTEXT;
51+
sw_read(): |
52+
# check if mstateen0 is implemented
53+
if (implemented?(ExtensionName::Smstateen) && CSR[mstateen0].CONTEXT != 0) {
54+
unimplemented_csr($encoding);
55+
}
56+
57+
# check if HCONTEXT is available
58+
if (!HCONTEXT_AVAILABLE) {
59+
unimplemented_csr($encoding);
60+
}
61+
62+
# return the value of mcontext
63+
return $bits(CSR[mcontext]); # might truncate if xlen() < MXLEN, but that's the expected behavior

‎spec/std/isa/csr/mcontext.yaml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Copyright (c) Katherine Hsu
2+
# SPDX-License-Identifier: BSD-3-Clause-Clear
3+
4+
# yaml-language-server: $schema=../../../schemas/csr_schema.json
5+
6+
$schema: "csr_schema.json#"
7+
kind: csr
8+
name: mcontext
9+
long_name: Machine Context
10+
address: 0x7A8
11+
priv_mode: M
12+
length: MXLEN
13+
writable: true
14+
description: |
15+
This register must be implemented if `hcontext` is implemented, and is optional otherwise.
16+
It is only accessible in M-mode and Debug mode.
17+
18+
`hcontext` is primarily useful to set triggers on hypervisor systems that only fire when a
19+
given VM is executing. It is also useful in systems where M-Mode implements something like
20+
a hypervisor directly.
21+
22+
definedBy: Sdtrig
23+
fields:
24+
HCONTEXT:
25+
location: 13-0
26+
type: RW
27+
description: |
28+
M-Mode or HS-Mode (using `hcontext`) software can write a
29+
context number to this register, which can be used to set
30+
triggers that only fire in that specific context.
31+
32+
An implementation may tie any number of upper bits in
33+
this field to 0. If the H extension is not implemented, it’s
34+
recommended to implement 6 bits on RV32 and 13 bits on
35+
RV64 (as visible through the `mcontext` register). If the H
36+
extension is implemented, it’s recommended to
37+
implement 7 bits on RV32 and 14 bits on RV64.
38+
reset_value: 0
39+
sw_write(csr_value): |
40+
# check if MCONTEXT is available
41+
if (!MCONTEXT_AVAILABLE) {
42+
unimplemented_csr($encoding);
43+
}
44+
45+
# enforce width of HCONTEXT
46+
Bits<14> hcontext_value = csr_value.HCONTEXT & ((14'1 << DBG_HCONTEXT_WIDTH) - 1);
47+
return hcontext_value;
48+
sw_read(): |
49+
# check if MCONTEXT is available
50+
if (!MCONTEXT_AVAILABLE) {
51+
unimplemented_csr($encoding);
52+
}

‎spec/std/isa/csr/mscontext.yaml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Copyright (c) Katherine Hsu
2+
# SPDX-License-Identifier: BSD-3-Clause-Clear
3+
4+
# yaml-language-server: $schema=../../../schemas/csr_schema.json
5+
6+
$schema: "csr_schema.json#"
7+
kind: csr
8+
name: mscontext
9+
long_name: Machine Supervisor Context
10+
address: 0x7AA
11+
priv_mode: S
12+
length: XLEN
13+
writable: true
14+
description: |
15+
This optional register is an alias for `scontext`. It is only
16+
accessible in S/HS-mode, M-mode and Debug Mode. It is included
17+
for backward compatibility with version 0.13.
18+
19+
The encoding of this CSR does not conform to the CSR Address
20+
Mapping Convention in the Privileged Spec. It is expected that
21+
new implementations will not support this encoding and that new
22+
debuggers will not use this CSR if `scontext` is available.
23+
24+
definedBy:
25+
allOf:
26+
- Sdtrig
27+
- S
28+
fields:
29+
DATA:
30+
location_rv32: 31-0
31+
location_rv64: 63-0
32+
type: RW
33+
description: |
34+
Supervisor mode software can write a context number to
35+
this register, which can be used to set triggers that only fire
36+
in that specific context.
37+
38+
An implementation may tie any number of high bits in
39+
this field to 0. It’s recommended to implement 16 bits on
40+
RV32 and 32 bits on RV64.
41+
reset_value: 0

‎spec/std/isa/csr/scontext.yaml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Copyright (c) Katherine Hsu
2+
# SPDX-License-Identifier: BSD-3-Clause-Clear
3+
4+
# yaml-language-server: $schema=../../../schemas/csr_schema.json
5+
6+
$schema: "csr_schema.json#"
7+
kind: csr
8+
name: scontext
9+
long_name: Supervisor Context
10+
address: 0x5A8
11+
priv_mode: S
12+
length: XLEN
13+
writable: true
14+
description: |
15+
This optional register is only accessible in S/HS-mode, VS-mode, M-mode and Debug Mode.
16+
Accessibility of this CSR is controlled by `mstateen0[57]` and `hstateen0[57]` in the
17+
Smstateen extension. Enabling `scontext` can be a security risk in a virtualized system
18+
with a hypervisor that does not swap `scontext`.
19+
20+
definedBy:
21+
allOf:
22+
- Sdtrig
23+
- S
24+
fields:
25+
DATA:
26+
location: 31-0
27+
type: RW
28+
description: |
29+
Supervisor mode software can write a context number to
30+
this register, which can be used to set triggers that only fire
31+
in that specific context.
32+
33+
An implementation may tie any number of high bits in
34+
this field to 0. It’s recommended to implement 16 bits on
35+
RV32 and 32 bits on RV64.
36+
reset_value: 0
37+
sw_write(csr_value): |
38+
# check if mstateen0 or hstateen0 is clear
39+
if (implemented?(ExtensionName::Smstateen) && ((CSR[mstateen0].CONTEXT != 0) || (CSR[hstateen0].CONTEXT != 0))) {
40+
unimplemented_csr($encoding);
41+
}
42+
43+
# enforce width of SCONTEXT
44+
Bits<32> scontext_value = csr_value.DATA & ((32'1 << DBG_SCONTEXT_WIDTH) - 1);
45+
return scontext_value;
46+
sw_read(): |
47+
# check if mstateen0 or hstateen0 is clear
48+
if (implemented?(ExtensionName::Smstateen) && ((CSR[mstateen0].CONTEXT != 0) || (CSR[hstateen0].CONTEXT != 0))) {
49+
unimplemented_csr($encoding);
50+
}

‎spec/std/isa/csr/tdata1.yaml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Copyright (c) Katherine Hsu
2+
# SPDX-License-Identifier: BSD-3-Clause-Clear
3+
4+
# yaml-language-server: $schema=../../../schemas/csr_schema.json
5+
6+
$schema: "csr_schema.json#"
7+
kind: csr
8+
name: tdata1
9+
long_name: Trigger Data 1
10+
address: 0x7A1
11+
priv_mode: M
12+
length: XLEN
13+
writable: true
14+
description: |
15+
This register provides access to the trigger selected by `tselect`.
16+
The reset values listed here apply to every underlying trigger.
17+
18+
This register is optional if no triggers are implemented.
19+
Writing 0 to this register must result in a trigger that is disabled.
20+
If this trigger supports multiple types, then the hardware should disable it
21+
by changing type to 15.
22+
23+
definedBy: Sdtrig
24+
fields:
25+
TYPE:
26+
location_rv32: 31-28
27+
location_rv64: 63-60
28+
type: RW
29+
description: |
30+
0 (none):: There is no trigger at this `tselect`.
31+
1 (legacy):: The trigger is a legacy SiFive address match trigger. These should not be implemented and aren’t further documented here.
32+
2 (mcontrol):: The trigger is an address/data match trigger. The remaining bits in this register act as described in `mcontrol`.
33+
3 (icount):: The trigger is an instruction count trigger. The remaining bits in this register act as described in `icount`.
34+
4 (itrigger):: The trigger is an interrupt trigger. The remaining bits in this register act as described in `itrigger`.
35+
5 (etrigger):: The trigger is an exception trigger. The remaining bits in this register act as described in `etrigger`.
36+
6 (mcontrol6):: The trigger is an address/data match trigger. The remaining bits in this register act as described in `mcontrol6`. This is similar to a type 2 trigger, but provides additional functionality and should be used instead of type 2 in newer implementations.
37+
7 (tmexttrigger):: The trigger is a trigger source external to the TM. The remaining bits in this register act as described in `tmexttrigger`.
38+
12—14 (custom):: These trigger types are available for non-standard use.
39+
15 (disabled):: This trigger is disabled. In this state, `tdata2` and `tdata3` can be written with any value that is supported for any of the types this trigger implements. The remaining bits in this register, except for `DMODE`, are ignored.
40+
41+
Other values are reserved for future use.
42+
reset_value: UNDEFINED_LEGAL
43+
DMODE:
44+
location_rv32: 27
45+
location_rv64: 59
46+
type: RW
47+
description: |
48+
If type is 0, then this bit is hard-wired to 0.
49+
50+
0 (both): Both Debug and M-mode can write the `tdata` registers at the selected `tselect`.
51+
1 (dmode): Only Debug Mode can write the `tdata` registers at the selected `tselect`. Writes from other modes are ignored.
52+
53+
This bit is only writable from Debug Mode. In ordinary
54+
use, external debuggers will always set this bit when
55+
configuring a trigger. When clearing this bit, debuggers
56+
should also set the action field (whose location depends on
57+
type) to something other than 1.
58+
reset_value: 0
59+
DATA:
60+
location_rv32: 26-0
61+
location_rv64: 58-0
62+
type: RW
63+
description: |
64+
If type is 0, then this field is hard-wired to 0.
65+
Trigger-specific data.
66+
reset_value: UNDEFINED_LEGAL

‎spec/std/isa/csr/tdata2.yaml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Copyright (c) Katherine Hsu
2+
# SPDX-License-Identifier: BSD-3-Clause-Clear
3+
4+
# yaml-language-server: $schema=../../../schemas/csr_schema.json
5+
6+
$schema: "csr_schema.json#"
7+
kind: csr
8+
name: tdata2
9+
long_name: Trigger Data 2
10+
address: 0x7A2
11+
priv_mode: M
12+
length: XLEN
13+
writable: true
14+
description: |
15+
This register provides access to the trigger selected by `tselect`.
16+
The reset values listed here apply to every underlying trigger.
17+
18+
Trigger-specific data. It is optional if no implemented triggers use it.
19+
If the trigger is disabled, then this register can be written with any value
20+
supported by any of the trigger types supported by this trigger.
21+
If XLEN is less than DXLEN, writes to this register are sign-extended.
22+
23+
definedBy: Sdtrig
24+
fields:
25+
DATA:
26+
location_rv32: 31-0
27+
location_rv64: 63-0
28+
type: RW
29+
description: Data value
30+
reset_value: UNDEFINED_LEGAL

‎spec/std/isa/csr/tdata3.yaml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Copyright (c) Katherine Hsu
2+
# SPDX-License-Identifier: BSD-3-Clause-Clear
3+
4+
# yaml-language-server: $schema=../../../schemas/csr_schema.json
5+
6+
$schema: "csr_schema.json#"
7+
kind: csr
8+
name: tdata3
9+
long_name: Trigger Data 3
10+
address: 0x7A3
11+
priv_mode: M
12+
length: XLEN
13+
writable: true
14+
description: |
15+
This register provides access to the trigger selected by `tselect`.
16+
The reset values listed here apply to every underlying trigger.
17+
18+
Trigger-specific data. It is optional if no implemented triggers use it.
19+
If the trigger is disabled, then this register can be written with any value
20+
supported by any of the trigger types supported by this trigger.
21+
If XLEN is less than DXLEN, writes to this register are sign-extended.
22+
23+
definedBy: Sdtrig
24+
fields:
25+
DATA:
26+
location_rv32: 31-0
27+
location_rv64: 63-0
28+
type: RW
29+
description: Data value
30+
reset_value: UNDEFINED_LEGAL

‎spec/std/isa/csr/tselect.yaml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Copyright (c) Katherine Hsu
2+
# SPDX-License-Identifier: BSD-3-Clause-Clear
3+
4+
# yaml-language-server: $schema=../../../schemas/csr_schema.json
5+
6+
$schema: "csr_schema.json#"
7+
kind: csr
8+
name: tselect
9+
long_name: Trigger Select
10+
address: 0x7A0
11+
priv_mode: M
12+
length: XLEN
13+
writable: true
14+
description: |
15+
This register determines which trigger is accessible through the other Trigger Module registers.
16+
17+
It is optional if no triggers are implemented. The set of accessible triggers must start at 0,
18+
and be contiguous. This register is WARL. Writes of values greater than or equal to the number of
19+
supported triggers may result in a different value in this register than what was written or may
20+
point to a trigger where type=0.
21+
22+
To verify that what they wrote is a valid index, debuggers can
23+
read back the value and check that tselect holds what they wrote and read tdata1 to see that type
24+
is non-zero. Since triggers can be used both by Debug Mode and M-mode, the external debugger must
25+
restore this register if it modifies it.
26+
27+
definedBy: Sdtrig
28+
fields:
29+
INDEX:
30+
location_rv32: 31-0
31+
location_rv64: 63-0
32+
type: RW
33+
description: Index value
34+
reset_value: UNDEFINED_LEGAL

0 commit comments

Comments
 (0)