readme: basic documentation

TheMightyDuckOfDoom · May 10, 2024 · caf7955 · caf7955
1 parent e8e73a6
commit caf7955
Show file tree

Hide file tree

Showing 3 changed files with 115 additions and 53 deletions.
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -31,8 +31,8 @@ jobs:
         name: Checkout
         uses: actions/checkout@v4
       -
-        name: Run yamllint
-        run: make yamllint
+        name: Lint YML files
+        run: make lint-yaml
 
   lint-tcl:
     runs-on: self-hosted
@@ -41,8 +41,8 @@ jobs:
         name: Checkout
         uses: actions/checkout@v4
       -
-        name: Run tclint
-        run: make tclint
+        name: Lint TCL files
+        run: make lint-tcl
 
   lint-python:
     runs-on: self-hosted
@@ -51,10 +51,10 @@ jobs:
         name: Checkout
         uses: actions/checkout@v4
       -
-        name: Run pylint
+        name: Lint python files
         run: |
           set +e
-          make pylint
+          make lint-python
 
   lint-json:
     runs-on: self-hosted
@@ -63,8 +63,8 @@ jobs:
         name: Checkout
         uses: actions/checkout@v4
       -
-        name: Run jsonlint
-        run: make jsonlint
+        name: Lint JSON files
+        run: make lint-json
 
   lint-verilog:
     runs-on: self-hosted
@@ -73,8 +73,8 @@ jobs:
         name: Checkout
         uses: actions/checkout@v4
       -
-        name: Run veriloglint
-        run: make veriloglint
+        name: Lint verilog files
+        run: make lint-verilog
 
   lint-markdown:
     runs-on: self-hosted
@@ -97,7 +97,7 @@ jobs:
         run: make pdk/.pdk
       -
         name: Create Merge Cells
-        run: make gen_pdk
+        run: make gen-pdk
 
   pdk-lint-tcl:
     runs-on: self-hosted
@@ -108,10 +108,10 @@ jobs:
         uses: actions/checkout@v4
       -
         name: Generate PDK
-        run: make gen_pdk
+        run: make gen-pdk
       -
-        name: Run tclint
-        run: make tclint
+        name: Lint TCL files
+        run: make lint-tcl
 
   pdk-lint-verilog:
     runs-on: self-hosted
@@ -122,7 +122,7 @@ jobs:
         uses: actions/checkout@v4
       -
         name: Generate PDK
-        run: make gen_pdk
+        run: make gen-pdk
       -
-        name: Run veriloglint
-        run: make veriloglint
+        name: Lint verilog files
+        run: make lint-verilog
diff --git a/Makefile b/Makefile
@@ -31,9 +31,9 @@ VERILOG_FILE_NAME := $(basename $(VERILOG_FILES))
 SVERILOG_FILE_NAME := $(basename $(SVERILOG_FILES))
 MARKDOWN_FILE_NAME := $(basename $(MARKDOWN_FILES))
 
-.PHONY: all clean lint yamllint tclint pylint jsonlint veriloglint markdownlint
+.PHONY: all clean lint-all lint-yaml lint-tcl lint-python lint-json lint-verilog lint-markdown
 
-all: gen_pdk
+all: gen-pdk
 
 out/testboard.v: examples/testboard.v
 	cp $^ $@
@@ -66,9 +66,9 @@ openroad/out: config/merge_cells/*.v pdk/.pdk
 
 openroad-setup: openroad/out
 
-gen_pdk: pdk/.pdk openroad/out
+gen-pdk: pdk/.pdk openroad/out
 
-synth: gen_pdk
+synth: gen-pdk
 	mkdir -p out
 	mkdir -p yosys/reports
 	echo "set TOP "${PROJECT}"\nset SRC "${SRC}"\nset CORNER_GROUP "${CORNER_GROUP}"\nset PROCESS "${SYNTH_PROCESS}"\nsource yosys/synth.tcl" | yosys -C
@@ -85,27 +85,27 @@ dft:
 	cd out/dft && cat ../../verilog_models/DS9808.sv >> cells.sv
 	cd out/dft && fault -c cells.sv -v 1 -r 1 -m 95 --ceiling 1 --clock clk_i ${PROJECT}.cut.v
 
-chip: gen_pdk
+chip: gen-pdk
 	cd openroad && (echo "set design_name ${PROJECT}\nset CORNER_GROUP "${CORNER_GROUP}"\nset PCB_WIDTH "${PCB_WIDTH}"\nset PCB_HEIGHT "${PCB_HEIGHT}"\nset SCAN_CHAIN "${SCAN_CHAIN}"\nsource chip.tcl" | openroad -threads max -log openroad.log)
 
-chip_gui: gen_pdk
+chip_gui: gen-pdk
 	echo "set design_name ${PROJECT}\nset CORNER_GROUP "${CORNER_GROUP}"\nset PCB_WIDTH "${PCB_WIDTH}"\nset PCB_HEIGHT "${PCB_HEIGHT}"\nset SCAN_CHAIN "${SCAN_CHAIN}"\nsource chip.tcl" > openroad/start.tcl
 	cd openroad && openroad -threads max -gui -log openroad.log start.tcl
 
-pcb: gen_pdk
+pcb: gen-pdk
 	python3 utils/def2pcb.py openroad/out/${PROJECT}.final.def openroad/out/merge_cell_*.def
 
 open_pcb:
 	pcbnew out/${PROJECT}.final.kicad_pcb
 
-lint: yamllint tclint jsonlint veriloglint pylint markdownlint
+lint-all: lint-yaml lint-tcl lint-python lint-json lint-verilog lint-markdown
 
-yamllint: $(YAML_FILE_NAME)
-tclint: $(TCL_FILE_NAME)
-pylint: $(PY_FILE_NAME)
-jsonlint: $(JSON_FILE_NAME)
-veriloglint: $(VERILOG_FILE_NAME) $(SVERILOG_FILE_NAME)
-markdownlint: $(MARKDOWN_FILE_NAME)
+lint-yaml: $(YAML_FILE_NAME)
+lint-tcl: $(TCL_FILE_NAME)
+lint-python: $(PY_FILE_NAME)
+lint-json: $(JSON_FILE_NAME)
+lint-verilog: $(VERILOG_FILE_NAME) $(SVERILOG_FILE_NAME)
+lint-markdown: $(MARKDOWN_FILE_NAME)
 
 $(YAML_FILE_NAME): $(YAML_FILES)
 	yamllint --no-warnings $@.yml

diff --git a/Readme.md b/Readme.md
@@ -18,43 +18,105 @@ Liberty74 makes use of the following open-source projects:
 
 ### Synthesis and Layout
 
-- [Yosys - synthesis](https://https://github.com/YosysHQ/yosys)
-- [OpenROAD - layout](https://github.com/The-OpenROAD-Project/OpenROAD)
-- [KiCad - pcb](https://www.kicad.org/)
-- [Basilisk - synthesis strategy](https://github.com/pulp-platform/cheshire-ihp130-o/tree/basilisk-dev)
+- [Yosys](https://https://github.com/YosysHQ/yosys): Synthesis
+- [OpenROAD](https://github.com/The-OpenROAD-Project/OpenROAD): Layout
+- [KiCad](https://www.kicad.org/): PCB
+- [Basilisk](https://github.com/pulp-platform/cheshire-ihp130-o/tree/basilisk-dev):
+ Synthesis Strategy
 
 ### PDK Generator and other utilities
 
-- [lef def parser library - modified](https://github.com/trimcao/lef-parser)
-- [KiUtils - KiCad file parser library](https://pypi.org/project/kiutils/)
-- [Mako - template library](https://pypi.org/project/Mako/)
-- [Bender - hw dependency managment tool](https://github.com/pulp-platform/bender)
+- [lef def parser library](https://github.com/trimcao/lef-parser): modified,
+ see [`utils/lef_def_parser`](utils/lef_def_parser/)
+- [KiUtils](https://pypi.org/project/kiutils/): KiCad File Parser Library
+- [Mako](https://pypi.org/project/Mako/): Template Library
+- [Bender](https://github.com/pulp-platform/bender): HW Dependency Manager
 
 ### Linters
 
-- [tcllint - tcl lint tool](https://pypi.org/project/tclint/)
-- [pylint - python lint tool](https://pypi.org/project/pylint/)
-- [yamllint - yml lint tool](https://pypi.org/project/yamllint/)
-- [mdl - markdown lint tool](https://github.com/markdownlint/markdownlint)
-- [Verible - verilog lint tool](https://github.com/chipsalliance/verible)
-- [JSON lint - json lint tool](https://github.com/zaach/jsonlint)
-- [pulp actions - ci license lint](https://github.com/pulp-platform/pulp-actions)
+- [tcllint](https://pypi.org/project/tclint/): TCL Linter
+- [pylint](https://pypi.org/project/pylint/): Python Linter
+- [yamllint](https://pypi.org/project/yamllint/): YAML Linter
+- [mdl](https://github.com/markdownlint/markdownlint): Markdown Linter
+- [Verible](https://github.com/chipsalliance/verible): Verilog Linter
+- [JSON lint](https://github.com/zaach/jsonlint): JSON Linter
+- [pulp actions](https://github.com/pulp-platform/pulp-actions): CI License Linter
 
-## Documentation
+## Documentation - Basic Usage
 
-TODO
+### Generate PDK
+
+To generate the PDK files use:
+
+```bash
+make gen-pdk
+```
+
+### Synthesis
+
+To synthesize your RTL into a netlist use:
+
+```bash
+make synth
+```
+
+### Layout
+
+To layout your design use:
+
+```bash
+make chip
+```
+
+### Convert to PDK
+
+To convert your layout to a KiCad-PCB use:
+
+```bash
+make pcb
+```
+
+### Linting
+
+To lint all languages use:
+
+```bash
+make lint-all
+```
+
+You can also lint each language seperately:
+
+```bash
+make lint-yaml
+make lint-tcl
+make lint-python
+make lint-json
+make lint-verilog
+make lint-markdown
+```
+
+### Clean
+
+To clean use:
+
+```bash
+make clean
+```
 
 ## License
 
 Liberty74 is released under a permissive license.\
 All hardware sources and tool scripts are licensed under Solderpad v0.51 (SHL-0.51)
  see [`LICENSE`](LICENSE)\
-All software sources are licensed under Apache 2.0 (Apache-2.0) see [`Apache-2.0`](https://opensource.org/license/apache-2-0)\
-Exception: `utils/lef_def_parser` is licensed under MIT (MIT) see [`utils/lef_der_parser`]
-(utils/lef_def_parser/),\
- Original Author and Repo [&copy; Tri Minh Cao](https://github.com/trimcao/lef-parser)
+All software sources are licensed under Apache 2.0 (Apache-2.0) see [`Apache-2.0`](https://opensource.org/license/apache-2-0)
+
+Exceptions:
+
+- `utils/lef_def_parser` is licensed under MIT (MIT) see [`utils/lef_der_parser`](utils/lef_def_parser/)\
+  Original Author &copy;Tri Minh Cao, see [https://github.com/trimcao/lef-parser](https://github.com/trimcao/lef-parser)
 
 ## Contributing
 
-We are happy to accept pull requests and issues from any contributors. See [`CONTRIBUTING.md`](CONTRIBUTING.md)
+We are happy to accept pull requests and issues from any contributors.\
+See [`CONTRIBUTING.md`](CONTRIBUTING.md)
 for additional information.