Go to file
Wolfgang Wallner 6eec5a0d48 Fix typo in manpage of ptp4l
There is one parenthesis too many in the manpage of ptp4l.
2015-11-01 19:46:19 +01:00
.gitignore trivial: update gitignore with the timemaster build product. 2014-11-07 19:47:37 +01:00
CODING_STYLE.org Add a coding style document. 2013-02-06 14:42:12 +01:00
COPYING Add the license, a readme, and some header files. 2011-11-01 17:39:14 +01:00
README.org Explain how to contribute patches 2015-06-08 14:45:09 +02:00
address.h Use the standardized low level socket address format. 2015-08-29 11:32:41 +02:00
bmc.c Become the grand master when all alone. 2013-07-14 21:48:23 +02:00
bmc.h Add the best master clock algorithm. 2011-11-04 19:20:23 +01:00
clock.c uds: restore delay mechanism to zero value. 2015-09-05 21:27:04 +02:00
clock.h config: convert 'clock_servo' to the new scheme. 2015-08-23 21:09:46 +02:00
clockadj.c Set TAI offset of system clock. 2014-06-22 09:23:55 +02:00
clockadj.h Set TAI offset of system clock. 2014-06-22 09:23:55 +02:00
clockcheck.c Add clock sanity check. 2013-10-27 08:24:01 +01:00
clockcheck.h Add clock sanity check. 2013-10-27 08:24:01 +01:00
config.c Support hybrid E2E using unicast delay requests and responses. 2015-08-29 11:33:34 +02:00
config.h config: introduce a proper creation method. 2015-08-23 21:48:09 +02:00
contain.h Fix a trivial spelling mistake in a comment. 2014-06-02 18:00:21 +02:00
ddt.h adds CLOCK_DESCRIPTION struct 2013-02-25 18:11:03 +01:00
default.cfg Merge the hybrid E2E work. 2015-09-05 21:40:48 +02:00
dm.h Expose the peer delay flavors in their own header file. 2012-04-05 17:48:59 +02:00
ds.h Update UTC offset 2015-09-17 13:12:28 +02:00
ether.h config: convert 'p2p_dst_mac', letting it be a per-port option. 2015-08-23 21:09:46 +02:00
fault.c port: allow running a boundary clock with multiple clock devices. 2014-12-18 11:38:00 +01:00
fault.h port: allow running a boundary clock with multiple clock devices. 2014-12-18 11:38:00 +01:00
fd.h Add a timer implementing the sync receive timeout. 2013-08-26 18:30:54 +02:00
filter.c Add median filter. 2013-10-30 21:54:07 +01:00
filter.h Add median filter. 2013-10-30 21:54:07 +01:00
filter_private.h Add modular filter interface. 2013-10-30 21:43:37 +01:00
foreign.h Implement the PTP clock. 2011-11-12 18:59:13 +01:00
fsm.c Fix the port finite state machine. 2012-01-07 08:07:56 +01:00
fsm.h Hide the grandmaster port state. 2013-02-06 13:34:49 +01:00
gPTP.cfg Support hybrid E2E using unicast delay requests and responses. 2015-08-29 11:33:34 +02:00
hash.c Introduce a simple hash table implementation. 2015-08-16 11:20:23 +02:00
hash.h Introduce a simple hash table implementation. 2015-08-16 11:20:23 +02:00
hwstamp_ctl.8 Bump the date on the hwstamp_ctl man page. 2014-06-04 15:17:22 +02:00
hwstamp_ctl.c Fix copying of device name to ifreq. 2014-09-21 13:10:27 +02:00
incdefs.sh Add timemaster. 2014-10-03 14:25:19 +02:00
linreg.c linreg: use sample weight. 2015-03-27 10:58:04 +01:00
linreg.h Add an adaptive servo based on linear regression. 2014-03-14 09:52:40 +01:00
makefile config: introduce a new API for reading configuration settings. 2015-08-23 21:09:19 +02:00
mave.c Add modular filter interface. 2013-10-30 21:43:37 +01:00
mave.h Add modular filter interface. 2013-10-30 21:43:37 +01:00
missing.h Use SO_SELECT_ERR_QUEUE when available. 2014-11-07 19:47:36 +01:00
mmedian.c Add median filter. 2013-10-30 21:54:07 +01:00
mmedian.h Add median filter. 2013-10-30 21:54:07 +01:00
msg.c Introduce a helper function to identify valid (non-zero) time stamps. 2014-12-12 21:44:56 +01:00
msg.h Introduce a helper function to identify valid (non-zero) time stamps. 2014-12-12 21:44:56 +01:00
notification.h Event notification: port state 2014-05-06 20:08:59 +02:00
ntpshm.c config: convert 'ntpshm_segment' to the new scheme. 2015-08-23 21:09:45 +02:00
ntpshm.h config: convert 'ntpshm_segment' to the new scheme. 2015-08-23 21:09:45 +02:00
nullf.c Add a servo that inhibits all frequency adjustment 2015-07-24 22:17:09 +02:00
nullf.h Add a servo that inhibits all frequency adjustment 2015-07-24 22:17:09 +02:00
pdt.h Add the license, a readme, and some header files. 2011-11-01 17:39:14 +01:00
phc.c Don't return bogus clock id 2013-06-06 17:00:25 +02:00
phc.h phc2sys: enable PPS output from PHC 2013-04-19 17:52:25 +02:00
phc2sys.8 Add option to set NTP SHM segment number. 2014-09-21 12:43:09 +02:00
phc2sys.c config: introduce a proper creation method. 2015-08-23 21:48:09 +02:00
phc_ctl.8 linuxptp: add phc_ctl program to help debug PHC devices 2014-07-19 07:15:24 +02:00
phc_ctl.c Don't include config.h in util.h 2014-10-03 14:25:19 +02:00
pi.c config: convert 'pi_integral_norm_max' to the new scheme. 2015-08-23 21:09:45 +02:00
pi.h config: convert 'pi_integral_norm_max' to the new scheme. 2015-08-23 21:09:45 +02:00
pmc.8 Append PID to client UDS paths. 2014-09-21 12:34:05 +02:00
pmc.c config: introduce a proper creation method. 2015-08-23 21:48:09 +02:00
pmc_common.c transport: store the configuration in the transport data structure. 2015-08-16 11:20:23 +02:00
pmc_common.h pmc: require a configuration for creating a PMC instance. 2015-08-16 11:20:23 +02:00
port.c port: print bogus delay request message as rate limited info. 2015-09-11 21:24:34 +02:00
port.h Dynamic port allocation 2014-09-21 13:15:59 +02:00
print.c Print messages with level below LOG_NOTICE to stderr. 2013-02-06 19:30:01 +01:00
print.h print: add rate limited versions of pr_* macros. 2015-09-11 21:24:34 +02:00
ptp4l.8 Fix typo in manpage of ptp4l 2015-11-01 19:46:19 +01:00
ptp4l.c config: introduce a proper creation method. 2015-08-23 21:48:09 +02:00
raw.c Use the standardized low level socket address format. 2015-08-29 11:32:41 +02:00
raw.h config: convert 'p2p_dst_mac', letting it be a per-port option. 2015-08-23 21:09:46 +02:00
servo.c config: convert 'ntpshm_segment' to the new scheme. 2015-08-23 21:09:45 +02:00
servo.h config: convert the 'max_frequency' option to the new scheme. 2015-08-23 21:09:45 +02:00
servo_private.h servo: add support for weighted samples. 2015-03-27 10:58:04 +01:00
sk.c Use the standardized low level socket address format. 2015-08-29 11:32:41 +02:00
sk.h Common type holding an address 2014-04-25 14:28:14 +02:00
stats.c Add summary statistics. 2013-02-09 10:09:25 +01:00
stats.h Add summary statistics. 2013-02-09 10:09:25 +01:00
sysoff.c phc2sys: Print clock reading delay. 2013-02-08 18:41:34 +01:00
sysoff.h phc2sys: Print clock reading delay. 2013-02-08 18:41:34 +01:00
timemaster.8 fixed hyphen/minus signs in groff 2015-06-08 14:46:37 +02:00
timemaster.c timemaster: use wrapped memory allocation functions. 2015-08-29 10:33:35 +02:00
tlv.c Prefix TLV IDs. 2014-07-09 06:31:25 +02:00
tlv.h Prefix TLV IDs. 2014-07-09 06:31:25 +02:00
tmv.h port: adjust peer delay calculation using neighborRateRatio 2014-02-25 14:13:05 +01:00
transport.c transport: store the configuration in the transport data structure. 2015-08-16 11:20:23 +02:00
transport.h transport: store the configuration in the transport data structure. 2015-08-16 11:20:23 +02:00
transport_private.h transport: store the configuration in the transport data structure. 2015-08-16 11:20:23 +02:00
tsproc.c tsproc: add raw and weighting modes. 2015-03-27 10:58:04 +01:00
tsproc.h tsproc: add raw and weighting modes. 2015-03-27 10:58:04 +01:00
udp.c Use the standardized low level socket address format. 2015-08-29 11:32:41 +02:00
udp.h Add missing release method to the UDPv4 transport. 2012-03-17 17:30:21 +01:00
udp6.c Merge the hybrid E2E work. 2015-09-05 21:40:48 +02:00
udp6.h config: convert 'udp6_scope' to the new scheme. 2015-08-23 21:09:45 +02:00
uds.c config: convert 'uds_address' to the new scheme. 2015-08-23 21:09:46 +02:00
uds.h config: convert 'uds_address' to the new scheme. 2015-08-23 21:09:46 +02:00
util.c util: add function for simple rate limiting. 2015-09-11 21:24:34 +02:00
util.h util: add function for simple rate limiting. 2015-09-11 21:24:34 +02:00
version.c Add utility functions to get the software version string. 2012-12-10 15:11:51 +01:00
version.h Add utility functions to get the software version string. 2012-12-10 15:11:51 +01:00
version.sh Version 1.6 2015-09-19 16:25:11 +02:00

README.org

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.

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.

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.

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

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).

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.

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.

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.

Hardware Timestamping - PHY

Driver Hardware Version
dp83640 National Semiconductor PHYTER 3.0

Hardware Timestamping - MAC

Driver Hardware Version
amd-xgbe AMD 10GbE Ethernet Soc 3.17
bfin_mac Analog Blackfin 3.8
bnx2x Broadcom NetXtremeII 10G 3.18
cpts Texas Instruments am335x 3.8
e1000e Intel 82574, 82583 3.9
fm10k Intel FM10000 3.18
fec Freescale i.mx6 3.8
gianfar Freescale eTSEC PowerPC 3.0
i40e Intel XL710 Family 3.14
igb Intel 82576, 82580 3.5
ixgbe Intel 82599 3.5
mlx4 Mellanox 40G PCI 3.14
ptp_ixp46x Intel IXP465 3.0
ptp_phc Lapis EG20T PCH 3.5
sfc Solarflare SFC9000 3.7
stmmac STM Synopsys IP Core 3.10
tg3 Broadcom Tigon3 PCI 3.8
tilegx Tilera GBE/XGBE 3.12

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.

Driver Hardware Version PHY
3c59x 3Com EtherLink PCI 3.14 N
altera_tse Altera Triple-Speed MAC 3.15 Y
bna Brocade 1010/1020 10Gb 3.14 N
bnx2x Broadcom Everest 3.5 N
davinci_emac TI DaVinci, Sitara 3.1 Y
dnet Dave Ethernet MAC 3.1 Y
e100 Intel PRO/100 3.5 N
e1000 Intel PRO/1000 PCI/PCI-X 3.5 N
e1000e Intel PRO/1000 PCIe 3.5 N
emaclite Xilinx Ethernet Lite 3.1 Y
ethoc OpenCores 10/100 MAC 3.1 Y
fec Freescale Coldfire 3.1 Y
fec_mpc52xx Freescale MPC5200 3.1 Y
forcedeth NVIDIA nForce 3.5 N
fs_enet Freescale MPC512x 3.1 Y
genet Broadcom GENET 3.15 Y
ixp4xx_eth Intel IXP4xx 3.0 Y
lib8390 Asix AX88796 3.1 Y
lib8390 Various 8390 based HW 3.1 N
ll_temac Xilinx LL TEMAC 3.1 Y
macb Atmel AT32, AT91 3.1 Y
mv643xx_eth Marvell Discovery, Orion 3.1 Y
pxa168_eth Marvell pxa168 3.1 Y
r6040 RDC Ethernet MAC 3.1 Y
r8169 Realtek 8169/8168/8101 3.4 N
samsun-sxgbe Samsung SXGBE 10G 3.15 Y
smsc911x SMSC LAN911x, LAN921x 3.1 Y
smsc9420 SMSC LAN9420 PCI 3.1 Y
stmmac STM Synopsys IP Core 3.1 Y
tg3 Broadcom Tigon3 PCI 3.1 Y
ucc_geth Freescale QE Gigabit 3.1 Y
usbnet USB network devices 3.2 Y/N
xgene-enet APM X-Gene SoC 3.17 Y

Installation

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.

Option Description
CONFIG_PPS Required
CONFIG_NETWORK_PHY_TIMESTAMPING Timestamping in PHY devices
PTP_1588_CLOCK PTP clock support

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.

Getting Involved

The software development is hosted at Source Forge.

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

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

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

Submitting Patches

  1. Before submitting patches, please make sure that you are starting your work on the current HEAD of the git repository.
  2. Please checkout the CODING_STYLE.org file for guidelines on how to properly format your code.
  3. Describe your changes. Each patch will be reviewed, and the reviewers need to understand why you did what you did.
  4. Sign-Off each commit, so the changes can be properly attributed to you and you explicitely give your agreement for distribution under linuxptp's license. Signing-off is as simple as:

    git commit -s
    

    or by adding the following line (replace your real name and email) to your patch:

    Signed-off-by: Random J Developer <random@developer.example.org>
    
  5. Finally, send your patches via email to the linuxptp-devel mailing list, where they will be reviewed, and eventually be included in the official code base.

    git send-email --to linuxptp-devel@lists.sourceforge.net origin/master
    

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.