How xl4-shiro/excelfore-gptp works
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