(no commit message)

[libreriscv.git] / HDL_workflow.mdwn

diff --git a/HDL_workflow.mdwn b/HDL_workflow.mdwn
index 365e18bbc54e0816696dbd9bda3beda470de8690..ef9cdbd4c6e4a003fd8a6e3621c8d1faa8d9698e 100644 (file)
--- a/HDL_workflow.mdwn
+++ b/HDL_workflow.mdwn
@@ -1,7 +1,7 @@
 # HDL workflow
 
 This section describes the workflow and some best practices for developing
-the LibreSoC hardware. We use nmigen, yosys and symbiyosys, and this
+the Libre-SoC hardware. We use nmigen, yosys and symbiyosys, and this
 page is intended not just to help you get set up, it is intended to
 help advise you of some tricks and practices that will help you become
 effective team contributors.
@@ -174,7 +174,8 @@ eight files open *and on-screen* at once, without overlaps i.e. not in
 hidden tabs, next to at least two if not three additional free and clear
 terminals into which commands are regularly and routinely  typed (make,
 git commit, nosetests3 etc).  Illustrated with the following 3840x2160
-screenshot (click to view full image):
+screenshot (click to view full image), where *every one* of those 80x70
+xterm windows is *relevant to the task at hand*.
 
 [[!img 2020-01-24_11-56.png size=640x ]]
 
@@ -272,8 +273,42 @@ testing can then be carried out with "python3 setup.py test"
 
 These are a test suite dependency for the ieee754fpu library, and
 will be changed in the future to use Jacob's algorithmic numeric
-library.  In the meantime the README describing the process is here:
-<https://git.libre-riscv.org/?p=ieee754fpu.git;a=blob;f=README.md;h=d219864a341e4b656680de476e385b6a7f70fb9b;hb=HEAD>
+library.  In the meantime, sfpy can be built as follows:
+
+    git clone --recursive https://github.com/billzorn/sfpy.git
+    cd sfpy
+    cd SoftPosit
+    git apply ../softposit_sfpy_build.patch
+    git apply /path/to/ieee754fpu/SoftPosit.patch
+    cd ../berkely-softfloat-3
+    # Note: Do not apply the patch included in sfpy for berkely-softfloat, 
+    # it contains the same changes as this one
+    git apply /path/to/ieee754fpu/berkeley-softfloat.patch
+    cd ..
+
+    # install dependencies    
+    python3 -m venv .env
+    . .env/bin/activate
+    pip3 install --upgrade -r requirements.txt
+
+    # build
+    make lib -j8
+    make cython
+    make inplace -j8
+    make wheel
+
+    # install
+    deactivate # deactivates venv, optional 
+    pip3 install dist/sfpy*.whl
+
+You can test your installation by doing the following:
+
+    python3
+    >>> from sfpy import *
+    >>> Posit8(1.3)
+
+It should print out `Posit8(1.3125)`
+  
 
 # Registering for git repository access
 
@@ -297,6 +332,31 @@ repos at http://git.libre-riscv.org:
 
     git clone gitolite3@git.libre-riscv.org:REPONAME.git
 
+Alternatively, the .ssh/config can be skipped and this used:
+
+     git clone ssh://gitolite3@git.libre-riscv.org:922/REPONAME.git
+
+# git configuration
+
+Although there are methods online which describe how (and why) these
+settings are normally done, honestly it is simpler and easier to open
+~/.gitconfig and add them by hand.
+
+core.autocrlf is a good idea to ensure that anyone adding DOS-formatted
+files they don't become a pain.  pull.rebase is something that is greatly
+preferred for this project because it avoids the mess of "multiple
+extra merge git tree entries", and branch.autosetuprebase=always will,
+if you want it, always ensure that a new git checkout is set up with rebase.
+
+    [core]
+        autocrlf = input
+    [push]
+        default = simple
+    [pull]
+        rebase = true
+    [branch]
+        autosetuprebase = always
+
 # Checking out the HDL repositories
 
 * mkdir ~/src
@@ -358,6 +418,7 @@ for actual code development:
   **do not** add the actual output of **any** command to the repository.
   ever.  this is really important.  even if it is a human-readable file
   rather than a binary object file.
+  it is very common to add pdfs (the result of running latex2pdf) or configure.in (the result of running automake), they are an absolute nuisance and interfere hugely with git diffs, as well as waste hard disk space *and* network bandwidth. don't do it.
 * if the command needed to create any given autogenerated output is not
   currently in the list of known project dependencies, first consult on
   the list if it is okay to make that command become a hard dependency of
@@ -379,6 +440,7 @@ for actual code development:
   commits, and it actually becomes a nuisance).
 * prior to committing make sure that relevant unit tests pass, or that
   the change is a zero-impact addition (no unit tests fail at the minimum)
+* keep working code working **at all times**. find ways to ensure that this is the case. examples include writing alternative classes that replace existing functionality and adding runtime optiobs to select between old and new code.
 * commit no more than around 5 to 10 lines at a time, with a CLEAR message
   (no "added this" or "changed that").
 * if as you write you find that the commit message involves a *list* of
@@ -410,7 +472,8 @@ it (a large amount of code) is perfectly fine.
 
 as a general rule, however, do not use this an an excuse to write code
 first then write unit tests as an afterthought.  write *less* code *in
-conjunction* with its (more basic) unit tests, instead.
+conjunction* with its (more basic) unit tests, instead. then, folliw up with
+additions and improvements.
 
 the reason for separating out commits to single purpose only becomes
 obvious (and regretted if not followed) when, months later, a mistake