feat(docs): documentation on sky130spconv (#572)

Author: rahulk29

bins/sky130spconv/Cargo.toml

@@ -2,6 +2,7 @@
 name = "sky130spconv"
 version = "0.0.0"
 edition = "2021"
+readme = "README.md"
 
 [dependencies]
 anyhow = "1"

bins/sky130spconv/README.md

@@ -0,0 +1,79 @@
+# sky130spconv
+
+A command line utility for converting SPICE netlists between
+different flavors ("schemas") of the SKY130 PDK.
+
+## Installation
+
+Clone the [`substrate2`](https://github.com/ucb-substrate/substrate2) repository,
+`cd` to the root of the cloned repository,
+then run the following in your terminal:
+
+```bash
+cd bins/sky130spconv
+cargo install --path .
+```
+
+This will typically install `sky130spconv` to `~/.cargo/bin`.
+Ensure that you have your `~/.cargo/bin` directory added to `$PATH`
+if you wish to invoke this tool from the command line.
+
+## Usage
+
+```
+Aggregate a SPICE netlist (with potentially many include statements) into one file, converting to the desired schema
+
+Usage: sky130spconv [OPTIONS] <INPUT>
+
+Arguments:
+  <INPUT>
+          The input netlist file
+
+Options:
+  -d, --dialect <DIALECT>
+          The SPICE dialect
+          
+          [default: spice]
+
+  -s, --schema <SCHEMA>
+          The desired output SKY130 schema (open, cds, or src-nda)
+          
+          [default: open]
+
+  -o, --out <OUT>
+          The path where the output SPICE file should be saved.
+          
+          The file and its parent directories will be created if necessary. If the file already exists, it will be overwritten.
+          
+          If unspecified, the output will be written to stdout.
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+  -V, --version
+          Print version
+```
+
+## Schemas
+
+In Substrate jargon, schemas are a set of primitives.
+
+This tool supports three schemas:
+* `open`: this schema is compatible with open-source tools (Magic, netgen, etc.)
+* `cds`: this schema is compatible with Cadence tools (Spectre, Pegasus, Quantus, etc.)
+* `src-nda`: this schema is compatible with the NDA PDK decks for Spectre and Calibre.
+
+All three schemas support the same fundamental devices, but they have slight differences.
+For example, `sky130_fd_pr__nfet_01v8` in the `open` schema is equivalent to
+`nfet_01v8` in the `cds` schema and
+`nshort` in the `src-nda` schema.
+Additionally, MOS devices in SPICE netlists of the `src-nda` schema are `M`-class instances,
+whereas they are `X`-class instances in the `cds` and `open` schemas.
+
+This tool takes care of the quirks of each schema,
+allowing you to convert SKY130 netlists between any of the three supported schemas.
+
+## Limitations
+
+This tool is meant for simple SPICE netlists, such as those generated by Substrate.
+It does not support more advanced SPICE features, such as assigning mathematical expressions to subcircuit parameters.

bins/sky130spconv/src/main.rs

@@ -35,7 +35,7 @@ fn main() -> anyhow::Result<()> {
 #[command(
     version,
     about,
-    long_about = "Aggregate a SPICE netlist (with potentially many include statements) into one file"
+    long_about = "Aggregate a SPICE netlist (with potentially many include statements) into one file, converting to the desired schema"
 )]
 pub struct Args {
     /// The SPICE dialect.