X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=HDL_workflow.mdwn;h=32660164f18974345ea24dcd883ef4413944801b;hb=f9d862820cdfef2bcc3e86276ad5e4d12c9d90a4;hp=6c63b29ea57256d3a119f0d0d462267fe43a2048;hpb=332d9a874fc3efbbcbbb12244288669f7f1d16a4;p=libreriscv.git
diff --git a/HDL_workflow.mdwn b/HDL_workflow.mdwn
index 6c63b29ea..32660164f 100644
--- a/HDL_workflow.mdwn
+++ b/HDL_workflow.mdwn
@@ -40,9 +40,6 @@ The main message here: **use the right tool for the right job**.
* ftp server (): large (temporary,
auto-generated) file store.
-We will add an IRC channel at some point when there are enough people
-to warrant having one (and it will be publicly archived)
-
Note also the lack of a "forum" in the above list. this is very
deliberate. forums are a serious distraction when it comes to technical
heavily goal-orientated development. recent internet users may enjoy
@@ -285,6 +282,11 @@ access to ultra-high resolution screens.
# Software prerequisites
+**Please make sure if you install manually that you install dependencies
+in strict order. Failing to adhere to this will result in pip3 downloading
+unauthorised older software versions. See
+**
+
Whilst many resources online advocate "`sudo`" in front of all root-level
commands below, this quickly becomes tiresome. run "`sudo bash`", get a
root prompt, and save yourself some typing.
@@ -292,7 +294,7 @@ root prompt, and save yourself some typing.
* sudo bash
* apt-get install vim exuberant-ctags
* apt-get install build-essential
-* apt-get install git python3.7 python3.7-dev python-nosetest3
+* apt-get install git python3.7 python3.7-dev python3-nose
* apt-get install graphviz xdot gtkwave
* apt-get install python3-venv
* apt-get install python-virtualenv # this is an alternative to python3-venv
@@ -335,20 +337,27 @@ relevant unit tests pass 100%. This ensures that people's work does not
get "lost" or isolated and out of touch due to major branch diversion,
and that people communicate and coordinate with each other.
+This is not a hard rule: under special cirmstances branches can be useful.
+They should not however be considered "routine".
+
+For advice on commit messages see
+[here](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html),
+and [here](https://github.com/torvalds/subsurface-for-dirk/blob/master/README.md#contributing)).
+
## yosys
Follow the source code (git clone) instructions here, do **not** use
the "stable" version (do not download the tarball):
-
+
Or, alternatively, use the
-[yosys-et-al](https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=yosys-et-al;hb=HEAD)
+[hdl-tools-yosys](https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=hdl-tools-yosys;hb=HEAD)
script (which also installs symbiyosys and its dependencies)
Do not try to use a fixed revision of yosys (currently 0.9), nmigen is
evolving and frequently interacts with yosys.
-[Yosys](http://www.clifford.at/yosys/) is a framework for Verilog RTL.
+[Yosys](https://github.com/YosysHQ/yosys is a framework for Verilog RTL.
[Verilog](https://en.wikipedia.org/wiki/Verilog) is a hardware description
language.
RTL [Register Transfer
@@ -374,11 +383,15 @@ flows.
## nmigen
-[nmigen](https://m-labs.hk/gateware/nmigen/) may be installed as follows:
+**PLEASE NOTE: it is critical to install nmigen as the first dependency
+prior to installing any further python-based Libre-SOC HDL repositories.
+If "pip3 list" shows that nmigen has been auto-installed please remove it**
+
+[nmigen](https://nmigen.info/) may be installed as follows:
* mkdir ~/src
* cd !$
-* git clone https://github.com/nmigen/nmigen.git
+* git clone https://gitlab.com/nmigen/nmigen.git
* cd nmigen
* sudo bash
* python3 setup.py develop
@@ -430,7 +443,7 @@ In the meantime, sfpy can be built as follows:
You can test your installation by doing the following:
python3
- >>> from sfpy import *
+ >>> from sfpy import Posit8
>>> Posit8(1.3)
It should print out `Posit8(1.3125)`
@@ -534,7 +547,9 @@ See [[HDL_workflow/coriolis2]] page, for those people doing layout work.
A portable FPGA place and route tool.
-See [[HDL_workflow/nextpnr]] page for installation instructions of nextpnr with ECP5 support for Lattice FPGA ECP5 series.
+See [[HDL_workflow/nextpnr]] page for installation instructions of nextpnr with ECP5 support for Lattice FPGA ECP5 series. Also see
+[[HDL_workflow/ECP5_FPGA]] for connecting up to JTAG with a ULX3S
+and the Lattice VERSA_ECP5.
## Verilator
@@ -570,10 +585,12 @@ See [[HDL_workflow/cocotb]] page for installation instructions.
## Symbiflow
-needed for the Arty A7 100t Digilent FPGA board
+A fully open source toolchain for the development of FPGAs. Currently it targets Xilinx 7-series, Lattice iCE40 and ECP5, Quicklogic EOS S3.
+
+Needed for the Arty A7 100t Digilent FPGA board.
See [[HDL_workflow/symbiflow]] for installation instructions
-and dependencies
+and dependencies.
# Registering for git repository access
@@ -646,6 +663,10 @@ Before running the following, install the
dependencies. This is easiest done with this script
+**It is critically important to install these in STRICT order, otherwise
+pip3 interferes and performs unauthorised downloads without informing
+you of what it is doing**.
+
* mkdir ~/src
* cd !$
* git clone gitolite3@git.libre-soc.org:nmigen.git
@@ -656,7 +677,7 @@ dependencies. This is easiest done with this script
* git clone gitolite3@git.libre-soc.org:nmigen-soc.git
* git clone gitolite3@git.libre-soc.org:soc.git
-In each of these directories, in the order listed, track down the
+In each of these directories, **in the order listed***, track down the
`setup.py` file, then, as root (`sudo bash`), run the following:
* python3 setup.py develop
@@ -667,7 +688,9 @@ for multi-user machine use however it is often just easier to get your
own machine these days.
The reason for the order is because soc depends on ieee754fpu, and
-ieee754fpu depends on nmutil
+ieee754fpu depends on nmutil. If you do not follow the listed order
+pip3 will go off and download an arbitrary version without your
+consent.
If "`python3 setup.py install`" is used it is a pain: edit, then
install. edit, then install. It gets extremely tedious, hence why
@@ -908,6 +931,11 @@ the double import of the class from two separate locations, immediately.
Really. don't. use. wildcards.
+More about this here:
+
+*
+*
+
### Keep file and variables short but clear
* try to keep both filenames and variable names short but not ridiculously
@@ -1063,10 +1091,10 @@ Find appropriate tutorials for nmigen and yosys, as well as symbiyosys.
* Although a verilog example this is very useful to do
* This tutorial looks pretty good and will get you started
- and
- walks not just through simulation, it takes you through using gtkwave
- as well.
+
+ and walks not just through simulation, it takes you through using
+ gtkwave as well.
* There exist several nmigen examples which are also executable
- exactly as
+ exactly as
described in the above tutorial (python3 filename.py -h)
-
+* More nmigen tutorials at [[learning_nmigen]]