diff --git a/README.md b/README.md index 87abf5e4..f1826430 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,44 @@ # Board definitions for Amaranth HDL -TODO +The Amaranth Board Definitions contain platform specific information for deploying Amaranth projects onto readily available and common FPGA hardware. The boards defined within this repository are listed within `amaranth_boards/`. + +*TODO: describe a typical board file, or point to general Amarnath documentation.* + +For a quick reference of the boards described by this repository, reference the [Boards Table](docs/boards_table.md) or see the board sources defined in [`amaranth_boards/`](amaranth_boards/) directly. + +## Installation + +After following the setup instructions for the core [Amaranth HDL tool chain](https://amaranth-lang.org/docs/amaranth/latest/install.html), the `amaranth_boards` package can be installed in the same location as site-packages or dist-packages. The boards package follows a conventional setup process for a source based python package. + +### Setup Requirements + +This guide assumes a supported version of Python and `pip` are available on the host system. Reference the [Amaranth HDL documentation](https://amaranth-lang.org/docs/amaranth/latest/install.html) for specific versions and detailed setup instructions for for python and pip. + +Prior to attempting to install the boards package, ensure your system has the required setuptools packages available. + +- `setuptools` > 67.0 +- `setuptools_scm[toml]` > 6.2 + +If you find you are missing either setuptools package, running the following command should install them locally assuming `pip` is available. + +```bash +pip install setuptools setuptools_scm[toml] +``` + +### Quick Installation + +Use the following command to directly install from this repository +```bash +pip install 'amaranth-boards @ git+https://github.com/amaranth-lang/amaranth-boards.git' +``` + +### Local Installation + +Either clone a copy of the source code from the repository, or download a bundled copy of the current `main` branch from the releases on this page. From within the root directory of the repository run the following command to install the current release of the boards package to the current user's python packages directory. + +```bash +pip install --user -e . +``` ## License diff --git a/docs/boards_table.md b/docs/boards_table.md new file mode 100644 index 00000000..2b834823 --- /dev/null +++ b/docs/boards_table.md @@ -0,0 +1,49 @@ +# Board Summary List + +The following table provides reference links for the boards with interfaces and capabilities defined by this repository. + +| Platform Python File | Reference Information | Platform Type | +| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- | +| `alchitry_au` | Alchitry [Au](https://alchitry.com/boards/au) | Xilinx | +| `arrow_deca` | Arrow [Deca](https://www.arrow.com/en/products/deca/arrow-development-tools) | Intel | +| `arty_a7`, `arty_s7`, `arty_z7` | Digilent [A7](https://digilent.com/reference/programmable-logic/arty-a7/reference-manual), [S7](https://digilent.com/reference/programmable-logic/arty-s7/reference-manual), [Z7](https://digilent.com/reference/programmable-logic/arty-z7/reference-manual) | Xilinx | +| `atlys` | Digilent [Atlys](https://digilent.com/reference/programmable-logic/atlys/reference-manual) | Xilinx | +| `blackice`, `blackice_ii` | Blackice[^todo] *TODO*, [BlackIce II](https://github.com/mystorm-org/BlackIce-II/wiki) | LatticeICE40 | +| `chameleon96` | 96Boards [Chameleon96](https://www.96boards.org/product/chameleon96/) | Intel | +| `cmod_a7`, `cmod_s7` | Digilent CMOD [A7](https://digilent.com/reference/programmable-logic/cmod-a7/reference-manual), [S7](https://digilent.com/reference/programmable-logic/cmod-s7/reference-manual) | Xilinx | +| `colorlight_5a75b_r7_0` | ColorLight [5A-75B v7.0](https://github.com/q3k/chubby75/blob/master/5a-75b/hardware_V7.0.md) | LatticeECP5 | +| `de0`, `de0_cv`, `de10_lite`, `de10_nano`, `de1_soc` | TerasIC [DE0](https://www.terasic.com.tw/cgi-bin/page/archive.pl?Language=English&CategoryNo=56&No=364), [DE0-CV](https://www.terasic.com.tw/cgi-bin/page/archive.pl?Language=English&No=921&PartNo=4), [DE10-Lite](https://www.terasic.com.tw/cgi-bin/page/archive.pl?Language=English&CategoryNo=218&No=1021), [DE10-Nano](https://www.terasic.com.tw/cgi-bin/page/archive.pl?Language=English&CategoryNo=167&No=1046), [DE1-SoC](https://www.terasic.com.tw/cgi-bin/page/archive.pl?Language=English&CategoryNo=167&No=836) | Intel | +| `ebaz4205` | [EBAZ4205](https://github.com/xjtuecho/EBAZ4205) | Xilinx | +| `ecp5_5g_evn` | Lattice [ECP5 5G Eval Board](https://www.latticesemi.com/products/developmentboardsandkits/ecp5evaluationboard) | LatticeECP5 | +| `ecpix5` | Lambda Concept [ECPIX-5](http://docs.lambdaconcept.com/ecpix-5/) | LatticeECP5 | +| `fomu_hacker`, `fomu_pvt` | [Fomu Platform Docs](https://tomu.im/fomu.html) | LatticeICE40 | +| `genesys2` | Digilent [Genesys2Platform](https://digilent.com/reference/programmable-logic/genesys-2/reference-manual) | Xilinx | +| `ice40_hx1k_blink_evn` | Lattice [40HGX1K](https://www.latticesemi.com/iCEblink40-HX1K), [40-HX8K](https://www.latticesemi.com/Products/DevelopmentBoardsAndKits/iCE40HX8KBreakoutBoard.aspx), [40-UP5K](https://www.latticesemi.com/products/developmentboardsandkits/ice40ultraplusbreakoutboard) | LatticeICE40 | +| `icebreaker`, `icebreaker_bitsy` | [iCEBreaker](https://docs.icebreaker-fpga.org/hardware/icebreaker/), [iCEBreaker Bitsy](https://docs.icebreaker-fpga.org/hardware/bitsy/) | LatticeICE40 | +| `icestick` | Lattice [iCEstick](https://www.latticesemi.com/icestick) | LatticeICE40 | +| `icesugar`, `icesugar_nano` | [iCESugar](https://github.com/wuxx/icesugar/blob/master/README_en.md), [iCESugar Nano](https://github.com/wuxx/icesugar-nano) | LatticeICE40 | +| `kc705` | Xilinx [KC705 Eval Kit](https://www.xilinx.com/products/boards-and-kits/ek-k7-kc705-g.html) | Xilinx | +| `kcu105` | Xilinx [KCU105 Eval Kit](https://www.xilinx.com/products/boards-and-kits/kcu105.html) | Xilinx | +| `logicbone` | [logicbone](https://github.com/oskirby/logicbone) | LatticeECP5 | +| `machxo3_sk` | Lattice [MachXO3LF Starter Kit](https://www.latticesemi.com/products/developmentboardsandkits/machxo3lfstarterkit) | LatticeMachXO3L | +| `mercury` | micronova [Mercury](https://www.micro-nova.com/mercury) | Xilinx | +| `microzed_z010`, `microzed_z020` | Avnet [MicroZed Family](https://www.avnet.com/wps/portal/us/products/avnet-boards/avnet-board-families/microzed/) | Xilinx | +| `mister` | [MiSTer](https://mister-devel.github.io/MkDocs_MiSTer/) | Intel | +| `nandland_go` | [nandland Go Board](https://nandland.com/the-go-board/) | LatticeICE40 | +| `nexys4ddr` | Digilent [Nexys4 DDR](https://digilent.com/reference/programmable-logic/nexys-4-ddr/reference-manual) | Xilinx | +| `numato_mimas` | Numato Lab [Mimas Spartan 6 Dev Board](https://numato.com/docs/mimas-spartan-6-fpga-development-board/) | Xilinx | +| `orangecrab_r0_1`, `orangecrab_r0_2` | 1Bit Squared [OrangeCrab](https://github.com/orangecrab-fpga) | LatticeECP5 | +| `quickfeather` | Quicklogic [Quickfeather Dev Kit](https://www.quicklogic.com/products/eos-s3/quickfeather-development-kit/) | Quicklogic | +| `rz_easyfpga_a2_2` | [RZ EasyFPGA A2.2](https://github.com/cosmolabs-ru/RZ-EasyFPGA-A2.2) (*TODO, better link*) | Intel | +| `sk_xc6slx9` | Xilinx Spartan 6 Starter Kit[^todo] | Xilinx | +| `supercon19badge` | Hack-a-Day [2019 Supercon Badge](https://hackaday.com/2019/11/16/behind-the-scenes-of-the-2019-superconference-badge/) | LatticeECP5 | +| `tang_nano` | SiPEED [Tang Nano](http://tangnano.sipeed.com/en/) | Gowin | +| `te0714_03_50_2I` | trenz electronic [TE0714](http://trenz.org/te0714-info) Artix 7 | Xilinx | +| `tinyfpga_ax1`, `tinyfpga_ax2` | TinyFPGA [A Series](https://tinyfpga.com/a-series-guide.html), [AX2]() | LatticeMachXO2 | +| `tinyfpga_bx` | TinyFPGA [BX](https://tinyfpga.com/bx/guide.html) | LatticeICE40 | +| `ulx3s` | Radiona [ULX3s](https://radiona.org/ulx3s/) | LatticeECP5 | +| `upduino_v1`, `upduino_v2`, `upduino_v3` | *TODO v1*[^todo], [v2](https://github.com/tinyvision-ai-inc/UPduino-v2.1), [v3](https://github.com/tinyvision-ai-inc/UPduino-v3.0) | LatticeICE40 | +| `versa_ecp5_5g`, `versa_ecp5` | Lattice [ECP5-5G Versa Dev Kit](https://www.latticesemi.com/products/developmentboardsandkits/ecp55gversadevkit), [ECP5 Versa Dev Kit](https://www.latticesemi.com/Products/DevelopmentBoardsAndKits/ECP5VersaDevelopmentKit) | VersaECP5 | +| `zturn_lite_z007s`, `zturn_lite_z010` | MYIR Tech [Z-turn Lite](https://www.myirtech.com/list.asp?id=565) | Xilinx | + +[^todo]: link needed