Protocol 39 of 81Layer 7FrameAssembly v3.1.2
llms-full.txt
ptpIEEE 1588 Precision Time Protocol v2

Nanosecond Hardware Clock Sync (gm -> BoundaryClock ptp IEEE 1588v2)

Default Port / Protocol
UDP 319 (Event) / UDP 320 (General)
Host Endpoint Rule
Dual-Stack IPv4/IPv6
Wireshark Display Filter
ptp
Standards & Specs
IEEE 1588-2008, SMPTE ST 2059-2, ITU-T G.8275.2
Wire Stack:Ethernet II[802.1Q / QinQ / MPLS]IPv4 / IPv6UDP 319 (Event) / UDP 320 (General)PTPv2 (IEEE 1588)

What It Does on the Wire

For high-frequency trading, 5G fronthaul, and substation synchrophasors where NTP is way too slow, ptp routes event messages to UDP 319 and general messages to UDP 320 automatically.

IEEE 1588 Precision Time Protocol v2 (ptp) delivers sub-microsecond hardware timestamp synchronization for 5G fronthaul (ITU-T G.8275), SMPTE ST 2110 broadcast media, IEC 61850 power substations, and high-frequency trading fabrics. PTPv2 splits messages across two UDP ports: hardware-timestamped Event messages on UDP 319 (sync 0x0, delayreq 0x1) and software General messages on UDP 320 (followup 0x8, delayresp 0x9, announce 0xb).

FrameAssembly selects UDP 319 or 320 automatically from the message type, populates the 34-byte PTPv2 Common Header (versionPTP = 2, domainNumber, 8-byte ClockIdentity + 2-byte PortNumber, sequenceId, controlField), and appends precision 10-byte (48b sec, 32b nsec) timestamp payloads.

Two-Step Grandmaster Clock Sync (announce + sync + followup + delayreq/delayresp)

Model a complete 5-packet IEEE 1588 two-step slave offset and path-delay measurement loop with nanosecond .pcapng frame spacing (wait 250us).

SMPTE ST 2110 Broadcast & Financial Trading Switch Boundary Clock Testing

Verify QoS priority queuing (dscp 46 EF for Event UDP 319, dscp 34 AF41 for General UDP 320) and PTP domain isolation across leaf switches.

IEC 61850 Digital Substation Time-Distribution Security

Test OT IDS rules that alert on rogue ptp announce messages attempting Best Master Clock Algorithm (BMCA) takeover.

Minimal Quickstart (ptp_quickstart.frasm)

Hit Preview Packets to compile in-browser and eyeball timestamps + wire byte lengths, or ship it straight to the Playground.

ptp_quickstart.frasm7 lines
Open in Playground
host grandmaster { ip 10.60.1.1 }
host boundary_sw { ip 10.60.1.10 }
compile {
grandmaster -> boundary_sw ptp sync domain 0 seqid 100 clockid "001c73fffe000001" wait 200us
grandmaster -> boundary_sw ptp followup domain 0 seqid 100 clockid "001c73fffe000001"
}

What the Compiler Calculates So You Don't Have To

  • Routes time-critical Event messages (sync, delayreq) to UDP 319 and General messages (followup, delayresp, announce) to UDP 320 automatically.
  • Computes exact IEEE 1588-2008 messageLength (44 bytes for sync/followup/delayreq, 54 bytes for delayresp, 64 bytes for announce) and sets twoStepFlag on sync.
  • Swaps 319/320 onto srcport cleanly when <- reverse arrows are used.
Multi-Frame Lab · Ready to Compile

Complete Two-Step IEEE 1588v2 Grandmaster <-> Ordinary Clock Exchange (.pcapng Ready)

Executes a 5-frame PTPv2 announce -> sync -> followup -> delayreq -> delayresp cycle with sub-millisecond wait intervals ideal for .pcapng nanosecond export.

ptp_twostep_grandmaster.frasm13 lines
Open in Playground
host gm_clock { ip 172.22.0.1 }
host media_node { ip 172.22.0.45 }
compile {
// 1. Grandmaster announces BMCA hierarchy on UDP 320 (domain 127 = SMPTE ST 2059-2)
gm_clock -> media_node ptp announce domain 127 seqid 500 clockid "ec4670fffe010203" dscp 46 wait 500us
// 2. Two-step Sync (UDP 319) + Follow_Up (UDP 320) with matching seqid 501
gm_clock -> media_node ptp sync domain 127 seqid 501 clockid "ec4670fffe010203" dscp 46 wait 120us
gm_clock -> media_node ptp followup domain 127 seqid 501 clockid "ec4670fffe010203" dscp 46 wait 250us
// 3. Slave measures reverse path delay via Delay_Req (UDP 319) -> Delay_Resp (UDP 320)
media_node -> gm_clock ptp delayreq domain 127 seqid 88 clockid "001b21fffeaa0045" dscp 46 wait 180us
media_node <- gm_clock ptp delayresp domain 127 seqid 88 clockid "ec4670fffe010203" dscp 46
}
Terminal Commands (FrameAssembly CLI v3.1.2)
# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show ptp_twostep_grandmaster.frasm

# 2. Compile .frasm -> classic .pcap (tcpdump/tcpreplay/Suricata) or nanosecond .pcapng
frameassembly ptp_twostep_grandmaster.frasm ptp_twostep_grandmaster.pcap
frameassembly ptp_twostep_grandmaster.frasm ptp_twostep_grandmaster.pcapng

# 3. Round-trip .pcap <-> .frasm whenever you want to scrub or tweak an existing capture
frameassembly reverse ptp_twostep_grandmaster.pcap ptp_twostep_grandmaster_edited.frasm

All ptp Keywords & Header Options

Every sub-keyword and header option is lowercase [a-z0-9]+ with zero underscores — mix and match them in any order after ptp:

src_host -> dst_host ptp [sync | delayreq | followup | delayresp | announce | msgtype "<text>"] [domain <0..255>] [seqid <0..65535>] [clockid "<text>"]
Keyword / OptionAccepted ValueDefaultEffect on Packet
sync | delayreq | followup | delayresp | announce | msgtype "<text>"PTPv2 message type keywordsync (0x0 on UDP 319)Selects lower nibble of byte 0 and target UDP port (0x0 Sync/319, 0x1 Delay_Req/319, 0x8 Follow_Up/320, 0x9 Delay_Resp/320, 0xb Announce/320).
domain <0..255>Whole number (0..255)0Sets domainNumber in byte 4 (0 default IEEE 1588, 24/44 telecom G.8275, 127 SMPTE ST 2059).
seqid <0..65535>Whole number (0..65535)1Sets sequenceId in bytes 30..31 pairing sync with followup and delayreq with delayresp.
clockid "<text>"16-char EUI-64 hex ("001c73fffe000001") or 8B stringDerived from source MAC (EUI-64 fffe)Populates the 8-byte ClockIdentity inside the 10-byte sourcePortIdentity field.

Cross-Layer Wrappers Valid with ptp

802.1Q VLAN / QinQ / MPLS tags, IPv4/IPv6 QoS & TTL fields, wait gaps, and transport overrides allowed on this protocol

10 options
OptionRange / FormatDefaultEffect on Packet
wait <number><ns|us|ms|s|m>Time gap (ns, us, ms, s, m)10msAdvances the packet timestamp clock after sending this packet and before the next packet (wait 0ns sends back-to-back).
payload "<text>" | hexpayload "<hex>"Quoted text or hex bytes (choose one)OmittedAppends or overrides raw payload bytes ("deadbeef" or "de:ad:be:ef") and updates packet lengths and checksums.
srcmac <mac> | dstmac <mac>Colon, hyphen, or Cisco dot MACHost MAC / RFC multicast MACOverrides the 14-byte Ethernet II source or destination MAC address for this single packet.
vlan <0..4095> [pcp <0..7>] [dei <0|1>]VLAN ID 0..4095, PCP 0..7, DEI 0..1UntaggedWraps the packet in an IEEE 802.1Q VLAN tag (0x8100) with optional 802.1p QoS priority.
qinq <0..4095> [innervlan <0..4095>]Outer S-VLAN 0..4095, Inner C-VLAN 0..4095Untagged (innervlan 1 when qinq is set)Double-tags the packet with outer IEEE 802.1ad S-Tag (0x88a8) plus inner IEEE 802.1Q C-Tag (0x8100).
mpls <0..1048575> [exp|tc <0..7>] [bos <0|1>] [mplsttl <0..255>]Label 0..1048575, exp/tc 0..7, bos 0..1, ttl 0..255Unlabeled (at most 1 mpls tag per packet)Inserts a 32-bit MPLS label header (0x8847) ahead of the Layer 3 header.
ttl <0..255> [dscp <0..63>] [ecn <0..3>]TTL/Hop Limit 0..255, DSCP 0..63, ECN 0..3ttl 64, dscp 0, ecn 0Sets IPv4 TTL or IPv6 Hop Limit plus DiffServ (DSCP) and ECN QoS markings.
ipid <0..65535> [df] [mf] [fragoffset <0..8191>]IPv4 ID, DF/MF flags, fragment offset 0..8191ipid 1, flags 0, fragoffset 0Sets IPv4 Identification, Do-Not-Fragment (df), More-Fragments (mf), and fragment offset (ignored over IPv6).
flowlabel <0..1048575>20-bit IPv6 Flow Label (0..1048575)0Sets the 20-bit IPv6 Flow Label for ECMP routing tests (ignored when running over IPv4 hosts).
srcport <0..65535> | dstport <0..65535>Port number 0..65535srcport 49152 (remembered), UDP 319 (Event) / UDP 320 (General)Overrides source or destination port and remembers the port pair automatically on <- replies.

Gotchas & Quick Fixes

Message Keywords Contain Zero Underscores (delayreq, followup, delayresp)

Avoid
gm_clock -> media_node ptp follow_up seqid 501
Valid v3.1.2 Syntax
gm_clock -> media_node ptp followup seqid 501

Spell PTPv2 message types without underscores: sync, delayreq, followup, delayresp, and announce.

Export Sub-Microsecond PTP Captures as .pcapng for 1ns Timestamp Resolution

Valid v3.1.2 Syntax
frameassembly ptp_twostep_grandmaster.frasm ptp_twostep_grandmaster.pcapng

Classic .pcap (0xa1b2c3d4) stores 1us timestamps; .pcapng writes if_tsresol = 9 (10^-9s) so wait 25ns or wait 150ns hardware timestamps are preserved without rounding.

Field Guide 07
Physical Hardware Labs: Blasting .pcap Captures onto Real Copper & Fiber (tcpreplay)