Troubleshooting

Common issues and solutions for Nexus development.

Build Issues

CMake Configuration Fails

Symptom: CMake configuration error

Common Causes:

  1. Missing toolchain

  2. Incorrect CMake version

  3. Missing dependencies

Solutions:

# Check CMake version (requires 3.20+)
cmake --version

# Install correct CMake version
pip install cmake --upgrade

# Verify toolchain is in PATH
arm-none-eabi-gcc --version

# Clean and reconfigure
rm -rf build
python scripts/building/build.py

Compilation Errors

Symptom: Compilation fails with errors

Common Causes:

  1. Missing header files

  2. Syntax errors

  3. Incompatible compiler flags

Solutions:

# Check for syntax errors
python scripts/tools/format.py --check

# Verify include paths
python scripts/building/build.py --verbose

# Check compiler version
arm-none-eabi-gcc --version

Linker Errors

Symptom: Undefined reference errors

Common Causes:

  1. Missing source files

  2. Incorrect library order

  3. Missing symbols

Solutions:

# Check if all sources are included
grep -r "function_name" platforms/

# Verify library dependencies in CMakeLists.txt
# Check linker map file
cat build/platform/application.map

Runtime Issues

Hard Fault

Symptom: System crashes with hard fault

Common Causes:

  1. Stack overflow

  2. Null pointer dereference

  3. Unaligned memory access

  4. Invalid function pointer

Debugging Steps:

# Enable fault handlers
# Check fault status registers
# Examine call stack in debugger
arm-none-eabi-gdb build/application.elf
(gdb) bt

Solutions:

  • Increase stack size in linker script

  • Add null pointer checks

  • Use proper alignment

  • Validate function pointers

Memory Issues

Symptom: Random crashes or corruption

Common Causes:

  1. Buffer overflow

  2. Memory leak

  3. Use after free

  4. Stack/heap collision

Debugging:

# Run with AddressSanitizer (native)
python scripts/building/build.py --sanitizer address
./build/native/debug/tests/test

# Check memory usage
arm-none-eabi-size build/application.elf

Solutions:

  • Add bounds checking

  • Track allocations/frees

  • Use static analysis tools

  • Increase heap size

Peripheral Issues

GPIO Not Working

Checklist:

☐ Clock enabled for GPIO port ☐ Pin configured correctly ☐ No conflicting alternate function ☐ Pull-up/down configured if needed ☐ Output driver enabled

Debug Steps:

/* Verify clock is enabled */
if (!(RCC->AHB1ENR & RCC_AHB1ENR_GPIOAEN)) {
    LOG_ERROR("GPIO clock not enabled");
}

/* Check pin configuration */
LOG_DEBUG("MODER: 0x%08X", GPIOA->MODER);
LOG_DEBUG("ODR: 0x%08X", GPIOA->ODR);

UART Not Transmitting

Checklist:

☐ UART clock enabled ☐ Baud rate configured correctly ☐ TX pin configured as alternate function ☐ UART enabled ☐ TX buffer not full

Debug Steps:

/* Check UART status */
LOG_DEBUG("SR: 0x%08X", USART1->SR);
LOG_DEBUG("CR1: 0x%08X", USART1->CR1);

/* Verify baud rate */
uint32_t brr = USART1->BRR;
uint32_t baudrate = SystemCoreClock / brr;
LOG_DEBUG("Calculated baudrate: %u", baudrate);

Testing Issues

Tests Failing

Symptom: Unit tests fail

Common Causes:

  1. Test dependencies

  2. Incorrect test setup

  3. Platform-specific behavior

  4. Timing issues

Solutions:

# Run specific test
python scripts/test/test.py --suite hal --test gpio

# Run with verbose output
python scripts/test/test.py --verbose

# Check test logs
cat build/test_results.log

Coverage Not Generated

Symptom: Coverage report empty

Solutions:

# Build with coverage enabled
python scripts/building/build.py --coverage

# Run tests
python scripts/test/test.py

# Generate report
python scripts/test/coverage.py

# View report
open build/coverage/index.html

See Also

Summary

This guide covers common issues in:

  • Build system (CMake, compilation, linking)

  • Runtime (hard faults, memory issues)

  • Peripherals (GPIO, UART, etc.)

  • Testing (test failures, coverage)

For additional help, check the documentation or ask in GitHub Discussions.