# libcsp/libcsp architecture

> Architecture diagram of the GitHub repository libcsp/libcsp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/libcsp/libcsp
- Repository: https://github.com/libcsp/libcsp

## Overview

##### Project Type and Purpose
- This is an open-source, modular C library implementing the Cubesat Space Protocol (CSP), a lightweight TCP/IP-like stack for embedded systems.
- It provides a connection-oriented and connection-less transport, routing, quality-of-service, and a socket API, running on multiple OS targets (FreeRTOS, Zephyr, POSIX/Linux).

##### High-Level Architectural Layers
a. Application Layer
- Examples and user programs (e.g., `examples/`, Python clients) invoking the CSP socket API.
b. API Layer
- Thread-safe socket API and service interfaces (`src/csp_*`, `include/csp/*.h`).
c. Core Protocol Stack
- Transport: connection management (`csp_conn`, `csp_rdp`, `csp_sfp`)
- Routing: router task, routing table (`csp_route`, `csp_rtable_*`)
- Buffer & Queue management: zero-copy buffers, queues (`csp_buffer`, `csp_qfifo`)
- Utilities: CRC, HMAC/sha1 (`src/crypto`, `src/csp_crc32`, `src/csp_hmac`)
d. Abstraction Layer
- OS abstraction (`src/arch/*`): semaphores, clocks, queues, system calls for FreeRTOS, Zephyr, POSIX
- Network interface abstraction (`src/interfaces/*`): CAN, UDP, KISS, loopback, ZMQ hub
- Driver implementations (`src/drivers/*`): CAN socketcan, eth_linux, usart_kiss, etc.
e. Bindings & Tools
- Python bindings (`src/bindings/python/pycsp.c`)
- Build scripts and CI configurations (`CMakeLists.txt`, `meson.build`, `.github/workflows`)
f. Documentation & Tests
- Sphinx docs (`doc/`), unittests (`unittests/`), examples illustrating usage

##### Component Relationships and Data Flows
- Applications call the CSP socket API → Core CSP transports calls to router and connection modules → Core CSP requests buffer allocation → Abstraction layer provides OS primitives (mutexes, queues) → CSP passes packets down to interface plugins → Drivers transmit frames on physical/virtual media → Incoming frames follow reverse path into the core and up to applications.
- Crypto modules are invoked within the transport layer for integrity/authentication.
- OS abstraction “arch” modules sit between core and real RTOS or Linux.

##### Key Architectural Patterns
- Layered design: clear separation between API, core logic, abstraction, and hardware/drivers.
- Plugin modules: compile-time inclusion of specific interfaces and drivers.
- OS-agnostic core: single codebase for different RTOS and POSIX environments.
- Zero-copy buffer and queue system for efficiency in embedded contexts.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application Layer"
        Examples["examples/"]:::app
        PosixSamples["samples/posix/"]:::app
    end

    %% API Layer
    subgraph "API Layer"
        CSPAPI["Socket API & Services\n(include/csp/*.h)"]:::api
    end

    %% Core Protocol Stack
    subgraph "Core Protocol Stack"
        subgraph "Transport Modules"
            Conn["csp_conn"]:::core
            RDP["csp_rdp"]:::core
            SFP["csp_sfp"]:::core
            Handler["csp_service_handler"]:::core
            Services["csp_services"]:::core
        end
        subgraph "Routing Modules"
            Route["csp_route"]:::core
            RTcidr["csp_rtable_cidr"]:::core
            RTstdio["csp_rtable_stdio"]:::core
        end
        subgraph "Buffer & Queue Management"
            Buffer["csp_buffer"]:::core
            Qfifo["csp_qfifo"]:::core
            RdpQ["csp_rdp_queue"]:::core
        end
        subgraph "Utilities"
            Hmac["csp_hmac"]:::core
            Sha1["csp_sha1"]:::core
            CRC["csp_crc32"]:::core
        end
    end

    %% Abstraction Layer
    subgraph "Abstraction Layer"
        subgraph "OS Primitives"
            ArchPOSIX["src/arch/posix"]:::abstr
            ArchFree["src/arch/freertos"]:::abstr
            ArchZephyr["src/arch/zephyr"]:::abstr
        end
        subgraph "Network Interface Plugins"
            IfCAN["csp_if_can"]:::abstr
            IfEth["csp_if_eth"]:::abstr
            IfI2C["csp_if_i2c"]:::abstr
            IfKiss["csp_if_kiss"]:::abstr
            IfLo["csp_if_lo"]:::abstr
            IfTun["csp_if_tun"]:::abstr
            IfUDP["csp_if_udp"]:::abstr
            IfZMQ["csp_if_zmqhub"]:::abstr
        end
    end

    %% Drivers & Physical Layer
    subgraph "Drivers & Physical Layer"
        CanSock["can_socketcan"]:::driv
        CanZeph["can_zephyr"]:::driv
        EthLinux["eth_linux"]:::driv
        UsartKiss["usart_kiss"]:::driv
        UsartLin["usart_linux"]:::driv
        UsartZeph["usart_zephyr"]:::driv
    end

    %% Underlying OS & Hardware
    subgraph "Underlying OS & Hardware"
        POSIX["POSIX/Linux"]:::os
        FreeRTOS["FreeRTOS"]:::os
        ZephyrOS["Zephyr"]:::os
        Hardware["Physical Media"]:::os
    end

    %% Bindings & Tools
    subgraph "Bindings & Tools"
        Python["pycsp.c"]:::tool
        CMake["CMakeLists.txt"]:::tool
        Meson["meson.build"]:::tool
        CI[".github/workflows"]:::tool
    end

    %% Documentation & Tests
    subgraph "Docs & Tests"
        Doc["doc/"]:::tool
        Tests["unittests/"]:::tool
    end

    %% Data and Control Flows
    Examples -->|uses| CSPAPI
    PosixSamples -->|uses| CSPAPI
    CSPAPI -->|API calls| Conn
    CSPAPI -->|API calls| RDP
    CSPAPI -->|API calls| SFP
    CSPAPI -->|API calls| Handler
    CSPAPI -->|API calls| Services

    Conn -->|transport| Route
    RDP -->|transport| Route
    SFP -->|transport| Route
    Services -->|service dispatch| Route

    Route -->|routing table| RTcidr
    Route -->|routing table| RTstdio

    Conn -->|allocates| Buffer
    RDP -->|queues| RdpQ
    Buffer -->|manages| Qfifo

    Conn -->|crypto| Hmac
    Conn -->|crypto| Sha1
    Conn -->|crc| CRC

    Conn -->|OS primitives| ArchPOSIX
    Conn -->|OS primitives| ArchFree
    Conn -->|OS primitives| ArchZephyr

    Handler -->|if plugin| IfCAN
    Handler -->|if plugin| IfEth
    Handler -->|if plugin| IfI2C
    Handler -->|if plugin| IfKiss
    Handler -->|if plugin| IfLo
    Handler -->|if plugin| IfTun
    Handler -->|if plugin| IfUDP
    Handler -->|if plugin| IfZMQ

    IfCAN -->|driver| CanSock
    IfCAN -->|driver| CanZeph
    IfEth -->|driver| EthLinux
    IfKiss -->|driver| UsartKiss
    IfKiss -->|driver| UsartLin
    IfKiss -->|driver| UsartZeph

    CanSock -->|transmit| Hardware
    CanZeph -->|transmit| Hardware
    EthLinux -->|transmit| Hardware
    UsartKiss -->|transmit| Hardware
    UsartLin -->|transmit| Hardware
    UsartZeph -->|transmit| Hardware

    Hardware -->|incoming frames| IfCAN
    Hardware -->|incoming frames| IfEth
    Hardware -->|incoming frames| IfKiss

    %% Tools flows
    CMake -.->|build config| Conn
    CMake -.->|build config| IfCAN
    Meson -.->|build config| Conn
    Meson -.->|build config| IfCAN
    CI -.->|CI config| CMake
    CI -.->|CI config| Meson

    Python -->|bindings| CSPAPI

    Doc -.->|documentation| CSPAPI
    Tests -.->|unit tests| Conn

    %% Click Events
    click Examples "https://github.com/libcsp/libcsp/tree/develop/examples/"
    click PosixSamples "https://github.com/libcsp/libcsp/tree/develop/samples/posix/"
    click CSPAPI "https://github.com/libcsp/libcsp/blob/develop/include/csp/csp.h"
    click Conn "https://github.com/libcsp/libcsp/blob/develop/src/csp_conn.c"
    click RDP "https://github.com/libcsp/libcsp/blob/develop/src/csp_rdp.c"
    click SFP "https://github.com/libcsp/libcsp/blob/develop/src/csp_sfp.c"
    click Handler "https://github.com/libcsp/libcsp/blob/develop/src/csp_service_handler.c"
    click Services "https://github.com/libcsp/libcsp/blob/develop/src/csp_services.c"
    click Route "https://github.com/libcsp/libcsp/blob/develop/src/csp_route.c"
    click RTcidr "https://github.com/libcsp/libcsp/blob/develop/src/csp_rtable_cidr.c"
    click RTstdio "https://github.com/libcsp/libcsp/blob/develop/src/csp_rtable_stdio.c"
    click Buffer "https://github.com/libcsp/libcsp/blob/develop/src/csp_buffer.c"
    click Qfifo "https://github.com/libcsp/libcsp/blob/develop/src/csp_qfifo.c"
    click RdpQ "https://github.com/libcsp/libcsp/blob/develop/src/csp_rdp_queue.c"
    click Hmac "https://github.com/libcsp/libcsp/blob/develop/src/crypto/csp_hmac.c"
    click Sha1 "https://github.com/libcsp/libcsp/blob/develop/src/crypto/csp_sha1.c"
    click CRC "https://github.com/libcsp/libcsp/blob/develop/src/csp_crc32.c"
    click ArchPOSIX "https://github.com/libcsp/libcsp/tree/develop/src/arch/posix/"
    click ArchFree "https://github.com/libcsp/libcsp/tree/develop/src/arch/freertos/"
    click ArchZephyr "https://github.com/libcsp/libcsp/tree/develop/src/arch/zephyr/"
    click IfCAN "https://github.com/libcsp/libcsp/blob/develop/src/interfaces/csp_if_can.c"
    click IfEth "https://github.com/libcsp/libcsp/blob/develop/src/interfaces/csp_if_eth.c"
    click IfI2C "https://github.com/libcsp/libcsp/blob/develop/src/interfaces/csp_if_i2c.c"
    click IfKiss "https://github.com/libcsp/libcsp/blob/develop/src/interfaces/csp_if_kiss.c"
    click IfLo "https://github.com/libcsp/libcsp/blob/develop/src/interfaces/csp_if_lo.c"
    click IfTun "https://github.com/libcsp/libcsp/blob/develop/src/interfaces/csp_if_tun.c"
    click IfUDP "https://github.com/libcsp/libcsp/blob/develop/src/interfaces/csp_if_udp.c"
    click IfZMQ "https://github.com/libcsp/libcsp/blob/develop/src/interfaces/csp_if_zmqhub.c"
    click CanSock "https://github.com/libcsp/libcsp/blob/develop/src/drivers/can/can_socketcan.c"
    click CanZeph "https://github.com/libcsp/libcsp/blob/develop/src/drivers/can/can_zephyr.c"
    click EthLinux "https://github.com/libcsp/libcsp/blob/develop/src/drivers/eth/eth_linux.c"
    click UsartKiss "https://github.com/libcsp/libcsp/blob/develop/src/drivers/usart/usart_kiss.c"
    click UsartLin "https://github.com/libcsp/libcsp/blob/develop/src/drivers/usart/usart_linux.c"
    click UsartZeph "https://github.com/libcsp/libcsp/blob/develop/src/drivers/usart/usart_zephyr.c"
    click Python "https://github.com/libcsp/libcsp/blob/develop/src/bindings/python/pycsp.c"
    click CMake "https://github.com/libcsp/libcsp/blob/develop/CMakeLists.txt"
    click Meson "https://github.com/libcsp/libcsp/blob/develop/meson.build"
    click CI "https://github.com/libcsp/libcsp/tree/develop/.github/workflows/"
    click Doc "https://github.com/libcsp/libcsp/tree/develop/doc/"
    click Tests "https://github.com/libcsp/libcsp/tree/develop/unittests/"

    %% Styles
    classDef app fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1;
    classDef api fill:#E8F5E9,stroke:#66BB6A,color:#1B5E20;
    classDef core fill:#BBDEFB,stroke:#2196F3,color:#0D47A1;
    classDef abstr fill:#C8E6C9,stroke:#43A047,color:#1B5E20;
    classDef driv fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef os fill:#ECEFF1,stroke:#90A4AE,color:#37474F;
    classDef tool fill:#F3E5F5,stroke:#AB47BC,color:#4A148C;
```
