Installation

Installation

This is a basic guide for building the kernel, uploading it to the Pi and running it using the serial console as an input/output device.

Requirements

It is important to have a cross-compiler toolchain installed for the board you want to compile the kernel, if not follow the instructions in the Install-Toolchain page.

Instead of building from source, you can also download the kernel images from the latest release page, and go directly to the Transfer kernel to SD Card - Manually part.

Also, it is recommended to test the serial connection with the Pi firstly with the Raspberry Pi OS, in order to check that the connection is correct. See the Serial-Connection page for instructions.

If you want to omit the last step, just follow the following mandatory steps from the Serial-Connection page in order to be able to compile and run the kernel properly:

• Install Raspberry Pi OS, in order to have the SD properly formatted.
• Drivers for Linux Host, in order to use the serial console.
• Connect the USB to TTL Leads, to correctly connect the cable lead to the Pi.

Clone the repository

Firstly clone the repository in directory in your system:

git clone https://github.com/thanoskoutr/armOS.git

Set Toolchain Path

If you do not have installed the suggested toolchain or have not included it to your $PATH environmental variable, the Makefile would be unable to locate it. In order to fix this, just include the correct path of the toolchain in the ARMGNU or the ARMGNU_64 variables depending on the building architecture:

# Set Cross-Compiler Toolchain
ARMGNU = arm-none-eabi
ARMGNU_64 = aarch64-none-elf

Build Kernel and Transfer kernel to SD Card - Automatic

There is the build.sh script at the top-level directory of the project, that is responsible for building the kernel for the desired Pi device, and transfering it to the /boot partition of the SD card.

In order to use it just open it, and replace the $MOUNT_DIR variable with the path of the mounted directory of your SD card when it is inserted:

For example, on Ubuntu the default mount directory is under /media, under the system's user name:

MOUNT_DIR="/media/user"

Raspberry Pi Zero / Zero W

Build kernel and transfer to SD for the Raspberry Pi Zero or Zero W:

chmod +x build.sh
./build.sh 0

Raspberry 4

Build kernel and transfer to SD for the Raspberry Pi 4:

chmod +x build.sh
./build.sh 4

Build Kernel - Manually

Alternatively, you can follow all the steps the script does, manually for each Pi device.

There are separate instructions for compiling the kernel depending on the Pi devices that are currently supported.

Raspberry Pi Zero / Zero W

In order to compile for the Raspberry Pi Zero or Zero W, compile with the following flag:

make RASPI_MODEL=0

Raspberry 4

In order to compile for the Raspberry Pi 4, compile with the following flag:

make RASPI_MODEL=4

Also, compile the armstub:

make RASPI_MODEL=4 armstub

Transfer kernel to SD Card - Manually

Raspberry Pi Zero / Zero W

Copy the generated kernel7.img file to the /boot partition of your Raspberry Pi SD card, with the name kernel.img:

cp kernel7.img PATH_TO_MOUNT_DIR/boot/kernel.img

Delete kernel.img as well as any other kernel*.img files that may be present on the /boot partition of the SD card:

rm -f PATH_TO_MOUNT_DIR/boot/kernel*.img

Replace the config.txt on /boot with the config0.txt:

cp config0.txt PATH_TO_MOUNT_DIR/boot/config.txt

NOTE: If you leave the default config.txt, the enable_uart=1 option, will produce garbage to the serial console.

Make sure you left all other files in the boot partition untouched.

Eject the SD card from your system.

Using the terminal:

# Forces cache data to be written to disk
sudo sync

# Unmount SD card (file, boot partitions)

## If inserted as an SD card device:
sudo umount /dev/mmcblk0p1
sudo umount /dev/mmcblk0p2

## If inserted as a USB device (find your `/dev/sd*`, or else you could write to your hard drive):
sudo umount /dev/sdb1
sudo umount /dev/sdb2

Raspberry 4

Copy the generated kernel8.img (for Raspberry Pi 4) file to the /boot partition of your Raspberry Pi SD card:

cp kernel8.img PATH_TO_MOUNT_DIR/boot/kernel8.img

Delete kernel8.img as well as any other kernel*.img files that may be present on the /boot partition of the SD card:

rm -f PATH_TO_MOUNT_DIR/boot/kernel*.img

Replace the config.txt on /boot with the config4.txt:

cp config4.txt PATH_TO_MOUNT_DIR/boot/config.txt

Add the armstub binary armstub-new.bin on /boot

cp armstub-new.bin PATH_TO_MOUNT_DIR/boot/armstub-new.bin

Make sure you left all other files in the boot partition untouched.

Eject the SD card from your system.

Using the terminal:

# Forces cache data to be written to disk
sudo sync

# Unmount SD card (file, boot partitions)

## If inserted as an SD card device:
sudo umount /dev/mmcblk0p1
sudo umount /dev/mmcblk0p2

## If inserted as a USB device (find your `/dev/sd*`, or else you could write to your hard drive):
sudo umount /dev/sdb1
sudo umount /dev/sdb2

Serial Connection with Pi

Insert the SD card on the Pi and connect the USB to TTL cable leads on the Pi and the USB end to your Linux host, as explained in the [Serial-Connection]] page.

Open your terminal emulator:

sudo screen /dev/ttyUSB0 115200

Power on your Raspberry Pi.

Now you should be able to see the kernel booting up:

                  _____ _____ 
 ___ ___ _____   |     |   __|
| . |  _|     |  |  |  |__   |
|__,|_| |_|_|_|  |_____|_____|

armOS initializing...

        Board: Raspberry Pi 4
        Arch: aarch64

----- Exception level: EL1 -----
Initializing IRQs...Done
Enabling IRQ controllers...Done
Enabling IRQs...Done
Initializing LED...Done

This is a minimal console, type 'help' to see the available commands. (Maximum Input Length: 80)
root@pi-4# 

Notes

• It is important to first open the screen session, and then power on the Pi.
• Sometimes the serial console, might be a little laggy, it usually recovers after a restart.
• Sometimes it helps, to disconnect the cable entirely from the computer and reconnecting it before the other steps.
  • Check dmesg to see errors about the usb-ttl cable.

Previous Page

Serial Connection

Next Page

Bootloader