update pinset for hyperram resource

[libreriscv.git] / HDL_workflow.mdwn

diff --git a/HDL_workflow.mdwn b/HDL_workflow.mdwn
index 6c63b29ea57256d3a119f0d0d462267fe43a2048..32660164f18974345ea24dcd883ef4413944801b 100644 (file)
--- 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 (<https://ftp.libre-soc.org/>): large (temporary,
   auto-generated) file store.
 
 * ftp server (<https://ftp.libre-soc.org/>): 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
 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<a name="software-prerequisites"></a>
 
 
 # Software prerequisites<a name="software-prerequisites"></a>
 

+**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
+<http://lists.libre-soc.org/pipermail/libre-soc-dev/2021-September/003666.html>**
+

 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.
 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
 * 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
 * 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.
 
 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):
 ## yosys
 
 Follow the source code (git clone) instructions here, do **not** use
 the "stable" version (do not download the tarball):

-<http://www.clifford.at/yosys/download.html>
+<https://github.com/YosysHQ/yosys>

 
 Or, alternatively, use the
 
 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.
 
 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
 [Verilog](https://en.wikipedia.org/wiki/Verilog) is a hardware description
 language.
 RTL [Register Transfer


@@ -374,11 +383,15 @@ flows.
 
 ## nmigen
 
 
 ## 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 !$
 
 * 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
 * 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
 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)`
     >>> 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.
 
 
 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
 
 
 ## Verilator
 


@@ -570,10 +585,12 @@ See [[HDL_workflow/cocotb]] page for installation instructions.
 
 ## Symbiflow
 
 
 ## 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
 
 See [[HDL_workflow/symbiflow]] for installation instructions

-and dependencies
+and dependencies.

 
 # Registering for git repository access<a name="gitolite3_access"></a>
 
 
 # Registering for git repository access<a name="gitolite3_access"></a>
 


@@ -646,6 +663,10 @@ Before running the following, install the
 dependencies.  This is easiest done with this script
 <https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=install-hdl-apt-reqs;hb=HEAD>
 
 dependencies.  This is easiest done with this script
 <https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=install-hdl-apt-reqs;hb=HEAD>
 

+**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
 * 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
 
 * 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
 `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
 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
 
 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.
 
 
 Really.  don't.  use.  wildcards.
 

+More about this here:
+
+* <https://www.asmeurer.com/removestar/>
+* <https://rules.sonarsource.com/python/RSPEC-2208>
+

 ### Keep file and variables short but clear
 
 * try to keep both filenames and variable names short but not ridiculously
 ### 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
   <https://symbiyosys.readthedocs.io/en/latest/quickstart.html#first-step-a-simple-bmc-example>
 * This tutorial looks pretty good and will get you started
 * Although a verilog example this is very useful to do
   <https://symbiyosys.readthedocs.io/en/latest/quickstart.html#first-step-a-simple-bmc-example>
 * This tutorial looks pretty good and will get you started

-  <http://blog.lambdaconcept.com/doku.php?id=nmigen:nmigen_install> and
-  walks not just through simulation, it takes you through using gtkwave
-  as well.
+  <https://web.archive.org/web/20210123052724/http://blog.lambdaconcept.com/doku.php?id=nmigen:nmigen_install>
+  and walks not just through simulation, it takes you through using
+  gtkwave as well.

 * There exist several nmigen examples which are also executable
 * There exist several nmigen examples which are also executable

-  <https://github.com/m-labs/nmigen/tree/master/examples/> exactly as
+  <https://gitlab.com/nmigen/nmigen/tree/master/examples/> exactly as

   described in the above tutorial (python3 filename.py -h)
   described in the above tutorial (python3 filename.py -h)

-
+* More nmigen tutorials at [[learning_nmigen]]