add boot rom description

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

docs/developer_guide/software_reference/boot_process/boot_rom.md

@@ -0,0 +1,449 @@
+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.
+
+## 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][45] 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][46] and [here][47].
+
+!!! warning
+
+    For the V3s, it is mandatory to build the version from the
+    [repository][48], 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://linux-sunxi.org/FEL/Protocol
+[46]: https://linux-sunxi.org/FEL/USBBoot
+[47]: https://linux-sunxi.org/Sunxi-tools
+[48]: 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,4 @@
+
+--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
+You FunKey S is delivered with 4 extra sets of buttons (red, blue,
-screwdriver (PH0)**, **tweezers** and a **knife or scissors** for cutting up the plastic holding the new buttons together.
+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). 
+    Be careful to use the correct screwdriver head size and type to
-	FunKey Project is not responsible for replacing damaged screws.
+    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<--

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!). 
+    Be careful to use the correct screwdriver head size and type to
-	FunKey Project is not responsible for replacing damaged screws.
+    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). 
+    Be careful to use the correct screwdriver head size and type to
-	FunKey Project is not responsible for replacing damaged screws.
+    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<--

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'
+        - 'Boot ROM': 'developer_guide/software_reference/boot_process/boot_rom.md'
-        - 'Kernel': 'developer_guide/software_reference/boot_process/kernel.md'
+        - 'SPL': 'developer_guide/software_reference/boot_process/spl.md'
-        - 'Init Scripts': 'developer_guide/software_reference/boot_process/init_scripts.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'