mirror of
https://github.com/FunKey-Project/FunKey-Project.github.io.git
synced 2025-12-12 10:18:50 +01:00
fill-in build_system section
Signed-off-by: Michel-FK <michel.stempin@funkey-project.com>
This commit is contained in:
Michel-FK
parent
75df708565
commit
8c296e241e
@ -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
|
||||
|
||||
@ -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<--
|
||||
--8<--
|
||||
|
||||
@ -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<--
|
||||
|
||||
@ -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
|
||||
|
||||
38
docs/developer_guide/tutorials/build_system/get_sources.md
Normal file
38
docs/developer_guide/tutorials/build_system/get_sources.md
Normal file
@ -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<--
|
||||
@ -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
|
||||
|
||||
32
docs/developer_guide/tutorials/build_system/write_image.md
Normal file
32
docs/developer_guide/tutorials/build_system/write_image.md
Normal file
@ -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<--
|
||||
@ -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'
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user