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

Modifying the stand-alone Linux Kernel

The Gateworks Catalina BSP instructions above create an environment for building the Linux kernel among other targets.

You can modify the default Gateworks kernel config as well as build it manually:

• Modify kernel menuconfig:

  make linux-menuconfig
  

• Make kernel by hand

  source ./setup-environment
  cd linux
  make menuconfig
  make savedefconfig
  diff defconfig ../configs/imx95_catalina_linux-6.18_defconfig # show changes
  cp defconfig ../configs/imx95_catalina_linux-6.18_defconfig # copy changes (if desired)
  

ARM64 Toolchain

The buildroot based ARM64 toolchain is used can be used by sourcing the ​setup-environment file which adds to your PATH and sets the CROSS_COMPILE variables:

source ./setup-environment

Note this is not necessary to do if you are using the Makefile as it specifies the necessary ARCH and CROSS_COMPILE vars where needed.

Buildroot based toolchain

The Catalina BSP uses buildroot to build the ARM64 toolchain used to build everything that runs on the A55 cores: ATF, kernel and bootloader firmware.

The buidlroot config is ​configs/buildroot_arm64_toolchain_defconfig.

The bsp ​Makefile has an 'arm64-toolchain' target which is built as a pre-requisite for building code running on the A55 cores.

The toolchain is built using buildroot 2026.02 with the following details (which are all defaults for this version of buildroot):

• Linux 6.18 kernel headers
• glib libc
• binutils 2.44
• gcc 13.4
• C++ support (default is to disable this; we enable it)

Note there are other options you may want to change for your needs such as using a different libc, different compiler version, or enable WCHAR support or additional threading support. To do so you can:

make arm64-toolchain-menuconfig # select changes
make clean-toolchain
make

• make sure you clean and rebuild when changing toolchain options

External toolchain

The Catalina BSP uses buildroot to build the toolchain used to build the kernel and bootloader firmware.

While the BSP makefile will always build the buildroot ARM64 toolchain (unless you comment that out in the Makefile) you can easily use a toolchain of your liking by modifying the environment like 'setup-environment' does and adjusting the PATH and CROSS_COMPILE statements int he Makefile.

Cross compile examples

Examples of cross-compiling on your development host using the ARM64 buildroot toolchain

• ANSI-C hello world:

  cat << EOF > helloworld.c
  #include <stdio.h>
  #include <stdlib.h>
  
  int main(int argc, char **argv)
  {
          printf("hello world!\n");
  
          return 0;
  }
  EOF
  . ./setup-environment # setup environment for buildroot toolchain
  ${CROSS_COMPILE}gcc helloworld.c --static -o helloworld
  

  • Note that if you want to use shared libraries you would either need to copy the toolchains libc (buildroot/output/target/lib/) to the target so that the interpreter and shared libs are present or you can use Ubuntu's cross-toolchain instead (see ubuntu/cross-compile)
• C++ hello world:

  cat << EOF > helloworld.cpp
  #include <iostream>
  
  using namespace std;
  
  int main() {
          cout << "Hello World!";
          return 0;
  }
  EOF
  . ./setup-environment # setup environment for buildroot toolchain
  ${CROSS_COMPILE}gcc helloworld.cpp --static -lstdc++ -o helloworld
  

  • Note that if you want to use shared libraries you would either need to copy the toolchains libc (buildroot/output/target/lib/) to the target so that the interpreter and shared libs are present or you can use Ubuntu's cross-toolchain instead (see ubuntu/cross-compile)
• kernel module:

  . ./setup-environment # setup environment for buildroot toolchain
  make kernel_image # first build the kernel
  make -C linux M=$PWD/my-module modules
  

  • Note that some out-of-tree kernel modules do not follow the suggested Makefile standards and may need to be modified to use the CROSS_COMPILE prefix and/or specify the kernel directory (as opposed to the above example where you do a make in the linux dir and set M to the path of your module)

Building applications on the Catalina Target

Out-of-Tree Kernel Modules on Target

Gateworks Catalina BSP now creates images that have built in support for building external or out-of-tree kernel modules on a target board, allowing users to extend the functionality of the kernel with custom or third-party modules. Below are some examples demonstrating how to build and install external modules on a one of our Catalina boards:

Before building any external kernel modules, it's essential to ensure your system has necessary dependencies installed. We recommend starting with an update of package lists followed by the installation of essential tools. Run the following commands:

apt update
apt install -y build-essential git bc file flex bison

Examples:

1. cryptodev-linux (a properly defined Makefile)

   git clone http://github.com/cryptodev-linux/cryptodev-linux
   cd cryptodev-linux
   make && make modules_install
   modprobe cryptodev
   

1. something with an improper or problematic Makefile but with a single C file for example uiodma.c

   git clone https://github.com/nxp-imx-support/uiodma-driver.git
   cd uiodma-driver/uiodma
   # build module
   make -C /lib/modules/$(uname -r)/build M=$PWD obj-m=uiodma.o modules
   # install module
   make -C /lib/modules/$(uname -r)/build M=$PWD obj-m=uiodma.o modules_install
   

   • The kernel build system will still look for a file named Makefile or Kbuild in your directory. If the existing files are so broken that it can't even parse them you will need to rename/remove them
   • If you need to pass flags to the compiler define them as 'KCFLAGS' - ie 'KCFLAGS="-Wno-missing-prototypes -Wno-missing-declarations"

These examples illustrate the process of building and installing external kernel modules. Users can adapt these instructions for other modules as needed, ensuring that dependencies are met and the module is properly installed and loaded into the kernel.