From 6246142ef4c7418bd51d3660fae448370481ec9f Mon Sep 17 00:00:00 2001 From: Luke Date: Sat, 7 Oct 2023 11:48:30 -0700 Subject: [PATCH 1/2] added basic installation documentation, and reference docs for boards. --- README.md | 33 ++++++++++++++++++++++++++++- docs/boards_table.md | 49 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 docs/boards_table.md diff --git a/README.md b/README.md index 87abf5e4..ba42d79f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,37 @@ # 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] +``` + +### 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 . +``` ## 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 From ec6f321bfe578dc26ee4b026cb0c3854c9ec3ba9 Mon Sep 17 00:00:00 2001 From: Luke Date: Sat, 7 Oct 2023 13:59:12 -0700 Subject: [PATCH 2/2] added easy install method directly from github. --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ba42d79f..f1826430 100644 --- a/README.md +++ b/README.md @@ -25,12 +25,19 @@ If you find you are missing either setuptools package, running the following com 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 . +pip install --user -e . ``` ## License