251 lines
9.7 KiB
Org Mode
251 lines
9.7 KiB
Org Mode
|
|
* 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.
|
|
|
|
#+BEGIN_EXAMPLE
|
|
git clone git://git.code.sf.net/p/linuxptp/code linuxptp
|
|
#+END_EXAMPLE
|
|
|
|
If the git protocol is blocked by your local area network, then you
|
|
can use the alternative HTTP protocol instead.
|
|
|
|
#+BEGIN_EXAMPLE
|
|
git clone http://git.code.sf.net/p/linuxptp/code linuxptp
|
|
#+END_EXAMPLE
|
|
|
|
* 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.
|
|
|
|
#+BEGIN_EXAMPLE
|
|
ethtool -T eth0
|
|
#+END_EXAMPLE
|
|
|
|
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 table below shows the Linux drivers that support the new
|
|
API. The meaning of the column abbreviations is as follows.
|
|
|
|
- SOTS: SO_TIMESTAMPING support. This comes in three flavors.
|
|
|
|
1. RAW: Supports time stamping using the PHC time values.
|
|
2. SW: Supports software time stamping using the system time.
|
|
3. SYS: Supports time stamping using PHC time values scaled to
|
|
the system time. This is a legacy mode and its use in new
|
|
drivers is discouraged.
|
|
|
|
- PHC: PTP Hardware Clock support. These drivers will offer a
|
|
character device that allows direct control of the hardware
|
|
clock.
|
|
|
|
- PHY: Supports time stamping in the PHY. This indicates an
|
|
Ethernet MAC driver supporting SO_TIMESTAMPING and PHC in the
|
|
PHY. If you have or build a computer that combines this MAC with
|
|
a PTP capable PHY, then it will work with the Linux PHC
|
|
subsystem.
|
|
|
|
- VER: Linux kernel version when the PTP API support was added.
|
|
|
|
*** Hardware Timestamping
|
|
|
|
|------------+-------------------------+------+-----+-----+-----|
|
|
| Driver | Hardware | SOTS | PHC | PHY | VER |
|
|
|------------+-------------------------+------+-----+-----+-----|
|
|
| bfin_mac | Analog Blackfin | RAW | Y | NA | 3.8 |
|
|
| e1000e | Intel 82574, 82583 | RAW | Y | NA | 3.9 |
|
|
| igb | Intel 82576, 82580 | RAW | Y | NA | 3.5 |
|
|
| ixgbe | Intel 82599 | RAW | Y | NA | 3.5 |
|
|
| dp83640 | Nat Semi PHYTER | RAW | Y | NA | 3.0 |
|
|
| gianfar | Freescale eTSEC PowerPC | RAW | Y | NA | 3.0 |
|
|
| ptp_ixp46x | Intel IXP465 | RAW | Y | NA | 3.0 |
|
|
| ptp_phc | Lapis EG20T PCH | RAW | Y | NA | 3.5 |
|
|
| sfc | Solarflare SFC9000 | RAW | Y | NA | 3.7 |
|
|
|------------+-------------------------+------+-----+-----+-----|
|
|
|
|
*** Software Timestamping
|
|
|
|
|--------------+--------------------------+------+-----+-----+-----|
|
|
| Driver | Hardware | SOTS | PHC | PHY | VER |
|
|
|--------------+--------------------------+------+-----+-----+-----|
|
|
| bnx2x | Broadcom Everest | SW | N | N | 3.5 |
|
|
| davinci_emac | TI DaVinci, Sitara | SW | N | Y | 3.1 |
|
|
| dnet | Dave Ethernet MAC | SW | N | Y | 3.1 |
|
|
| e100 | Intel PRO/100 | SW | N | N | 3.5 |
|
|
| e1000 | Intel PRO/1000 PCI/PCI-X | SW | N | N | 3.5 |
|
|
| e1000e | Intel PRO/1000 PCIe | SW | N | N | 3.5 |
|
|
| emaclite | Xilinx Ethernet Lite | SW | N | Y | 3.1 |
|
|
| ethoc | OpenCores 10/100 MAC | SW | N | Y | 3.1 |
|
|
| fec | Freescale Coldfire | SW | N | Y | 3.1 |
|
|
| fec_mpc52xx | Freescale MPC5200 | SW | N | Y | 3.1 |
|
|
| forcedeth | NVIDIA nForce | SW | N | N | 3.5 |
|
|
| fs_enet | Freescale MPC512x | SW | N | Y | 3.1 |
|
|
| ixp4xx_eth | Intel IXP4xx | SW | N | Y | 3.0 |
|
|
| lib8390 | Asix AX88796 | SW | N | Y | 3.1 |
|
|
| lib8390 | Various 8390 based HW | SW | N | N | 3.1 |
|
|
| ll_temac | Xilinx LL TEMAC | SW | N | Y | 3.1 |
|
|
| macb | Atmel AT32, AT91 | SW | N | Y | 3.1 |
|
|
| mv643xx_eth | Marvell Discovery, Orion | SW | N | Y | 3.1 |
|
|
| pxa168_eth | Marvell pxa168 | SW | N | Y | 3.1 |
|
|
| r6040 | RDC Ethernet MAC | SW | N | Y | 3.1 |
|
|
| r8169 | Realtek 8169/8168/8101 | SW | N | N | 3.4 |
|
|
| smsc911x | SMSC LAN911x, LAN921x | SW | N | Y | 3.1 |
|
|
| smsc9420 | SMSC LAN9420 PCI | SW | N | Y | 3.1 |
|
|
| stmmac | STM Synopsys IP Core | SW | N | Y | 3.1 |
|
|
| tg3 | Broadcom Tigon3 PCI | SW | N | Y | 3.1 |
|
|
| ucc_geth | Freescale QE Gigabit | SW | N | Y | 3.1 |
|
|
| usbnet | USB network devices | SW | N | Y/N | 3.2 |
|
|
|--------------+--------------------------+------+-----+-----+-----|
|
|
|
|
* 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.
|
|
|
|
#+BEGIN_EXAMPLE
|
|
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
|
|
#+END_EXAMPLE
|
|
|
|
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
|
|
|
|
* Thanks
|
|
|
|
Thanks to AudioScience Inc for sponsoring the 8021.AS support.
|
|
|
|
- http://www.audioscience.com
|
|
|
|
Thanks to Intel Corporation for donating four NICs, the 82574,
|
|
82580, 82599, and the i210.
|
|
|
|
- http://www.intel.com
|
|
- http://e1000.sourceforge.net
|
|
|
|
For testing I use an OTMC 100 grandmaster clock donated by OMICRON Lab.
|
|
|
|
- http://www.omicron-lab.com/ptp
|