The main message here: **use the right tool for the right job**.
* mailing list: general communication and discussion.
-* irc channel #libre-soc: real(ish)-time communication.
+* irc channel #libre-soc on irc.libera.chat: real(ish)-time communication.
* bugtracker: task-orientated, goal-orientated *focussed* discussion.
* ikiwiki: document store, information store, and (editable) main website
* git repositories: code stores (**not binary or auto-generated output 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
### Mailing list != editable document store
Also, please do not use the mailing list as an "information or document
-store or poor-man's editor". We have the wiki for that. Edit a page and
+store or poor-man's editor" **including not sending large images**.
+We have the wiki for that. Edit a page and
tell people what you did (summarise rather than drop the entire contents
at the list) and include the link to the page.
# 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.
* 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
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):
-<http://www.clifford.at/yosys/download.html>
+<https://github.com/YosysHQ/yosys>
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
front-end driver program for Yosys-based formal hardware verification
flows.
-## nmigen
+## nmigen (TM)
+
+*nmigen is a registered trademark of M-Labs <https://uspto.report/TM/88980893>*
-[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
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)`
As we are doing POWER ISA, POWER ISA compilers, toolchains and
emulators are required.
+Again, if you want to save yourself some typing, use the dev scripts.
+[install-hdl-apt-reqs](https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=install-hdl-apt-reqs;hb=HEAD)
+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 doubt,
+consider checking and running the scripts.
Install powerpc64 gcc:
- apt-get install gcc-9-powerpc64-linux-gnu
+ apt-get install gcc-8-powerpc64-linux-gnu
Install qemu:
apt-get install qemu-system-ppc
Install gdb from source. Obtain the required tarball matching
-the version of gcc (9.1) from here <https://ftp.gnu.org/gnu/gdb/>,
+the version of gcc (8.3) from here <https://ftp.gnu.org/gnu/gdb/>,
unpack it, then:
- cd gdb-9.1 (or other location)
+ cd gdb-8.3 (or other location)
mkdir build
cd build
../configure --srcdir=.. --host=x86_64-linux --target=powerpc64-linux-gnu
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
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.
+
+## Nextpnr-xilinx
+
+An open source place and route framework for Xilinx FPGAs using Project Xray. We will use it for Xilinx 7-series FPGAs like Artix-7.
+
+One of the ways to get Arty A7 100t Digilent FPGA board working.
+
+See [[HDL_workflow/nextpnr-xilinx]] for installation instructions and dependencies.
+
## Verilator
See [[HDL_workflow/cocotb]] page for installation instructions.
-# Registering for git repository access
+## Symbiflow
+
+A fully open source toolchain for the development of FPGAs. Currently it targets Xilinx 7-series, Lattice iCE40 and ECP5, Quicklogic EOS S3.
+
+One way to get the Arty A7 100t Digilent FPGA board working.
+
+See [[HDL_workflow/symbiflow]] for installation instructions
+and dependencies.
+
+## FPGA/Board Boot-Loaders-Programmers
+
+Open source FPGA/Board boot-loaders and programmers for ULX3S, ECP5 and
+OrangeCrab.
+
+Currently these programs dfu-util, openFPGALoader, ujprog, fujprog,
+xc3sprog and ecpprog are going to be used.
+
+See [[HDL_workflow/fpga-boot-loaders-progs]] for installation instructions and dependencies.
+
+## ls2 peripheral fabric
+
+[[HDL_workflow/ls2]]
+
+# Registering for git repository access<a name="gitolite3_access"></a>
After going through the onboarding process and having agreed to take
responsibility for certain tasks, ask on the mailing list for git
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/:
git clone ssh://gitolite3@git.libre-soc.org:922/REPONAME.git
+Note: **DO NOT ATTEMPT TO LOG IN TO THE SERVER WITH A PERSONAL ACCOUNT**.
+fail2ban is running and, due to repeated persistent port-scanning spammers
+is set up to instantly ban any unauthorised ssh access for up to two weeks.
+This keeps log file sizes down on the server (which is resource-constrained).
+If you are wondering why this is done, it's a *lot* of port-scans.
+
+Therefore, *only* ssh in to server with the gitolite3 account, *only*
+on port 922, and *only* once the systems administrator has given you
+the all-clear that the ssh key has been added.
+
# git configuration
Although there are methods online which describe how (and why) these
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
+* git clone https://gitlab.com/nmigen/nmigen
+* git clone https://gitlab.com/nmigen/nmigen-boards
+* git clone https://gitlab.com/nmigen/nmigen-soc
+* git clone https://gitlab.com/nmigen/nmigen-stdio
* git clone gitolite3@git.libre-soc.org:c4m-jtag.git
* git clone gitolite3@git.libre-soc.org:nmutil.git
* git clone gitolite3@git.libre-soc.org:openpower-isa.git
* git clone gitolite3@git.libre-soc.org:ieee754fpu.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
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
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
preferably with a link to a URL in the [bugtracker](https://bugs.libre-soc.org/)
with further details as to why the unit test should not be run.
+# Task management guidelines
+
+1. Create the task in appropriate "Product" section with appropriate
+ "Component" section. Most code tasks generally use "Libre-SOC's
+ first SOC".
+2. Fill in "Depends on" and "Blocks" section whenever appropriate.
+ Also add as many related ("See Also") links to other bugreports
+ as possible. bugreports are never isolated.
+3. Choose the correct task for a budget allocation. Usually the parent
+ task is used.
+4. Choose the correct NLnet milestone. The best practice is to check
+ the parent task for a correct milestone.
+5. Assign the budget to the task in `"USER=SUM"` form, where "USER"
+ corresponds to your username and "SUM" corresponds to the actual
+ budget in EUR. There may be multiple users.
+6. When the task is completed, you can begin writing an RFP.
+ **DO NOT submit it without explicit authorisation and review**.
+ Leave out your bank and personal address details if you prefer
+ when sending to the Team Manager for review.
+7. Once the RFP is written, notify the Team Manager and obtain their
+ explicit approval to send it.
+8. Once approval is received and the RFP sent, update the `"USER=SUM"`
+ field to include the submitted date:
+ `"USER={amount=SUM, submitted=SDATE}"`. The SDATE is entered in
+ `YYYY-MM-DD` form.
+9. Once the task is paid, again notify the Team Manager (IRC is fine),
+ and update `"USER={amount=SUM, submitted=SDATE}"`
+ to `"USER={amount=SUM, submitted=SDATE, paid=PDATE}"`. The PDATE is
+ entered in `YYYY-MM-DD` form, too.
+
+Throughout all of this you should be using budget-sync to check the
+database consistency
+<https://git.libre-soc.org/?p=utils.git;a=blob;f=README.txt;hb=HEAD>
+
+[[!img bugzilla_RFP_fields.jpg size=640x ]]
+
# TODO Tutorials
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://gitlab.com/nmigen/nmigen/tree/master/examples/> exactly as
described in the above tutorial (python3 filename.py -h)
-
+* More nmigen tutorials at [[learning_nmigen]]
projects / libreriscv.git / blobdiff