Skip to content

Commit c90ab5d

Browse files
davidschrammelrswarbrick
davidschrammel
authored and
rswarbrick
committed
[racl_ctrl,doc] Add documentation and example config
Signed-off-by: David Schrammel <[email protected]>
1 parent 8bb0087 commit c90ab5d

File tree

9 files changed

+743
-7
lines changed

9 files changed

+743
-7
lines changed

‎hw/ip_templates/racl_ctrl/README.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,118 @@
11
# RACL Control Permission IP
2+
3+
`racl_ctrl` is currently being used in [top_darjeeling.hjson](../../../../hw/top_darjeeling/data/top_darjeeling.hjson).
4+
There `racl_config` points to the main configuration file of the RACL Controller.
5+
E.g., `racl_config: 'racl/racl.hjson'`.
6+
Furthermore, each module instance that supports RACL must specify a valid `racl_mapping` for each of its `bus_interfaces`.
7+
If there is only one such interface, the racl mapping may be specified as follows:
8+
```
9+
racl_mapping: 'racl/soc_rot_mapping.hjson'
10+
```
11+
whereas multiple `bus_interfaces` require a mapping for each interface:
12+
```hjson
13+
racl_mappings: {
14+
soc: 'racl/soc_rot_mapping.hjson'
15+
sram: 'racl/all_rd_wr_mapping.hjson'
16+
}
17+
```
18+
19+
## Example RACL configuration
20+
21+
```hjson
22+
{
23+
// error_response controls whether to return TLUL error on RACL errors
24+
error_response: true
25+
// The CTN UID is transfered via the TLUL reserved user bits: rsvd[ctn_uid_bit_msb:ctn_uid_bit_lsb]
26+
ctn_uid_bit_lsb: 0
27+
ctn_uid_bit_msb: 4
28+
// The RACL role is transfered via the TLUL reserved user bits: rsvd[role_bit_msb:role_bit_lsb]
29+
role_bit_lsb: 5
30+
role_bit_msb: 8
31+
roles: {
32+
"ROT" : { role_id: 0 }
33+
"ROLE1": { role_id: 1 }
34+
"SOC": { role_id: 2 }
35+
}
36+
policies: {
37+
Null: [
38+
// Standard policies allowing all roles to access a register
39+
{ name: "ALL_RD_WR"
40+
allowed_rd: [ "ROT", "ROLE1", "SOC" ]
41+
allowed_wr: [ "ROT", "ROLE1", "SOC" ]
42+
}
43+
// Standard policies allowing only the ROT role to access a register
44+
{ name: "ROT_PRIVATE"
45+
rot_private: true
46+
allowed_rd: [ "ROT" ]
47+
allowed_wr: [ "ROT" ]
48+
}
49+
// Custom policy
50+
{ name: "SOC_ROT"
51+
allowed_rd: [ "ROT", "SOC" ]
52+
allowed_wr: [ "ROT", "SOC" ]
53+
}
54+
]
55+
}
56+
}
57+
```
58+
59+
## Example RACL mappings
60+
61+
A minimal example for a module that only uses registers (and no windows or ranges) can look as follows.
62+
There the `*` maps to all registers.
63+
64+
```hjson
65+
{
66+
Null: {
67+
registers: {
68+
"*": "SOC_ROT"
69+
}
70+
}
71+
}
72+
```
73+
74+
The `*` option does not exist for ranges. These must be explicitly defined as follows.
75+
76+
```hjson
77+
{
78+
Null: {
79+
registers: {
80+
"*": "SOC_ROT"
81+
}
82+
windows: {
83+
"*": "SOC_ROT"
84+
}
85+
ranges: [
86+
{
87+
'base': "0x0000"
88+
'size': "0x1000"
89+
'policy': "ROT_PRIVATE"
90+
}
91+
{
92+
'base': "0x1000"
93+
'size': "0x0004"
94+
'policy': "ALL_RD_WR"
95+
}
96+
]
97+
}
98+
}
99+
```
100+
101+
Mapping individual registers/windows is done like so (using the `mbx` as an example):
102+
103+
```hjson
104+
{
105+
Null: {
106+
registers: {
107+
"SOC_CONTROL": "SOC_ROT"
108+
"SOC_STATUS": "SOC_ROT"
109+
"SOC_DOE_INTR_MSG_ADDR": "SOC_ROT"
110+
"SOC_DOE_INTR_MSG_DATA": "SOC_ROT"
111+
}
112+
windows: {
113+
"WDATA": "SOC_ROT"
114+
"RDATA": "SOC_ROT"
115+
}
116+
}
117+
}
118+
```

‎hw/ip_templates/racl_ctrl/doc/racl_configuration.md.tpl

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
${"#"} RACL Configuration
2+
3+
<!-- BEGIN CMDGEN util/raclgen.py --doc ./hw/top_${topname}/data/autogen/top_${topname}.gen.hjson -->
4+
<!-- END CMDGEN -->

‎hw/top_darjeeling/data/racl/racl.hjson

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,12 @@
33
// SPDX-License-Identifier: Apache-2.0
44

55
{
6+
// error_response controls whether to return TLUL error on RACL errors
67
error_response: true
8+
// The CTN UID is transfered via the TLUL reserved user bits: rsvd[ctn_uid_bit_msb:ctn_uid_bit_lsb]
79
ctn_uid_bit_lsb: 0
810
ctn_uid_bit_msb: 4
11+
// The RACL role is transfered via the TLUL reserved user bits: rsvd[role_bit_msb:role_bit_lsb]
912
role_bit_lsb: 5
1013
role_bit_msb: 8
1114
roles: {

‎hw/top_darjeeling/ip_autogen/racl_ctrl/README.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,118 @@
11
# RACL Control Permission IP
2+
3+
`racl_ctrl` is currently being used in [top_darjeeling.hjson](../../../../hw/top_darjeeling/data/top_darjeeling.hjson).
4+
There `racl_config` points to the main configuration file of the RACL Controller.
5+
E.g., `racl_config: 'racl/racl.hjson'`.
6+
Furthermore, each module instance that supports RACL must specify a valid `racl_mapping` for each of its `bus_interfaces`.
7+
If there is only one such interface, the racl mapping may be specified as follows:
8+
```
9+
racl_mapping: 'racl/soc_rot_mapping.hjson'
10+
```
11+
whereas multiple `bus_interfaces` require a mapping for each interface:
12+
```hjson
13+
racl_mappings: {
14+
soc: 'racl/soc_rot_mapping.hjson'
15+
sram: 'racl/all_rd_wr_mapping.hjson'
16+
}
17+
```
18+
19+
## Example RACL configuration
20+
21+
```hjson
22+
{
23+
// error_response controls whether to return TLUL error on RACL errors
24+
error_response: true
25+
// The CTN UID is transfered via the TLUL reserved user bits: rsvd[ctn_uid_bit_msb:ctn_uid_bit_lsb]
26+
ctn_uid_bit_lsb: 0
27+
ctn_uid_bit_msb: 4
28+
// The RACL role is transfered via the TLUL reserved user bits: rsvd[role_bit_msb:role_bit_lsb]
29+
role_bit_lsb: 5
30+
role_bit_msb: 8
31+
roles: {
32+
"ROT" : { role_id: 0 }
33+
"ROLE1": { role_id: 1 }
34+
"SOC": { role_id: 2 }
35+
}
36+
policies: {
37+
Null: [
38+
// Standard policies allowing all roles to access a register
39+
{ name: "ALL_RD_WR"
40+
allowed_rd: [ "ROT", "ROLE1", "SOC" ]
41+
allowed_wr: [ "ROT", "ROLE1", "SOC" ]
42+
}
43+
// Standard policies allowing only the ROT role to access a register
44+
{ name: "ROT_PRIVATE"
45+
rot_private: true
46+
allowed_rd: [ "ROT" ]
47+
allowed_wr: [ "ROT" ]
48+
}
49+
// Custom policy
50+
{ name: "SOC_ROT"
51+
allowed_rd: [ "ROT", "SOC" ]
52+
allowed_wr: [ "ROT", "SOC" ]
53+
}
54+
]
55+
}
56+
}
57+
```
58+
59+
## Example RACL mappings
60+
61+
A minimal example for a module that only uses registers (and no windows or ranges) can look as follows.
62+
There the `*` maps to all registers.
63+
64+
```hjson
65+
{
66+
Null: {
67+
registers: {
68+
"*": "SOC_ROT"
69+
}
70+
}
71+
}
72+
```
73+
74+
The `*` option does not exist for ranges. These must be explicitly defined as follows.
75+
76+
```hjson
77+
{
78+
Null: {
79+
registers: {
80+
"*": "SOC_ROT"
81+
}
82+
windows: {
83+
"*": "SOC_ROT"
84+
}
85+
ranges: [
86+
{
87+
'base': "0x0000"
88+
'size': "0x1000"
89+
'policy': "ROT_PRIVATE"
90+
}
91+
{
92+
'base': "0x1000"
93+
'size': "0x0004"
94+
'policy': "ALL_RD_WR"
95+
}
96+
]
97+
}
98+
}
99+
```
100+
101+
Mapping individual registers/windows is done like so (using the `mbx` as an example):
102+
103+
```hjson
104+
{
105+
Null: {
106+
registers: {
107+
"SOC_CONTROL": "SOC_ROT"
108+
"SOC_STATUS": "SOC_ROT"
109+
"SOC_DOE_INTR_MSG_ADDR": "SOC_ROT"
110+
"SOC_DOE_INTR_MSG_DATA": "SOC_ROT"
111+
}
112+
windows: {
113+
"WDATA": "SOC_ROT"
114+
"RDATA": "SOC_ROT"
115+
}
116+
}
117+
}
118+
```

0 commit comments

Comments
 (0)