The Linux PTP Project

1 Introduction

This software is an implementation of the Precision Time Protocol (PTP) according to IEEE standard 1588 for Linux. The dual design goals are to provide a robust implementation of the standard and to use the most relevant and modern Application Programming Interfaces (API) offered by the Linux kernel. Supporting legacy APIs and other platforms is not a goal.

2 License

The software is copyrighted by the authors and is licensed under the GNU General Public License. See the file, COPYING, for details of the license terms.

3 Features

  • Supports hardware and software time stamping via the Linux SO_TIMESTAMPING socket option.
  • Supports the Linux PTP Hardware Clock (PHC) subsystem by using the clock_gettime family of calls, including the new clock_adjtimex system call.
  • Implements Boundary Clock (BC) and Ordinary Clock (OC).
  • Transport over UDP/IPv4, UDP/IPv6, and raw Ethernet (Layer 2).
  • Supports IEEE 802.1AS-2011 in the role of end station.
  • Modular design allowing painless addition of new transports and clock servos.

4 Getting the Code

You can download the latest released version at Source Forge.

http://sourceforge.net/projects/linuxptp/files/latest/download

The source code is managed using the git version control system. To get your own copy of the project sources, use the following command.

git clone git://git.code.sf.net/p/linuxptp/code linuxptp

If the git protocol is blocked by your local area network, then you can use the alternative HTTP protocol instead.

git clone http://git.code.sf.net/p/linuxptp/code linuxptp

5 System Requirements

In order to run this software, you need Linux kernel version 3.0 or newer, and the kernel header files must available at compile time.

In addition, you will also need to have either:

  1. A supported Ethernet MAC device.
  2. A supported PHY device paired with a MAC that allows time stamping in the PHY (indicated by PHY=Y in the table below).

5.1 Linux Kernel Support

In order to support PTP, the operating system needs to provide two services: network packet time stamping and clock control. In 2009, Patrick Ohly added a new socket option called SO_TIMESTAMPING for packet time stamping, especially for PTP. This work appeared in Linux version 2.6.30.

In July of 2011, the PTP Hardware Clock (PHC) subsystem was merged into Linux version 3.0. The PHC code provides a driver framework and the user space API for clock control.

5.2 Ethtool Support

Starting with version 3.5 of the Linux kernel, you can query the time stamping capabilities of a network interface using the ETHTOOL_GET_TS_INFO ioctl. Using ethtool version 3.4 or later, you can check your system's time stamping support as shown in the following example.

ethtool -T eth0

If the ethtool ioctl is available, then the ptp4l program will use it in order to discover the proper PHC device.

5.3 Driver Support Matrix

The following two tables list the drivers that support the PHC subsystem and the Linux kernel version when they first appeared. These drivers will create a PHC device for controlling the hardware clock.

5.3.1 Hardware Timestamping - PHY

DriverHardwareVersion
dp83640National Semiconductor PHYTER3.0

5.3.2 Hardware Timestamping - MAC

DriverHardwareVersion
bfin_macAnalog Blackfin3.8
cptsTexas Instruments am335x3.8
e1000eIntel 82574, 825833.9
fecFreescale i.mx63.8
gianfarFreescale eTSEC PowerPC3.0
igbIntel 82576, 825803.5
ixgbeIntel 825993.5
ptp_ixp46xIntel IXP4653.0
ptp_phcLapis EG20T PCH3.5
sfcSolarflare SFC90003.7

5.3.3 Software Timestamping

The table below shows the Linux drivers that support software time stamping. In addition, the 'PHY' column indicates whether the Ethernet MAC driver can support a PTP Hardware Clock in an external PHY. The letter 'Y' in this column means that if you design a mother board that combines such a MAC with a PTP capable PHY, then it will work with the Linux PHC subsystem.

DriverHardwareVersionPHY
bnaBrocade 1010/1020 10Gb3.14N
bnx2xBroadcom Everest3.5N
davinci_emacTI DaVinci, Sitara3.1Y
dnetDave Ethernet MAC3.1Y
e100Intel PRO/1003.5N
e1000Intel PRO/1000 PCI/PCI-X3.5N
e1000eIntel PRO/1000 PCIe3.5N
emacliteXilinx Ethernet Lite3.1Y
ethocOpenCores 10/100 MAC3.1Y
fecFreescale Coldfire3.1Y
fec_mpc52xxFreescale MPC52003.1Y
forcedethNVIDIA nForce3.5N
fs_enetFreescale MPC512x3.1Y
ixp4xx_ethIntel IXP4xx3.0Y
lib8390Asix AX887963.1Y
lib8390Various 8390 based HW3.1N
ll_temacXilinx LL TEMAC3.1Y
macbAtmel AT32, AT913.1Y
mv643xx_ethMarvell Discovery, Orion3.1Y
pxa168_ethMarvell pxa1683.1Y
r6040RDC Ethernet MAC3.1Y
r8169Realtek 8169/8168/81013.4N
smsc911xSMSC LAN911x, LAN921x3.1Y
smsc9420SMSC LAN9420 PCI3.1Y
stmmacSTM Synopsys IP Core3.1Y
tg3Broadcom Tigon3 PCI3.1Y
ucc_gethFreescale QE Gigabit3.1Y
usbnetUSB network devices3.2Y/N

6 Installation

6.1 Linux kernel

There are many ways of getting a precompiled Linux kernel or compiling your own, so this section is only meant as an example. It is important to have the kernel headers available when compiling the Linux PTP stack.

export ARCH=x86
export CROSS_COMPILE=
export KBUILD_OUTPUT=/home/richard/kernel/ptp_debian
mkdir -p $KBUILD_OUTPUT
cp /boot/config-2.6.38-bpo.2-686 $KBUILD_OUTPUT/.config
make oldnoconfig
make menuconfig
time make -j4
make headers_install

Here is a table of kernel configuration options needed for PTP support. In addtion to these, you should enable the specific Ethernet MAC and PHY drivers for your hardware.

OptionDescription
CONFIG_PPSRequired
CONFIG_NETWORK_PHY_TIMESTAMPINGTimestamping in PHY devices
PTP_1588_CLOCKPTP clock support

6.2 PTP stack

  1. Just type 'make'
  2. If you compiled your own kernel (and the headers are not installed into the system path), then you should set the KBUILD_OUTPUT environment variable as in the example, above.
  3. In order to install the programs and man pages into /usr/local, run the 'make install' target. You can change the installation directories by setttings the variables prefix, sbindir, mandir, and man8dir on the make command line.

7 Getting Involved

The software development is hosted at Source Forge.

https://sourceforge.net/projects/linuxptp/

7.1 Reporting Bugs

Please report any bugs or other issues with the software to the linuxptp-users mailing list.

https://lists.sourceforge.net/lists/listinfo/linuxptp-users

7.2 Development

If you would like to get involved in improving the software, please join the linuxptp-devel mailing list.

https://lists.sourceforge.net/lists/listinfo/linuxptp-devel

8 Thanks

Thanks to AudioScience Inc for sponsoring the 8021.AS support.

Thanks to Intel Corporation for donating four NICs, the 82574, 82580, 82599, and the i210.

For testing I use an OTMC 100 grandmaster clock donated by OMICRON Lab.

HTML generated by org-mode 6.33x in emacs 23