Skip to content

Commit e22ae2b

Browse files
author
Derek Hower
committed
Update arch/README.adoc to reflect actual YAML flow
1 parent 70518d6 commit e22ae2b

File tree

1 file changed

+60
-41
lines changed

1 file changed

+60
-41
lines changed

‎arch/README.adoc‎

Lines changed: 60 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,16 @@ A few challenging issues that arise include:
1515

1616
To tame this challenge, this specification generator takes the following approach:
1717

18-
* The generic architecture (in the `arch/` folder) is described in a way that covers all implementation options. As much as possible, the architecture is defined in a structured way that can be easily parsed using any programming language with a https://en.wikipedia.org/wiki/YAML[YAML] library. Complex behavior (_e.g._, instruction operation) and some configuration-dependent metadata is specified in an architecture definition language (xref:prose/idl.adoc[IDL]) that can formally define the architecture in arbitrary ways.
18+
* The RVI standard architecture (in the `arch/` folder) is described in a way that covers all implementation options. As much as possible, the architecture is defined in a structured way that can be easily parsed using any programming language with a https://en.wikipedia.org/wiki/YAML[YAML] library. Complex behavior (_e.g._, instruction operation) and some configuration-dependent metadata is specified in an architecture definition language (xref:prose/idl.adoc[IDL]) that can formally define the architecture in arbitrary ways.
1919
* An implementation of RISC-V is specified as a _configuration_ containing all unnamed parameters and list of named supported extensions (in the `cfgs/` folder).
2020
* A tool, included in this repository, can generate an implmentation-specific specification by applying the configuration to the generic spec. Behaviors that are not relevant are left out, and behaviors that are affected by multiple extensions are merged into a single description.
2121

22+
Three standard configs are present:
23+
24+
* `_`: A completely _unconfigured_ configuration, i.e., where there are no restrictions and no known parameter values.
25+
* `rv32`: A configuration where only `MXLEN` is known to be 32, i.e., the RV32 ISA.
26+
* `rv64`: A configuration where only `MXLEN` is known to be 64, i.e., the RV64 ISA.
27+
2228
The architecture is specified in a series of https://en.wikipedia.org/wiki/YAML[YAML]
2329
files for _Extensions_, _Instructions_, and _Control and Status Registers (CSRs)_.
2430
Each extension/instruction/CSR has its own file.
@@ -27,48 +33,61 @@ Each extension/instruction/CSR has its own file.
2733

2834
[ditaa]
2935
....
30-
+----------------------------------------------------------------------------------------------+
31-
| Config (cfgs/NAME) |
32-
| +-------------------------+ +-------------------------+ +---------------------------------+ |
33-
| | Implementation Options | | Extension List | | Implementation Overlay | |
34-
| | (cfgs/NAME/params.yaml) | | (cfgs/NAME/params.yaml) | | (cfgs/NAME/arch_overlay/*.yaml) | |
35-
| +-------------------------+ +-------------------------+ +---------------------------------+ |
36-
+------------------------|-----|--------------------------------|------------------------------+
37-
| | |
38-
+----------------+ v v v
39-
|{s} Generic | /----------\ /----------\
40-
| Arch Spec |-->| Render | | Render |
41-
| (arch) | | (ERB) : | (ERB) :
42-
+----------------+ \----------/ \----------/
43-
| |
44-
v v
45-
+-----------------------------+ +-----------------------------------+
46-
| {s} Redered Arch Spec | | {s} Redered Overlay |
47-
| (gen/NAME/.rendered_arch) | | (gen/NAME/.rendered_overlay_arch) |
48-
+-----------------------------+ +------------------------------------+
49-
| |
50-
v |
51-
/-------------------------\ |
52-
| Overlay |<-------------------+
53-
| (gen/NAME/.merged_arch) :
54-
\-------------------------/
55-
|
56-
|
57-
/-----------\
58-
| Normalize |
59-
\-----------/
60-
|
61-
v
62-
+-----------------------------+
63-
| {s} Implementation-specific |
64-
| Archiecture Spec |
65-
| (gen/NAME/arch) |
66-
+-----------------------------+
36+
+--------------------------------------------------------------------------+
37+
| Config (cfgs/NAME) |
38+
| +------------------------------+ +-----------------------------------+ |
39+
| | Config (extensions & params) | | Implementation Overlay [optional] | |
40+
| | (cfgs/NAME/cfg.yaml) | | (cfgs/NAME/arch_overlay/*.yaml) | |
41+
| +------------------------------+ +-----------------------------------+ |
42+
+--------|------------------------------------------------------|----------+
43+
| |
44+
| +----------------+ v
45+
| |{s} Standard | /--------------------\
46+
| | Arch Spec |--->| JSON Merge Patch |
47+
| | (arch) | | RFC 7386 |
48+
| +----------------+ \--------------------/
49+
| |
50+
| v
51+
| +--------------------------+
52+
| | {s} Merged Arch Spec |
53+
| | (gen/arch/NAME/*.yaml) |
54+
| +--------------------------+
55+
| |
56+
| v
57+
| /---------------------\
58+
| | Resolve Operators |
59+
| | ($inherits/$remove) |
60+
| \---------------------/
61+
| |
62+
| v
63+
| +---------------------------------+
64+
| | {s} Implementation-specific |
65+
| | Archiecture Spec |
66+
| | (gen/resolved_arch/NAME/*.yaml) |
67+
| +---------------------------------+
68+
| |
69+
+------|-------------------------------------------------|---------+
70+
| | Ruby Interface | |
71+
| /--------\ | |
72+
| | Config | | |
73+
| \--------/ /---------------\ | |
74+
| | +-| Architecture |<----------------------+ |
75+
| | | \---------------/ |
76+
| | | |
77+
| v v |
78+
| /------------------------\ |
79+
| | ConfiguredArchitecture | |
80+
| \------------------------/ |
81+
+------------------------------------------------------------------+
6782
....
6883

69-
The normalization step transitively determines all extensions/instructions/csrs that are implemented
70-
(_e.g._, because some extensions have implied dependencies) and ensures that missing fields are
71-
filled in with their defaults.
84+
The final architecture files go through two transformation steps. First, config overlay files, if present,
85+
are merged on top of the standard architecture files according to JSON Merge Patch. This step is where
86+
any custom behavior can be added to the specification. Second, the (possibly) merged files are _resolved_
87+
by implementing the database operators `$inherits` and `$remove`.
88+
89+
The `ConfiguredArchitecture` class represents a configured view of the database, and is the basis
90+
of most queries about a config.
7291

7392
== Data Format
7493

0 commit comments

Comments
 (0)