From 34abbca0d8d47559fdd384aed27fb33db1b2da12 Mon Sep 17 00:00:00 2001 From: mole99 Date: Fri, 15 Mar 2024 12:30:01 +0100 Subject: [PATCH 1/3] Improve and clarify the docs --- Makefile | 4 + README.md | 81 ++--------- docs/source/about.md | 23 --- docs/source/characterization.md | 107 ++++++++++++++ docs/source/conf.py | 4 +- docs/source/dev/codebase.md | 15 ++ docs/source/dev/coding_style.md | 3 + docs/source/dev/index.md | 11 ++ docs/source/formats/format_description.md | 139 +++++++++---------- docs/source/formats/schematic_description.md | 23 ++- docs/source/index.md | 36 +++++ docs/source/index.rst | 19 --- docs/source/usage/cace_cli.md | 43 ++++++ docs/source/usage/cace_gui.md | 19 +++ docs/source/usage/characterize_help.md | 106 -------------- docs/source/usage/getting_started.md | 83 +---------- docs/source/usage/index.md | 3 +- requirements_docs.txt | 2 + 18 files changed, 341 insertions(+), 380 deletions(-) delete mode 100644 docs/source/about.md create mode 100644 docs/source/characterization.md create mode 100644 docs/source/dev/codebase.md create mode 100644 docs/source/dev/coding_style.md create mode 100644 docs/source/dev/index.md create mode 100644 docs/source/index.md delete mode 100644 docs/source/index.rst create mode 100644 docs/source/usage/cace_cli.md create mode 100644 docs/source/usage/cace_gui.md delete mode 100644 docs/source/usage/characterize_help.md diff --git a/Makefile b/Makefile index fa50617..38e81c1 100644 --- a/Makefile +++ b/Makefile @@ -40,6 +40,10 @@ docs: host-docs: python3 -m http.server --directory ./docs/build/html +.PHONY: auto-docs +auto-docs: + sphinx-autobuild docs/source docs/build/html + .PHONY: clean clean: rm -rf build/ diff --git a/README.md b/README.md index 239cd5e..0cc07c4 100644 --- a/README.md +++ b/README.md @@ -90,80 +90,14 @@ To host the docs, run: make host-docs ``` -> [!NOTE] -> The documentation can be viewed online at [cace.readthedocs.io](https://cace.readthedocs.io/). - -## CACE GUI syntax - - $ cace-gui [path/to/project.txt] - - where optional file project.txt (normally .txt - where is the name of the circuit to be - characterized) is a circuit characterization description in the - file format described below. If a file is not specified, then - the GUI window will come up without content. Click on the button - with text "(no selection)" to find and select a characterization - file to load. The project file may also be in JSON format. - - Normally, cace_gui.py is called from a project top level directory, - while the project.txt file is usually in a subdirectory called - cace/. The project.txt file may be the output file from a CACE - run, which will add results to all of the parameter entries. - - There may be multiple characterization files in a single project - (repository), as a project may contain multiple subcircuits that - may need independent characterization or be able to be used as - standalone circuits, or a project may simply be a collection of - circuits (library) without a specific single top level. - -## CACE command line syntax - - $ cace [options] - - where is a format 4.0 ASCII CACE file - and is the name of the file to write. - - Options may be one of: - - -source=schematic|layout|rcx|all|best - -param= - -force - -json - -keep - -debug - -sequential - -summary - - When run from the top level, this program parses the CACE - characterization file, runs simulations, and outputs a - modified file annotated with characterization results. +To automatically refresh the docs upon changes, run: - With option "-source", restrict characterization to the - specific netlist source, which is either schematic capture, - layout extracted, or full R-C parasitic extracted. If not - specified, then characterization is run on the full R-C - parasitic extracted layout netlist if available, and the - schematic captured netlist if not (option "best"). - - Option "-param=" runs simulations on only - the named electrical or physical parameter. - - Option "-force" forces new regeneration of all netlists. - - Option "-json" generates an output file in JSON format. - - Option "-keep" retains files generated for characterization. - - Option "-noplot" will not generate any graphs. - - Option "-debug" generates additional diagnostic output. - - Option "-sequential" runs simulations sequentially. - - Option "-nosim" does not re-run simulations if the output file exists. - (Warning---does not check if simulations are out of date). +``` +make auto-docs +``` - Option "-summary" prints a summary of results at the end. +> [!NOTE] +> The latest documentation can be viewed online at [cace.readthedocs.io](https://cace.readthedocs.io/). ## Examples @@ -187,4 +121,5 @@ Example circuit repositories: Each of these repositories contains a circuit designed with the SkyWater sky130 process open PDK, and contains schematics, layout, and CACE characterization. -NOTE: These repositories are a work in progress, and may not exist yet or may not have a characterization setup for CACE. +> [!NOTE] +> These repositories are a work in progress, and may not exist yet or may not have a characterization setup for CACE. diff --git a/docs/source/about.md b/docs/source/about.md deleted file mode 100644 index 265db10..0000000 --- a/docs/source/about.md +++ /dev/null @@ -1,23 +0,0 @@ -# About - -CACE is a set of python scripts that take an input file in the -[CACE 4.0 format](formats/format_description) and uses the information found there in combination with CACE-compatible testbenches and analysis scripts to characterize a circuit and to produce a datasheet showing the circuit performance. The CACE python code is the part of CACE which is common to all circuit designs. - -The CACE python code does the following: - -1. Reads the specification input file -2. Determines how many simulations will need to be run for each electrical parameter -3. Generates testbench templates from schematics -4. Substitutes values for all parameters for each simulation -5. Generates the circuit netlist to be tested (either pre-layout or post-layout) -6. Runs simulations in parallel -7. Runs additional scripts to analyze specific performance metrics, as specified in the input file -8. Collates results and generates pass/fail results for all electrical parameters -9. Generates graphs of results as specified in the input file -10. Runs additional measurements for DRC, LVS, and physical dimensions as specified in the input file -11. Collates results and generates pass/fail results for all physical parameters - -By necessity, every circuit will have its own set of testbench -schematics, which no common code system can automatically generate, as every test bench will be specific to the circuit design. Certain general principles apply, and are covered by a number of example circuits available on github; each of these designs has a "cace/" directory containing the specification, testbench schematics, and any additional code needed to analyze the results. - -The CACE input file describes the specification for the circuit in terms of electrical and physical parameters that need to be measured and analyzed. After simulation, a copy of the file is produced containing measured results and providing a pass/fail result for each parameter. diff --git a/docs/source/characterization.md b/docs/source/characterization.md new file mode 100644 index 0000000..432a17e --- /dev/null +++ b/docs/source/characterization.md @@ -0,0 +1,107 @@ +# Characterization + +## Selecting a datasheet + +Start by selecting a datasheet. This step is only necessary if the application is started from the command line. + +%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. + +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. + +%The project design folders are in the `design` subfolder in the user's home directory. + +The challenge datasheet has the name of the project and the file extension `.txt` + +When the JSON file is selected, a full display should be shown with each electrical parameter critical to the challenge, and its status. + +## Characterization + +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. + +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: + +1. "Parameter" --- The name of the electrical or physical parameter. +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. +3. "Min" --- The minimum limit (if any) of the electrical parameter. After simulation, also shows the measured result of the circuit. +4. "Typ" --- The typical value (if any) of the electrical parameter. After simulation, also shows the measured result of the circuit. +5. "Max" --- The maximum limit (if any) of the electrical parameter. After simulation, also shows the measured result of the circuit. +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. +7. "Simulate" --- This is a button that will initiate an ngspice simulation of the electrical parameter. + +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: + +- "Close" --- Quits the characterization tool. If new results have been simulated but not saved, the user will have to respond to a prompt. +- "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. +- "Help" --- Activates this help window. +- "Settings" --- Controls global settings for CACE. + + The available settings are: + + - Print debug output --- + Produce additional output for diagnostic and debugging purposes. + - Force netlist regeneration --- + Require netlists to be regenerated for every simulation. Otherwise, + netlists are only regenerated when the source file (schematic or layout) + is found to post-date the netlist. + - Allow edit of all parameters --- + Allow the use of "Simulate-->Edit", which provides a method for in-app + editing and copying of parameters (note that the characterization file + itself may always be edited). + - Simulate single-threaded --- + Normally all simulations are done multi-threaded (with low priority). + Selecting this option forces simulations to run one at a time. + - Keep simulation files --- + Normally simulation files are removed after simulation and only the + results are kept. This option forces the files to remain after + simulation. + - Do not create plot files --- + Normally plot files are generated for each plot. If this option is + selected, plots may be viewed in-app but no file is generated. + - Log simulation output --- + Copy all simulation output into a log file. + + +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: + +- **Schematic Capture**: Simulations are done from schematic +- **Layout Extracted**: Simulations are done from layout without parasitics +- **R-C Extracted**: Simulations are done from layout with parasitics + +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. + +### Generating a netlist + + +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. + +### Simulation + +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: + + Run + Stop + Edit + Copy + +Left-click on the selection to initiate it. + +- **Run:** +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)`. + +- **Stop:** +If a testbench is running, then selecting "Stop" will end the simulations. + +- **Edit:** +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. + +- **Copy:** +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. + +### Results + +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. + +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. + +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. + diff --git a/docs/source/conf.py b/docs/source/conf.py index 002e787..7357e8a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -33,6 +33,6 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -html_theme = 'alabaster' +html_title = "CACE Documentation" +html_theme = 'furo' html_static_path = ['_static'] diff --git a/docs/source/dev/codebase.md b/docs/source/dev/codebase.md new file mode 100644 index 0000000..1919079 --- /dev/null +++ b/docs/source/dev/codebase.md @@ -0,0 +1,15 @@ +# Codebase + +TODO information about how the codebase is structured + +``` +├── cace +│   ├── cace_cli.py +│   ├── cace_gui.py +│   ├── common +│   ├── doc +│   ├── gui +│   ├── __init__.py +│   ├── __main__.py +│   └── __version__.py +``` diff --git a/docs/source/dev/coding_style.md b/docs/source/dev/coding_style.md new file mode 100644 index 0000000..df30d6d --- /dev/null +++ b/docs/source/dev/coding_style.md @@ -0,0 +1,3 @@ +# Coding Style + +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". diff --git a/docs/source/dev/index.md b/docs/source/dev/index.md new file mode 100644 index 0000000..8b9c836 --- /dev/null +++ b/docs/source/dev/index.md @@ -0,0 +1,11 @@ +# Development + +If you want to start developing CACE, please read these pages. + +```{toctree} +:glob: +:maxdepth: 2 + +coding_style +codebase +``` diff --git a/docs/source/formats/format_description.md b/docs/source/formats/format_description.md index 933ab45..1c85d51 100644 --- a/docs/source/formats/format_description.md +++ b/docs/source/formats/format_description.md @@ -1,9 +1,9 @@ -# The CACE version 4.0 format description +# Version 4.0 format description ## NOTE CACE files prior to version 4 (November 2023) are in JSON format -and can be run through the script cace_compat.py to produce a +and can be run through the script `cace_compat.py` to produce a version 4.0 text format. ## Syntax @@ -11,7 +11,7 @@ version 4.0 text format. Every line is either a key:value pair or a key:dictionary or a key:list, or a blank line, or a comment. -A comment is any line beginning with "#". +A comment is any line beginning with `#`. A blank line is any line consisting only of spaces, tabs, and a newline. @@ -20,12 +20,12 @@ For key:value, the format is : 1. Spaces outside of and are optional. -2. A keyword must be alphanumeric only; it cannot contain spaces. +2. A keyword must be alphanumeric only; it cannot contain spaces. 3. The value may not begin with a space character but may contain space - characters. If the value is interpreted as a string, the spaces are - taken literally. If the value has multiple parts, then the spaces + characters. If the value is interpreted as a string, the spaces are + taken literally. If the value has multiple parts, then the spaces (or tabs) separate the entries. -4. The key: value assignment ends with a newline. The may be +4. The key: value assignment ends with a newline. The may be made multi-line by ending lines with backslash-newline. For key:dictionary, the format is @@ -54,14 +54,15 @@ For key:list, the format is } 1. Each is a dictionary as described above (one or more newline- - separated key:value pairs, key:dictionary, or nested key:list). + separated key:value pairs, key:dictionary, or nested key:list). 2. The "+" may be on its own line or precede the first dictionary keyword, separated by space. A blank line preceding the "+" is optional. 3. Each key within a dictionary must be unique, but different dictionaries in the list will contain the same keywords. -All entries in the file are from the ASCII character set. Non-ASCII characters +All entries in the file are from the ASCII character set. Non-ASCII characters can be handled with known keywords in braces, such as (but not limited to): + {degrees} {micro} {sigma} @@ -70,18 +71,16 @@ can be handled with known keywords in braces, such as (but not limited to): {sqrt} Dictionaries are generally searched for known keys but unknown keys are not -flagged. Therefore comments and other non-critical information can be put -in otherwise unused dictionary keys. The key "note" is considered the +flagged. Therefore comments and other non-critical information can be put +in otherwise unused dictionary keys. The key "note" is considered the proper way to pass comments about the contents of a specific dictionary; these can end up as notes in a formatted datasheet output. -. -4. -CACE format description: Characterization file contents ------------------------------------------------------------------ -The top level file itself is a dictionary of :, :, -or : entries. The top-level dictionary does not have a key and is -not delimited by braces. The file starts with the first key in the dictionary. +## Characterization file contents + +The top level file itself is a dictionary of ``:``, ``:``, +or ``:`` entries. The top-level dictionary does not have a key and is +not delimited by braces. The file starts with the first key in the dictionary. Top-level dictionary: @@ -109,13 +108,12 @@ Top-level dictionary: physical_parameters: List of specified physical parameters, for spec and measurement (see below). -The order of entries is not meaningful except that "default_conditions" must be -declared before "electrical_parameters", since the electrical parameters will +The order of entries is not meaningful except that `default_conditions` must be +declared before `electrical_parameters`, since the electrical parameters will take default conditions before applying specific conditions. -4.1 -Authorship --------------- +### Authorship + "authorship" dictionary: designer: @@ -136,9 +134,8 @@ Authorship license: A known license type, such as "Apache 2.0". -4.2 -Paths --------------- +### Paths + "paths" dictionary: documentation: @@ -183,10 +180,10 @@ Paths This is the location of the project and the root of all the other paths in this dictionary. It is automatically inserted by CACE. -4.3 -Dependencies --------------- +### Dependencies + "dependencies" list: + Each entry in the list is a project on which the design under test is dependent. Each entry lists a dictionary with the following dictionary entries: @@ -208,9 +205,8 @@ Dependencies project. TBD: Various values that define actions such as updating the repository. -4.4 -Pins --------------- +### Pins + "pins" dictionary: name: @@ -240,9 +236,8 @@ Pins another pin; and may be referenced to another pin with an offset (e.g., "vdd + 0.3"). -4.5 -Default conditions --------------- +### Default conditions + "default_conditions" dictionary: name: @@ -291,9 +286,8 @@ Default conditions enumeration or multiplicative values for logarithmic enumeration. -4.6 -Parameter conditions --------------- +### Parameter conditions + "conditions" dictionary: The "conditions" dictionary entries are the same as the @@ -304,9 +298,8 @@ Parameter conditions condition name exists in the netlist to be simulated or the file to be evaluated (see "simulate" and "measure" entries). -4.7 -Electrical conditions --------------- +### Electrical conditions + "electrical_parameters" dictionary: name: @@ -367,9 +360,8 @@ Electrical conditions This entry is automatically generated by CACE and enumerates all of the testbenches to be simulated and evaluated, and the results. -4.8 -Specification --------------- +### Specification + "spec" dictionary: minimum: |any [fail] [-] @@ -400,10 +392,10 @@ Specification spec. If - is specified, then it overrides the default calculation of "maximum-below" -4.9 -Results --------------- +### Results + "results" dictionary: + A set of results that is the measurement counterpart to the "spec" dictionary for an electrical parameter. The difference is that it includes a key "name" that specifies the netlist @@ -420,10 +412,10 @@ Results typical: [pass|fail] maximum: [pass|fail] -4.10 -Variables --------------- +### Variables + "variables" list: + A variable is any property that affects the electrical parameter result but which is not a condition. A variable may be used in a plot to graph the result vs. something that is not a condition. @@ -447,9 +439,8 @@ Variables This is the unit that will be displayed after the display string. -4.11 -Simulation information --------------- +### Simulation information + "simulate" dictionary: tool: @@ -491,10 +482,10 @@ Simulation information runs over all the specified conditions before passing the result to the first "measure" handler. -4.12 -Measurement information --------------- +### Measurement information + "measure" dictionary: + Additional entries are tools that operate on the output of the simulator to produce the final results for the datasheet. They may be number-crunching tools like "octave" for compute- @@ -524,10 +515,10 @@ Measurement information the output is passed in stdout, and is a list of "result" values that replaces the existing "result" values in the testbench. -4.13 -Internal calculations --------------- +### Internal calculations + Internal calculation (measurement) methods: + time: remove: rebase: @@ -543,10 +534,10 @@ Internal calculation (measurement) methods: stabletime: inside: -4.14 -Plots --------------- +### Plots + "plot" dictionary: + filename: Name of a graphic format and filename to use for graph output. Plots are done with python matplotlib, so it must be a format @@ -574,9 +565,8 @@ produced by plot-generating tools may contain vectors not in the listed conditions for the electrical parameter, such as TIME for time or TRACE for the result. -4.15 -Testbenches --------------- +### Testbenches + "testbenches" dictionary: filename: @@ -602,9 +592,8 @@ Testbenches the format, and entries must match the order of the entries in the format. -4.16 -Physical parameters --------------- +### Physical parameters + "physical_parameters" list: The physical parameters list has the same keywords as the @@ -620,10 +609,10 @@ Physical parameters and takes the place of "simulate" and "measure" for electrical parameters (see below). -4.17 -Evaluation information --------------- +### Evaluation information + "evaluate" dictionary: + The "evaluate" dictionary is unique to the physical_parameters dictionaries. It describes how to obtain a specific physical or other non-electrical parameter, such as cell size or number @@ -643,10 +632,10 @@ Evaluation information by "tool", if the tool is not an internal procedure. The file should exist in the testbench directory. -4.18 -Internal physical parameter tools --------------- +### Internal physical parameter tools + Internal physical parameter (evaluation) tools: + cace_drc: Returns the number of DRC errors found in the design. The result is generally useful only as being zero or non-zero. @@ -659,4 +648,4 @@ Internal physical parameter (evaluation) tools: cace_width: Returns the width of the layout. - cace_length: Returns the length of the layout. \ No newline at end of file + cace_length: Returns the length of the layout. diff --git a/docs/source/formats/schematic_description.md b/docs/source/formats/schematic_description.md index babcf29..442ef0e 100644 --- a/docs/source/formats/schematic_description.md +++ b/docs/source/formats/schematic_description.md @@ -1,22 +1,23 @@ -# The CACE version 4.0 schematic description +# Version 4.0 schematic description Schematics are drawn normally but statements can have special syntax that is substituted by CACE. The syntax follows three essential rules: -(1) Condition and variable names in the project specification file +1. Condition and variable names in the project specification file are written in the schematic in braces, so "temperature" in the project file is "{temperature}" in the schematic. -(2) Expressions involving equations using condition and variable +2. Expressions involving equations using condition and variable names are written in the schematic in brackets, so, for example, half of condition vdd would be written "[{vdd} / 2]". These expressions are evaluated in python, so any python expression that evaluates to a valid result may appear inside the brackets. -(3) There are a handful of reserved variable names that are automatically +3. There are a handful of reserved variable names that are automatically substituted by CACE if they appear in the schematic: {PIN|pin_name|net_name} + Used in symbol descriptions. Indicates a pin of a subcircuit including both the pin name in the subcircuit and the name of the net connecting to the pin. This allows a subcircuit @@ -24,10 +25,12 @@ that is substituted by CACE. The syntax follows three essential rules: determine the pin order and output the correct syntax. {FUNCTIONAL|ip_name} + Indicates that the subcircuit ip_name will be replaced with its functional view (xspice or verilog) for simulation. {cond=value} + For any condition cond, this form indicates that "value" is to be subsituted for the condition if the condition is not declared in the CACE project file. @@ -36,6 +39,7 @@ that is substituted by CACE. The syntax follows three essential rules: {cond|maximum} {cond|stepsize} {cond|steps} + Instead of substituting one value for a condition, a value over all conditions is substituted, including the maximum over all conditions, minimum over all conditions, the @@ -46,35 +50,44 @@ that is substituted by CACE. The syntax follows three essential rules: not iterated over multiple netlists. {N} + This is substituted with the simulation index. Most often used as a filename suffix for the output data file. {filename} + The root name of the schematic file. {simpath} + The name of the path to simulation files. {random} + A random integer number. {DUT_path} + The full path to the DUT subcircuit definition netlist. {include_DUT} + A shorthand that inserts a ".include" statement with the DUT path, or else in the case of a functional block, in-lines the functional definition of the block. {DUT_call} + The pin list from the DUT schematic {DUT_name} + The name of the DUT subcircuit {PDK_ROOT} + The path to the directory containing the PDK {PDK} + The name of the PDK -. diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 0000000..65bc97a --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,36 @@ +# The Documentation for CACE + +## Circuit Automatic Characterization Engine + +**! Please note that this documentation is still a work in progress !** + +CACE is a set of python scripts that take an input file in the [CACE 4.0 format](formats/format_description) and uses the information found there in combination with CACE-compatible testbenches and analysis scripts to characterize a circuit and to produce a datasheet showing the circuit performance. The CACE python code is the part of CACE which is common to all circuit designs. + +The CACE python code does the following: + +1. Reads the specification input file +2. Determines how many simulations will need to be run for each electrical parameter +3. Generates testbench templates from schematics +4. Substitutes values for all parameters for each simulation +5. Generates the circuit netlist to be tested (either pre-layout or post-layout) +6. Runs simulations in parallel +7. Runs additional scripts to analyze specific performance metrics, as specified in the input file +8. Collates results and generates pass/fail results for all electrical parameters +9. Generates graphs of results as specified in the input file +10. Runs additional measurements for DRC, LVS, and physical dimensions as specified in the input file +11. Collates results and generates pass/fail results for all physical parameters + +By necessity, every circuit will have its own set of testbench schematics, which no common code system can automatically generate, as every test bench will be specific to the circuit design. Certain general principles apply, and are covered by a number of example circuits available on github; each of these designs has a `cace/` directory containing the specification, testbench schematics, and any additional code needed to analyze the results. + +The CACE input file describes the specification for the circuit in terms of electrical and physical parameters that need to be measured and analyzed. After simulation, a copy of the file is produced containing measured results and providing a pass/fail result for each parameter. + +```{toctree} +:glob: +:hidden: +:maxdepth: 3 + +usage/index +formats/index +characterization +dev/index +``` diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 6248dc2..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -Welcome to CACE's documentation! -================================ - -Please note that this documentation is still a work in progress. - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - about - usage/index - formats/index - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/source/usage/cace_cli.md b/docs/source/usage/cace_cli.md new file mode 100644 index 0000000..1f42e3d --- /dev/null +++ b/docs/source/usage/cace_cli.md @@ -0,0 +1,43 @@ +# Command Line Interface + +CACE can be run directly from your command line: + + $ cace [options] + +Where `` is a format 4.0 ASCII CACE file and `` is the name of the file to write. +Options may be one of: + + -source=schematic|layout|rcx|all|best + -param= + -force + -json + -keep + -debug + -sequential + -summary + +When run from the top level, this program parses the CACE characterization file, runs simulations, and outputs a modified file annotated with characterization results. + +With option `-source`, restrict characterization to the specific netlist source, which is either schematic capture, +layout extracted, or full R-C parasitic extracted. If not specified, then characterization is run on the full R-C +parasitic extracted layout netlist if available, and the schematic captured netlist if not (option "best"). + + Option "-param=" runs simulations on only + the named electrical or physical parameter. + + Option "-force" forces new regeneration of all netlists. + + Option "-json" generates an output file in JSON format. + + Option "-keep" retains files generated for characterization. + + Option "-noplot" will not generate any graphs. + + Option "-debug" generates additional diagnostic output. + + Option "-sequential" runs simulations sequentially. + + Option "-nosim" does not re-run simulations if the output file exists. + (Warning---does not check if simulations are out of date). + + Option "-summary" prints a summary of results at the end. diff --git a/docs/source/usage/cace_gui.md b/docs/source/usage/cace_gui.md new file mode 100644 index 0000000..b56e568 --- /dev/null +++ b/docs/source/usage/cace_gui.md @@ -0,0 +1,19 @@ +# Graphical User Interface + +CACE has also support for a graphical user interface, started via: + + $ cace-gui [path/to/project.txt] + +Where optional file `project.txt` (normally `.txt` where `` is the name of the circuit to be +characterized) is a circuit characterization description in the file format described below. If a file is not specified, then +the GUI window will come up without content. Click on the button with text `(no selection)` to find and select a characterization +file to load. The project file may also be in JSON format. + +Normally, `cace_gui.py` is called from a project top level directory, while the project.txt file is usually in a subdirectory called +cace/. The `project.txt` file may be the output file from a CACE run, which will add results to all of the parameter entries. + +There may be multiple characterization files in a single project (repository), as a project may contain multiple subcircuits that +may need independent characterization or be able to be used as standalone circuits, or a project may simply be a collection of +circuits (library) without a specific single top level. + +![CACE GUI Screenshot](../_static/cace_screenshot.png) diff --git a/docs/source/usage/characterize_help.md b/docs/source/usage/characterize_help.md deleted file mode 100644 index a79e7b4..0000000 --- a/docs/source/usage/characterize_help.md +++ /dev/null @@ -1,106 +0,0 @@ -# Characterize Help - -1. -Selecting a datasheet -------- -Start by selecting a datasheet. This step is only necessary if the application is started from the command line. 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. - -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 JSON (.json) file. A challenge datasheet should be found in the design folder for each accepted challenge. The project design folders are in the 'design' subfolder in the user's home directory. The challenge datasheet has the name of the project and the file extension '.json'. - -When the JSON file is selected, a full display should be shown with each electrical parameter critical to the challenge, and its status. -. -2. -Characterization ------------- -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. - -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: - -(1) "Parameter" --- The name of the electrical or physical parameter. -(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. -(3) "Min" --- The minimum limit (if any) of the electrical parameter. After simulation, also shows the measured result of the circuit. -(4) "Typ" --- The typical value (if any) of the electrical parameter. After simulation, also shows the measured result of the circuit. -(5) "Max" --- The maximum limit (if any) of the electrical parameter. After simulation, also shows the measured result of the circuit. -(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. -(7) "Simulate" --- This is a button that will initiate an ngspice simulation of the electrical parameter. - -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: - -"Close" --- Quits the characterization tool. If new results have been simulated but not saved, the user will have to respond to a prompt. - -"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. - -"Help" --- Activates this help window. - -"Settings" --- Controls global settings for CACE. The available settings are: - - Print debug output --- - Produce additional output for diagnostic and debugging purposes. - Force netlist regeneration --- - Require netlists to be regenerated for every simulation. Otherwise, - netlists are only regenerated when the source file (schematic or layout) - is found to post-date the netlist. - Allow edit of all parameters --- - Allow the use of "Simulate-->Edit", which provides a method for in-app - editing and copying of parameters (note that the characterization file - itself may always be edited). - Simulate single-threaded --- - Normally all simulations are done multi-threaded (with low priority). - Selecting this option forces simulations to run one at a time. - Keep simulation files --- - Normally simulation files are removed after simulation and only the - results are kept. This option forces the files to remain after - simulation. - Do not create plot files --- - Normally plot files are generated for each plot. If this option is - selected, plots may be viewed in-app but no file is generated. - Log simulation output --- - Copy all simulation output into a log file. - - -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: - - Schematic Capture: Simulations are done from schematic - Layout Extracted: Simulations are done from layout without parasitics - R-C Extracted: Simulations are done from layout with parasitics - -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. - -2.1 -Generating a netlist -------- -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. - -2.2 -Simulation -------- -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: - - Run - Stop - Edit - Copy - -Left-click on the selection to initiate it. - -Run: -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)'. - -Stop: -If a testbench is running, then selecting "Stop" will end the simulations. - -Edit: -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. - -Copy: -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. - -2.3 -Results --------- -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. - -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. - -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. -. diff --git a/docs/source/usage/getting_started.md b/docs/source/usage/getting_started.md index d8c2566..f63ab9d 100644 --- a/docs/source/usage/getting_started.md +++ b/docs/source/usage/getting_started.md @@ -76,86 +76,15 @@ To host the docs, run: make host-docs ``` -> [!NOTE] -> The documentation can be viewed online at [cace.readthedocs.io](https://cace.readthedocs.io/). - -## CACE GUI syntax - - $ cace-gui [path/to/project.txt] - - where optional file project.txt (normally .txt - where is the name of the circuit to be - characterized) is a circuit characterization description in the - file format described below. If a file is not specified, then - the GUI window will come up without content. Click on the button - with text "(no selection)" to find and select a characterization - file to load. The project file may also be in JSON format. - - Normally, cace_gui.py is called from a project top level directory, - while the project.txt file is usually in a subdirectory called - cace/. The project.txt file may be the output file from a CACE - run, which will add results to all of the parameter entries. - - There may be multiple characterization files in a single project - (repository), as a project may contain multiple subcircuits that - may need independent characterization or be able to be used as - standalone circuits, or a project may simply be a collection of - circuits (library) without a specific single top level. - -## CACE command line syntax - - $ cace [options] - - where is a format 4.0 ASCII CACE file - and is the name of the file to write. - - Options may be one of: - - -source=schematic|layout|rcx|all|best - -param= - -force - -json - -keep - -debug - -sequential - -summary - - When run from the top level, this program parses the CACE - characterization file, runs simulations, and outputs a - modified file annotated with characterization results. - - With option "-source", restrict characterization to the - specific netlist source, which is either schematic capture, - layout extracted, or full R-C parasitic extracted. If not - specified, then characterization is run on the full R-C - parasitic extracted layout netlist if available, and the - schematic captured netlist if not (option "best"). - - Option "-param=" runs simulations on only - the named electrical or physical parameter. - - Option "-force" forces new regeneration of all netlists. - - Option "-json" generates an output file in JSON format. - - Option "-keep" retains files generated for characterization. - - Option "-noplot" will not generate any graphs. - - Option "-debug" generates additional diagnostic output. - - Option "-sequential" runs simulations sequentially. - - Option "-nosim" does not re-run simulations if the output file exists. - (Warning---does not check if simulations are out of date). - - Option "-summary" prints a summary of results at the end. +> [!NOTE] +> The latest documentation can be viewed online at [cace.readthedocs.io](https://cace.readthedocs.io/). ## Examples The following repositories contain example circuit designs, each having a "cace/" subdirectory with a specification input file in the format described below, and a set of testbench schematics which are used by CACE to measure all specified electrical and physical parameters, generate results, and analyze them to determine circuit performance over corners. -(NOTE: Example repositories, like CACE itself, are currently a work in progress.) +> [!NOTE] +> Example repositories, like CACE itself, are currently a work in progress. All repositories are rooted at: [https://github.com/RTimothyEdwards/](https://github.com/RTimothyEdwards/). @@ -172,4 +101,6 @@ Example circuit repositories: Each of these repositories contains a circuit designed with the SkyWater sky130 process open PDK, and contains schematics, layout, and CACE characterization. -NOTE: These repositories are a work in progress, and may not exist yet or may not have a characterization setup for CACE. +> [!NOTE] +> These repositories are a work in progress, and may not exist yet or may not have a characterization setup for CACE. + diff --git a/docs/source/usage/index.md b/docs/source/usage/index.md index c15c9a1..7b4be17 100644 --- a/docs/source/usage/index.md +++ b/docs/source/usage/index.md @@ -7,5 +7,6 @@ This pages gives you an overview of how to use CACE. :maxdepth: 2 getting_started -characterize_help +cace_cli +cace_gui ``` diff --git a/requirements_docs.txt b/requirements_docs.txt index f475742..d4da308 100644 --- a/requirements_docs.txt +++ b/requirements_docs.txt @@ -1,2 +1,4 @@ sphinx>=7.1.0 myst-parser>=2.0.0,<3 +furo>=2023.8.19 +sphinx-autobuild>=2021.3.14 From b7ad406180f79c3f90e891b74dde96e7a85f6332 Mon Sep 17 00:00:00 2001 From: mole99 Date: Fri, 15 Mar 2024 12:33:38 +0100 Subject: [PATCH 2/3] Increment version --- cace/__version__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cace/__version__.py b/cace/__version__.py index 515faab..1a6367e 100644 --- a/cace/__version__.py +++ b/cace/__version__.py @@ -11,7 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -__version__ = '2.1.7' +__version__ = '2.1.8' if __name__ == '__main__': print(__version__, end='') From 9d0b276ab8aa483e95e2e6a7c969cdbeed50edc6 Mon Sep 17 00:00:00 2001 From: mole99 Date: Fri, 15 Mar 2024 12:38:18 +0100 Subject: [PATCH 3/3] Reformat --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 7357e8a..32feaa0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -33,6 +33,6 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_title = "CACE Documentation" +html_title = 'CACE Documentation' html_theme = 'furo' html_static_path = ['_static']