Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fpgawars/apio-examples
:seedling: Apio examples
https://github.com/fpgawars/apio-examples
apio examples verilog
Last synced: 29 days ago
JSON representation
:seedling: Apio examples
- Host: GitHub
- URL: https://github.com/fpgawars/apio-examples
- Owner: FPGAwars
- License: gpl-2.0
- Created: 2016-04-24T16:21:35.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-12-21T05:43:49.000Z (about 1 month ago)
- Last Synced: 2024-12-21T06:25:25.750Z (about 1 month ago)
- Topics: apio, examples, verilog
- Language: Python
- Homepage:
- Size: 1.99 MB
- Stars: 34
- Watchers: 5
- Forks: 26
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Apio examples package
A package with sample FPGA project for [Apio](https://github.com/fpgawars/apio)
## Creating a release
Start with a clean repository, with no build artifact. Not sure? Run the script
``clean_examples.sh``
1. Decide the new version number, e.g. ``0.1.12``
2. Update the version number in the file ``build.sh`` and ``VERSION_DEV`` to the new version.
3. Run ``./build.sh`` to build the new package zip file in the ``_package`` directory.
4. Commit the changes to ``build.sh`` and ``VERSION_DEV``
5. Created on github a new release with the new version number and upload to it
the package's zip file from directory ``_package``.
## Updating the examples report
1. Run the script ``./generate_reports.sh``. This may take a few minutes.
2. Submit the ``_*.csv`` files it modified.
---------
## Guides for authoring examples
### Directory structure
The examples in the apio-examples repository have the following directory structure
```
examples
```
Where:
**Board-id**
This the exact FPGA board id of the example, as listed by ``apio examples -l``. This is also the ``board=`` value in the ``apio.ini`` file of the example.
```
alhambra-ii # good
Alhambra-II # bad
```
**Example-id**
This is a short name that identify the example among the examples of that bord and it is in lower-case format with ASCII alphanumeric characters only (no unicode).
```
blinky # good
divide-by-pi # good
Blinky # bad
Divide By Pi # bad
divide_by_pi # bad
divide-by-3.14 # bad
```
**Examble-files**
These are the files that make up the examples. Subdirectories are not allow in the example directory.
---------
### Board level requirements
**A board should have at least one example.** This is self explanatory.
---------
### Example level requirements
**An example should be license compatible**
The publishing of the example should be compatible with the LICESNE of the FPGAWars' apio-examples repository.
**An example should include an 'info' file**
The example directory should include a text file named ``info`` with a single
line, up to 50 characters long, desdribing the example.
**An example should have an apio.ini**
Each example should contain an apio.ini file with all the required options. Example
```
[env]
board = alhambra-ii
top-module = main
```
**An example should not be broken**
An example should pass successfuly the following commands ``apio build``, ``apio upload``, ``apio report``, ``apio graph``.
**A testbench should not be broken**
If an example contains a testbench (*_tb.v files), they should pass successfuly the commands ``apio test`` and ``apio sim ``.
---------
### Board level 'nice to have'
**A 'template' example for new projects**
Having for your board an example called ``template`` will provide your users with
good starting point to start a new project. The ``template`` should have a full
constrains file for that FPGA which the users can then trim or comment out.
---------
### Example level 'nice to have'
**lower-case file names**
It's recomanded to use ``lower-case`` format (ASCII a-z, 0-9, no unicode) for base file
names. For example:
```
clock-divider.v
my-test-bench_tb.v.
main.v
```
**A least one testbench**
A good example should have at least one testbench.
**A .gtkw file for each testbench**
Having a .gtkw file for each testbench makes your example more user friedly.
You can the .gtkw files by running ``apio sim ``,
selecting in the GUI the signals to display, and saving the .gtkw file using the menu entry ``File | Write Save File``.
**Consistnet example names**
If you create a hello-world example that turn on or blinks a led, prefer to reuse
common example name from other boards, such as ``ledon`` or ``blinky`` rathe than
inventing new names.
-----------