Starkl

Building 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.

We recommend that you use Docker, and perform the builds inside a container - this 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 throughout the process, these are installed via this command:

$ 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 by a wide margin. Installation instructions can be found on the Docker site. Please ensure that you create a Docker group to for this, example below, 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 (they overlay each other):

$ mkdir starkl
$ cd starkl
$ tar -xf ../starkl-4kopen-v1.0.0.tar.bz2
$ tar -xf ../starkl_licensed-4kopen-v1.0.0.tar.bz2

Building Starkl

Now there are two options:

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

The Docker image may solve build issues that may present, as well as removing the need for a lot of the dependencies.

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 run -it --rm --cap-add=SYS_PTRACE --privileged=true -v "$(pwd)":/starkl 4kopen/starkl-builder:latest

Using Docker you can skip to "Prepare the Boot Media". Please note that if the instructions don't match what is created in your local copy, you may have an outdated version of the starkl-builder such that you should try deleting the local docker image as the first method of attempting a fix. This can be done through the following:

docker image rm 4kopen/starkl-builder


Building Natively

Alternatively you can simply running a make command as follows:

$ make outputs/starkl-b2264-default/images

Prepare Boot Files

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

The key files are:

  • sdk2-dt.dtb - the device tree
  • zImage - the kernel, with a rootfs builtin

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: 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. (Inspiration from the tools shipped with Starkl - see ${STARKL}/launchers/stmc2/.handle-images.bash)

Run the script from the Starkl root directory, you may need to  give it execute permissions beforehand with:

$ chmod +x make_fit_image.sh
$ ./make_fit_image.sh

This may output some "unit_address_vs_reg" warnings, but they can be safely ignored.

Once it completes, you should see ${STARKL}/outputs/starkl-b2264-default/images/kernel.fit has been created (~34 MB).

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 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 above) 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.

$ mkfs.vfat ${DEVICE}1
mkfs.fat 4.1 (2017-01-24)

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

$ umount ${DEVICE}1

At this point, you should be able to run the mkfs.vfat command.

Mount

Now you need to mount the filesystem, either creating a folder or just mounting onto an existing one.

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

With Docker

During the process, docker will have created a kernel.tar file containing the uenv.txt and the kernel.fit, this simply needs to be extracted into your new partition with the following:

tar -xf ${STARKL}/outputs/starkl-b2254/images/kernel.tar -C ./mnt/

Once this is done, skip to "Unmount".

Without Docker

uenv.txt

The basic uenv.txt shown below will allow you to boot the system, ${bootdev} does not need to be set, and you should copy the entirety of it over, from cat to the second EOF.

However if (when) you require more advanced features, such as the hardware accelerated encode/decode, you will need to provide additional bootargs.

$ cat <<"EOF" >./mnt/uenv.txt
bootcmd=fatload ${bootdev} 0:1 0x98000000 kernel.fit; bootm 0x98000000;
EOF

kernel.fit

Place the kernel.fit on the partition

$ cp ${STARKL}/outputs/starkl-b2264-default/images/kernel.fit ./mnt/

Unmount

now you simply need to unmount the filesystem.

$ 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 minicom):

Welcome to Starkl OS
board login:

Credentials

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

Username: root

Password: <none>