Skip to content

Commit 34abbca

Browse files
mole99mole99
committed
Improve and clarify the docs
1 parent 0f93160 commit 34abbca

18 files changed

+341
-380
lines changed

‎Makefile

+4
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,10 @@ docs:
4040
host-docs:
4141
python3 -m http.server --directory ./docs/build/html
4242

43+
.PHONY: auto-docs
44+
auto-docs:
45+
sphinx-autobuild docs/source docs/build/html
46+
4347
.PHONY: clean
4448
clean:
4549
rm -rf build/

‎README.md

+8-73
Original file line numberDiff line numberDiff line change
@@ -90,80 +90,14 @@ To host the docs, run:
9090
make host-docs
9191
```
9292

93-
> [!NOTE]
94-
> The documentation can be viewed online at [cace.readthedocs.io](https://cace.readthedocs.io/).
95-
96-
## CACE GUI syntax
97-
98-
$ cace-gui [path/to/project.txt]
99-
100-
where optional file project.txt (normally <name_of_project>.txt
101-
where <name_of_project> is the name of the circuit to be
102-
characterized) is a circuit characterization description in the
103-
file format described below. If a file is not specified, then
104-
the GUI window will come up without content. Click on the button
105-
with text "(no selection)" to find and select a characterization
106-
file to load. The project file may also be in JSON format.
107-
108-
Normally, cace_gui.py is called from a project top level directory,
109-
while the project.txt file is usually in a subdirectory called
110-
cace/. The project.txt file may be the output file from a CACE
111-
run, which will add results to all of the parameter entries.
112-
113-
There may be multiple characterization files in a single project
114-
(repository), as a project may contain multiple subcircuits that
115-
may need independent characterization or be able to be used as
116-
standalone circuits, or a project may simply be a collection of
117-
circuits (library) without a specific single top level.
118-
119-
## CACE command line syntax
120-
121-
$ cace <filename_in> <filename_out> [options]
122-
123-
where <filename_in> is a format 4.0 ASCII CACE file
124-
and <filename_out> is the name of the file to write.
125-
126-
Options may be one of:
127-
128-
-source=schematic|layout|rcx|all|best
129-
-param=<parameter_name>
130-
-force
131-
-json
132-
-keep
133-
-debug
134-
-sequential
135-
-summary
136-
137-
When run from the top level, this program parses the CACE
138-
characterization file, runs simulations, and outputs a
139-
modified file annotated with characterization results.
93+
To automatically refresh the docs upon changes, run:
14094

141-
With option "-source", restrict characterization to the
142-
specific netlist source, which is either schematic capture,
143-
layout extracted, or full R-C parasitic extracted. If not
144-
specified, then characterization is run on the full R-C
145-
parasitic extracted layout netlist if available, and the
146-
schematic captured netlist if not (option "best").
147-
148-
Option "-param=<parameter_name>" runs simulations on only
149-
the named electrical or physical parameter.
150-
151-
Option "-force" forces new regeneration of all netlists.
152-
153-
Option "-json" generates an output file in JSON format.
154-
155-
Option "-keep" retains files generated for characterization.
156-
157-
Option "-noplot" will not generate any graphs.
158-
159-
Option "-debug" generates additional diagnostic output.
160-
161-
Option "-sequential" runs simulations sequentially.
162-
163-
Option "-nosim" does not re-run simulations if the output file exists.
164-
(Warning---does not check if simulations are out of date).
95+
```
96+
make auto-docs
97+
```
16598

166-
Option "-summary" prints a summary of results at the end.
99+
> [!NOTE]
100+
> The latest documentation can be viewed online at [cace.readthedocs.io](https://cace.readthedocs.io/).
167101
168102
## Examples
169103

@@ -187,4 +121,5 @@ Example circuit repositories:
187121

188122
Each of these repositories contains a circuit designed with the SkyWater sky130 process open PDK, and contains schematics, layout, and CACE characterization.
189123

190-
NOTE: These repositories are a work in progress, and may not exist yet or may not have a characterization setup for CACE.
124+
> [!NOTE]
125+
> These repositories are a work in progress, and may not exist yet or may not have a characterization setup for CACE.

‎docs/source/about.md

-23
This file was deleted.

‎docs/source/characterization.md

+107
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Characterization
2+
3+
## Selecting a datasheet
4+
5+
Start by selecting a datasheet. This step is only necessary if the application is started from the command line.
6+
7+
%If started from the project manager, then it can only be run if a datasheet exists for the project, in which case that datasheet is automatically loaded.
8+
9+
If running from the command line, there is a button at the top with the text `Datasheet:` and `(no selection)`. Push this button to get a file browser. Find a project datasheet, which is a text (`.txt`) file. A challenge datasheet should be found in the design folder for each accepted challenge.
10+
11+
%The project design folders are in the `design` subfolder in the user's home directory.
12+
13+
The challenge datasheet has the name of the project and the file extension `.txt`
14+
15+
When the JSON file is selected, a full display should be shown with each electrical parameter critical to the challenge, and its status.
16+
17+
## Characterization
18+
19+
The purpose of the characterization tool is to check the netlist against the official characterization specification for a circuit. The tool allows a quick check of the circuit design against the datasheet specification values, and presents a summary of results to the user. The purpose of these simulations is to see whether or not the design will pass or fail the specification. Details from these simulations are limited to the characterization values. They are not intended to replace the simulations done in the normal course of a circuit design.
20+
21+
The list of electrical parameters will vary by the type of design. However, each electrical paramater has a common set of properties that are listed in columns across the window. These are:
22+
23+
1. "Parameter" --- The name of the electrical or physical parameter.
24+
2. "Testbench" --- The testbench corresponds to a netlist filename with the extension ".spice" (SPICE netlist) that can be found in the "cace" folder of the project (or the "testbench" path declared in the characterization file). The testbench netlists are in a special format that allows them to be altered by substitution for a specific measurement.
25+
3. "Min" --- The minimum limit (if any) of the electrical parameter. After simulation, also shows the measured result of the circuit.
26+
4. "Typ" --- The typical value (if any) of the electrical parameter. After simulation, also shows the measured result of the circuit.
27+
5. "Max" --- The maximum limit (if any) of the electrical parameter. After simulation, also shows the measured result of the circuit.
28+
6. "Status" --- Is one of "(not checked)" if the circuit has not yet been simulated, "(in progress)" if the simulation is ongoing; "pass" if the circuit has been simulated and passed the specification for the eletrical parameter, and "fail" if it failed the specification. If the status is "pass" or "fail", this entry is a button that can be pressed to see a detailed view of the results.
29+
7. "Simulate" --- This is a button that will initiate an ngspice simulation of the electrical parameter.
30+
31+
At the bottom of the window is a space for program messages, warnings, and errors. Below that is a button bar with the following buttons:
32+
33+
- "Close" --- Quits the characterization tool. If new results have been simulated but not saved, the user will have to respond to a prompt.
34+
- "Save" --- Saves the current characterization results. These results will be loaded the next time the characterization tool is run, unless there is a design netlist newer than the saved results.
35+
- "Help" --- Activates this help window.
36+
- "Settings" --- Controls global settings for CACE.
37+
38+
The available settings are:
39+
40+
- Print debug output ---
41+
Produce additional output for diagnostic and debugging purposes.
42+
- Force netlist regeneration ---
43+
Require netlists to be regenerated for every simulation. Otherwise,
44+
netlists are only regenerated when the source file (schematic or layout)
45+
is found to post-date the netlist.
46+
- Allow edit of all parameters ---
47+
Allow the use of "Simulate-->Edit", which provides a method for in-app
48+
editing and copying of parameters (note that the characterization file
49+
itself may always be edited).
50+
- Simulate single-threaded ---
51+
Normally all simulations are done multi-threaded (with low priority).
52+
Selecting this option forces simulations to run one at a time.
53+
- Keep simulation files ---
54+
Normally simulation files are removed after simulation and only the
55+
results are kept. This option forces the files to remain after
56+
simulation.
57+
- Do not create plot files ---
58+
Normally plot files are generated for each plot. If this option is
59+
selected, plots may be viewed in-app but no file is generated.
60+
- Log simulation output ---
61+
Copy all simulation output into a log file.
62+
63+
64+
At the top of the window is the name and location of the datasheet, and on the right is a button that indicates what the source of the netlist being simulated is. The netlist source can be one of the following choices:
65+
66+
- **Schematic Capture**: Simulations are done from schematic
67+
- **Layout Extracted**: Simulations are done from layout without parasitics
68+
- **R-C Extracted**: Simulations are done from layout with parasitics
69+
70+
Separate results are maintained for each of these source cases. Proper sign-off characterization of a circuit should be done with a netlist from an R-C extracted layout.
71+
72+
### Generating a netlist
73+
74+
75+
Design your project schematic in a directory called "xschem" (or the path declared for "schematic" in the characterization file) using the xschem schematic tool. See the xschem user manual and tutorials for details. The netlist is generated automatically when running simulations in CACE.
76+
77+
### Simulation
78+
79+
To simulate a single electrical parameter, click the `Simulate` button for each electrical parameter. Pressing the button creates a drop-down menu with the choices:
80+
81+
Run
82+
Stop
83+
Edit
84+
Copy
85+
86+
Left-click on the selection to initiate it.
87+
88+
- **Run:**
89+
This will combine the design netlist with a testbench, simulate using ngspice, collate results, and display the resulting margin values. While ngspice is running, the `Simulate` button says `(in progress)`.
90+
91+
- **Stop:**
92+
If a testbench is running, then selecting "Stop" will end the simulations.
93+
94+
- **Edit:**
95+
This allows a testbench definition to be edited through the GUI, to modify the conditions of simulation. Note that the characterization definition file is text and can also be modified directly with an editor. Note that parameters are not editable by default. Go to "Settings" and select "Allow edit of all parameters" to allow parameters to be edited.
96+
97+
- **Copy:**
98+
This creates a new parameter that is a copy of the one selected. The new parameter can then be edited to simulate under a different set of conditions. This can also be done by directly modifying the characterization definition file with a text editor.
99+
100+
### Results
101+
102+
Every electrical parameter is specified over a range of conditions. This results in a series of simulations, usually one simulation run per unique set of conditions. Each simulation typically provides one result value, and the set of all values from all simulated conditions is used to find the minimum, typical, and maximum results that are printed on the main characterization page.
103+
104+
When an electrical parameter has finished simulating, clicking on the "Status" entry will generate a window showing details of the simulation. The window has one line per unique set of conditions simulated. For each line, the result value is given in the leftmost column. The remaining columns show each variable condition, and the value it had for the given simulation. The top of the column shows the range of values for the given parameter. This graph allows the user to quickly determine what are the conditions under which a circuit may be failing, and the degree to which the value is out of range of the specification. Rows in which the result is outside of the specified limit are shown in red.
105+
106+
In the results window, click on the title `Results` to change the view from having results ordered highest to lowest, to lowest to highest. Click on the name (column header) of any condition or variable to change the tabular view to a graph showing results vs. the selected condition or variable.
107+

‎docs/source/conf.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,6 @@
3333

3434
# -- Options for HTML output -------------------------------------------------
3535
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
36-
37-
html_theme = 'alabaster'
36+
html_title = "CACE Documentation"
37+
html_theme = 'furo'
3838
html_static_path = ['_static']

‎docs/source/dev/codebase.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Codebase
2+
3+
TODO information about how the codebase is structured
4+
5+
```
6+
├── cace
7+
│   ├── cace_cli.py
8+
│   ├── cace_gui.py
9+
│   ├── common
10+
│   ├── doc
11+
│   ├── gui
12+
│   ├── __init__.py
13+
│   ├── __main__.py
14+
│   └── __version__.py
15+
```

‎docs/source/dev/coding_style.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Coding Style
2+
3+
As coding style for the whole codebase of CACE, ["blue"](https://github.com/grantjenks/blue) is used. It is based on ["black"](https://github.com/psf/black) and allows us to automatically lint and format the whole codebase. Before you push new code, please format the codebase using "blue".

‎docs/source/dev/index.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Development
2+
3+
If you want to start developing CACE, please read these pages.
4+
5+
```{toctree}
6+
:glob:
7+
:maxdepth: 2
8+
9+
coding_style
10+
codebase
11+
```

0 commit comments

Comments
 (0)