[RACL] Add documentation and example config #26198
Conversation
davidschrammel
requested review from
Razer6,
rswarbrick,
andreaskurth and
vogelpi
davidschrammel
force-pushed
the
racl-doc-1
branch
2 times, most recently
from
8aebeae to
873e7a6
Compare
davidschrammel
force-pushed
the
racl-doc-1
branch
4 times, most recently
from
af586d9 to
9f6cebf
Compare
hw/ip_templates/racl_ctrl/README.md
Outdated
|
|
||
| Furthermore, each module instance that supports RACL must specify a valid `racl_mapping` for each of its `bus_interfaces`. | ||
| If there is only one such interface, a racl mapping may be specified as follows: | ||
|
|
There was a problem hiding this comment.
Nit: Is there a reason to include the blank lines like this? I think that some tools might interpret this as a paragraph break, which we don't need around the code fragments. (Obviously, it would depend on the word processor or whatever, but we don't want "whereas" to be indented)
hw/ip_templates/racl_ctrl/README.md
Outdated
| E.g., `racl_config: 'top_darjeeling/data/racl/racl.hjson'`. | ||
|
|
||
| Furthermore, each module instance that supports RACL must specify a valid `racl_mapping` for each of its `bus_interfaces`. | ||
| If there is only one such interface, a racl mapping may be specified as follows: |
There was a problem hiding this comment.
Nit: I'd say "the racl mapping" to make it clear that there's only one in this case.
hw/ip_templates/racl_ctrl/README.md
Outdated
| ```hjson | ||
| racl_mappings: { | ||
| soc: 'top_darjeeling/data/racl/all_rd_wr_mapping.hjson' | ||
| sram: 'top_darjeeling/data/racl/all_rd_wr_mapping.hjson' |
There was a problem hiding this comment.
Would it make sense to give an example where the different interfaces have different mappings?
|
|
||
| ```hjson | ||
| { | ||
| error_response: true |
There was a problem hiding this comment.
Do we have documentation anywhere that explains what these keys mean? If not, maybe this file is the right place for it?
There was a problem hiding this comment.
Good point! I have added some comments.
| parser.add_argument('--racl-config', | ||
| '-r', | ||
| required=True, | ||
| required=not is_doc, |
There was a problem hiding this comment.
This is rather clever! But the error messages might be a bit confusing. I'd probably make these optional for argparse, but then put an extra check just after the call to parse_args, which does something like this? (Completely untested!)
if not args.is_doc:
if (args.racl_config is None or
args.ip is None or
args.mapping is None):
raise SystemExit("--racl-config, --ip and --mapping are all required for non-doc runs.")There was a problem hiding this comment.
@rswarbrick I pushed some changes and came up with a different solution. Let me know what you think of it!
% ./util/raclgen.py
usage:
raclgen.py --doc DOC
Generates markdown documentation of the RACL configuration for a given top.
raclgen.py --racl-config RACL_CONFIG --ip IP --mapping MAPPING [--if-name IF_NAME]
Generates the RACL policy selection vector for the given IP, RACL mapping, and interface name.
raclgen.py: error: the following arguments are required: --racl-config/-r, --ip/-i, --mapping/-m
Arguably, this error message is still not 100% correct but I would like to avoid the if (args.racl_config ... checks.
| for if_name, racl_mappings in module['racl_mappings'].items(): | ||
| racl_mapping = { | ||
| 'if_name': if_name, | ||
| 'racl_group': racl_mappings['racl_group'], |
There was a problem hiding this comment.
Do we already know that this key is valid for some reason? (An argument for using proper data types!)
There was a problem hiding this comment.
I agree, we should probably add a proper serializer/class for the racl mappings and racl configuration. However, I would defer this to a future PR.
davidschrammel
force-pushed
the
racl-doc-1
branch
from
9f6cebf to
897072c
Compare
Signed-off-by: David Schrammel <[email protected]>
Signed-off-by: David Schrammel <[email protected]>
davidschrammel
force-pushed
the
racl-doc-1
branch
from
897072c to
b687cea
Compare
This commit adds initial documentation for RACL and describes the racl configuration files in the form of inline examples.
Furthermore, it generates a
racl_configuration.mdfile which documents the current RACL configuration for each module instance and interface.I don't have a strong opinion on how to format the RACL config information in the generated tables. We can still discuss and changes this!
Note: This commit already mentions RACL ranges from #26094 that are not yet merged.
The
Private CIerrorsModuleNotFoundError: No module named 'reggen.md_helpers'are likely introduced in this commit, but I'm not sure how to fix them as I cannot reproduce them locally.