README.org - pub/scm/linux/kernel/git/bigeasy/linuxptp-hsr - Git at Google


 * 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 clock_adjtimex system
     call.

   - Implements Boundary Clock (BC), Ordinary Clock (OC) and
     Transparent Clock (TC).

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

   - Implements unicast operation.

   - Supports a number of profiles, including:

     - The automotive profile

     - The default 1588 profile.

     - The enterprise profile.

     - The telecom profiles G.8265.1, G.8275.1, and G.8275.2.

   - Supports the NetSync Monitor protocol.

   - Implements Peer to peer one-step.

   - Supports bonded, IPoIB, and vlan interfaces.

   - Supports Authentication TLV using Nettle, GnuTLS, or OpenSSL

     - NOTE: OpenSSLv3+ is distributed under Apache 2 license. When
             compiled with this library, LinuxPTP is distributed
             under GPL3. An additional flag is required for linking:
             ~make EXTRA_CFLAGS=-DUSE_OPENSSL~

 * 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.  Check whether your network interface supports PTP with the
   following command.

 #+BEGIN_EXAMPLE
   ethtool -T eth0
 #+END_EXAMPLE

   This command shows whether a MAC supports hardware or software time
   stamping.  The following example output indicates support for
   hardware time stamping.

 #+BEGIN_EXAMPLE
 Time stamping parameters for eth6:
 Capabilities:
         hardware-transmit     (SOF_TIMESTAMPING_TX_HARDWARE)
         software-transmit     (SOF_TIMESTAMPING_TX_SOFTWARE)
         hardware-receive      (SOF_TIMESTAMPING_RX_HARDWARE)
         software-receive      (SOF_TIMESTAMPING_RX_SOFTWARE)
         software-system-clock (SOF_TIMESTAMPING_SOFTWARE)
         hardware-raw-clock    (SOF_TIMESTAMPING_RAW_HARDWARE)
 PTP Hardware Clock: 1
 Hardware Transmit Timestamp Modes:
         off                   (HWTSTAMP_TX_OFF)
         on                    (HWTSTAMP_TX_ON)
 Hardware Receive Filter Modes:
         none                  (HWTSTAMP_FILTER_NONE)
         all                   (HWTSTAMP_FILTER_ALL)
 #+END_EXAMPLE

   The next example shows the case where the MAC only supports software
   time stamping.  The ~ptp4l~ program requires either the ~-S~ command
   line argument or the ~time_stamping software~ configuration option
   when using such interfaces.

 #+BEGIN_EXAMPLE
 Time stamping parameters for enp6s0:
 Capabilities:
         software-transmit     (SOF_TIMESTAMPING_TX_SOFTWARE)
         software-receive      (SOF_TIMESTAMPING_RX_SOFTWARE)
         software-system-clock (SOF_TIMESTAMPING_SOFTWARE)
 PTP Hardware Clock: none
 Hardware Transmit Timestamp Modes: none
 Hardware Receive Filter Modes: none
 #+END_EXAMPLE

   Note the ~software-transmit (SOF_TIMESTAMPING_TX_SOFTWARE)~
   capability.  If this is lacking, then the MAC cannot be used at
   all.  However, adding this capability entails adding a single line
   of code to the device driver.

 * Installation

    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.nwtime.org/sympa/info/linuxptp-users

 ** Development

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

    https://lists.nwtime.org/sympa/info/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:

       #+BEGIN_EXAMPLE
       git commit -s
       #+END_EXAMPLE

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

       #+BEGIN_EXAMPLE
       Signed-off-by: Random J Developer <random@developer.example.org>
       #+END_EXAMPLE

    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.

       #+BEGIN_EXAMPLE
       git send-email --to linuxptp-devel@lists.nwtime.org origin/master
       #+END_EXAMPLE

 * Thanks

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

   - http://www.audioscience.com

   Thanks to Exablaze for donating an ExaNIC X10

   - http://exablaze.com/exanic-x10

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

   - http://www.intel.com
   - http://e1000.sourceforge.net

   Thanks to Meinberg Funkuhren for donating a LANTIME M1000.

   - https://www.meinbergglobal.com

   Thanks to Moser Baer for sponsoring the Telecom Profiles and unicast
   support.

   - http://www.mobatime.com

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

   - http://www.omicron-lab.com/ptp

	* 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 clock_adjtimex system
	call.

	- Implements Boundary Clock (BC), Ordinary Clock (OC) and
	Transparent Clock (TC).

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

	- Implements unicast operation.

	- Supports a number of profiles, including:

	- The automotive profile

	- The default 1588 profile.

	- The enterprise profile.

	- The telecom profiles G.8265.1, G.8275.1, and G.8275.2.

	- Supports the NetSync Monitor protocol.

	- Implements Peer to peer one-step.

	- Supports bonded, IPoIB, and vlan interfaces.

	- Supports Authentication TLV using Nettle, GnuTLS, or OpenSSL

	- NOTE: OpenSSLv3+ is distributed under Apache 2 license. When
	compiled with this library, LinuxPTP is distributed
	under GPL3. An additional flag is required for linking:
	~make EXTRA_CFLAGS=-DUSE_OPENSSL~

	* 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. Check whether your network interface supports PTP with the
	following command.

	#+BEGIN_EXAMPLE
	ethtool -T eth0
	#+END_EXAMPLE

	This command shows whether a MAC supports hardware or software time
	stamping. The following example output indicates support for
	hardware time stamping.

	#+BEGIN_EXAMPLE
	Time stamping parameters for eth6:
	Capabilities:
	hardware-transmit (SOF_TIMESTAMPING_TX_HARDWARE)
	software-transmit (SOF_TIMESTAMPING_TX_SOFTWARE)
	hardware-receive (SOF_TIMESTAMPING_RX_HARDWARE)
	software-receive (SOF_TIMESTAMPING_RX_SOFTWARE)
	software-system-clock (SOF_TIMESTAMPING_SOFTWARE)
	hardware-raw-clock (SOF_TIMESTAMPING_RAW_HARDWARE)
	PTP Hardware Clock: 1
	Hardware Transmit Timestamp Modes:
	off (HWTSTAMP_TX_OFF)
	on (HWTSTAMP_TX_ON)
	Hardware Receive Filter Modes:
	none (HWTSTAMP_FILTER_NONE)
	all (HWTSTAMP_FILTER_ALL)
	#+END_EXAMPLE

	The next example shows the case where the MAC only supports software
	time stamping. The ~ptp4l~ program requires either the ~-S~ command
	line argument or the ~time_stamping software~ configuration option
	when using such interfaces.

	#+BEGIN_EXAMPLE
	Time stamping parameters for enp6s0:
	Capabilities:
	software-transmit (SOF_TIMESTAMPING_TX_SOFTWARE)
	software-receive (SOF_TIMESTAMPING_RX_SOFTWARE)
	software-system-clock (SOF_TIMESTAMPING_SOFTWARE)
	PTP Hardware Clock: none
	Hardware Transmit Timestamp Modes: none
	Hardware Receive Filter Modes: none
	#+END_EXAMPLE

	Note the ~software-transmit (SOF_TIMESTAMPING_TX_SOFTWARE)~
	capability. If this is lacking, then the MAC cannot be used at
	all. However, adding this capability entails adding a single line
	of code to the device driver.

	* Installation

	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.nwtime.org/sympa/info/linuxptp-users

	** Development

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

	https://lists.nwtime.org/sympa/info/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:

	#+BEGIN_EXAMPLE
	git commit -s
	#+END_EXAMPLE

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

	#+BEGIN_EXAMPLE
	Signed-off-by: Random J Developer <random@developer.example.org>
	#+END_EXAMPLE

	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.

	#+BEGIN_EXAMPLE
	git send-email --to linuxptp-devel@lists.nwtime.org origin/master
	#+END_EXAMPLE

	* Thanks

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

	- http://www.audioscience.com

	Thanks to Exablaze for donating an ExaNIC X10

	- http://exablaze.com/exanic-x10

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

	- http://www.intel.com
	- http://e1000.sourceforge.net

	Thanks to Meinberg Funkuhren for donating a LANTIME M1000.

	- https://www.meinbergglobal.com

	Thanks to Moser Baer for sponsoring the Telecom Profiles and unicast
	support.

	- http://www.mobatime.com

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

	- http://www.omicron-lab.com/ptp