## Bugtracker
+* **LibreSOC bug/task process**: [[libresoc_bug_process]]
+
bugzilla. old and highly effective. sign up in the usual way. any
problems, ask on the list.
proprietary nonfree service "because it's soooo convenient", as the
lions are getting wind and gout from overfeeding on that one.
+one.
+
## ikiwiki
Runs the main libre-soc.org site (including this page). effective,
* 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
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
[hdl-tools-yosys](https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=hdl-tools-yosys;hb=HEAD)
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>*
**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:
+[nmigen](https://m-labs.hk/gateware/nmigen/) 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
git clone --recursive https://github.com/billzorn/sfpy.git
cd sfpy
+ git apply /path/to/ieee754fpu/sfpy.patch
cd SoftPosit
git apply ../softposit_sfpy_build.patch
git apply /path/to/ieee754fpu/SoftPosit.patch
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)`
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
## 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.
+
+One way to get the Arty A7 100t Digilent FPGA board working.
See [[HDL_workflow/symbiflow]] for installation instructions
-and dependencies
+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>
* 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
commit confuses several unrelated changes, not only the diff is larger
than it should be, the reversion process becomes extremely painful.
+### PHP-style python format-strings
+
+As the name suggests, "PHP-style" is not given as a compliment.
+Format-strings - `f"{variable} {pythoncodefragment}" are a nightmare
+to read. The lesson from PHP, Zope and Plone: when code is embedded,
+the purpose of the formatting - the separation of the format from
+the data to be placed in it - is merged, and consequently become
+unreadable.
+
+By contrast, let us imagine a situation where 12 variables need to
+be inserted into a string, four of which are the same variablename:
+
+ x = "%s %s %s %s %s %s %s %s %s %s %s %s" % (var1, var2, var3,
+ var3, var4, var2,
+ var1, var9, var1,
+ var3, var4, var1)
+
+This is just as unreadable, but for different reasons. Here it *is*
+useful to do this as:
+
+ x = f"{var1} {var2} {var3}" \
+ ...
+ f"{var3} {var4} {var1}"
+
+As a general rule, though, format-specifiers should be strongly
+avoided, given that they mix even variable-names directly inside
+a string.
+
+This additionally gives text editors (and online web syntax
+highlighters) the opportunity to colour syntax-highlight the
+ASCII string (the format) from the variables to be inserted *into*
+that format. gitweb for example (used by this project) cannot
+highlight string-formatted code.
+
+It turns out that colour is processed by the **opposite** hemisphere
+of the brain from written language. Thus, colour-syntax-highlighting
+is not just a "nice-to-have", it's **vital** for easier and faster
+identification of context and an aid to rapid understanding.
+
+Anything that interferes with that - such as python format-strings -
+has to take a back seat, regardless of its perceived benefits.
+
+**If you absolutely must** use python-format-strings, **only** do
+so by restricting to variables. Create temporary variables if you
+have to.
+
+ y = '/'.join(a_list)
+ x = f"{y}"
+
### PEP8 format
* all code needs to conform to pep8. use either pep8checker or better
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.
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/nmigen/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