From c2db563faa0b9c367f266328256b7e8a8934eced Mon Sep 17 00:00:00 2001 From: Obijuan Date: Fri, 29 Sep 2023 20:39:57 +0200 Subject: [PATCH] update readme --- README.md | 119 +++++++++++++++++++++--------------------------------- 1 file changed, 46 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 42a427c5..4230a549 100644 --- a/README.md +++ b/README.md @@ -16,51 +16,69 @@ Open source **ecosystem for open FPGA boards** -Apio (pronounced [ˈa.pjo]) is a **multiplatform toolbox**, with static pre-built packages, project configuration tools and easy command interface to verify, synthesize, simulate and upload your **verilog** designs. +## What is Apio? -Apio is used by [Icestudio](https://github.com/FPGAwars/icestudio). +Apio is a **multiplatform** toolbox with **static** pre-built packages to verify, synthesize, simulate and upload your verilog designs into the supported **FPGA boards** + +## What?????? + +Apio makes **extremely easy** the process of working with **FPGAs**. Go from **scratch** to having a **blinky LED** in your FPGA board in minutes! This is because it is based only on **Free/Libre Open Source Software** (FLOSS). Just install it and use it as you want + + +In this animation you can see the whole process of testing the Blinky led circuit: Just type one command and the circuit will be synthesized, and uploaded into the FPGA + +![](https://github.com/FPGAwars/Apio-wiki/raw/main/wiki/Quick-start/apio-alhambra-II-01.gif) + +Think of Apio as a small **FPGA distribution**, which **collects** and **packages** **FLOSS toolchains for FPGAs**. You can install packages in **Linux**, **Mac** and **Windows** for synthesizing hardware, verifying and simulating from verilog files + +The goal is making it **very easy** to start with FPGAs + +As the user **gh02t** said in this post on [Hacker-news](https://news.ycombinator.com/item?id=17912510): +> Apio is a command line tool that automates installing the toolchain for your FPGA and running it. It just simplifies things, you don't have to use it if you'd rather call the individual tools for synthesis, P&R, simulation etc. It'd be reasonable to think of it as akin to a very smart Makefile combined with an automatic package manager, specialized to FPGAs (it's based on PlatformIO). It's nice when you're still kind of getting oriented, because you don't need to know how to set up and invoke the different tools... just call `apio build` or `apio simulate` + +## Apio and higher level tools + +Apio has a **command line interface** (CLI). It is the **building block** for other **higher level tools**, like [Icestudio](https://icestudio.io/), [Apio-IDE](https://github.com/FPGAwars/apio-ide) or working with FPGAs from IDEs such as [Visual Studio Code](https://code.visualstudio.com/) + + +### A circuit in Icestdio + +![](https://github.com/FPGAwars/Apio-wiki/raw/main/wiki/Introduction/icestudio-example.png) + +### A verilog circuit in Apio-IDE + +![](https://github.com/FPGAwars/Apio-wiki/raw/main/wiki/Introduction/apio-ide-example.jpg) + +### A verilog circuit in VSCode + +![](https://github.com/FPGAwars/Apio-wiki/raw/main/wiki/Introduction/vscode-example.png) + + +------- +[![](https://github.com/FPGAwars/icestudio-wiki/raw/main/Logos/fgpawars-banner.svg)](https://fpgawars.github.io/) -### Table of contents -* [Installation](#installation) -* [Apio packages](#apio-packages) -* [Supported boards](#supported-boards) -* [Documentation](#documentation) -* [Development](#development) -* [Videos](#videos) -* [Authors](#authors) -* [Contributors](#contributors) -* [License](#license) # Documentation Find all the information on this [WIKI PAGE](https://github.com/FPGAwars/apio/wiki) -# Installation -1. Install [Python](https://www.python.org/downloads) and [pip](https://pip.pypa.io) -2. Install the latest apio: ```pip install -U apio``` + +----- + + ## Apio packages | Package | Installation | Description |---------|----------------|--------------- -| [drivers](https://github.com/FPGAwars/tools-drivers) | apio install drivers | Drivers tools (only for Windows) +| [tools-oss-cad-suite](https://github.com/FPGAwars/tools-oss-cad-suite) | apio install oss-cad-suite| Selected binaries from the [YosysHQ/oss-cad-suite project](https://github.com/YosysHQ/oss-cad-suite-build) | [examples](https://github.com/FPGAwars/apio-examples) | apio install examples | Verilog basic examples, pinouts, etc -| [gtkwave](https://github.com/FPGAwars/tool-gtkwave) | apio install gtkwave | Simulation viewer. [GTKWave project](http://gtkwave.sourceforge.net) (only for Windows) -| [yosys](https://github.com/FPGAwars/toolchain-yosys) | apio install yosys | FPGA synthesis. [Yosys project](http://www.clifford.at/yosys) -| [ice40](https://github.com/FPGAwars/toolchain-ice40) | apio install ice40 | iCE40 place & route and configuration tools. [Icestorm project](http://www.clifford.at/icestorm) -| [ecp5](https://github.com/FPGAwars/toolchain-ecp5) | apio install ecp5 | ECP5 tools including [Project Trellis](https://github.com/SymbiFlow/prjtrellis) and [nextpnr](https://github.com/YosysHQ/nextpnr) -| [iverilog](https://github.com/FPGAwars/toolchain-iverilog) | apio install iverilog | Verilog simulation and synthesis tool. [Icarus Verilog project](http://iverilog.icarus.com) -| [scons](https://github.com/FPGAwars/tool-scons) | apio install scons | A software construction tool. [Scons project](http://scons.org) -| [verilator](https://github.com/FPGAwars/toolchain-verilator) | apio install verilator | Verilog HDL simulator. [Verilator project](https://www.veripool.org/wiki/verilator) -| [icesprog](https://github.com/FPGAwars/toolchain-icesprog) | apio install icesprog | Programmer for the [iCESugar](https://github.com/wuxx/icesugar) -| [fujprog](https://github.com/FPGAwars/toolchain-fujprog) | apio install fujprog | Programmer for ULX2/3S boards - +| [drivers](https://github.com/FPGAwars/tools-drivers) | apio install drivers | Drivers tools (only for Windows) +| [gtkwave](https://github.com/FPGAwars/tool-gtkwave) | apio install gtkwave | Simulation viewer. [GTKWave project](http://gtkwave.sourceforge.net) (only for Windows) -**Supported platforms** -*linux_x86_64, linux_i686, linux_armv7l, linux_aarch64, windows_x86, windows_amd64, darwin*. ## Supported boards @@ -145,51 +163,6 @@ Find all the information on this [WIKI PAGE](https://github.com/FPGAwars/apio/wi NOTE: all supported [Icestorm FPGAs](http://www.clifford.at/icestorm/) can be used with [--fpga or --size, --type and --pack options](http://apiodoc.readthedocs.io/en/develop/source/user_guide/project_commands/cmd_build.html#options). -## Documentation - -The complete documentation of the project can be found in Read the Docs: http://apiodoc.readthedocs.io. There is also a list of frequently asked questions (FAQ) that you can check [here](./FAQ.md). - -## Development - -```bash -git clone https://github.com/FPGAwars/apio.git -cd apio -``` - -### Testing - -```bash -pip install tox -``` - -```bash -tox -``` - -```bash -tox -e offline -tox -e coverage -``` - -### Documentation - -```bash -cd docs -make html -firefox _build/html/index.html -``` - -### Debian packaging - -Also you can find the debian scripts to package the full application and all the packages here: https://github.com/set-soft/apio-debian. - -Thanks Salvador E. Tropea! - -## Videos - -[![Apio in RPI2: iCEstick, Icezum and icoBOARD ](http://img.youtube.com/vi/xLb7T4pw9iY/0.jpg)](https://www.youtube.com/watch?v=xLb7T4pw9iY "Apio in RPI2: iCEstick, Icezum and icoBOARD ") - -[![Apio: an easy multi-platform toolbox for open FPGAs](http://img.youtube.com/vi/UJ6-_42P5BE/0.jpg)](https://www.youtube.com/watch?v=UJ6-_42P5BE "Apio: an easy multi-platform toolbox for open FPGAs") ## Authors