From e1154144d68bff231c03665f31076154092e6213 Mon Sep 17 00:00:00 2001
From: annoyatron255 <annoyatron255@gmail.com>
Date: Mon, 6 May 2024 01:13:41 -0500
Subject: [PATCH] Add README.md

---
 README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bf3b121
--- /dev/null
+++ b/README.md
@@ -0,0 +1,51 @@
+_yosys4gal_: Verilog Flow for the GAL16V8 and GAL22V10
+======================================================
+
+A Verilog flow for GAL16V8 and GAL22V10 logic chips
+(and pin-compatible alternatives like the ATF16V8 and ATF22V10).
+It leverages [Yosys](github.com/YosysHQ/yosys) and [Galette](github.com/simon-frankau/galette).
+
+Usage
+-----
+To synthesize a Verilog file:
+```
+./synth_gal.tcl <VERILOG_FILE> [CHIP]
+```
+Where `[CHIP]` is either `GAL16V8` (default) or `GAL22V10`. The synthesized
+JSON netlist will be put in `output/`.
+
+To fit the synthesized design and generate the JEDEC file used for programming,
+first build the Rust compiler `ver2gal` (see the `compiler/` directory) and run:
+```
+./ver2gal synth <JSON NETLIST> <PCF_CONSTRAINTS> --chip <CHIP>
+```
+Where `<CHIP>` is either `gal16v8` or `gal22v10`. The generate JEDEC file will
+be generated in the current directory as `output.jed`.
+
+This JEDEC file can be optionally be verified programmatically using the
+scripts and Verilog models found the `models/` directory. 
+
+The JEDEC file can then be flashed to the GAL chips. A convenience flashing
+script is provided for the cheap/common TL866 family of programmers. This works
+around the verification bugs in the upstream `minipro` programming software:
+```
+./flash_minipro.sh <JEDEC FILE> <CHIP>
+```
+Where `<CHIP>` is `GAL16V8`, `GAL22V10`, `ATF16V8B`, etc.
+
+Limitations
+-----------
+The GAL16V8 mode only supports the "Registered" mode and does not handle
+tristate Verilog for registered outputs (since they're globally shared). The
+GAL22V10 mode does not support the asynchronous set/reset signals for the
+registers. Additionally, in both modes, there is no guarantee that the mapping
+will be the most efficient (especially for timing). While fairly well tested,
+there is no guarantee of correctness either. Use at your own risk.
+
+Dependencies
+------------
+- `yosys` 0.38 or higher
+- Rust
+- `jedutil` from MAME utilities for model-based verification checking
+- `xxd` from Vim for model-based verification checking
+- `minipro` for the provided convenience flashing script