(no commit message)

[libreriscv.git] / HDL_workflow.mdwn

diff --git a/HDL_workflow.mdwn b/HDL_workflow.mdwn
index 1d36b9f503f111f14a16b83580eb251171e0b4f4..0d42fe402992181e34983ad97bc6e5e394d965c2 100644 (file)
--- a/HDL_workflow.mdwn
+++ b/HDL_workflow.mdwn
@@ -126,6 +126,8 @@ send this to Spam" option.
 
 ## 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.
 
@@ -133,6 +135,8 @@ Please do not ask for the project to be transferred to github or other
 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,
@@ -389,7 +393,7 @@ flows.
 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 !$
@@ -413,6 +417,7 @@ In the meantime, sfpy can be built as follows:
 
     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
@@ -1158,6 +1163,71 @@ Simply mark it with an appropriate
 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.
 
+## Liskov Substitution Principle
+
+* [Wikipedia entry](https://en.wikipedia.org/wiki/Liskov_substitution_principle)
+* [Stackoverflow answer on LSP](https://stackoverflow.com/questions/56860/what-is-an-example-of-the-liskov-substitution-principle)
+* [Article on LSP](https://reflectoring.io/lsp-explained/)
+
+Copying from Wikipedia:
+
+```
+The Liskov substitution principle (LSP) is a particular definition of a
+subtyping relation, called strong behavioral subtyping, that was initially
+introduced by Barbara Liskov in a 1987 conference keynote address titled
+Data abstraction and hierarchy. It is based on the concept of
+"substitutability" - a principle in object-oriented programming stating
+that an object (such as a class) may be replaced by a sub-object (such as
+a class that extends the first class) without breaking the program.
+It is a semantic rather than merely syntactic relation, because it intends
+to guarantee semantic interoperability of types in a hierarchy, object
+types in particular.
+```
+
+To paraphrase: an *original object/class may be replaced with another object*
+(whose class extends the first class) *without breaking* the program.
+
+Python is a programming language which makes using LSP pretty straightforward.
+
+In LibreSOC, we aim to follow this principle whenever possible and (bearing
+time and budget constraints).
+
+*(Luke, please include some examples from LibreSOC source here)*
+
+## Principle of Least Astonishment/Surprise (POLA)
+
+* Example shown by Luke on
+[comment #33 bug #1039](https://bugs.libre-soc.org/show_bug.cgi?id=1039#c33)
+* [Wikipedia entry](https://en.wikipedia.org/wiki/Principle_of_least_astonishment)
+* Example answer on
+[software eng. stack exchange](https://softwareengineering.stackexchange.com/questions/187457/what-is-the-principle-of-least-astonishment)
+
+Wikipedia mentions that the origin of the term "Principle of Least
+Astonishment" (or Surprise) comes from a PL/I programming language bulletin
+board from 1957:
+
+```
+For those parts of the system which cannot be adjusted to the peculiarities
+of the user, the designers of a systems programming language should obey
+the "Law of Least Astonishment." In short, this law states that every construct
+in the system should behave exactly as its syntax suggests. Widely accepted
+conventions should be followed whenever possible, and exceptions to previously
+established rules of the language should be minimal.
+```
+
+If a method name has a prefix `test_` it should be a unit test (or some other
+test which is there to check the functionality of a given feature).
+
+A method/function (or attributes/variables, etc.) *shouldn't* be given a name
+which is wildly different from the what the user would expect it to do.
+
+*Andrey*: One example which may meet this rule is `TestIssuer`,
+which is the FSM-based nMigen HDL CPU core used by LibreSOC (so far).
+It is so called because it is used to issue unit tests (while also
+being synthesisable). This name was however was initially confusing
+to me, because my background is in hardware not software engineering.
+
+
 # Task management guidelines
 
 1. Create the task in appropriate "Product" section with appropriate