Catalina Board Support Package (BSP)

Gateworks provides a Board Support Package for Catalina which provides source code and an easy mechanism to build different images, including a minimal Buildroot based distro as well as an Ubuntu based distro.

The Gateworks BSP is the easiest comprehensive software process because it contains everything. If a deep dive, expert path is desired, each piece of the BSP (boot firmware, rootfs, kernel) can all be built separately:

• Gateworks Catalina Linux Kernel
• Gateworks Catalina Boot Firmware

Notes:

• For pre-built images and instructions on installation see catalina/firmware
• For details of Gateworks Ubuntu based OS for Catalina see catalina/ubuntu

BSP Source Code

Source code for the boot firmware, bootloader and kernel are hosted at GitHub. We highly recommend you create a GitHub account and 'Watch' these repositories to keep abreast of important feature additions, bugfixes, and firmware-releases. You can configure your GitHub account to e-mail you when changes are made to repositories ​here.

The following GitHub repos are used for Catalina:

• ​bsp-catalina - Catalina BSP support scripts and Makefile (​watch)
• ​oei-catalina - Optional Executable Image (OEI) for configuring DRAM and TCM (Tightly Coupled Memory) (​watch)
• ​sm-catalina - System Manager (SM) for configuring pinmux, clocks, and power (​watch)
• ​imx-atf - ARM Trusted Firmware (​watch) (not modified by Gateworks)
• ​uboot-catalina - Catalina Bootloader (​watch)
• ​linux-catalina - Catalina Linux Kernel (​watch)

Building the BSP from source

Below are instructions for building the entire BSP, which includes all of the bootloader components, Linux kernel, and Ubuntu. Pre-built images are available above.

The Gateworks Catalina Board Support Package uses GIT submodules to include and track the various GIT repos above.

The following pre-requisites are needed to build the Catalina BSP:

• Linux Development host (desktop or laptop computer)
• Python 3.x
• Git (used for source code repositories)
• various tools

Ubuntu Jammy (20.04) and Ubuntu Noble (24.04) have been verified by Gateworks for automated builds of the Catalina BSP. If using a different OS or version you may need to adjust the above packages.

Installing pre-requisites:

# install packages
sudo apt install -y build-essential git wget unzip coreutils fdisk cpio rsync file bc bison flex kmod python3-dev python3-venv python3-setuptools swig libssl-dev ncurses-dev
# configure git
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
git config --global color.ui true

Building:

1. clone repo with git

   mkdir $HOME/catalina
   cd $HOME/catalina
   git clone --recurse-submodules --jobs $(nproc) https://github.com/Gateworks/bsp-catalina bsp
   

   • This will fetch the source repos described above. The first time it can take several minutes depending on your Internet connection and will take approximately ~9GB of disk space
   • Note if you have already cloned without submodules you can use 'git submodule update --init --recursive' to sync the submodule repos
2. Build desired software target as defined below. For example:

   make -j$(nproc) boot-firmware # build boot firmware
   make -j$(nproc) ubuntu-image # build Ubuntu based compressed disk image
   

The following commonly used build targets exist:

• arm32-toolchain - download and extract the ARM32 toolchain used for code running on the M33 (OEI, SM)
• arm64-toolchain - build ARM64 buildroot toolchain
• boot-firmware - entire boot firmware
• kernel-image - kernel tarball (including external modules)
• ubuntu-image - Ubuntu based root filesystem compressed disk image
• clean-toolchain - removes both ARM32 and ARM64 toolchains
• clean-kernel - removes kernel build dir and tarball
• clean-boot - cleans all boot firmware components; uboot, imx-oei, imx-sm, and imx-atf (but doesn't remove ddr firmware)
• clean-rootfs - cleans rootfs (ext4) as well as the buildroot build dir for the image creation
• distclean - removes all built and downloaded sources

Working with the git submodules

The git tool supports submodules defined in .gitmodules to unify multiple git code repositories into a single project.

Updating to the latest code (repo sync)

You can update to the latest code via:

git pull --recurse-submodules

Building sub-modules by hand

If you wish to do some development and build submodules like U-Boot and Linux by hand you can source the 'environment-setup' script to setup the ARM64 cross toolchain:

source ./setup-environment