Project Structure¶

This document describes the complete directory structure and organization of the EmbSec Kit project.

Directory Tree Overview¶

embsec-kit/
├── CMakeLists.txt          # Root CMake configuration
├── CMakePresets.json       # CMake preset configurations
├── Makefile               # Convenience wrapper for CMake
├── VERSION                # Project version file
├── README.md              # Project introduction
├── LICENSE                # License information
├── CHANGELOG.md           # Version history
├── mkdocs.yml             # Documentation configuration
├── docs/                  # Documentation source files
├── labs/                  # Lab exercises
├── sdk/                   # EmbSec SDK
├── tools/                 # Development tools
└── vendor/                # Third-party dependencies

Root Files¶

Build Configuration¶

`CMakeLists.txt`¶

Root CMake configuration that:

Sets up the project and version
Configures build options
Includes SDK and labs subdirectories
Sets up installation rules

`CMakePresets.json`¶

Defines CMake configuration presets:

embedded - Base hardware configuration
tm4c-debug - Debug build for TM4C123GH6PM
tm4c-release - Release build for TM4C123GH6PM
qemu - QEMU emulation build
host-debug - Native host testing
docs - Documentation only

`Makefile`¶

User-friendly wrapper around CMake commands providing:

Simplified target names
Colored output
Dependency checking
Common workflow shortcuts

Project Metadata¶

VERSION - Single source of truth for project version
README.md - Project overview and quick start guide
LICENSE - MIT license file
CHANGELOG.md - Version history and release notes

Documentation (`docs/`)¶

docs/
├── CMakeLists.txt         # Documentation build configuration
├── requirements.txt       # Python dependencies for MkDocs
├── index.md              # Documentation home page
├── assets/               # Images and stylesheets
│   ├── logo.png
│   └── stylesheet.css
├── architecture/         # System design documentation
│   ├── index.md
│   ├── build-system.md
│   ├── platform-differences.md
│   ├── security-model.md
│   └── test-framework.md
├── contributing/         # Contribution guidelines
├── development/          # Development guides
│   ├── index.md
│   ├── building.md
│   ├── debugging.md
│   ├── environment-setup.md
│   └── testing.md
├── getting-started/      # New user guides
│   ├── index.md
│   ├── installation.md
│   ├── quick-start.md
│   └── first-lab.md
├── instructor/           # Instructor resources
│   ├── index.md
│   ├── best-practices.md
│   ├── creating-labs.md
│   ├── lab-design.md
│   ├── vulnerability-patterns.md
│   └── writing-tests.md
├── labs/                 # Lab documentation
│   ├── index.md
│   ├── lab-structure.md
│   ├── 01-buffer-overflow.md
│   └── 02-format-string.md
├── reference/            # Reference documentation
│   ├── index.md
│   ├── cmake-targets.md
│   ├── makefile-targets.md
│   ├── project-structure.md
│   ├── configuration.md
│   └── troubleshooting.md
└── sdk/                  # SDK API documentation
    ├── index.md
    ├── api-reference.md
    ├── core.md
    ├── uart.md
    ├── gpio.md
    ├── timer.md
    ├── crypto.md
    ├── flag.md
    └── examples.md

Labs (`labs/`)¶

labs/
├── CMakeLists.txt        # Labs build configuration
├── README.md             # Labs overview
├── common/               # Shared lab resources
│   ├── startup_gcc.c     # ARM startup code
│   ├── tm4c123gh6pm.ld   # Linker script
│   └── test_framework.py # Python test utilities
├── template/             # Template for new labs
│   ├── CMakeLists.txt
│   ├── README.md
│   ├── INSTRUCTOR.md
│   ├── metadata.yml
│   ├── src/
│   │   └── main.c
│   ├── solution/
│   │   ├── exploit.py
│   │   └── writeup.md
│   └── tests/
│       └── test_lab.py
├── 01-buffer-overflow/   # Buffer overflow lab
│   └── (same structure as template)
└── 02-format-string/     # Format string lab
    └── (same structure as template)

Lab Directory Structure¶

Each lab follows a consistent structure:

CMakeLists.txt - Lab-specific build configuration
README.md - Student-facing lab instructions
INSTRUCTOR.md - Instructor notes and solution guide
metadata.yml - Lab metadata (difficulty, topics, etc.)
src/ - Source code files
main.c - Main lab implementation
solution/ - Solution files (not distributed to students)
exploit.py - Example exploit
writeup.md - Detailed solution explanation
tests/ - Automated tests
test_lab.py - Unit tests for the lab

SDK (`sdk/`)¶

sdk/
├── CMakeLists.txt        # SDK build configuration
├── README.md             # SDK overview
├── embsec.pc.in          # pkg-config template
├── cmake/                # CMake modules
│   ├── CTestConfig.cmake
│   ├── EmbSecConfig.cmake
│   ├── EmbSecLab.cmake   # Lab helper functions
│   ├── TM4CToolchain.cmake
│   ├── LM3S6965Toolchain.cmake
│   └── embsec-config.cmake.in
├── include/              # Public headers
│   └── embsec/
│       ├── embsec.h      # Main header
│       ├── uart.h        # UART interface
│       ├── gpio.h        # GPIO interface
│       ├── timer.h       # Timer interface
│       ├── crypto.h      # Cryptography utilities
│       ├── flag.h        # Flag management
│       └── version.h     # Version macros
├── src/                  # Implementation files
│   ├── embsec.c
│   ├── uart.c
│   ├── gpio.c
│   ├── timer.c
│   ├── crypto.c
│   └── flag.c
└── tests/                # SDK unit tests
    ├── CMakeLists.txt
    └── sdk/
        ├── CMakeLists.txt
        ├── test_crypto.c
        └── test_utils.c

Tools (`tools/`)¶

tools/
├── docker/               # Container configurations
│   ├── Dockerfile        # Development container
│   ├── Dockerfile.ci     # CI/CD container
│   ├── docker-compose.yml
│   ├── env.example       # Environment template
│   ├── README.md
│   └── devcontainer/
│       └── devcontainer.json
├── scripts/              # Build and test scripts
│   ├── debug_lab.sh      # GDB debugging helper
│   ├── release.sh        # Release automation
│   ├── run_lab.sh        # QEMU execution wrapper
│   └── test_labs.py      # Lab test runner
└── utilities/            # Development utilities
    ├── analyze_binary.py # Binary analysis tool
    └── create_lab.py     # Lab creation wizard

Script Purposes¶

Build Scripts¶

release.sh - Automates release process
test_labs.py - Runs lab unit tests

Development Scripts¶

debug_lab.sh - Launches GDB with QEMU
run_lab.sh - Runs lab in QEMU
analyze_binary.py - Analyzes compiled binaries
create_lab.py - Creates new lab from template

Vendor (`vendor/`)¶

Third-party dependencies:

vendor/
└── tivaware/             # TI TivaWare SDK
    ├── driverlib/        # Hardware abstraction layer
    ├── inc/              # Hardware definitions
    └── ...

Build Directories¶

Created during build process:

build/                    # Hardware build directory
├── CMakeCache.txt        # CMake cache
├── compile_commands.json # IDE support
├── labs/                 # Built lab binaries
├── sdk/                  # Built SDK library
└── packages/             # Lab zip packages

build-qemu/               # QEMU build directory
└── (similar structure)

File Types and Conventions¶

Source Files¶

.c - C source files
.h - C header files
.S - Assembly source files
.ld - Linker scripts

Build Files¶

CMakeLists.txt - CMake configuration
*.cmake - CMake modules

Documentation¶

.md - Markdown documentation
.yml - YAML configuration/metadata

Generated Files¶

.elf - Executable and Linkable Format
.bin - Raw binary for flashing
.hex - Intel HEX format
.map - Linker map file

Important Files by Purpose¶

For Students¶

labs/*/README.md - Lab instructions
sdk/include/embsec/*.h - API reference

For Instructors¶

labs/*/INSTRUCTOR.md - Teaching notes
labs/*/solution/* - Solution files
labs/template/ - New lab template

For Developers¶

sdk/cmake/*.cmake - Build system modules
tools/scripts/* - Development scripts
docs/development/ - Development guides

For CI/CD¶

.gitlab-ci.yml - GitLab CI configuration
tools/docker/Dockerfile.ci - CI container