PCIe Timing Card Installation Guide

BRIDZA

Table of Contents

• Hardware Installation
• Linux Driver Installation
• Windows Driver Installation
• API Usage Examples
• PTP Configuration (linuxptp)
• Troubleshooting

1. Hardware Installation

1.1 Card Specifications

1.2 System Requirements

Minimum Requirements:

• PCIe x1 slot (or larger)
• Linux kernel ≥3.2 (for native driver) or Windows 10/11
• 1GB RAM minimum
• Admin/root access for driver installation

Recommended:

• PCIe x4 or x8 slot for best performance
• Isolated PCIe slot (not sharing with high-bandwidth devices)
• Modern CPU (Intel i5/i7 or equivalent) for PTP processing

1.3 Pre-Installation Checklist

• [ ] Verify card model (STW-PCIe-10M, STW-PCIe-GNSS, etc.)
• [ ] Check PCIe slot compatibility
• [ ] Prepare reference frequency source (10MHz)
• [ ] Gather required cables (1PPS, reference input)
• [ ] Backup system (recommended)
• [ ] Download latest driver from BRIDZA support site

1.4 Physical Installation Steps

CAUTION: Handle card by edges only. Avoid touching gold contacts or components.

• Power Down System: Shut down completely, disconnect power cord
• Discharge Static: Touch metal chassis or use ESD wrist strap
• Open Case: Remove side panel per system documentation
• Locate Slot: Identify available PCIe x1/x4/x8 slot
• Remove Slot Cover: Unscrew and remove expansion slot cover
• Insert Card: Align card edge with slot, press firmly until seated
• Secure Card: Fasten mounting bracket screw
• Connect Cables: Attach 1PPS and reference input cables
• Close Case: Reassemble system
• Power On: Connect power and boot system

1.5 LED Indicators

1.6 I/O Connector Pinout (STW-PCIe Reference)

1PPS Input (J1):

1PPS Output (J2):

10MHz Reference Input (J3):

2. Linux Driver Installation

2.1 Kernel Module Overview

The BRIDZA PCIe timing card uses a kernel module (bridza_ptp) that provides:

• PTP Hardware Clock (PHC) interface
• Character device for raw register access
• Sysfs interface for configuration

2.2 Automated Installation

# Download driver package
wget https://rf.bridza.com/driver/bridza-pcie-latest.tar.gz

# Extract
tar -xzf bridza-pcie-latest.tar.gz
cd bridza-pcie-*

# Run installation script (requires root)
sudo ./install.sh

# Script will:
# 1. Check kernel version compatibility
# 2. Install kernel headers if needed
# 3. Compile kernel module
# 4. Install module to /lib/modules
# 5. Load module
# 6. Create device nodes

2.3 Manual Installation

Step 1: Install Dependencies

# Debian/Ubuntu
sudo apt-get install build-essential linux-headers-$(uname -r)

# RHEL/CentOS
sudo yum install gcc kernel-devel kernel-headers

# SUSE
sudo zypper install gcc kernel-devel

Step 2: Compile Module

cd bridza-pcie-driver
make clean
make

Step 3: Install Module

# Copy module to kernel directory
sudo cp bridza_ptp.ko /lib/modules/$(uname -r)/kernel/drivers/ptp/

# Update module dependencies
sudo depmod -a

# Load module
sudo modprobe bridza_ptp

# Verify load
lsmod | grep bridza
dmesg | tail -20

2.4 Verify Installation

# Check if PHC device is available
ls -la /dev/ptp*

# Check PHC capabilities
phc_ctl /dev/ptp0 get capabilities

# Expected output:
# capabilities:
# maximum_adjustment: 312500
# n_alarms: 5
# n_ext_timestamps: 4
# n_programmable_pins: 8
# pps_channels: 1
# n_timestamp_channels: 1
# version: 3.0

# Check current time
phc_ctl /dev/ptp0 get time

2.5 Module Parameters

# Load with custom parameters
sudo modprobe bridza_ptp debug=1

# Available parameters:
# debug=0|1 Enable debug output (default: 0)
# pps_channel=0-3 1PPS channel to use (default: 0)
# ref_freq=10000000 Reference frequency in Hz (default: 10000000)

2.6 Persistent Module Loading

Option 1: /etc/modules

echo "bridza_ptp" | sudo tee -a /etc/modules

Option 2: /etc/modprobe.d/

echo "options bridza_ptp debug=0" | sudo tee /etc/modprobe.d/bridza-ptp.conf

3. Windows Driver Installation

3.1 Driver Installation Steps

• Download Driver: Get from BRIDZA support site
• Extract Archive: Right-click → Extract All
• Open Device Manager: Press Win+X → Device Manager
• Locate Device: Look for "PCI Device" with yellow warning
• Update Driver: Right-click → Update Driver
• Browse Computer: Select "Let me pick..."
• Navigate: Browse to extracted driver folder
• Install: Click Next, wait for completion
• Verify: Device should show under "Time Frequency Instruments"

3.2 Windows Driver Signing

For Windows 10/11 (64-bit), driver must be signed.

Option 1: Automatic Installation

• Use signed driver package from BRIDZA (recommended)

Option 2: Test Mode (Development Only)

:: Enable test signing (requires admin)
bcdedit /set testsigning on

:: Reboot
shutdown /r /t 0

:: After testing, disable:
bcdedit /set testsigning off

3.3 Verify Installation

Device Manager:

• Device should appear without warning symbol
• Properties → General tab shows "This device is working properly"

Check via Command Prompt:

:: List PTP devices
wmic path win32_pnpentity get name, status | findstr /i "ptp"

:: Check device properties
pnputil /enum-devices | findstr -i "BRIDZA"

4. API Usage Examples

4.1 Linux PHC API (C)

#include 
#include 
#include 
#include 
#include 
#include 

#define PHC_DEVICE "/dev/ptp0"

int main() {
 int fd;
 struct ptp_clock_time ptc;
 struct timespec ts;
 
 // Open PHC device
 fd = open(PHC_DEVICE, O_RDONLY);
 if (fd < 0) {
 perror("open");
 return -1;
 }
 
 // Read current PHC time
 if (ioctl(fd, PTP_CLOCK_GETTIME, &ptc) < 0) {
 perror("PTP_CLOCK_GETTIME");
 close(fd);
 return -1;
 }
 
 printf("PHC Time: %ld seconds, %ld nanoseconds\n",
 (long)ptc.sec, (long)ptc.nsec);
 
 // Read system time
 clock_gettime(CLOCK_REALTIME, &ts);
 printf("System Time: %ld seconds, %ld nanoseconds\n",
 ts.tv_sec, ts.tv_nsec);
 
 close(fd);
 return 0;
}

4.2 Linux PHC API (Python)

#!/usr/bin/env python3
import os
import struct
import time
from ctypes import *

# Constants
PTP_CLOCK_GETCAPS = 0x80000d01
PTP_CLOCK_GETTIME = 0x80000d02
PTP_CLOCK_SETTIME = 0x80000d03

# Structures
class timespec(Structure):
 _fields_ = [("tv_sec", c_long), ("tv_nsec", c_long)]

class ptp_clock_time(Structure):
 _fields_ = [("sec", c_int64), ("nsec", c_uint32), ("reserved", c_uint32)]

# Load library
libc = CDLL("libc.so.6")

def ptp_gettime(fd):
 """Get PHC time"""
 ptc = ptp_clock_time()
 result = libc.ioctl(fd, PTP_CLOCK_GETTIME, byref(ptc))
 if result < 0:
 raise IOError("ioctl PTP_CLOCK_GETTIME failed")
 return (ptc.sec, ptc.nsec)

def clock_gettime(clock_id=0):
 """Get system time"""
 ts = timespec()
 libc.clock_gettime(clock_id, byref(ts))
 return (ts.tv_sec, ts.tv_nsec)

# Main
if __name__ == "__main__":
 PHC_DEVICE = "/dev/ptp0"
 
 try:
 fd = os.open(PHC_DEVICE, os.O_RDONLY)
 except OSError:
 print(f"Cannot open {PHC_DEVICE}")
 print("Ensure driver is loaded: sudo modprobe bridza_ptp")
 exit(1)
 
 print(f"Opened {PHC_DEVICE}")
 
 while True:
 phc_time = ptp_gettime(fd)
 sys_time = clock_gettime()
 
 print(f"PHC: {phc_time[0]}.{phc_time[1]:09d}")
 print(f"Sys: {sys_time[0]}.{sys_time[1]:09d}")
 
 time.sleep(1)

4.3 Reading 1PPS Interrupt Timestamp

#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 

int main() {
 int fd;
 struct ptp_extts_event event;
 struct pollfd pfd;
 
 fd = open("/dev/ptp0", O_RDONLY);
 if (fd < 0) {
 perror("open");
 return 1;
 }
 
 // Request external timestamp on channel 0
 struct ptp_extts_request req = {
 .index = 0,
 .flags = PTP_ENABLE_FEATURE
 };
 
 if (ioctl(fd, PTP_EXTTS_REQUEST, &req) < 0) {
 perror("PTP_EXTTS_REQUEST");
 return 1;
 }
 
 printf("Listening for 1PPS interrupts...\n");
 
 pfd.fd = fd;
 pfd.events = POLLIN;
 
 while (1) {
 int ret = poll(&pfd, 1, 2000); // 2 second timeout
 
 if (ret > 0) {
 read(fd, &event, sizeof(event));
 
 printf("1PPS timestamp: %llu seconds, %u nanoseconds\n",
 (unsigned long long)event.tsec,
 (unsigned int)event.tv_nsec);
 } else if (ret == 0) {
 printf("Timeout - no 1PPS signal detected\n");
 }
 }
 
 close(fd);
 return 0;
}

4.4 Cross-Timestamping (PHC to System)

#!/usr/bin/env python3
"""
Cross-timestamp to correlate PHC with system time.
Critical for accurate time distribution.
"""
import os
import time
import ctypes

class timespec64(ctypes.Structure):
 _fields_ = [("tv_sec", ctypes.c_longlong), ("tv_nsec", ctypes.c_long)]

# Open PHC
phc_fd = os.open("/dev/ptp0", os.O_RDONLY)

# ioctl numbers
PTP_SYS_OFFSET = 0x80000d3f # Get cross-timestamp

class ptp_sys_offset(ctypes.Structure):
 _fields_ = [
 ("n_samples", ctypes.c_uint32),
 ("rsvd", ctypes.c_uint32),
 ("ts", (ctypes.c_int64 * 5)), # 5 pairs of timestamps
 ]

def get_cross_timestamp():
 """Get PHC and system time simultaneously"""
 pso = ptp_sys_offset()
 pso.n_samples = 1 # Number of measurement pairs
 
 # Perform cross-timestamp
 result = ctypes.c_int32(0)
 # Note: This requires kernel 5.0+ or specific driver support
 # See kernel documentation for implementation details
 
 return pso.ts[0], pso.ts[1] # phc_ts, system_ts

print("Cross-timestamp capability check...")
print("For production use, consider using phc2sys from linuxptp package")

os.close(phc_fd)

5. PTP Configuration (linuxptp)

5.1 Install linuxptp

# Debian/Ubuntu
sudo apt-get install linuxptp

# RHEL/CentOS
sudo yum install linuxptp

# Verify installation
ptp4l -h
phc2sys -h

5.2 ptp4l Configuration

Basic /etc/linuxptp/ptp4l.conf:

[global]
# PTP device
interface		eth0

# Clock settings
twoStepFlag		1
slaveOnly		0

# Timing parameters
priority1		128
priority2		128
domainNumber		0

# Profile-specific settings
# For Default Profile:
# domainNumber should be 0

# Logging
verbose			1
use_syslog		1

Telecom Profile (/etc/linuxptp/ptp4l-telecom.conf):

[global]
interface		eth0
twoStepFlag		1
slaveOnly		0

# Telecom profile settings
priority1		136
priority2		128
domainNumber		0

# Telecom timing
sync_intv		-4		# 1/16 second
announce_intv		0		# 1 second
delay_intv		-4		# 1/16 second

# Transport
transportSpecific	0x1
ptp_profile_std		1

verbose			1

5.3 Run ptp4l

# Run as master clock
sudo ptp4l -i eth0 -m -f /etc/linuxptp/ptp4l.conf

# Run as slave clock
sudo ptp4l -i eth0 -m -s -f /etc/linuxptp/ptp4l.conf

# Run with hardware timestamping
sudo ptp4l -i eth0 -m -H -f /etc/linuxptp/ptp4l.conf

# Background service
sudo systemctl enable ptp4l
sudo systemctl start ptp4l

5.4 phc2sys Configuration

phc2sys synchronizes the system clock to the PHC.

Start phc2sys:

# Sync system clock to PHC
sudo phc2sys -c /dev/ptp0 -s eth0 -O 0 -m

# Parameters:
# -c: PHC device
# -s: System clock source (eth0 uses NIC hardware clock)
# -O: Offset between clocks (0 = sync)
# -m: Log to stdout

phc2sys as Service:

# Create systemd service /etc/systemd/system/phc2sys.service
[Unit]
Description=PHC to System Clock Synchronization
After=network.target ptp4l.service

[Service]
Type=simple
ExecStart=/usr/sbin/phc2sys -c /dev/ptp0 -s eth0 -O 0 -m
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable phc2sys
sudo systemctl start phc2sys

5.5 Verify PTP Operation

# Check ptp4l status
pmc -u 127.0.0.1 get CURRENT_DATA_SET

# Expected output:
# CURRENT_DATA_SET
# Port 1:
# meanPathDelay.............. 0.000 nsec
# portState.................. SLAVE
# frmSeqId................... 32676
# masterPortIdentity......... 000800.fffe.000001-1
# stepsRemoved............... 1
# offsetFromMaster........... -42.000 nsec
# meanPathDelay.............. 0.000 nsec

# Check phc2sys status
cat /var/log/syslog | grep phc2sys

# Monitor real-time performance
watch -n 1 "pmc -u 127.0.0.1 get CURRENT_DATA_SET"

6. Troubleshooting

6.1 PHC Not Detected

Diagnostic Commands:

# Check kernel messages
dmesg | grep -i bridza
dmesg | grep -i ptp

# Check PCI enumeration
lspci | grep -i time
lspci -v | grep -A5 -i ptp

# Check device node
ls -la /dev/ptp*

6.2 Time Offset Issues

Diagnostic:

# Measure offset between PHC and system
phc2sys -c /dev/ptp0 -s CLOCK_REALTIME -w

# Check ptp4l sync quality
pmc -u 127.0.0.1 get CURRENT_DATA_SET

# Monitor with timestat
tail -f /var/log/phc2sys.log

6.3 1PPS Signal Issues

Test 1PPS:

# Use ptp4l to enable 1PPS output
sudo ptp4l -i eth0 -P -A -H -m

# Or use external timestamp test
gcc -o extts_test extts_test.c
sudo ./extts_test

6.4 PTP Not Synchronizing

Debug:

# Run ptp4l with debug output
sudo ptp4l -i eth0 -l 6 -m

# Check if packets are received
tcpdump -i eth0 port 319 or port 320

# Verify master announcements
pmc -u 127.0.0.1 get PARENT_DATA_SET

Technical Support

For additional assistance:

• Email: [email protected]
• Documentation: https://rf.bridza.com/downloads
• Knowledge Base: https://rf.bridza.com/support

Document Version: 1.0 | Last Updated: 2025