(no commit message)

[libreriscv.git] / HDL_workflow.mdwn

diff --git a/HDL_workflow.mdwn b/HDL_workflow.mdwn
index c97d9efdb47b3d0e684e2318497a50a78bbe2c1c..b48749a0bf57fbba8601533f573be20536a31986 100644 (file)
--- a/HDL_workflow.mdwn
+++ b/HDL_workflow.mdwn
@@ -33,7 +33,7 @@ either actively prevents or makes that much harder.
 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**)
@@ -109,7 +109,8 @@ on the server, that is a high security risk, and i'm not doing it. sorry.)
 ### 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.
 
@@ -438,20 +439,27 @@ 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
@@ -462,37 +470,25 @@ unpack it, then:
 programs.  [qemu](https://www.qemu.org/) emulates processors, you can
 run programs under qemu.
 
-## power_instruction_analyzer (pia)
+## power-instruction-analyzer (pia)
 
-We have a custom tool built in rust by programmerjake to help analyze
-the power instructions execution on *actual* hardware.
+We have a custom tool built in Rust by programmerjake to help analyze
+the OpenPower instructions' execution on *actual* hardware.
 
-Note: a very recent version of pip3 is required for this to work.
-
-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
 
@@ -572,7 +568,7 @@ cocotb is a COroutine based COsimulation TestBench environment for verifying VHD
 
 See [[HDL_workflow/cocotb]] page for installation instructions.
 
-# Registering for git repository access
+# 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
@@ -598,6 +594,16 @@ Alternatively, the .ssh/config can be skipped and this used:
 
      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