X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=HDL_workflow.mdwn;h=21bc60f45fb53959d15d371e2d78613b393b5227;hb=9ec40d93391f105167f173df349cfc630a5aef29;hp=263afc6cb82257a0124ba8eb31436d04206c3fa1;hpb=6884539b1f0223de9af72727c812d4c7aef4affc;p=libreriscv.git

diff --git a/HDL_workflow.mdwn b/HDL_workflow.mdwn
index 263afc6cb..21bc60f45 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 (<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
@@ -285,6 +282,11 @@ access to ultra-high resolution screens.
 
 # 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.
@@ -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,6 +337,9 @@ 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".
+
 ## yosys
 
 Follow the source code (git clone) instructions here, do **not** use
@@ -342,7 +347,7 @@ the "stable" version (do not download the tarball):
 <http://www.clifford.at/yosys/download.html>
 
 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
@@ -374,7 +379,11 @@ 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 !$
@@ -444,7 +453,7 @@ Again, if you want to save yourself some typing, use the dev scripts.
 script will install the qemu;
 [ppc64-gdb-gcc](https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=ppc64-gdb-gcc;hb=HEAD)
 script will install the toolchain and the corresponding debugger.
-The steps are provided below only for reference; when in doubts,
+The steps are provided below only for reference; when in doubt,
 consider checking and running the scripts.
 
 Install powerpc64 gcc:
@@ -470,37 +479,25 @@ unpack it, then:
 programs.  [qemu](https://www.qemu.org/) emulates processors, you can
 run programs under qemu.
 
-## power_instruction_analyzer (pia)
-
-We have a custom tool built in rust by programmerjake to help analyze
-the power instructions execution on *actual* hardware.
+## power-instruction-analyzer (pia)
 
-Note: a very recent version of pip3 is required for this to work.
+We have a custom tool built in Rust by programmerjake to help analyze
+the OpenPower instructions' execution on *actual* hardware.
 
-Install rust:
+Install Rust:
 
     curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 
-Make sure we have the correct and up-to-date rust compiler (rustc):
+Make sure we have the correct and up-to-date rust compiler (rustc & cargo):
 
     rustup default stable
     rustup update
 
-Use rust's package manager *cargo* to install the rust-python build
-tool maturin:
-
-    cargo install maturin
-
-Install from git source by doing the following:
+Install the Python extension from git source by doing the following:
 
     git clone https://salsa.debian.org/Kazan-team/power-instruction-analyzer.git pia
     cd pia
-    maturin build --cargo-extra-args=--features=python-extension
-    python3 -m pip install --user target/wheels/*.whl
-
-Note: an ongoing bug in maturin interferes with successful installation.
-This can be worked around by explicitly installing only the `.whl`
-files needed rather than installing everything (`\*.whl`).
+    ./libre-soc-install.sh
 
 ## Chips4Makers JTAG
 
@@ -546,7 +543,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
 
@@ -580,6 +579,15 @@ cocotb is a COroutine based COsimulation TestBench environment for verifying VHD
 
 See [[HDL_workflow/cocotb]] page for installation instructions.
 
+## Symbiflow
+
+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.
+
 # Registering for git repository access<a name="gitolite3_access"></a>
 
 After going through the onboarding process and having agreed to take
@@ -596,6 +604,14 @@ Create a file `~/.ssh/config` with the following lines:
     Host git.libre-soc.org
     Port 922
 
+Test that you have access with this command:
+
+    ssh -v -p922 gitolite3@git.libre-soc.org
+
+Please note: **DO NOT TYPE A PASSWORD** - the server gets hit by a lot of
+port-scanning, and detection of password failures are used to instantly
+ban IP addresses.
+
 Wait for the Project Admin to confirm that the ssh key has been added
 to the required repositories.  Once confirmed, you can clone any of the
 repos at https://git.libre-soc.org/:
@@ -643,6 +659,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>
 
+**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
@@ -653,7 +673,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
@@ -664,7 +684,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
@@ -1060,10 +1082,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
-  <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
-  <https://github.com/m-labs/nmigen/tree/master/examples/> exactly as
+  <https://github.com/nmigen/nmigen/tree/master/examples/> exactly as
   described in the above tutorial (python3 filename.py -h)
-
+* More nmigen tutorials at [[learning_nmigen]]