Merge branch 'source' of https://github.com/FunKey-Project/FunKey-Project.github.io into source

docs/developer_guide/software_reference/boot_process/boot_rom.md

@@ -0,0 +1,455 @@
+According to the [Allwinner V3s datasheet][1], the integrated boot
+system consists in a 32KB boot ROM mapped at addresses
+`0xffff0000-0xffff7fff`, that can boot from SPI NOR Flash, SPI NAND
+Flash, SD Card and USB.
+
+In Allwinner terminology, this boot ROM is called "**BROM**" (for
+"Boot ROM") or "**eGON.BRM**" (for "Embedded GO-ON Bootloader Boot
+ROM", who knows what this means exactly?).
+
+But in [another place][2] in the same datasheet, it is stated that it
+can boot from eMMC, too.
+
+!!! failure "Wrong!"
+
+    **We found that the available information is either incomplete,
+    inacurate, misleading or completely false**.
+
+What triggered our suspicion was this first mismatch and the lack of
+details regarding the boot process: not a single explanation on the
+boot firmware format and/or exact location.
+
+The original [v3s_lichee.zip][3] SDK is not very helpful in this regard.
+
+Hopefully, as Allwinner tends to use a rather consistent similar boot
+process for all its SoCs, the [lichee-v2.0.tar.gz][4] from Olimex is
+actually giving some clues, albeit it does not mention the V3s.
+
+But the best source of information on the Allwinner chips is certainly
+the [sunxi community][5], that is dedicated to gather information
+around the Allwinner SoCs.
+
+And although it describes in details the Allwinner A10/A20 and A31
+chips and not the V3s, their [BROM page][6] is a golden mine.
+
+The [A20-V1.2.tar.gz][7] SDK from Olimex is also relevant, as it
+contains some original source code for the Allwinner A20 SoC
+bootloader.
+
+Eventually, in order to clear all doubts regarding the Boot ROM role,
+we had to reverse-engineer the Allwinner V3s Boot ROM by disassembling
+its source code. The current findings are available in our repository,
+in the "[brom.s][8]" file, with our comments added:
+
+https://github.com/FunKey-Project/Allwinner-V3s-BROM
+
+## Power-On Reset (POR)
+
+As it is common to all ARM Cortex-A architecture CPUs, the Allwinner
+V3s fetches the first instruction to execute from the first 32-bit
+word in a vector table located at address `0xffff0000`.
+
+On the V3s, this location is the [first 32-bit word][11] in the Boot
+ROM, that contains as its first vector a branch instruction to the
+`reset` [function][12]", located immediately after the vector table.
+
+And except for the [irq vector][14] that contains a branch instruction
+to the [first-level routine handling interrupt request][15], all other
+standard ARM vectors only contain a branch to a "[forever loop][16]"
+as they are not implemented at this stage.
+
+!!! note
+
+    A non-standard ["FEL" vector][17] is appended at the end of the
+    vector table.
+
+    This provides an indirect way to access the FEL code,
+    allowing to change its actual location while keeping the ability
+    to address it using a fixed location.
+
+## Reset Function
+
+The `reset` [function][12] is the first useful piece of code executed
+on the CPU.
+
+At this point, the only known-working hardware is the CPU 24 MHz clock
+derived from the external crystal, the CPU itself and its internal
+registers which may not even be initialized.
+
+### Register Initialization
+
+This is the role of the short `reset` [function][12] that clears all
+CPU registers (except r0 that is set to `1`) and jumps to the actual
+BROM header first 32-bit word.
+
+### BROM Header
+
+The [BROM location][18] contains a "BROM header" structure made up of:
+
+ - a 32-bit word branch instruction that jumps to the `start`
+   [function][13]
+
+ - an ASCII magic signature "**eGON.BRM**"
+
+ - a header length in bytes (32)
+
+ - a boot version in ASCII ("1100" for version 1.1.00)
+
+ - an eGON version in ASCII ("1100" for version 1.1.00)
+
+ - a platform information in ASCII ("1681" for the V3s)
+
+ - a 32-bit word padding
+
+## Start Function
+
+The `start` [function][13] role is to setup a minimal execution
+environment with a call stack, using the internal static RAM A1 and C
+memory.
+
+### BROM Output Pin Toggling
+
+We found that the [first step][19] of the `start` function consists in
+toggling an unidentified "BROM Output" pin.
+
+This guess is based on the fact that, according to the [H6 User
+Manual][20] which has a register with similar offset (`0xa4`) in its
+system configuration block, it is indeed `BROM_OUTPUT_REG`, and its
+bit 0 is `BROM_OUTPUT_ENABLE`, and bit 1 is `BROM_OUTPUT_VALUE`.
+
+!!! tip
+
+    If this pin is actually available, this would allow to check with
+    an oscilloscope if the CPU is running or not, but we were not able
+    to locate it.
+
+### Multi-CPU Check
+
+The second step in the `start` function is to [check for
+multi-CPUs][21]. This is unlikely to do anything, as the V3s only
+contains a single CPU, but the code is probably here for compatibility
+with other multi-core SoCs.
+
+### Start CPU #0
+
+The third step in the `start` function is to [initialize the CPU #0
+operating mode][22]:
+
+ - define the system as an ARMv4+ architecture
+
+ - set the CPU #0 in SVC (supervisor) mode
+
+ - disable both normal IRQ and fast FIRQ interrupt requests
+
+ - set the system as little-endian
+
+### Disable Memory Access Features
+
+The next step in the `start` function is to [disable all kind of
+memory access optimization features][23]:
+
+ - disable the MMU
+
+ - disable the data cache (D-Cache)
+
+ - disable the program flow prediction and the instruction cache
+   (I-Cache)
+
+### Disable Watchdog
+
+The next step in sequence in the `start` function is to [disable the
+watchdog][24].
+
+!!! tip
+
+    However, this is described in the datasheet as having "no effect"?
+
+    It may be a _write-once_ capability that is disabled when written
+    anything but zeros.
+
+### Configure Internal System Bus Clocks
+
+The clocks for the AHB1 (Advanced High-speed Bus \#1) and APB1
+(Advanced Peripheral Bus \#1) [bus clocks are set up][25] to enable
+access to most of the internal peripheral controllers, except UART,
+TWI that are on APB2 bus and EMAC and USB that are on AHB2 bus, as can
+be seen in the diagram below:
+
+![System Bus Tree](/assets/images/System_Bus.png){.lightbox}
+
+!!! bug
+
+    In the above diagram taken from the datasheet, the BROM looks like
+    is located on the APB1 bus, which is certainly not possible, as
+    the system already accesses it before enabling its clock!
+
+### Initialize DMA and PIO
+
+In the [next step][26] in the `start` function:
+
+ - the DMA engine is enabled
+
+ - the PIO (Peripheral I/O) controller is enabled to access external
+   pins
+
+ - the DMA engine is reset
+
+### Initialize Stack Pointer in SRAM A1
+
+At this stage, the 16KB SRAM A1 is available at addresses
+`0x00000000-0x00003fff`, so a [first stack pointer is initialized at the
+top of SRAM A1 memory][27].
+
+### Resume from Standby Mode
+
+A [check][28] is then performed to see if the CPU is resuming from
+standby mode.
+
+!!! hint
+
+    This standby mode is not documented anywhere!
+
+If yes, a jump to the `resume_from_standby` [function][29] is done,
+where further checking is performed on the resume header:
+
+ - check for a "**eGON.BT0**" signature at an address `0x01f01da8`
+   that is suspected to be a "**standby resume entry address
+   register**"
+ 
+ - check if the resume address the follows the signature is valid (if
+    its 10 MSB bits are all zeros)
+
+ - verify the header checksum
+
+If all these checks passed, the resume entry point is called,
+otherwise a call to the `boot` [function][33] is performed to try to
+resume the normal boot sequence.
+
+!!! bug
+
+    However, the normal boot sequence will not be able to continue, as
+    the next steps to enable the SRAM C block are skipped, so this is
+    expected to fail!
+
+### Enable SRAM C
+
+In the next to final step of the `start` function, the SRAM C (44 KB)
+is enabled at addresses `0x00004000-0x000efff`:
+
+ - first, [an undocumented register in System Control block is
+   cleared][30], that is suspected to enable SRAM C access to the CPU
+   and the DMA
+
+ - Then [the Video Engine (VE) is started][31] by enabling its clock
+   and reseting it. It is suspected that the reason it is done here is
+   because the SRAM C block is tied to the Video Engine function
+
+### Initialize Stack Pointer in SRAM C
+
+In the last step of the `start` function, the [stack pointer is set
+4KB below the end of SRAM C][32] (address `0x0000dffc`), before calling
+the final `boot` [function][33].
+
+## Boot Function
+
+The role of the `boot` [function][33] is to implement the boot sequence
+described in the datasheet:
+
+![Boot Sequence](/assets/images/Boot_Sequence.png){.lightbox}
+
+!!! failure "Wrong!"
+
+    **However, we found out that this diagram is inacurate!**
+
+### Check UBoot Button
+
+The first step in the `boot` function is to check if an "UBoot button"
+is pressed by calling the `check_uboot` [function][34].
+
+!!! note
+
+    Here, "UBoot" stands for "USB Boot", it has nothing to do whith
+    "Das U-Boot" bootloader!
+
+However, as the `check_uboot` function uses a special register to
+check the input pin rather than the standard PIO controller, it is not
+possible to determine from the code which pin is actually involved.
+
+We are not aware of any pin on the V3s that has this capability,
+although we suspected the PF6 pin (pin 100) to have this function as
+it has no alternate function like all the other pins, but this is not
+the case: pulling this pin to GND during the boot process has no
+effect, so likely, this function is not implemented on the V3s.
+
+If this hypothetical button is pressed during the boot sequence, the
+`boot` function would branch directly to the FEL USB Boot code,
+bypassing the normal boot process.
+
+### Boot from Flash Memory
+
+Unlike what is describe in the control flow diagram above, the V3s
+search order for the Flash memory to boot from is actually the
+following:
+
+ 1. SD Card on SDC0 interface
+
+ 2. eMMC chip on SDC2 interface
+
+ 3. SD Card on SDC2 interface
+
+ 4. NOR Flash chip on SPI interface
+
+ 5. NAND Flash chip on SPI interface
+
+For all Flash memory types, the boot process is similar:
+
+ - read one 512 byte block at address `0x00000000` from the Flash
+   device to get a "**BOOT0 Header**"
+
+ - check the "**eGON.BT0**" signature at the very beginning of the
+   loaded block using the `check_magic` [function][35] ([example for
+   booting from MMC0][36])
+
+ - check the length field at offset 16: the second stage bootloader
+   length must be < 32KB (0x8000), [example for booting from MMC0][37]
+
+ - check if the length field bits 24:31 are null (which is always true
+   anyway because of the test above, [example for booting from
+   MMC0][38])
+
+ - perform 2 attempts to read the required number of 512-byte blocks
+   for the specified length and load them at address `0x00000000` from
+   the Flash device (it looks like the first block is re-read,
+   [example for booting from MMC0][39]). The reason to perform 2
+   attempts is unknown
+
+ - eventually, jump to the `.boot_spl` [function][40], which:
+
+    - loads `0xfc` into register r1 and `0x0` into register r0
+
+    - calls the `jump_spl` [function][41] that:
+
+      - saves the r0 contents to r4
+
+      - calls in turn the `jump_to` [function][42] that:
+ 
+        - loads r0 into the program counter and never returns,
+          actually launching the loaded SPL (Secondary Program Loader)
+          at address `0x00000000` in SRAM A1 and C
+
+If no bootable Flash memory is found, the `boot` function will branch
+to the FEL USB Boot code.
+
+### Booting from SD Card
+
+As on the **FunKey S** the only available Flash memory to boot from is
+the SD Card, we will focus on this one and ignore the other devices.
+
+The only SD Card specificity regarding the boot process is that the
+BOOT0 header above is fetched from 2 byte-offsets from the beginning
+of the card:
+
+ - [at offset 8KB][43]
+
+ - [at offset 128KB][44]
+
+The reason why these particular offsets were chosen is unknown, but
+they are not very convenient for card following a standard
+partitioning scheme:
+
+ - the 8KB offset falls in the middle of the Primary GPT in a GUID
+   Partition Table scheme. As most SD Card are optimized in hardware
+   for the old MBR scheme, it is not critical
+
+ - both offsets fall within the first 1GB on the disk, which is most
+   of the time not allocated for disk partitions, so they require
+   specific tools to access them
+
+On the **FunKey S**, the 8KB offset is used for the SPL, detailed in
+the next section.
+
+The SD Card interface used (0 or 2) is stored into the BOOT0 header in
+the byte at offset 40, and bit 5 in this byte is set to `1` when the
+BOOT0 header is loaded from offset 128 KB, and to `0` when booted from
+offset 8KB by this [code][45].
+
+## FEL
+
+The FEL is a low-level subroutine also contained in the BootROM on
+Allwinner devices. It is used for initial programming and recovery of
+devices using USB.
+
+The FEL is actually implementing a tiny USB stack for a [proprietary
+USB protocol][46] different from the standard DFU (Device Firmware
+Update) protocol used by many other devices.
+
+Using some specific tools on the host computer, it is possible to read
+or write data to/from the device over USB and execute code on it,
+providing a way to boot the system over USB.
+
+These "sunxi-tools" are described [here][47] and [here][48].
+
+!!! warning
+
+    For the V3s, it is mandatory to build the version from the
+    [repository][49], as the versions packaged in the different
+    operating systems are too old and do not take into account the V3s
+    chip.
+
+Using the "sunxi-tools" and the built-in FEL mode from the BootROM, it
+is possible to boot the V3s CPU over USB without any attached Flash
+storage.
+
+--8<--
+includes/glossary.md
+--8<--
+
+[1]: https://linux-sunxi.org/images/2/23/Allwinner_V3s_Datasheet_V1.0.pdf#page=60
+[2]: https://linux-sunxi.org/images/2/23/Allwinner_V3s_Datasheet_V1.0.pdf#page=41
+[3]: https://drive.google.com/file/d/0BwAsAOITzQTGb2hSeXp3WE1qeGM/view?usp=sharing
+[4]: http://dl.linux-sunxi.org/users/tsvetan/ANDROID-4.2.2-SDK2.0-KERNEL-3.4/lichee-v2.0.tar.gz
+[5]: https://linux-sunxi.org/Main_Page
+[6]: https://linux-sunxi.org/BROM
+[7]: http://dl.linux-sunxi.org/users/tsvetan/A20-SDK-V1.2/A20-V1.2.tar.gz
+[8]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s
+[9]: https://forum.armbian.com/topic/3033-h3-soc-boot-rom-security-e-fuse/?tab=comments#comment-76971
+[10]: https://linux-sunxi.org/SID_Register_Guide#LCJS
+[11]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L2
+[12]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L16-L31
+[13]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3015
+[14]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L8
+[15]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L34-L38
+[16]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L12-L13
+[17]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L10
+[18]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L2994
+[19]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3015-L3084
+[20]: https://linux-sunxi.org/images/4/46/Allwinner_H6_V200_User_Manual_V1.1.pdf#page=239
+[21]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3086-L3100
+[22]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3102-L3109
+[23]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3111-L3115
+[24]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3117-L3121
+[25]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3123-L3130
+[26]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3132-L3146
+[27]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3148-L3149
+[28]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3151-L3158
+[29]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3288-L3317
+[30]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3160-L3164
+[31]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3166-L3182
+[32]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3184-L3187
+[33]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3219
+[34]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L7037-L7063
+[35]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L7133-L7158
+[36]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3688-L3692
+[37]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3698-L3701
+[38]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3702-L3705
+[39]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3711-L3728
+[40]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3284-L3286
+[41]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3210-L3215
+[42]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L7267-L7268
+[43]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3792-L3799
+[44]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3801-L3807
+[45]: https://github.com/FunKey-Project/Allwinner-V3s-BROM/blob/main/brom.s#L3740-L3756
+[46]: https://linux-sunxi.org/FEL/Protocol
+[47]: https://linux-sunxi.org/FEL/USBBoot
+[48]: https://linux-sunxi.org/Sunxi-tools
+[49]: https://github.com/linux-sunxi/sunxi-tools

docs/developer_guide/software_reference/boot_process/index.md

@@ -1,3 +1,65 @@
+!!! quote
+
+    _Analyzing the boot processes of systems that are functioning well
+    prepares users and developers to deal with the inevitable
+    failures._
+
+    _Alison Chaiken in "[Analyzing the Linux boot process][1]"_
+
+Learning how the **FunKey S** boots and shuts down is not required in
+order to develop for this platform, but it is certainly an interesting
+experience in order to understand the way to optimize a Linux embedded
+system.
+
+And then, when something goes wrong, it provides some useful insight
+on where to find the solution...
+
+## Startup Process
+
+The startup process for a Linux machine is like a space rocket launch,
+but in reverse order: you start small and end up big, each stage
+helping to launch the next one.
+
+The reason for this is because many resources are involved when
+booting a Linux system, that require a significant amount of set up
+before you can use them, as they are not available right from the
+beginning; the most critical ones are probably memory and system
+clocks.
+
+When the **FunKey S** is started, its CPU is merely as powerful as an
+Arduino board: what is available is a 32-bit ARM CPU running @ 24MHz,
+with no reliable memory besides its 30 internal registers and a 32KB
+boot ROM.
+
+In order to get up to full speed (1.2GHz) and with all its memory
+(64MB DRAM, access to the 8GB SDcard) requires several steps, in
+order:
+
+ - The [Boot ROM][2]
+
+ - The [SPL][3] (Secondary Program Loader)
+
+ - The [U-Boot bootloader][4]
+
+ - The [Linux kernel][5]
+
+ - The userland [System V init scripts][6]
+
+## Shutdown Process
+
+Unlike the startup process, the [shutdown process][7] is much more
+straightforward, but it must be optimized to run as quiclky as
+possible, as the time from when the shutdown is initiated when the
+user press the <i class="funkey-menu"></i> key or close the **FunKey
+S** lid to actual poweroff is extremely short (3 s).
+
+[1]: https://opensource.com/article/18/1/analyzing-linux-boot-process
+[2]: boot_rom
+[3]: spl
+[4]: bootloader
+[5]: kernel
+[6]: init_scripts
+[7]: shutdown_process
 
 --8<--
 includes/glossary.md

docs/developer_guide/software_reference/boot_process/spl.md

@@ -0,0 +1,24 @@
+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
+--8<--

docs/developer_guide/software_reference/sd_card_layout/index.md

@@ -1,3 +1,4 @@
+![Flash Layout](/assets/images/Flash_Layout.png){.lightbox}
 
 --8<--
 includes/glossary.md

docs/developer_guide/tutorials/access_recovery.md

@@ -1,4 +1,114 @@
+The Recovery Mode is a special boot mode that can be entered when
+booting the **FunKey S** console.
+
+Its main purpose is to handle system updates, but it can also be used
+to recover the main system when it is no longer accessible, or to
+access some advanced test or developement features.
+
+## Enter the Recovery Mode
+
+There are 2 different ways to enter Recovery Mode:
+
+ - by holding both the <i class="funkey-start"></i> and the <i
+   class="funkey-fn"></i> keys at the same time while booting the
+   **FunKey S** console
+
+ - by typing the following command at the Shell prompt, either
+      using ssh over USB Ethernet or the serial console:
+
+```
+$ recovery_mode
+```
+
+While booting, the system will display the following logo instead of
+the familiar **FunKey S** logo:
+
+![Recovery Logo](/assets/images/Recovery_Logo.png){.lightbox}
+
+## Recovery mode commands
+
+The Recovery Mode automatically enables the USB network client upon
+startup, allowing ssh connection over the USB cable for debug
+purposes. For more information, please check the [SSH Connection over
+USB section][1].
+
+At the same time, the Recovery mode provides a simple text menu, with
+the current menu item displayed at the top of the screen.
+
+Navigation through the menu commands is using the <i
+class="funkey-up"></i> and <i class="funkey-down"></i> keys, and
+validation is using the <i class="funkey-A"></i> key.
+
+### INFO
+
+This command displays useful information regarding the **FunKey S**:
+
+ - the Recovery Mode version
+
+ - the rootfs (e.g. "Normal" Mode) version
+
+ - if connected to a host through USB network, the device IP address
+
+    ```
+    Recovery: 2.0.0
+	rootfs  : 2.0.0
+	IP addr : 192.168.137.20
+    ```
+	
+### USB MOUNT/UNMOUNT
+
+This toggle commands performs the same way as the FunKey menu command,
+except that no confirmation is asked.
+
+### USB CHECK
+
+This command performs a check of the FAT32 USB partition, and try to
+repair it if it finds some errors, such as when the partition was not
+cleanly unmounted from a host computer.
+
+### USB FORMAT
+
+This commands formats the FAT32 USB partition.
+
+!!! warning
+
+    This function will delete all the files on the USB partition, so be careful!
+
+### NETWORK ENABLE/DISABLE
+
+This toggle command will enable/disable the USB network upon next
+boot.
+
+### QR CODE
+
+This command will display a full screen QR Code containing the
+**FunKey S** serial number:
+
+![QR Code](/assets/images/qrcode.png){.lightbox}
+
+### FACTORY TEST ENABLE/DISABLE
+
+This toggle command will enable/disable the factory tests upon next
+boot.
+
+### FIRST BOOT ENABLE/DISABLE
+
+This toggle command will enable/disable the "first boot" sequence that:
+
+ - expands the rootfs "Normal" system partition
+
+ - create the swap partition
+
+ - create the USB shared partition
+
+ - install the free built-in games
+
+### EXIT RECOVERY
+
+This comand exits the Recovery Mode and reboots in Normal Mode.
+
+[1]: ../ssh_connection
 
 --8<--
 includes/glossary.md
---8<--
+--8<--

docs/developer_guide/tutorials/build_system/build_program_using_sdk.md

@@ -1,3 +1,112 @@
+This page will guide you through building a very simple application for FunKey using the SDK.
+
+FunKey is an embedded Linux device with an ARM processor at its core. Programs made for other computers will not work on FunKey, and developing programs on the FunKey itself is rather impractical. Instead, development for embedded devices like FunKey almost always uses a method known as cross compilation: building software on one platform (such as a desktop computer) to be used on another (like FunKey).
+
+The FunKey-SDK contains a cross-compilation environment based on GCC, including the compiler toolchain and the libraries available on the FunKey.
+
+Before we can begin, setup a Linux-based compilation environment as shown on [this page][1].
+
+## Installing the FunKey-SDK
+
+The FunKey-SDK is included in releases of the FunKey-OS, starting from version 2.0.0, and can be found on [GitHub][2]. Alternatively, you can [compile the SDK yourself][3].
+
+Unpack the SDK's .tar.gz file somewhere on your build system. Before you can use the SDK you must first run the **relocate-sdk.sh** script. This will update all references paths in the SDK to its current location. If you decide to move the SDK to another directory at a later point, don't forget to re-run the script.
+
+The SDK is now ready to use. For additional convenience it is highly recommended to `source` the **environment-setup** of the SDK. This will add the SDK utilities to the *PATH*, setup standard variables such as *CC* and *LD* to refer to the SDK versions of the toolchain, setup standard options for *CFLAGS*, and create aliases for **configure** and **cmake** to work with the SDK.
+
+## Your first application
+
+### Building
+
+Let's build a simple application to test that everything is working. Below is a small C program that will use SDL to display a green square for 5 seconds, and then exits.
+
+```C
+#include <SDL/SDL.h>
+
+int main(int argc, char *argv[])
+{   
+    // Init SDL Video
+    SDL_Init(SDL_INIT_VIDEO);
+
+    // Open HW screen and set video mode 240x240, with double buffering 
+    SDL_Surface* hw_surface =
+        SDL_SetVideoMode(240, 240, 32,
+                         SDL_HWSURFACE | SDL_DOUBLEBUF | SDL_FULLSCREEN);
+    
+    // Hide the cursor, FunKey doesn't come with a mouse
+    SDL_ShowCursor(0);
+
+    // Draw a green square in the middle of the screen
+    SDL_Rect draw_rect = {.x=70, .y=70, .w=100, .h=100};
+    Uint32 color = SDL_MapRGB(hw_surface->format, 0, 255, 0);
+    SDL_FillRect(hw_surface, &draw_rect, color);
+    
+    // Switch buffers to show the square we just drew
+    SDL_Flip(hw_surface);
+
+    // Sleep for 5 seconds
+    SDL_Delay(5000);
+
+    /// Deinit SDL
+    SDL_Quit();
+
+    return 0;
+}
+```
+
+Save this file as **hello.c** somewhere outside of the SDK directory. If you've sourced the **environment-setup** you can use the variable *CC* to refer to the C compiler in the SDK. Let's build our program as **hello**:
+
+```bash
+$CC hello.c -o hello -lSDL
+```
+
+### Packing
+
+The **hello** program you've just created is a valid executable for FunKey, but in order for the launcher to find it we must first bundle the program in an *OPK* package. Create a new folder for the contents of the package and put into it:
+
+- The **hello** program.
+- An icon for your program in PNG format, 32 x 32 pixels in size, called **hello.png**.
+- A *desktop* file called **hello.funkey-s.desktop**, containing the following text:
+
+```ini
+[Desktop Entry]
+Type=Application
+Name=Hello
+Comment=A simple test app
+Exec=hello
+Icon=hello
+Terminal=false
+Categories=applications;
+```
+
+[This file describes your program to the launcher][4]:
+
+- **Type**: Always set to "Application"
+- **Name**: This is the name of the application shown in the launcher
+- **Comment**: A description of the application
+- **Exec**: This the command to execute your program
+- **Icon**: The name of the icon file, without the .png extension
+- **Terminal**: Always set to false, FunKey doesn't support terminal applications
+- **Categories**: The categories under which the launcher will show the application, in a semicolon-separated list
+
+Once you've got everything ready you can turn the folder into a package using the [OpenPackage Creator][5]. Select your folder with the **Open** button, or drag it over the window. The OpenPackage Creator will note that you've already created *.desktop* file. Choose the "Use existing as is" option. Finally, click the **Pack** button to create **hello.opk**, ready to be transferred to the FunKey.
+
+### Installing
+
+[Connect the FunKey to your computer via USB.][6] Open the menu on the FunKey, select Mount USB and press A twice to confirm. Your FunKey will now be visible as a USB drive on your computer. You can place your application in any 1st-level folder, and you can create as many as you want to organise your applications. Let's create a new folder called Applications and place hello.opk in there. Safely remove the USB drive from your computer, and in the FunKey menu select Eject USB and press A twice to confirm.
+
+![Hello program is now visible in the Launcher](/assets/images/Hello_program_shown_in_launcher.png)
+
+Your application is now installed on FunKey. Note that **only the GMENU2X launcher can open custom applications**. So switch to that launcher via the FunKey menu if you haven't already. You should find an application called **Hello** under the **applications** category in the launcher.
+
+![The Hello program running on FunKey](/assets/images/Hello_program_running.png)
+
+[1]: ../compilation_environments
+[2]: https://github.com/FunKey-Project/FunKey-OS/releases/
+[3]: ../compile_sdk
+[4]: https://github.com/gcwnow/buildroot/wiki/Package-file-format
+[5]: https://github.com/Harteex/OpenPackageCreator/releases
+[6]: /user_manual/tutorials/software/add_opk
 
 --8<--
 includes/glossary.md

docs/developer_guide/tutorials/build_system/compilation_environments.md

@@ -1,4 +1,155 @@
+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
+
+First, make sure your version of Windows 10 is new enough. Press **Win** + **R** to open the *Run* window and type in `winver` to check your Windows version and build number. The version should be **1903** or higher, the build number **18362** or higher.
+
+#### Enabling Windows Features
+
+![Enable Virtual Machine Platform and Windows Subsystem for Linux.](/assets/images/WSL2_Windows_features.png)
+
+Some addition Windows features need to be enabled. Open the Windows Features window either by searching for "Windows Features" in the Start Menu, or by opening **Settings** -> **Apps & features** -> **Optional features** -> **More Windows features**. There ensure that both **Virtual Machine Platform** and **Windows Subsystem for Linux** are enabled. After pressing OK to confirm, Windows will ask you to reboot your computer to complete installation.
+
+#### Download the Linux kernel update package
+
+An additional update is required to run WSL2. Download and install the following package from Microsoft:
+
+- [WSL2 Linux kernel update package for x64 machines][4]
+#### Set WSL2 as your default version (optional)
+You can run the following command in PowerShell to make WSL2 the default version. New installations of Linux distributions on Windows will then automatically use WSL2. Otherwise they will use WSL version 1 by default.
+
+```
+wsl --set-default-version 2
+```
+
+#### Install Ubuntu using the Microsoft Store
+
+Now that WSL2 is ready to be used you can download a Linux distribution from the Microsoft Store. For this guide, it is recommended to install [Ubuntu 20.04 LTS][5]. After installing, Ubuntu can be started by either selecting it from the Start Menu or typing `ubuntu2004` on the command prompt. The first time you run Ubuntu you will be asked to create a new user account with a username and password. These do not have to be the same as your Windows account.
+
+If you've enabled WSL2 as the default version in the previous step, Ubuntu will be automatically configured to use that version. If you haven't set WSL2 as default, or if you've installed Ubuntu before setting WSL2 as default, it's possible to manually change the version for this distro. First, open a PowerShell window and type the following command to list all installed Linux distributions:
+
+```
+wsl --list --verbose
+```
+
+Check the name of the distribution you want to upgrade and run:
+
+```
+wsl --set-version <distribution name> <versionNumber>
+```
+
+With `<versionNumber>` set to `2` to use WSL2. You can use the same command with version number `1` to return to WSL 1.
+
+#### WSL2 is now ready to be used
+
+Your Ubuntu installation is now ready to be used. Starting Ubuntu from the Start Menu will open a terminal with a Bash prompt. Everything you type here will be executed in Ubuntu. You can run and install applications within Ubuntu as you would on a complete installation or virtual machine.
+
+Follow the instructions in the **Build on a Physical/Virtual Machine** section to install the requirements needed to build FunKey-OS.
+
+You can access the Windows filesystem via `/mnt`; the C: drive is mounted as `/mnt/c`. From Windows you can access the Linux filesystem via the special path `\\wsl$`. Note that you can only access the files there when Ubuntu is running on WSL2.
+
+
+[1]: https://www.docker.com/
+[2]: https://www.virtualbox.org/
+[3]: https://docs.microsoft.com/en-us/windows/wsl/install-win10
+[4]: https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi
+[5]: https://www.microsoft.com/store/productId/9N6SVWS3RX71
 
 --8<--
 includes/glossary.md
---8<--
+--8<--

docs/developer_guide/tutorials/build_system/compile_distribution.md

@@ -1,4 +1,65 @@
+## 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
---8<--
+--8<--

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<--

docs/miscellaneous/glossary.md

@@ -10,6 +10,8 @@
 ## D
 
  - **DAC**: Digital to Analog Converter
+ - **DFU**: Device Firmware Update
+ - **DMA**: Direct Memory Access
  - **DDR**: Dual Data Rate
  - **DRAM**: Dynamic Random-Access Memory
  - **DSi**: Display Serial Interface
@@ -44,6 +46,7 @@
 
 ## M
 
+ - **MMU**: Memory Management Unit
  - **MIPI**: Mobile Industry Processor Interface
 
 ## N
@@ -58,6 +61,7 @@
 
  - **PCBA**: Printed Circuit Board Assembly
  - **PCB**: Printed Circuit Board
+ - **PIO**: Peripheral I/O
  - **PLL**: Phase-Locked Loop
  - **PMIC**: Power Management Integrated Circuit
  - **PMU**: Power Managment Unit
@@ -67,6 +71,8 @@
 
 ## R
 
+ - **RAM**: Random-Access Memory
+ - **ROM**: Read-Only Memory
  - **RTC**: Real-Time Clock
 
 ## S
@@ -77,6 +83,7 @@
  - **SMPS**: Switched-Mode Power Supply
  - **SoC**: System on Chip
  - **SPI**: Serial Peripheral Interface
+ - **SPL**: Secondary Program Loader
  - **SRAM**: Static Random-Access Memory
 
 ## T

docs/user_manual/tutorials/hardware/change_buttons.md

@@ -1,8 +1,14 @@
-You FunKey S is delivered with 4 extra sets of buttons (red, blue, yellow and green) so that you can customize them at will. It only requires a standard **Phillips
-screwdriver (PH0)**, **tweezers** and a **knife or scissors** for cutting up the plastic holding the new buttons together.
+You FunKey S is delivered with 4 extra sets of buttons (red, blue,
+yellow and green) so that you can customize them at will. It only
+requires a standard **Phillips screwdriver (PH0)**, **tweezers** and a
+**knife or scissors** for cutting up the plastic holding the new
+buttons together.
 
 !!! note
-	Be careful when opening up the console. FunKey Project is not responsible for any damage done to your console when changing the buttons.
+
+    Be careful when opening up the console. FunKey Project is not
+    responsible for any damage done to your console when changing the
+    buttons.
 
 ### **STEP 1 - Removing the screws** {.step-title}
 
@@ -14,16 +20,18 @@ Using a standard **Phillips PH0 screwdriver**, remove the 2 screws on
 the back of your FunKey S.
 
 !!! warning
-	Be careful to use the correct screwdriver head size and type to
-	prevent damaging the screws (do not use JIS screwdrivers). 
-	FunKey Project is not responsible for replacing damaged screws.
+
+    Be careful to use the correct screwdriver head size and type to
+    prevent damaging the screws (do not use JIS screwdrivers).  FunKey
+    Project is not responsible for replacing damaged screws.
 
 ### **STEP 2 - Opening up the console** {.step-title}
 
 ![Pull up hinge first](/assets/images/disassembly/IMG_8848.jpg){.step-thumb}
 ![Console opened](/assets/images/disassembly/IMG_8989.jpg){.step-thumb}
 
-Carefully remove the plastic back of the console by pulling up the hinge side first
+Carefully remove the plastic back of the console by pulling up the
+hinge side first
 
 ### **STEP 3 - Removing the keychain lanyard** {.step-title}
 
@@ -31,9 +39,11 @@ Carefully remove the plastic back of the console by pulling up the hinge side fi
 ![Console opened](/assets/images/disassembly/IMG_8993.jpg){.step-thumb}
 ![Pull up the plastic buttons](/assets/images/disassembly/IMG_8896.jpg){.step-thumb}
 
-Carefully remove the keychain lanyard and its axis by pulling gently (it may fall off when opening).
+Carefully remove the keychain lanyard and its axis by pulling gently
+(it may fall off when opening).
 
 !!! warning
+
     The axis is a small part, be careful not to loose it.
 
 ### **STEP 4 - Removing the LR buttons** {.step-title}
@@ -42,9 +52,11 @@ Carefully remove the keychain lanyard and its axis by pulling gently (it may fal
 ![Pull up the plastic buttons](/assets/images/disassembly/IMG_8844.jpg){.step-thumb}
 ![Pull up the plastic buttons](/assets/images/disassembly/IMG_8900.jpg){.step-thumb}
 
-Carefully remove the L/R plastic buttons by gently pulling them out of their axis
+Carefully remove the L/R plastic buttons by gently pulling them out of
+their axis
 
 !!! warning
+
     Be careful not to damage the L/R switches on the circuit board!
 
 ### **STEP 5 - Unplugging the battery** {.step-title}
@@ -54,12 +66,20 @@ Carefully remove the L/R plastic buttons by gently pulling them out of their axi
 ![Get the battery out of the way](/assets/images/disassembly/IMG_8986_arrow.jpg){.step-thumb}
 
 !!! note
-	This step is not required for changing the buttons, but we still advise it. You can however jump to the next step and not unplug the battery.
 
-Lift the battery and pull gently by the top of the circuit board to unplug the battery. The battery may be stuck to the processor with double-sided adhesive, it's perfectly normal if you have to lift with a bit of force to unstick it. 
+    This step is not required for changing the buttons, but we still
+    advise it. You can however jump to the next step and not unplug
+    the battery.
+
+Lift the battery and pull gently by the top of the circuit board to
+unplug the battery. The battery may be stuck to the processor with
+double-sided adhesive, it's perfectly normal if you have to lift with
+a bit of force to unstick it.
 
 !!! warning
-	Be sure to pull on the connector and **NOT the wires** when removing the battery. It is recommended to use tweezers.
+
+    Be sure to pull on the connector and **NOT the wires** when
+    removing the battery. It is recommended to use tweezers.
 
 ### **STEP 6 - Unplugging the screen** {.step-title}
 
@@ -68,8 +88,11 @@ Lift the battery and pull gently by the top of the circuit board to unplug the b
 ![Unplug screen](/assets/images/disassembly/IMG_8938.jpg){.step-thumb}
 
 Now that you have access to the circuit board, you can unplug the screen. 
+
 !!! warning
-	This connector is fragile, unplug it vertically without force. It is recommended to use tweezers.
+
+    This connector is fragile, unplug it vertically without force. It
+    is recommended to use tweezers.
 
 ### **STEP 7 - Removing the circuit board** {.step-title}
 
@@ -77,14 +100,16 @@ Now that you have access to the circuit board, you can unplug the screen.
 ![Pull PCB by its micro-USB port](/assets/images/disassembly/IMG_8943.jpg){.step-thumb}
 ![Pull PCB by its micro-USB port](/assets/images/disassembly/IMG_8902.jpg){.step-thumb}
 
-By grabbing it **by the hinge side**, gently pull up the circuit board from the plastic casing.
+By grabbing it **by the hinge side**, gently pull up the circuit board
+from the plastic casing.
 
 ### **STEP 8 - Removing the buttons you wish to change** {.step-title}
 
 ![Remove buttons](/assets/images/disassembly/IMG_8934.jpg){.step-thumb}
 ![Remove buttons](/assets/images/disassembly/IMG_8905.jpg){.step-thumb}
 
-Remove the buttons from their socket. It is recommended to use tweezers.
+Remove the buttons from their socket. It is recommended to use
+tweezers.
 
 ### **STEP 9 - Separating the new buttons** {.step-title}
 
@@ -92,11 +117,17 @@ Remove the buttons from their socket. It is recommended to use tweezers.
 ![Cut buttons](/assets/images/disassembly/IMG_8923.jpg){.step-thumb}
 ![Cut buttons](/assets/images/disassembly/IMG_8929.jpg){.step-thumb}
 
-Cut up the buttons from the four sets of colors included with your FunKey S. 
+Cut up the buttons from the four sets of colors included with your
+FunKey S.
+
 In this exemple one of the A/B/X/Y button is cut from each color.
 
 !!! warning
-	When replacing a specific button, for example the top arrow, you need to get the same exact button (top arrow). For example a left arrow should not replace a top arrow or the console might not close properly when reassembling it.
+
+    When replacing a specific button, for example the top arrow, you
+    need to get the same exact button (top arrow). For example a left
+    arrow should not replace a top arrow or the console might not
+    close properly when reassembling it.
 
 ### **STEP 10 - Assembling the new buttons** {.step-title}
 
@@ -115,13 +146,14 @@ Reassemble the new cut buttons in their hole.
 Insert first the speaker into its location in the casing before
 putting the circuit board back in the case, like in the pictures.
 
-Reassemble the console by following the previous steps in reverse order.
+Reassemble the console by following the previous steps in reverse
+order.
 
 !!! warning
+
     Be careful not to damage the switches on the circuit board when
     putting back the L/R plastic buttons.
 
-
 --8<--
 includes/glossary.md
---8<--
+--8<--

docs/user_manual/tutorials/hardware/flash_change_sd_card.md

@@ -60,9 +60,10 @@ Using a standard **Phillips PH0 screwdriver**, remove the 2 screws on
 the back of your FunKey S.
 
 !!! warning
-	Be careful to use the correct screwdriver head size and type to
-	prevent damaging the screws (do not use JIS screwdrivers!). 
-	FunKey Project is not responsible for replacing damaged screws.
+
+    Be careful to use the correct screwdriver head size and type to
+    prevent damaging the screws (do not use JIS screwdrivers!).
+    FunKey Project is not responsible for replacing damaged screws.
 
 ### **STEP 2 - Opening up the console** {.step-title}
 ![Pull up hinge first](/assets/images/disassembly/IMG_8848.jpg){.step-thumb}
@@ -76,6 +77,7 @@ Carefully remove:
 2. The keychain lanyard and axis
 
 !!! warning
+
     Be careful not to damage the L/R switches on the circuit board!
 
 ### **STEP 3 - Exposing the circuit board** {.step-title}
@@ -102,6 +104,7 @@ the new one (previously flashed as described [in the 1st part of this
 tutorial][4]).
 
 !!! note
+
     You may need to use some tweezers and pull with some strength in
     order to remove the micro-SD card from its socket, as it is
     strongly inserted to prevent loose connections.
@@ -116,6 +119,7 @@ putting the circuit board back in the case, like in the pictures.
 Reassemble the console by following the previous steps in reverse order.
 
 !!! warning
+
     Be careful not to damage the switches on the circuit board when
     putting back the L/R plastic buttons.
 

docs/user_manual/tutorials/hardware/teardown.md

@@ -3,7 +3,9 @@ pretty straightforward. It only require a standard **Phillips
 screwdriver (PH0)** and **tweezers**.
 
 !!! note
-	FunKey Project is not responsible for any damage done to your console during a teardown.
+
+    FunKey Project is not responsible for any damage done to your
+    console during a teardown.
 
 ### **STEP 1 - Removing the screws** {.step-title}
 
@@ -15,16 +17,18 @@ Using a standard **Phillips PH0 screwdriver**, remove the 2 screws on
 the back of your FunKey S.
 
 !!! warning
-	Be careful to use the correct screwdriver head size and type to
-	prevent damaging the screws (do not use JIS screwdrivers). 
-	FunKey Project is not responsible for replacing damaged screws.
+
+    Be careful to use the correct screwdriver head size and type to
+    prevent damaging the screws (do not use JIS screwdrivers).  FunKey
+    Project is not responsible for replacing damaged screws.
 
 ### **STEP 2 - Opening up the console** {.step-title}
 
 ![Pull up hinge first](/assets/images/disassembly/IMG_8848.jpg){.step-thumb}
 ![Console opened](/assets/images/disassembly/IMG_8989.jpg){.step-thumb}
 
-Carefully remove the plastic back of the console by pulling up the hinge side first
+Carefully remove the plastic back of the console by pulling up the
+hinge side first
 
 ### **STEP 3 - Removing the keychain lanyard** {.step-title}
 
@@ -32,9 +36,11 @@ Carefully remove the plastic back of the console by pulling up the hinge side fi
 ![Console opened](/assets/images/disassembly/IMG_8993.jpg){.step-thumb}
 ![Pull up the plastic buttons](/assets/images/disassembly/IMG_8896.jpg){.step-thumb}
 
-Carefully remove the keychain lanyard and its axis by pulling gently (it may fall off when opening).
+Carefully remove the keychain lanyard and its axis by pulling gently
+(it may fall off when opening).
 
 !!! warning
+
     The axis is a small part, be careful not to loose it.
 
 ### **STEP 4 - Removing the LR buttons** {.step-title}
@@ -43,7 +49,8 @@ Carefully remove the keychain lanyard and its axis by pulling gently (it may fal
 ![Pull up the plastic buttons](/assets/images/disassembly/IMG_8844.jpg){.step-thumb}
 ![Pull up the plastic buttons](/assets/images/disassembly/IMG_8900.jpg){.step-thumb}
 
-Carefully remove the L/R plastic buttons by gently pulling them out of their axis
+Carefully remove the L/R plastic buttons by gently pulling them out of
+their axis.
 
 !!! warning
     Be careful not to damage the L/R switches on the circuit board!
@@ -54,10 +61,15 @@ Carefully remove the L/R plastic buttons by gently pulling them out of their axi
 ![Get the battery out of the way](/assets/images/disassembly/IMG_8828.jpg){.step-thumb}
 ![Get the battery out of the way](/assets/images/disassembly/IMG_8986_arrow.jpg){.step-thumb}
 
-Lift the battery and pull gently by the top of the circuit board to unplug the battery. The battery may be stuck to the processor with double-sided adhesive, it's perfectly normal if you have to lift with a bit of force to unstick it. 
+Lift the battery and pull gently by the top of the circuit board to
+unplug the battery. The battery may be stuck to the processor with
+double-sided adhesive, it's perfectly normal if you have to lift with
+a bit of force to unstick it.
 
 !!! warning
-	Be sure to pull on the connector and **NOT the wires** when removing the battery. It is recommended to use tweezers.
+
+    Be sure to pull on the connector and **NOT the wires** when
+    removing the battery. It is recommended to use tweezers.
 
 ### **STEP 6 - Unplugging the screen** {.step-title}
 
@@ -65,9 +77,13 @@ Lift the battery and pull gently by the top of the circuit board to unplug the b
 ![Pull PCB by its micro-USB port](/assets/images/disassembly/IMG_8963.jpg){.step-thumb}
 ![Pull PCB by its micro-USB port](/assets/images/disassembly/IMG_8938.jpg){.step-thumb}
 
-Now that you have access to the circuit board, you can unplug the screen. 
+Now that you have access to the circuit board, you can unplug the
+screen.
+
 !!! warning
-	This connector is fragile, unplug it vertically without force. It is recommended to use tweezers.
+
+    This connector is fragile, unplug it vertically without force. It
+    is recommended to use tweezers.
 
 ### **STEP 7 - Removing the circuit board** {.step-title}
 
@@ -75,7 +91,8 @@ Now that you have access to the circuit board, you can unplug the screen.
 ![Pull PCB by its micro-USB port](/assets/images/disassembly/IMG_8943.jpg){.step-thumb}
 ![Pull PCB by its micro-USB port](/assets/images/disassembly/IMG_8902.jpg){.step-thumb}
 
-By grabbing it **by the hinge side**, gently pull up the circuit board from the plastic casing.
+By grabbing it **by the hinge side**, gently pull up the circuit board
+from the plastic casing.
 
 ### **STEP 8 - Removing the micro-SD card** {.step-title}
 
@@ -85,11 +102,17 @@ By grabbing it **by the hinge side**, gently pull up the circuit board from the
 Remove the micro-SD card from its socket.
 
 !!! note
+
     You may need to use some tweezers and pull with some strength in
     order to remove the micro-SD card from its socket, as it is
     strongly inserted to prevent loose connections.
+
 !!! warning
-	During this step be very careful not to damage the L/R switches. Never put the PCB on a flat surface (this would apply force on the LR switches) and do not grab the PCB by these switches.
+
+    During this step be very careful not to damage the L/R
+    switches. Never put the PCB on a flat surface (this would apply
+    force on the LR switches) and do not grab the PCB by these
+    switches.
 
 ### **STEP 9 - Removing the buttons** {.step-title}
 
@@ -97,14 +120,15 @@ Remove the micro-SD card from its socket.
 ![Insert the new micro-SD](/assets/images/disassembly/IMG_8905.jpg){.step-thumb}
 ![Insert the new micro-SD](/assets/images/disassembly/IMG_8933.jpg){.step-thumb}
 
-Remove the buttons from their socket. It is recommended to use tweezers.
+Remove the buttons from their socket. It is recommended to use
+tweezers.
 
 ### **STEP 10 - Teardown complete** {.step-title}
 
 ![Remove the micro-SD](/assets/images/disassembly/IMG_8975.jpg){.step-thumb}
 ![Insert the new micro-SD](/assets/images/disassembly/IMG_8983.jpg){.step-thumb}
 
-Good job the teardown is complete.
+Good job the teardown is complete!
 
 ### **STEP 11 - Reassembly** {.step-title}
 
@@ -117,10 +141,10 @@ putting the circuit board back in the case, like in the pictures.
 Reassemble the console by following the previous steps in reverse order.
 
 !!! warning
+
     Be careful not to damage the switches on the circuit board when
     putting back the L/R plastic buttons.
 
-
 --8<--
 includes/glossary.md
---8<--
+--8<--

includes/glossary.md

@@ -5,6 +5,8 @@
 *[CSi]: Camera Serial Interface
 *[DAC]: Digital to Analog Converter
 *[DACs]: Digital to Analog Converters
+*[DFU]: Device Firmware Update
+*[DMA]: Direct Memory Access
 *[DDR]: Dual Data Rate
 *[DRAM]: Dynamic Random-Access Memory
 *[DSi]: Display Serial Interface
@@ -21,19 +23,23 @@
 *[LCD]: Liquid-Crystal Display
 *[LDO]: Low Drop-Out
 *[LiPo]: Lithium Polymer
+*[MMU]: Memory Management Unit
 *[MIPI]: Mobile Industry Processor Interface
 *[NTC]: Negative Temperature Coefficient
 *[OPK]: Open Package
 *[OTG]: On-The-Go
 *[PCBA]: Printed Circuit Board Assembly
 *[PCB]: Printed Circuit Board
+*[PIO]: Peripheral I/O
 *[PLL]: Phase-Locked Loop
 *[PLLs]: Phase-Locked Loops
 *[PMIC]: Power Management Integrated Circuit
-*[PMU]: Power Managment Unit
+*[PMU]: Power Management Unit
 *[PoP]: Package on Package
 *[PSRR]: Power Supply Rejection Ratio
 *[PWM]: Pulse Width Modulation
+*[RAM]: Random-Access Memory
+*[ROM]: Read-Only Memory
 *[RTC]: Real-Time Clock
 *[SD]: Secure Digital
 *[SIMD]: Single Instruction Multiple Data
@@ -42,6 +48,7 @@
 *[SoC]: System on Chip
 *[SoCs]: System on Chips
 *[SPI]: Serial Peripheral Interface
+*[SPL]: Secondary Program Loader
 *[SRAM]: Static Random-Access Memory
 *[TFT LCD]:  Thin-Film-Transistor Liquid-Crystal Display
 *[TVS]: Transcient Voltage Suppressor

mkdocs.yml

@@ -180,9 +180,11 @@ nav:
       - 'developer_guide/software_reference/index.md'
       - Boot Process:
         - 'developer_guide/software_reference/boot_process/index.md'
-        - 'Bootloader': 'developer_guide/software_reference/boot_process/bootloader.md'
-        - 'Kernel': 'developer_guide/software_reference/boot_process/kernel.md'
-        - 'Init Scripts': 'developer_guide/software_reference/boot_process/init_scripts.md'
+        - 'Boot ROM': 'developer_guide/software_reference/boot_process/boot_rom.md'
+        - 'SPL': 'developer_guide/software_reference/boot_process/spl.md'
+        - 'U-Boot Bootloader': 'developer_guide/software_reference/boot_process/bootloader.md'
+        - 'Linux Kernel': 'developer_guide/software_reference/boot_process/kernel.md'
+        - 'System V Init Scripts': 'developer_guide/software_reference/boot_process/init_scripts.md'
         - 'Shutdown Process': 'developer_guide/software_reference/boot_process/shutdown_process.md'
       - SD-Card Layout:
         - 'developer_guide/software_reference/sd_card_layout/index.md'
@@ -199,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'