From 8c296e241ea0f1633990a3c149b7fa54abeabdc4 Mon Sep 17 00:00:00 2001 From: Michel-FK Date: Sun, 21 Feb 2021 12:13:02 +0100 Subject: [PATCH] fill-in build_system section Signed-off-by: Michel-FK --- .../software_reference/boot_process/spl.md | 20 ++++ .../build_system/compilation_environments.md | 105 +++++++++++++++++- .../build_system/compile_distribution.md | 63 ++++++++++- .../tutorials/build_system/compile_sdk.md | 62 +++++++++++ .../tutorials/build_system/get_sources.md | 38 +++++++ .../tutorials/build_system/index.md | 43 +++++++ .../tutorials/build_system/write_image.md | 32 ++++++ mkdocs.yml | 2 + 8 files changed, 363 insertions(+), 2 deletions(-) create mode 100644 docs/developer_guide/tutorials/build_system/get_sources.md create mode 100644 docs/developer_guide/tutorials/build_system/write_image.md diff --git a/docs/developer_guide/software_reference/boot_process/spl.md b/docs/developer_guide/software_reference/boot_process/spl.md index 9c55f17..12010aa 100644 --- a/docs/developer_guide/software_reference/boot_process/spl.md +++ b/docs/developer_guide/software_reference/boot_process/spl.md @@ -1,3 +1,23 @@ +The SPL is the Secondary Program Loader (the Primary Program Loader +being the code in the [Boot ROM][1]), it is the first +user-customizable piece of code run on the CPU. + +The SPL is built as part of the U-Boot bootlader. Actually, it shares +most of its code with it. + +The SPL is loaded by the Boot ROM at address `0x00000000` in SRAM A1 +and C, and has a maximum size of 32KB. It contains a "**BOOT0 +Header**" that has been checked previously by the Boot ROM, and its +byte at offset 40 has been updated with the SD card interface used to +boot, with its bit 5 set to `1` if it was loaded from offset 128KB +from the SD Card, or `0` if was loaded from offset 8KB. + +The role of the SPL stage is to set up the CPU clocks to their nominal +speeds and set up the main SDRAM memory in order to load into it the +next boot stage: either the U-Boot bootloader or the Linux kernel, as +these are too large to fit into the small SRAM memory. + +[1]: ../boot_rom --8<-- includes/glossary.md diff --git a/docs/developer_guide/tutorials/build_system/compilation_environments.md b/docs/developer_guide/tutorials/build_system/compilation_environments.md index 26ae347..9b5ab53 100644 --- a/docs/developer_guide/tutorials/build_system/compilation_environments.md +++ b/docs/developer_guide/tutorials/build_system/compilation_environments.md @@ -1,4 +1,107 @@ +Even if the resulting disk image and firmware update files are +relatively small (202 MB and 55MB, respectively), the size of the +corresponding sources and the compilation by-products tend to be +rather large, such that an available disk space of at least 12GB is +required during the build. + +And even if the resulting FunKey-OS boots in less than 5s, it still +requires a considerable amount of time to compile: please account for +1 1/2 hour on a modern multi-core CPU with SSD drives and a decent +Internet bandwidth. + +The FunKey-OS is meant to be built on a native Ubuntu or Debian Linux +host machine (Ubuntu 20.04 LTS in our case, but this should also work +with other versions, too). And with only a few changes to the +prerequisites, it can certainly be adapted to build on other common +Linux distros. + +However, if your development machine does not match this setup, there +are still several available solutions: + + - use a lightweight container system such as [Docker][1] and run an + Ubuntu or Debian Linux container in it + + - use a VM (Virtual Machine), such as provided by [VirtualBox][2] and + run an Ubuntu or Debian Linux in it + + - for Windows 10 users, use the [WSL2][3] (Windows System for Linux + 2) subsystem and run an Ubuntu Linux distro in it + +In order to install one of these virtualized environments on your +machine, please refer to the corresponding documentation. + +## Build on a Physical/Virtual Machine + +### Prerequisites + +While Buildroot itself will build most host packages it needs for the +compilation, some standard Linux utilities are expected to be already +installed on the host system. If not already present, you will need to +install the following packages beforehand: + + - bash + - bc + - binutils + - build-essential + - bzip2 + - ca-certificates + - cpio + - cvs + - expect + - file + - g++ + - gcc + - git + - gzip + - liblscp-dev + - libncurses5-dev + - locales + - make + - mercurial + - openssh-client + - patch + - perl + - procps + - python + - python-dev + - python3 + - python3-dev + - python3-distutils + - python3-setuptools + - rsync + - rsync + - sed + - subversion + - sudo + - tar + - unzip + - wget + - which + - xxd + +On Ubuntu/Debian Linux, this is achieved by running the following +command: + +```bash +$ sudo apt install bash bc binutils build-essential bzip2 ca-certificates cpio cvs expect file g++ gcc git gzip liblscp-dev libncurses5-dev locales make mercurial openssh-client patch perl procps python python-dev python3 python3-dev python3-distutils python3-setuptools rsync rsync sed subversion sudo tar unzip wget which xxd +``` + +## Build in a Docker Container + +### Prerequisites + +When using a Docker container, all the prerequisites are automatically +installed. + +## Build on Windows 10 with WSL2 + +### Prerequisites + + +[1]: https://www.docker.com/ +[2]:https://www.virtualbox.org/ +[3]: https://docs.microsoft.com/en-us/windows/wsl/install-win10 --8<-- includes/glossary.md ---8<-- \ No newline at end of file +--8<-- diff --git a/docs/developer_guide/tutorials/build_system/compile_distribution.md b/docs/developer_guide/tutorials/build_system/compile_distribution.md index 26ae347..9b7cecf 100644 --- a/docs/developer_guide/tutorials/build_system/compile_distribution.md +++ b/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 ;-) + +Note: 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 ;-) + +Note: 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<-- \ No newline at end of file +--8<-- diff --git a/docs/developer_guide/tutorials/build_system/compile_sdk.md b/docs/developer_guide/tutorials/build_system/compile_sdk.md index 9c55f17..99416a8 100644 --- a/docs/developer_guide/tutorials/build_system/compile_sdk.md +++ b/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 ;-) + +Note: 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 ;-) + +Note: 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 diff --git a/docs/developer_guide/tutorials/build_system/get_sources.md b/docs/developer_guide/tutorials/build_system/get_sources.md new file mode 100644 index 0000000..ba9ea3f --- /dev/null +++ b/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<-- diff --git a/docs/developer_guide/tutorials/build_system/index.md b/docs/developer_guide/tutorials/build_system/index.md index 9c55f17..630c7cd 100644 --- a/docs/developer_guide/tutorials/build_system/index.md +++ b/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 diff --git a/docs/developer_guide/tutorials/build_system/write_image.md b/docs/developer_guide/tutorials/build_system/write_image.md new file mode 100644 index 0000000..0a74b18 --- /dev/null +++ b/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 +``` +Warning: 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<-- diff --git a/mkdocs.yml b/mkdocs.yml index fca7332..67787be 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -201,8 +201,10 @@ nav: - Build System: - 'developer_guide/tutorials/build_system/index.md' - 'Compilation Environments': 'developer_guide/tutorials/build_system/compilation_environments.md' + - 'Get the Sources': 'developer_guide/tutorials/build_system/get_sources.md' - 'Compile SDK': 'developer_guide/tutorials/build_system/compile_sdk.md' - 'Compile Distribution': 'developer_guide/tutorials/build_system/compile_distribution.md' + - 'Write firmware to SD Card': 'developer_guide/tutorials/build_system/write_image.md' - 'Build Programs using SDK': 'developer_guide/tutorials/build_system/build_program_using_sdk.md' - Miscellaneous: - 'Glossary': 'miscellaneous/glossary.md'