+# Tutorial on how to get into Libre-SOC development
+
+This tutorial is a guide for anyone wishing, literally, to start from
+scratch and learn how to contribute to the Libre-SOC. Much of this you
+should go through (skim and extract) the [[HDL_workflow]] document,
+however until you begin to participate much of that document is not
+fully relevant. This one is intended to get you "up to speed" with
+basic concepts.
+
+Discussions here:
+
+* <http://lists.libre-riscv.org/pipermail/libre-riscv-dev/2020-February/004166.html>
+* <http://lists.libre-riscv.org/pipermail/libre-riscv-dev/2020-March/004804.html>
+
+# Programming vs hardware.
+
+We are assuming here you know some programming language. You know that
+it works in sequence (unless you went to Imperial College in the 80s
+and have heard of [Parlog](https://en.m.wikipedia.org/wiki/Parlog)).
+
+Hardware basically comprises transistor circuits. There's nothing in the
+universe or the laws of physics that says light and electricity have to
+operate sequentially, and consequently all Digital ASICs are an absolutely
+massive arrays of unbelievably excruciatingly tediously low level "gates",
+in parallel, separated occasionally by clock-synchronised "latches" that
+capture data from one processing section before passing it on to the next.
+
+Thus, it is imperative to conceptually remind yourself, at all times,
+that everything that you do, even when writing your HDL code line by line,
+is, in fact, at the gate level, done as massively-parallel processing,
+**not** as sequential processing, at all. If you want "sequential"
+you have to store the results of one parallel block of processing in
+"latches", wait for the clock to "tick", and pass it on to the next block.
+
+ASIC designers avoid going completely off their heads at the level of
+detail involved by "compartmentalising" designs into a huge hierarchy of
+modular design, where the tools selected aid and assist in isolating as
+much of the contextually-irrelevant detail as practical, allowing the
+developer to think in relevant concepts without being overwhelmed.
+
+Understanding this is particularly important because the level of
+hierarchy of design may be *one hundred* or more modules deep *just in
+nmigen alone*, (and that's before understanding the abstraction that
+nmigen itself provides); yosys goes through several layers as well,
+and finally, alliance / corilolis2 have their own separate layers.
+
+Throughout each layer, the abstractions of a higher layer are removed
+and replaced with topologically-equivalent but increasingly detailed
+equivalents. nmigen has the *concept* of integers (not really: it has
+the concept of something that, when the tool is executed, will create
+a representation *of* an integer), and this is passed through intact to
+yosys. yosys however knows that integers need to be replaced by wires,
+buses and gates, so that's what it does.
+
+Thus, you can think safely in terms of "integers" when designing and
+writing the HDL, confident that the details of converting to gates and
+wires is taken care of.
+
+It is also critically important to remember that unlike a software
+environment there is no memory or stack, only if you create an actual SRAM
+and lay out the gates to address it with a binary to unary selector. There
+is no register file unless you actually create one. There is no ALU unless
+you make one... and so on. And beyond that hardware, if you forget to
+add something that might be needed for exceptional purposes, if it's
+not there you simply cannot add it later like you can in software. If
+it's not there, it's not there and that's the end of the discussion.
+Consequently a vast amount of time goes into planning and simulation
+(software, FPGA and SPICE) as mistakes and omissions can literally cost
+tens of millions of dollars to rectify.