Troubleshooting Guide¶

This guide covers common issues encountered when using the EmbSec Kit and their solutions.

Build Issues¶

CMake Configuration Errors¶

"CMake version 3.20 or higher is required"¶

Problem: Your CMake version is too old.

Solution:

# Check current version
cmake --version

# Ubuntu/Debian - update CMake
sudo apt-get update
sudo apt-get install cmake

# macOS
brew upgrade cmake

# Or download from https://cmake.org/download/

"The CMAKE_C_COMPILER: arm-none-eabi-gcc is not a full path"¶

Problem: ARM toolchain not found in PATH.

Solution:

# Check if installed
which arm-none-eabi-gcc

# Ubuntu/Debian
sudo apt-get install gcc-arm-none-eabi

# macOS
brew install arm-none-eabi-gcc

# Add to PATH if installed elsewhere
export PATH=/path/to/arm-toolchain/bin:$PATH

"TivaWare not found"¶

Problem: TivaWare SDK is not in the expected location.

Solution:

1. Download TivaWare from TI website
2. Extract to vendor/tivaware/
3. Ensure structure is:

   vendor/tivaware/
   ├── driverlib/
   ├── inc/
   └── ...
   

Note: This warning can be ignored for QEMU-only builds.

Build Failures¶

"undefined reference to __aeabi_*"¶

Problem: Missing ARM runtime library functions.

Solution: Ensure you're using the correct toolchain:

# For hardware
cmake --preset embedded

# For QEMU
cmake --preset qemu

"region `FLASH' overflowed by X bytes"¶

Problem: Program too large for target memory.

Solution:

1. Build with Release configuration:

   cmake -B build -DCMAKE_BUILD_TYPE=Release
   

2. Check code size:

   arm-none-eabi-size build/labs/*/lab-name
   

3. Reduce code size:

4. Remove debug prints
5. Optimize data structures
6. Use -Os optimization flag

"No rule to make target"¶

Problem: Missing source files or incorrect paths.

Solution:

1. Verify file exists:

   ls labs/01-buffer-overflow/src/main.c
   

2. Clean and rebuild:

   make distclean
   make configure
   make build
   

QEMU Issues¶

QEMU Won't Start¶

"qemu-system-arm: command not found"¶

Problem: QEMU not installed.

Solution:

# Ubuntu/Debian
sudo apt-get install qemu-system-arm

# macOS
brew install qemu

# Verify installation
qemu-system-arm --version

"qemu-system-arm: -M lm3s6965evb: unsupported machine type"¶

Problem: QEMU version too old or missing machine support.

Solution: Install QEMU 4.0 or newer:

# Check version
qemu-system-arm --version

# List supported machines
qemu-system-arm -M help | grep lm3s

QEMU Runtime Errors¶

"Guest crashed or hung"¶

Problem: Lab program crashed.

Solution:

1. Debug with GDB:

   make debug-01-buffer-overflow
   

2. Check for common issues:

3. Stack overflow
4. Invalid memory access
5. Infinite loops

"No output from QEMU"¶

Problem: UART not configured or program stuck.

Solution:

1. Verify UART initialization in code
2. Add debug output early in main()
3. Use -monitor stdio for QEMU monitor

Testing Issues¶

Python Test Failures¶

"ModuleNotFoundError: No module named 'test_framework'"¶

Problem: Python can't find test utilities.

Solution: Run tests from project root:

cd /path/to/embsec-kit
make test

"FileNotFoundError: build-qemu/labs/..."¶

Problem: Labs not built for QEMU.

Solution:

make qemu-build
make test

"timeout: the monitored command dumped core"¶

Problem: Test timeout or crash.

Solution:

1. Increase timeout in test script
2. Check for infinite loops in lab code
3. Debug the specific test:

   make unittest-lab LAB=01-buffer-overflow
   

Test Environment Issues¶

"Python 3.x required"¶

Problem: Python version too old.

Solution:

# Check version
python3 --version

# Ubuntu/Debian
sudo apt-get install python3

# Use virtual environment
python3 -m venv venv
source venv/bin/activate

Hardware Issues¶

Flash Programming¶

"lm4flash: command not found"¶

Problem: Flash tool not installed.

Solution:

# Install from source
git clone https://github.com/utzig/lm4tools.git
cd lm4tools/lm4flash
make
sudo cp lm4flash /usr/local/bin/

"Unable to find any ICDI devices"¶

Problem: Device not connected or drivers missing.

Solution:

1. Check USB connection
2. Verify device appears in lsusb (Linux) or System Information (macOS)
3. Add udev rules (Linux):

   echo 'ATTRS{idVendor}=="1cbe", ATTRS{idProduct}=="00fd", MODE="0666"' | \
   sudo tee /etc/udev/rules.d/99-stellaris.rules
   sudo udevadm control --reload-rules
   

Serial Communication¶

"Permission denied: '/dev/ttyACM0'"¶

Problem: No permission to access serial port.

Solution:

# Add user to dialout group
sudo usermod -a -G dialout $USER
# Log out and back in

"No serial output"¶

Problem: Wrong serial settings or cable.

Solution:

1. Check serial settings: 115200 8N1
2. Verify TX/RX connections
3. Test with serial terminal:

   screen /dev/ttyACM0 115200
   

Development Environment¶

IDE Integration¶

"No compile_commands.json found"¶

Problem: IDE can't find compilation database.

Solution:

# CMake generates this automatically
cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
# Link to project root
ln -s build/compile_commands.json .

"Includes not found in VS Code"¶

Problem: IntelliSense can't find headers.

Solution: Update .vscode/c_cpp_properties.json:

{
  "configurations": [{
    "name": "EmbSec",
    "compileCommands": "${workspaceFolder}/compile_commands.json",
    "intelliSenseMode": "gcc-arm"
  }]
}

Docker Issues¶

"docker-compose: command not found"¶

Problem: Docker Compose not installed.

Solution:

# Install Docker Compose
sudo apt-get install docker-compose
# Or use Docker Compose V2
docker compose version

"Permission denied while trying to connect to Docker daemon"¶

Problem: User not in docker group.

Solution:

sudo usermod -a -G docker $USER
# Log out and back in

Common Mistakes¶

Configuration Mistakes¶

1. Wrong build directory

   # Bad: mixing hardware and QEMU builds
   make configure
   make qemu-01-buffer-overflow  # Fails!
   
   # Good: use separate directories
   make qemu-build
   make qemu-01-buffer-overflow
   

2. Missing environment setup

   # Always run setup first
   make setup
   

Code Mistakes¶

1. Stack size issues
2. Default stack is 1KB
3. Large local arrays cause overflow

4. Use static or heap allocation

5. Uninitialized hardware

6. Always call embsec_init()

7. Initialize peripherals before use

8. Wrong flag format

9. Flags must be exactly 32 characters
10. Use embsec_flag_t type

Getting Help¶

Debug Information¶

Collect this information when reporting issues:

# System information
uname -a
cmake --version
arm-none-eabi-gcc --version
qemu-system-arm --version
python3 --version

# Build configuration
cmake -L build | grep -E "(CMAKE|EMBSEC)"

# Build output
make clean
make build 2>&1 | tee build.log

Support Resources¶

1. Documentation
2. Check /docs directory
3. Read lab README files

4. Review API documentation

5. Examples

6. Study working labs
7. Check SDK examples

8. Review test code

9. Community

10. GitLab issue tracker
11. Course forums
12. Office hours

Quick Fixes¶

Reset Everything¶

make distclean
rm -rf build-qemu
make setup

Verify Tools¶

make info
which cmake arm-none-eabi-gcc qemu-system-arm python3

Test Minimal Setup¶

# Test QEMU
qemu-system-arm -M lm3s6965evb -nographic -kernel /dev/null

# Test toolchain
echo 'int main(){}' | arm-none-eabi-gcc -x c - -o test.elf

See Also¶

• Environment Setup - Initial setup guide
• Building - Build instructions
• Debugging - Debugging techniques
• Testing - Test procedures