Starkl

Building and using Starkl is more complex than just making use of the Raspbian release. If you are trying to get a system up and running quickly, without too many technical details, we suggest you follow the Raspbian quick start guide.

If you would like to build and use Starkl, we recommend that you use the provided Docker container - this should alleviate will remove issues with dependencies and other effects that your system configuration can have.

Without Docker (Not Recommended)

If you decide that you want to build Starkl without using a Docker container, then there a number of packages you must install first.

There are several packages that are required to build Starkl, please ensure they are installed.

apt install -y \
  binwalk u-boot-tools device-tree-compiler automake autoconf bison \
  flex m4 libtool gperf shtool make wget cpio python git subversion bzip2 telnet \
  file rsync bc unzip build-essential g++ intltool libxml-tokeparser-perl

Setting up Docker

Docker is highly recommended for building Starkl as it will streamline the entire process. Installation instructions can be found on the Docker site.

Please ensure that your system has a docker group, as it is required for part of the build.

sudo groupadd docker
sudo usermod -aG docker $USER
systemctl restart docker.service

Download Sources

You will need to download two tarballs from the website:

Once you have the files listed above, extract them both to the same directory:-

mkdir ~/starkl
cd ~/starkl
tar -xvf ${PATH_TO}/4kopen-starkl-1db239b25737.tar.bz2 --strip-components 1
tar -xvf ${PATH_TO}/4kopen-starkl-licensed-v1.0.3.tar.bz2 --strip-components 2

Building Starkl

Now there are two options:

  1. Using the provided Docker image, or
  2. Run a make command natively

The Docker image may avoid build issues later in the process.

A full build of the starkl-b2264-default image will likely take around 30 minutes.

Building with Docker

The Docker image can be used by running the following in the Starkl root directory:

docker pull 4kopen/starkl-builder:latest
docker run -it --rm --cap-add=SYS_PTRACE --privileged=true -e ADDITIONAL=tar -v "$(pwd)":/starkl 4kopen/starkl-builder:latest

By default, the docker image will build the starkl-b2264-default image. If you would like to build an alternative image, please set the TARGET environment variable using the-e flag with docker run, for example: -e TARGET=starkl-b2264-minimal

If you are using Docker to, you can skip to "Prepare the Boot Media".

Building Natively

Alternatively you can simply running a make command as follows, where IMAGE_NAME is typically starkl-b2264-default.

make outputs/${IMAGE_NAME}/images
./make_fit_image.sh ${IMAGE_NAME}

Boot Files

Once the build has completed, the output files can be found in ${STARKL}/outputs/${IMAGE_NAME}/images/, where IMAGE_NAME is starkl-b2264-default by default.

The key files are:

  • sdk2-dt.dtb - the device tree
  • zImage - the kernel with a rootfs built in
  • kernel.fit - the kernel, rootfs and device tree in one file

The default U-Boot configuration only supports FIT image files - a FIT image contains both the device tree and kernel. For more information, see the U-Boot documentation: u-boot/doc/uImage.FIT/howto.txt.

Producing a FIT image that contains the device tree and kernel requires a few steps, so we have produce a script to do this for you (make_fit_image.sh) which follows a similar procedure to the included launcher scripts (see ${STARKL}/launchers/stmc2/.handle-images.bash).

Prepare the Boot Media

The 4Kopen board will attempt to boot from devices in the following order:

  1. MicroSD Card
  2. USB Memory Stick - USB 3.0 port only

Device

A simple way to discover the device is by running

lsblk -dp

This will provide a list of block devices with their size. Locate the device you wish to use, e.g: /dev/sdb.

Partition Table

Using fdisk or another tool, make a new partition table on the storage device you've decided to use.

The first partition must be vfat, and must be large enough to hold the FIT image (produced during the build) and the uenv.txt file (below).

We suggest 128 MB as a reasonable size.

An example interaction with fdisk is shown below:

$ fdisk ${DEVICE}

Welcome to fdisk (util-linux 2.31.1).
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.

Device does not contain a recognised partition table.
Created a new DOS disklabel with disk identifier 0xb4ca619e.

Command (m for help): o
Created a new DOS disklabel with disk identifier 0xf9a09a6d.

Command (m for help): n
Partition type
p primary (0 primary, 0 extended, 4 free)
e extended (container for logical partitions)
Select (default p):
Partition number (1-4, default 1):
First sector (2048-15633407, default 2048):
Last sector, +sectors or +size{K,M,G,T,P} (2048-15633407, default 15633407): +128M

Created a new partition 1 of type 'Linux' and of size 128 MiB.

Command (m for help): t
Selected partition 1
Hex code (type L to list all codes): c
Changed type of partition 'Linux' to 'W95 FAT32 (LBA)'.

Command (m for help): w
The partition table has been altered.
Calling ioctl() to re-read partition table.
Synching disks.

Filesystem

As mentioned above, the partition must have a valid vfat filesystem on it.

Note: the 1 after the ${DEVICE} identifies the partition and is important!

mkfs.vfat ${DEVICE}1

If this fails saying that the mount device or resource is busy, your device may have automatically mounted, to unmount it, do the following.

umount ${DEVICE}1

Mount, Copy Files & Unmount

Now you need to mount the filesystem.

mkdir ./mnt/
mount ${DEVICE}1 ./mnt/ -o uid=$(id -u),gid=$(id -g)

# single quotes prevent variable expansion
echo 'bootcmd=fatload ${bootdev} 0:1 0x98000000 kernel.fit; bootm 0x98000000;' > ./mnt/uenv.txt
cp ${STARKL}/outputs/${IMAGE_NAME}/images/kernel.fit ./mnt/kernel.fit

umount ./mnt/
sync

Boot

Once the storage device has been prepared, connect it to the 4Kopen, and power it up.

Once the device has booted, you'll see a plain blue screen on the HDMI output, and the following login prompt on the serial console (for example picocom):

Welcome to Starkl OS
board login:

Credentials

The default username and password for the starkl build are below:

Username: root

Password: <none>