# xl4-shiro/excelfore-gptp architecture

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

- Interactive diagram: https://gitdiagram.com/xl4-shiro/excelfore-gptp
- Repository: https://github.com/xl4-shiro/excelfore-gptp

## Overview

##### Project type and purpose
- This is a C-based implementation of IEEE 802.1AS Precision Time Protocol (gPTP) that can run as a daemon (gptp2d) in endpoint or bridge mode, supporting single/multiple PTP domains.
- It provides both a stand-alone process (gptp2d) and a reusable library (libx4gptp2) with APIs for clock access and IPC for monitoring.

##### File structure
- Top-level build/configuration: autogen.sh, configure.ac, Makefile.am, xl4gptp.pc.in
- Core daemon and library: gptp2d.c, gptpcommon.c/h, gptpclock.c/h, gptpmasterclock.c/h, gptpipc.c/h, gptpnet.h
- State-machines folder—all “*_sm.c” and “*_sm.h” files implement PTP message- and port-level state machines (announce, sync, delay, signaling, GM selection).
- Platform abstraction: posix/ directory provides socket, timestamp, PTP-clock and netlink implementations.
- Tools & tests: gptp2_test_run.sh, unit tests (cmocka), gpmongui.py (GUI monitor), sm_create.py (auto-generate SM code).

##### README for additional insights
- Describes gptp2d usage, configuration file (gptp2.conf), hardware timestamping dependencies, and linking with libx4gptp2 for external applications.
- Mentions IPC interfaces for status inspection (gptpipc) and master-clock API (gptpmasterclock_getts64).

##### Main components and their interactions
a. gptp2d Daemon
– Configuration loader (reads gptp2.conf or CLI flags)
– Network I/O layer (gptpnet + posix/ix_gptpnet)
– State-Machine Core (all *_sm modules implementing IEEE-802.1AS protocols)
– Clock Abstraction (gptpclock: hardware PHC vs virtual software clock)
– Master-Clock API (gptpmasterclock)
– IPC Server (gptpipc provides UNIX-socket interface to clients)
b. Underlying OS and Hardware
– Linux kernel PTP Hardware Clock interface
– Network driver with HW timestamping
c. External clients
– gpmongui.py or gptpipcmon (use IPC to query daemon)
– Any app linking to libx4gptp2 for timestamp retrieval

##### Relationships and data flows
- Packet receive path: NIC → kernel HW-timestamp → gptpnet → State Machines → Clock Abstraction → state update
- Packet transmit path: State Machines → gptpnet → NIC (with timestamp request)
- Clock adjustment: State Machines decide offset/frequency corrections → gptpclock sets PHC or software clock
- IPC: State Machines and clock modules publish status to gptpipc → external monitor UIs
- API usage: Applications call gptpmasterclock_getts64() → gptpclock returns current gPTP time

##### Architectural patterns and design principles
- Layered architecture: network layer → protocol state machines → clock layer → IPC/API layer
- State-machine pattern: each PTP message type and port operation is a distinct state machine module
- Abstraction of platform specifics: all OS- and hardware-specific code lives in posix/ subdirectory

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        direction TB
        GUI["gpmongui.py"]:::external
        IPCMon["gptpipcmon"]:::external
        App["User App (libx4gptp2)"]:::external
    end

    %% Linux Kernel and NIC
    subgraph "Linux Kernel & NIC" 
        direction TB
        NIC["NIC/HW Timestamping"]:::io
        KernelPTP["PTP HW Clock Interface"]:::io
    end

    %% gptp2d Process
    subgraph "gptp2d Daemon" 
        direction TB
        Config["Configuration Loader"]:::core
        NetIO["Network I/O Layer"]:::io
        SMCore["State-Machine Core"]:::core
        ClockAbs["Clock Abstraction"]:::core
        MasterAPI["Master-Clock API"]:::ipcapi
        IPCSrv["IPC Server"]:::ipcapi
    end

    %% Build & Tools (supporting)
    subgraph "Tools & Tests"
        direction TB
        SMGen["sm_create.py / sm_list.txt"]:::tools
        Tests["Unit Tests"]:::tools
        TestRun["gptp2_test_run.sh"]:::tools
    end

    %% Flows
    NIC -->|"ingress packets"| NetIO
    KernelPTP -->|"timestamps"| NetIO
    NetIO -->|"PTP messages"| SMCore
    SMCore -->|"state updates"| ClockAbs
    ClockAbs -->|"adjust clock"| KernelPTP
    SMCore -->|"status"| IPCSrv
    IPCSrv -->|"IPC messages"| IPCMon
    IPCMon -->|"monitor"| IPCSrv
    App -->|"getts API"| MasterAPI
    MasterAPI -->|"query time"| ClockAbs
    GUI -->|"monitor via IPC"| IPCSrv

    %% Click Events
    click Config "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptpman.c"
    click Config "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptpman.h"
    click Config "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptp_defaults.h"
    click NetIO "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptpnet.h"
    click NetIO "https://github.com/xl4-shiro/excelfore-gptp/blob/master/posix/ix_gptpnet.c"
    click SMCore "https://github.com/xl4-shiro/excelfore-gptp/blob/master/announce_interval_setting_sm.c"
    click SMCore "https://github.com/xl4-shiro/excelfore-gptp/blob/master/announce_interval_setting_sm.h"
    click ClockAbs "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptpclock.c"
    click ClockAbs "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptpclock.h"
    click ClockAbs "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptpclock_virtual.c"
    click ClockAbs "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptpclock_virtual.h"
    click ClockAbs "https://github.com/xl4-shiro/excelfore-gptp/blob/master/posix/ix_gptpclock.c"
    click MasterAPI "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptpmasterclock.c"
    click MasterAPI "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptpmasterclock.h"
    click MasterAPI "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptpmasterclock_response.c"
    click IPCSrv "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptpipc.c"
    click IPCSrv "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptpipc.h"
    click IPCMon "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptpipcmon.c"
    click IPCSrv "https://github.com/xl4-shiro/excelfore-gptp/tree/master/gptpipc_extscript"
    click SMGen "https://github.com/xl4-shiro/excelfore-gptp/blob/master/sm_create.py"
    click Tests "https://github.com/xl4-shiro/excelfore-gptp/blob/master/posix/ix_gptpnet_unittest.c"
    click Tests "https://github.com/xl4-shiro/excelfore-gptp/blob/master/posix/ix_gptpclock_unittest.c"
    click TestRun "https://github.com/xl4-shiro/excelfore-gptp/blob/master/gptp2_test_run.sh"

    %% Styles
    classDef core fill:#D0E1FF,stroke:#5B8FF9,color:#000
    classDef io fill:#DFFFE0,stroke:#38A169,color:#000
    classDef ipcapi fill:#FFE8B3,stroke:#D69E2F,color:#000
    classDef external fill:#FFD6D6,stroke:#E53E3E,color:#000
    classDef tools fill:#EDEDED,stroke:#888,color:#000
```
