fill-in build_system section

Signed-off-by: Michel-FK <michel.stempin@funkey-project.com>

docs/developer_guide/software_reference/boot_process/spl.md

@@ -1,3 +1,23 @@
+The SPL is the Secondary Program Loader (the Primary Program Loader
+being the code in the [Boot ROM][1]), it is the first
+user-customizable piece of code run on the CPU.
+
+The SPL is built as part of the U-Boot bootlader. Actually, it shares
+most of its code with it.
+
+The SPL is loaded by the Boot ROM at address `0x00000000` in SRAM A1
+and C, and has a maximum size of 32KB. It contains a "**BOOT0
+Header**" that has been checked previously by the Boot ROM, and its
+byte at offset 40 has been updated with the SD card interface used to
+boot, with its bit 5 set to `1` if it was loaded from offset 128KB
+from the SD Card, or `0` if was loaded from offset 8KB.
+
+The role of the SPL stage is to set up the CPU clocks to their nominal
+speeds and set up the main SDRAM memory in order to load into it the
+next boot stage: either the U-Boot bootloader or the Linux kernel, as
+these are too large to fit into the small SRAM memory.
+
+[1]: ../boot_rom
 
 --8<--
 includes/glossary.md

docs/developer_guide/tutorials/build_system/compilation_environments.md

@@ -1,3 +1,106 @@
+Even if the resulting disk image and firmware update files are
+relatively small (202 MB and 55MB, respectively), the size of the
+corresponding sources and the compilation by-products tend to be
+rather large, such that an available disk space of at least 12GB is
+required during the build.
+
+And even if the resulting FunKey-OS boots in less than 5s, it still
+requires a considerable amount of time to compile: please account for
+1 1/2 hour on a modern multi-core CPU with SSD drives and a decent
+Internet bandwidth.
+
+The FunKey-OS is meant to be built on a native Ubuntu or Debian Linux
+host machine (Ubuntu 20.04 LTS in our case, but this should also work
+with other versions, too). And with only a few changes to the
+prerequisites, it can certainly be adapted to build on other common
+Linux distros.
+
+However, if your development machine does not match this setup, there
+are still several available solutions:
+
+ -  use a lightweight container system such as [Docker][1] and run an
+    Ubuntu or Debian Linux container in it
+
+ - use a VM (Virtual Machine), such as provided by [VirtualBox][2] and
+   run an Ubuntu or Debian Linux in it
+
+ - for Windows 10 users, use the [WSL2][3] (Windows System for Linux
+   2) subsystem and run an Ubuntu Linux distro in it
+
+In order to install one of these virtualized environments on your
+machine, please refer to the corresponding documentation.
+
+## Build on a Physical/Virtual Machine
+
+### Prerequisites
+
+While Buildroot itself will build most host packages it needs for the
+compilation, some standard Linux utilities are expected to be already
+installed on the host system. If not already present, you will need to
+install the following packages beforehand:
+
+ - bash
+ - bc
+ - binutils
+ - build-essential
+ - bzip2
+ - ca-certificates
+ - cpio
+ - cvs
+ - expect
+ - file
+ - g++
+ - gcc
+ - git
+ - gzip
+ - liblscp-dev
+ - libncurses5-dev
+ - locales
+ - make
+ - mercurial
+ - openssh-client
+ - patch
+ - perl
+ - procps
+ - python
+ - python-dev
+ - python3
+ - python3-dev
+ - python3-distutils
+ - python3-setuptools
+ - rsync
+ - rsync
+ - sed
+ - subversion
+ - sudo
+ - tar
+ - unzip
+ - wget
+ - which
+ - xxd
+
+On Ubuntu/Debian Linux, this is achieved by running the following
+command:
+
+```bash
+$ sudo apt install bash bc binutils build-essential bzip2 ca-certificates cpio cvs expect file g++ gcc git gzip liblscp-dev libncurses5-dev locales make mercurial openssh-client patch perl procps python python-dev python3 python3-dev python3-distutils python3-setuptools rsync rsync sed subversion sudo tar unzip wget which xxd
+```
+
+## Build in a Docker Container
+
+### Prerequisites
+
+When using a Docker container, all the prerequisites are automatically
+installed.
+
+## Build on Windows 10 with WSL2
+
+### Prerequisites
+
+
+[1]: https://www.docker.com/
+[2]:https://www.virtualbox.org/
+[3]: https://docs.microsoft.com/en-us/windows/wsl/install-win10
 
 --8<--
 includes/glossary.md

docs/developer_guide/tutorials/build_system/compile_distribution.md

@@ -1,3 +1,64 @@
+## On a Physical Machine / In a Virtual Machine
+
+You may now build your FunKey with:
+
+```bash
+$ make sdk all
+```
+This may take a while (~1h30), so consider getting yourself
+a cup, a glass or a bottle of your favorite beverage ;-)
+
+<ins>Note</ins>: you will need to have access to the network, since
+buildroot will download the package sources.
+
+After building, you should obtain the SD Card image
+`FunKey-sdcard-X.Y.Z.img`, the SDK file `FunKey-sdk-X.Y.Z.tar.gz` and
+the firmware update file `FunKey-rootfs-X.Y.fwu` in the `images`
+directory.
+
+## In a Docker Container
+
+You may now build your FunKey with:
+
+```bash
+$ docker run --name funkey-os funkeyproject/funkey-os
+```
+
+Or alternatively, you can run it in the background with:
+
+```bash
+$ docker run -d --name funkey-os funkeyproject/funkey-os
+```
+
+If you launch it in the background, you can still follow what is going
+on with either:
+
+```bash
+$ docker top funkey-os
+```
+Or:
+
+```bash
+$ docker logs funkey-os
+```
+
+This may take a while (~1h30), so consider getting yourself a cup, a
+glass or a bottle of your favorite beverage ;-)
+
+<ins>Note</ins>: you will need to have access to the network, since
+buildroot will download the package sources.
+
+After building, you can copy the SD Card image `sdcard.img`, the SDK
+file `FunKey-sdk-X.Y.tar.gz` and the firmware update file
+`FunKey-rootfs-X.Y.fwu` from the container into the host current
+directory:
+
+```bash
+$ mkdir images
+$ docker cp funkey-os:/home/funkey/FunKey-OS/images/FunKey-sdcard-X.Y.Z.img images/
+$ docker cp funkey-os:/home/funkey/FunKey-OS/images/FunKey-sdk-X.Y.Z.tar.gz images/
+$ docker cp funkey-os:/home/funkey/FunKey-OS/images/FunKey-rootfs-X.Y.Z.fwu images/
+```
 
 --8<--
 includes/glossary.md

docs/developer_guide/tutorials/build_system/compile_sdk.md

@@ -1,3 +1,65 @@
+Starting from version 2.0.0, the pre-compiled FunKey SDK is available
+on [Github][1], and it is also compiled automatically as a first step
+when building the [full FunKey-OS distribution][2].
+
+However, if you want to compile the SDK only, here are the
+instructions below:
+
+## On a Physical Machine / In a Virtual Machine
+
+You may now build the SDK with:
+
+```bash
+$ make sdk
+```
+
+This may take a while (~1h), so consider getting yourself
+a cup, a glass or a bottle of your favorite beverage ;-)
+
+<ins>Note</ins>: you will need to have access to the network, since
+buildroot will download the package sources.
+
+After building, you should obtain the SDK file
+`FunKey-sdk-X.Y.Z.tar.gz` in the `images` directory.
+
+## In a Docker Container
+
+You may now build your FunKey with:
+```bash
+$ docker run --name funkey-os funkeyproject/funkey-os make sdk -C /home/funkey/FunKey-OS
+```
+
+Or alternatively, you can run it in the background with:
+```bash
+$ docker run -d --name funkey-os funkeyproject/funkey-os make sdk -C /home/funkey/FunKey-OS
+```
+
+If you launch it in the background, you can still follow what is going on with either:
+```bash
+$ docker top funkey-os
+```
+Or:
+
+```bash
+$ docker logs funkey-os
+```
+
+This may take a while (~1h), so consider getting yourself a cup, a
+glass or a bottle of your favorite beverage ;-)
+
+<ins>Note</ins>: you will need to have access to the network, since
+buildroot will download the package sources.
+
+After building, you can copy the SDK file `FunKey-sdk-X.Y.tar.gz` from
+the container into the host current directory:
+
+```bash
+$ mkdir images
+$ docker cp funkey-os:/home/funkey/FunKey-OS/images/FunKey-sdk-X.Y.Z.tar.gz images/
+```
+
+[1]: https://github.com/FunKey-Project/FunKey-OS/releases/
+[2]: ../compile_distribution
 
 --8<--
 includes/glossary.md

docs/developer_guide/tutorials/build_system/get_sources.md

@@ -0,0 +1,38 @@
+## On a Physical Machine / In a Virtual Machine
+
+When using either physical Linux machine or virtual Linux machines
+(VirtualBox or WSL2), you must clone the FunKey OS repository from
+Github (here we place it into a `FunKey-OS` directory):
+
+```bash
+$ git clone https://github.com/FunKey-Project/FunKey-OS.git FunKey-OS
+```
+
+Then enter into the newly created directory:
+
+```bash
+$ cd FunKey-OS
+```
+## In a Docker Container
+
+When using a Docker container, you must first create a new directory
+(here we create a `FunKey-OS` directory) and get the FunKey-OS
+[Dockerfile][1] in it:
+
+```bash
+$ mkdir FunKey-OS
+$ cd FunKey-OS
+$ wget https://raw.githubusercontent.com/FunKey-Project/FunKey-OS/master/docker/Dockerfile -o Dockerfile
+```
+
+You must then build the docker image (don't forget the final dot!):
+
+```bash
+$ docker build -t funkeyproject/funkey-os .
+```
+
+[1]: https://github.com/FunKey-Project/FunKey-OS/blob/master/docker/Dockerfile
+
+--8<--
+includes/glossary.md
+--8<--

docs/developer_guide/tutorials/build_system/index.md

@@ -1,3 +1,46 @@
+The **FunKey-S** console is based on a sophisticated [Allwinner V3s
+ARM Cortex-A7 1.2GHz CPU][2], an Operating System is mandatory in
+order to access all the hardware resources without re-inventing the
+wheel.
+
+Programs made for other computers will not work on the **FunKey S**,
+and developing programs on the **FunKey S** itself is rather
+impractical (too slow, not enough RAM, etc.).
+
+Instead, development for embedded devices like the **FunKey S** uses a
+method known as [cross compilation][2] for building software on a host
+platform (such as a desktop computer) to be used on another target
+platform (like the **FunKey S**).
+
+The [FunKey-OS repository on Github][3] contains all the sources
+required to build the Open-Source firmware at the heart of the [FunKey
+S retro-gaming console][4].
+
+This repository also contains a standalone SDK, which is a
+cross-compilation environment based on the GNU GCC compiler and
+binutils binary object tools, including the compiler toolchain and all
+the required libraries available on the **FunKey S** in order to build
+software for it.
+
+FunKey-OS is based on Linux, and is built from scratch using the
+[buildroot][5] tool that simplifies and automates the process of
+building a complete Linux system for an embedded system like this.
+
+Technically speaking, Funkey-OS is a [buildroot (v2) based external
+tree][6] for building the bootloader, the Linux kernel and user
+utilities, as well as the optimized retro-game launchers and console
+emulators.
+
+For detailed explanations on how to use buildroot itself, please refer
+to the [Buildroot Manual][7].
+
+[1]: http://www.allwinnertech.com/index.php?c=product&a=index&id=38
+[2]: https://en.wikipedia.org/wiki/Cross_compiler
+[3]: https://github.com/FunKey-Project/FunKey-OS
+[4]: https://www.funkey-project.com/
+[5]: http://nightly.buildroot.org/
+[6]: (https://buildroot.org/downloads/manual/manual.html#outside-br-custom)
+[7]: https://buildroot.org/downloads/manual/manual.html
 
 --8<--
 includes/glossary.md

docs/developer_guide/tutorials/build_system/write_image.md

@@ -0,0 +1,32 @@
+## How to Flash the Firmware to the SD Card
+
+You can copy the bootable `images/sdcard.img` onto an SD card using
+"dd":
+
+```bash
+$ sudo dd if=images/FunKey-sdcard-X.Y.Z.img of=/dev/sdX
+```
+<ins>Warning</ins>: Please make sure that */dev/sdX* device
+corresponds to your SD Card, otherwise you may wipe out one of your
+hard drive partitions!
+
+Alternatively, you can use the Balena-Etcher graphical tool to burn
+the image to the SD card safely and on any platform:
+
+https://www.balena.io/etcher/
+
+Once the SD card is burnt, insert it into the **FunKey S** console
+slot, and power it up. Your new system should come up now and start a
+console on the UART0 serial port and display the RetroFE game launcher
+on the graphical screen.
+
+## How to Update the FunKey S Firmware
+
+It is possible to update the **FunKey-S** over USB, please follow the
+steps described in the [Firmware Upgrade][1] section.
+
+[1]: /user_manual/tutorials/software/firmware_update/
+
+--8<--
+includes/glossary.md
+--8<--

mkdocs.yml

@@ -201,8 +201,10 @@ nav:
       - Build System:
         - 'developer_guide/tutorials/build_system/index.md'
         - 'Compilation Environments': 'developer_guide/tutorials/build_system/compilation_environments.md'
+        - 'Get the Sources': 'developer_guide/tutorials/build_system/get_sources.md'
         - 'Compile SDK': 'developer_guide/tutorials/build_system/compile_sdk.md'
         - 'Compile Distribution': 'developer_guide/tutorials/build_system/compile_distribution.md'
+        - 'Write firmware to SD Card': 'developer_guide/tutorials/build_system/write_image.md'
       - 'Build Programs using SDK': 'developer_guide/tutorials/build_system/build_program_using_sdk.md'
   - Miscellaneous:
     - 'Glossary': 'miscellaneous/glossary.md'