> ## 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 > NuttX Operating System 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: ```bash theme={"system"} 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: ```bash theme={"system"} # 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: ```bash theme={"system"} ./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: ```bash theme={"system"} 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. ```bash theme={"system"} 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. ```bash theme={"system"} make savedefconfig ``` ### 1.7. Cleanup Operations During development, you may sometimes need a fresh start. NuttX offers two levels of cleanup commands: ```bash theme={"system"} # 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.