Skip to content

Commit de57816

Browse files
amykyta3amykyta3
committed
Add more guides to docs
1 parent 2805d1d commit de57816

File tree

3 files changed

+343
-1
lines changed

3 files changed

+343
-1
lines changed

‎docs/best-practices.rst

+108
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
SystemRDL Best Practices
2+
========================
3+
4+
Avoid global scope
5+
------------------
6+
Only use the global lexical scope if you want to declare common components that
7+
you intend to use globally. This avoids polluting the global namespace and
8+
prevents unexpected component name collisions.
9+
10+
Bad:
11+
12+
.. code:: systemrdl
13+
14+
reg my_ctrl_reg {
15+
...
16+
};
17+
18+
reg my_status_reg {
19+
...
20+
};
21+
22+
addrmap my_device {
23+
my_ctrl_reg ctrl;
24+
my_status_reg status;
25+
};
26+
27+
Good:
28+
29+
.. code:: systemrdl
30+
31+
addrmap my_device {
32+
reg my_ctrl_reg {
33+
...
34+
};
35+
36+
reg my_status_reg {
37+
...
38+
};
39+
40+
my_ctrl_reg ctrl;
41+
my_status_reg status;
42+
};
43+
44+
45+
When to use addrmap vs regfile
46+
------------------------------
47+
The ``addrmap`` and ``regfile`` components are very similar. Sometimes it is not
48+
clear which you should use.
49+
50+
regfile
51+
Use a regfile when describing a *conceptual* grouping of registers inside
52+
a peripheral's register block.
53+
Regfiles are useful to group similar concepts together to make your register
54+
space logically organized.
55+
A regfile does not imply any physical boundary in the hardware implementation.
56+
57+
addrmap
58+
An addrmap is used to describe a grouping that *physically* separates
59+
subsystems in a design. An addrmap may be used to represent the top-level node
60+
of a peripheral's register block, a grouping of peripherals, or the top-level
61+
of your SoC.
62+
63+
64+
Use default assignments
65+
-----------------------
66+
Default assignments are an easy way to override the default value of an assignment
67+
within a lexical scope. These are very useful for common properties like ``sw``
68+
and ``hw`` in control or status registers that have many fields with similar behavior.
69+
70+
Without default assignments:
71+
72+
.. code:: systemrdl
73+
74+
reg my_control_reg {
75+
field {
76+
sw = rw;
77+
hw = r;
78+
} a;
79+
80+
field {
81+
sw = rw;
82+
hw = r;
83+
} b;
84+
85+
field {
86+
sw = rw;
87+
hw = r;
88+
} c;
89+
};
90+
91+
With default assignments:
92+
93+
.. code:: systemrdl
94+
95+
reg my_control_reg {
96+
default sw = rw;
97+
default hw = r;
98+
99+
field {} a;
100+
field {} b;
101+
field {} c;
102+
};
103+
104+
.. tip::
105+
106+
Use default assignments in the most local lexical scope possible.
107+
This improves readability, and prevents the assignment from affecting
108+
something you didn't intend.

‎docs/index.rst

+9-1
Original file line numberDiff line numberDiff line change
@@ -49,12 +49,20 @@ Links
4949

5050
self
5151
gallery
52-
systemrdl-tutorial
5352
processing-input
5453
configuring
5554
licensing
5655
community
5756

57+
.. toctree::
58+
:hidden:
59+
:caption: About SystemRDL
60+
61+
systemrdl-tutorial
62+
style-guide
63+
best-practices
64+
65+
5866
.. toctree::
5967
:hidden:
6068
:caption: Additional Exporter Docs

‎docs/style-guide.rst

+226
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
SystemRDL Style Guide
2+
=====================
3+
Style guides can be a helpful way to ensure code readability and build common
4+
best-practices. These are not hard rules, but rather they are recommendations
5+
to follow so that your SystemRDL is readable and beautiful to everyone that
6+
comes across it. Since all style guides are inherently opinionated, it is
7+
important not to take them too seriously. It is ok to break from the style
8+
guide if it will improve readability and consistency.
9+
10+
11+
12+
Indentation is 4 spaces per level
13+
---------------------------------
14+
15+
Do not use tabs. Use spaces for indentation.
16+
Configure your text editor to emit spaces when you press the tab key.
17+
18+
When to indent
19+
--------------
20+
Always add a level of indentation for component contents, enum contents,
21+
parameter lists, or anything else between braces: ``{``, ``}``, ``(``, ``)``,
22+
23+
Keep indentation consistent
24+
---------------------------
25+
26+
Yes:
27+
28+
.. code:: systemrdl
29+
30+
field {
31+
desc = "My field";
32+
sw = rw;
33+
hw = r;
34+
} my_field;
35+
36+
No:
37+
38+
.. code:: systemrdl
39+
40+
field {
41+
desc = "My field";
42+
sw = rw;
43+
hw = r;
44+
} my_field;
45+
46+
47+
Braces and Parentheses
48+
----------------------
49+
The opening brace ``{`` must be on the same line as the statement it belongs to.
50+
The closing brace ``}`` must be on a line of its own along with its instance
51+
name if appropriate.
52+
53+
54+
Yes:
55+
56+
.. code:: systemrdl
57+
58+
field {
59+
desc = "My field";
60+
sw = rw;
61+
hw = r;
62+
} my_field;
63+
64+
No:
65+
66+
.. code:: systemrdl
67+
68+
field
69+
{
70+
desc = "My field";
71+
sw = rw;
72+
hw = r;
73+
}
74+
my_field;
75+
76+
If a component has a parameter list, parentheses use the same convention:
77+
78+
.. code:: systemrdl
79+
80+
field my_field #(
81+
longint unsigned MY_PARAM = 1,
82+
longint unsigned OTHER_PARAM = 2
83+
){
84+
desc = "My field";
85+
sw = rw;
86+
hw = r;
87+
};
88+
89+
my_field #(
90+
.MY_PARAM(2),
91+
.OTHER_PARAM(3),
92+
) inst;
93+
94+
95+
Where to add spaces
96+
-------------------
97+
98+
On both sides of any assignment or expression operators
99+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
100+
101+
Yes:
102+
103+
.. code:: systemrdl
104+
105+
reset = 4 + MY_PARAM / 2;
106+
107+
No:
108+
109+
.. code:: systemrdl
110+
111+
reset=4+MY_PARAM/2;
112+
113+
Before and after open/close braces
114+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
115+
116+
Yes:
117+
118+
.. code:: systemrdl
119+
120+
field {
121+
desc = "My field";
122+
} my_field;
123+
124+
No:
125+
126+
.. code:: systemrdl
127+
128+
field{
129+
desc = "My field";
130+
}my_field;
131+
132+
Exception is if the next item after a closing brace is a semicolon: ``};``
133+
134+
135+
Only one property assignment per-line
136+
-------------------------------------
137+
138+
In most cases, keep each property assignment on its own distinct line.
139+
Since properties ``sw`` and ``hw``, are nearly always used together, it is
140+
acceptable to stack them on the same line.
141+
142+
Yes:
143+
144+
.. code:: systemrdl
145+
146+
field {
147+
desc = "My field";
148+
sw = r;
149+
hw = na;
150+
counter;
151+
onread = rclr;
152+
} my_field;
153+
154+
No:
155+
156+
.. code:: systemrdl
157+
158+
field {
159+
desc = "My field";
160+
sw = r; hw = na; counter; onread = rclr;
161+
} my_field;
162+
163+
164+
Acceptable:
165+
166+
.. code:: systemrdl
167+
168+
field {
169+
desc = "My field";
170+
sw = r; hw = na;
171+
counter;
172+
onread = rclr;
173+
} my_field;
174+
175+
176+
Component type and instance names are lowercase
177+
-----------------------------------------------
178+
There is no need to yell.
179+
180+
Yes:
181+
182+
.. code:: systemrdl
183+
184+
field my_field {
185+
...
186+
};
187+
188+
my_field inst;
189+
190+
No:
191+
192+
.. code:: systemrdl
193+
194+
field MY_FIELD {
195+
...
196+
};
197+
198+
MY_FIELD INST;
199+
200+
201+
202+
Parameters and Verilog-style macros are uppercase
203+
-------------------------------------------------
204+
Constants should be in ALL_CAPS
205+
206+
207+
Long descriptions
208+
-----------------
209+
210+
Break long descriptions into multiple lines, indented at the same level as the
211+
scope it is in.
212+
Start and end quotation marks use the same rules as braces.
213+
214+
.. code:: systemrdl
215+
216+
field {
217+
desc = "My short description";
218+
} my_field_a;
219+
220+
field {
221+
desc = "
222+
This is a long description.
223+
224+
It requires multiple lines that are all indented at the same level.
225+
";
226+
} my_field_b;

0 commit comments

Comments
 (0)