Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.t3gemstone.org/llms.txt

Use this file to discover all available pages before exploring further.

NuttX support for Gemstone is still in the development phase. It is not possible to use all peripherals on the board such as I2C, SPI, PWM, CAN Bus.
NuttX is an open-source operating system designed for real-time applications. Compliant with POSIX and ANSI standards, NuttX is optimized especially for embedded systems and microcontrollers. The primary reason for choosing NuttX for the R5F cores on the Gemstone board is its deterministic behavior and its ability to reliably manage real-time tasks. Additionally, NuttX is critical for drone and autonomous vehicle projects because it is a platform supported by popular autopilot software like Ardupilot and PX4. Since there is no official NuttX support for the AM67A SoC yet, a custom nsh configuration has been created in the boards/arm/am67/t3-gem-o1 directory. With this configuration, NuttX can be run on the R5F cores on our board, which are suitable for real-time processing.

​
1. Compilation

​
1.1. Installing Dependencies and Toolchain

To compile NuttX, the system must have several prerequisites installed. Additionally, we need a cross‑compiler that is compatible with ARM Cortex‑R5F cores. The gcc-arm-none-eabi toolchain is the standard solution that fulfills this requirement. On Ubuntu/Debian systems, you can install the dependencies and toolchain using the package manager: 
sudo apt update
sudo apt install \
    bison flex gettext texinfo libncurses5-dev libncursesw5-dev xxd \
    git gperf automake libtool pkg-config build-essential gperf genromfs \
    libgmp-dev libmpc-dev libmpfr-dev libisl-dev binutils-dev libelf-dev \
    libexpat1-dev gcc-multilib g++-multilib picocom u-boot-tools util-linux \
    kconfig-frontends gcc-arm-none-eabi
Alternatively, you can download the latest version of toolchain from ARM’s official site and perform a manual installation. After installation, you can verify the toolchain is working correctly with the arm-none-eabi-gcc --version command.

​
1.2. Downloading Source Codes

The NuttX ecosystem consists of two main repositories: the core operating system and the application framework. To download the versions customized for the Gemstone board, follow these steps: 
# Clone the main NuttX repository
git clone https://github.com/t3gemstone/nuttx.git

# Clone NuttX applications as the 'apps' folder
git clone https://github.com/t3gemstone/nuttx-apps.git apps

# Change to your main working directory
cd nuttx
This configuration creates the standard directory structure expected by NuttX. The apps folder contains the applications and services that will run on the operating system.

​
1.3. Applying the Default Configuration

NuttX uses pre-prepared configurations for different hardware platforms. Let’s start by applying the t3-gem-o1:nsh configuration for our Gemstone board: 
./tools/configure.sh -l t3-gem-o1:nsh
This command configures the basic settings appropriate for the AM67A SoC’s features and activates a simple command-line interface called NuttShell (nsh). NuttShell allows you to perform basic file operations and system management tasks on the system.

​
1.5. Compiling the Project

After the configuration is complete, we can compile NuttX: 
make -j$(nproc)
This command performs a parallel compilation using all the CPU cores available on your system. The compilation results in an ELF file named nuttx. This file contains the operating system image to be loaded onto the R5F core.

​
1.6. Customizing the Configuration

Sometimes you may need to make changes to the default configuration. NuttX uses the menuconfig tool, similar to the Linux kernel. Through this graphical interface, you can activate drivers, change memory settings, or add new features. Your changes are stored in the .config file. 
make menuconfig
To make your changes permanent and able to be added to the version control system, use the savedefconfig command. This command saves only the configurations that differ from the default settings, thus preventing the configuration file from becoming unnecessarily large. You can copy the resulting defconfig file to the nsh default configuration under the boards/arm/am67/t3-gem-o1/configs directory or create a new configuration with a different name. 
make savedefconfig

​
1.7. Cleanup Operations

During development, you may sometimes need a fresh start. NuttX offers two levels of cleanup commands: 
# Only cleans object files and binaries
make clean

# Cleans all build files and the configuration
make distclean
The make clean command deletes the files resulting from the compilation but preserves the configuration. make distclean completely reverts the project to its initial state, in which case you need to perform the configuration process again.

​
2. Running

While the NuttX operating system runs on the R5F cores, the Linux operating system also runs on the A53 cores. Code can be loaded onto the R5F cores using the remoteproc mechanism present in the Linux operating system and U-Boot. Program files to be loaded onto the cores via remoteproc must be copied to the /lib/firmware directory with predefined names. At system startup, the remoteproc mechanism will automatically load the programs onto the relevant cores. Follow the steps below to run NuttX using remoteproc.
  1. Copy the nuttx file resulting from the compilation to the /lib/firmware directory with the name j722s-main-r5f0_0-fw.
  2. Reboot the board.
  3. You can access NuttShell by connecting a USB-to-TTL device to the UART-MAIN1’s GPIO-14 (TX) and GPIO-15 (RX) pins on the 40-pin HAT.
  4. From the opened nsh console, you can run the program named blink and observe the user LEDs on the board blinking.

​
3. Debug

​
3.1. Enabling Debug Features

NuttX is configured in release mode by default, which produces a small-sized ELF file that is optimized but contains no debug information. To perform step-by-step debugging during development, you will need to switch to debug mode. Open the menuconfig tool and follow this path: Build Setup → Debug Options → Enable Debug Features. Also, enable the Generate Debug Symbols option. These settings cause the compiler to embed debug information into the ELF, allowing the debugger to debug at the source code level.

​
3.2. CCS IDE Integration

Texas Instruments Code Composer Studio (CCS) is a development environment specifically optimized for the AM67A SoC family. To integrate your NuttX project into CCS, open the IDE and use File → Import → C/C++ → Existing Code as Makefile Project. Select the nuttx folder as the project directory.

​
3.3. Loading the Program onto the Core

To start the debug process via the CCS IDE, first create a Target Configuration by selecting the Debug Probe model you will use (e.g., Texas Instruments XDS200) and the J722S_TDA4VEN_TDA4AEN_AM67 board. Then, start the Target Configuration and connect to the AM67A SoC. After the debugger connection is established, select the Main R5F core and use Run → Load → Load Program to select the nuttx ELF file. This operation loads the NuttX operating system into the R5F core’s memory. Once the program is loaded, you can set breakpoints, watch variables, and step through the code. You can examine critical components of NuttX, such as its task scheduler and interrupt handlers, in detail this way.