libptpmgmt Library to Communicate with IEEE 1558 PTP Clocks

Preface

The library for PTP management client uses IEEE 1558 management messages to communicate with PTP entities over the network. We support get, set and command of all management TLVs that are described in IEEE 1588-2019. In addition, we support LinuxPTP specific implementation management TLVs.

The library supports the three PTP network layers:

  1. UDP over IP version 4
  2. UDP over IP version 6
  3. PTP over Ethernet — we do not support VLAN tags

In addition, we support using the Unix network and communicate with LinuxPTP ptp4l.

We also support parsing incoming signaling messages.

Users can use Linux VLAN with all sockets.

libptpmgmt Library

The library is written in C++ using a data-oriented model.

It uses the namespace ptpmgmt.

Each class represent a data object with methods acting on the data. The socket classes are the exception, as they represent a system object.

Management TLV that have data, have a structure and a process function that build and parse from structure to message and via versa. The caller needs to fill the structure and use it with a message object. When receiving a reply message, the user can parse the message and get a pointer to a structure from the message object.

The configuration file uses the ptp4l parameters that are relevant to the pmc tool.

Using C

This project does NOT support C directly.

Users that want to use the library with their C application, need to write a wrapping in C++ and combine it with their application.

Scripting

This project uses SWIG to generate wrapper to script languages. For now, we support:

Though the C++ library uses the namespace ptpmgmt, SWIG for PHP does not support namespace.

Ruby uses Ptpmgmt as namespace, following Ruby convention.

Perl uses the name PtpMgmtLib, following Perl convention.

Tcl, Lua, Go, and Python use the namespace ptpmgmt.

Some C++ syntax is ignored or renamed in various scripts. For example in PHP: Binary::empty is renamed to Binary::c_empty. See comments in libptpmgmt.i and warn.i of each language for the relevant changes.

Some C++ structure and functions use C++ standard vector std::vector<>. SWIG maps C++ standard vector to a class. See libptpmgmt.i for the full list of the mapping classes.

All languages create the vector as a class object. In Python, Ruby, and Tcl the vector has the properties of a native list. Lua uses subst of C++ standard vector methods. Perl, PHP, and Go use class methods; see PtpMgmtLib.pm for Perl, ptpmgmt.php for php, and ptpmgmt.go for php, for these methods.

std_vectors.md provides more information on vectors mapping and the Doxygen documentation provides information per class.

Go wrapper

Since Go is a compile language and not a “pure” script, the wrapper is used a bit differently. The wrapper is only required during development,
as the resulting application is a binary that does not require the Go wrapper, only the main library. During development, you need the Go wrapper and the main library development headers, as the Go build checks compilation of the Go wrapper.

In addition add the -lm -lptpmgmt flags to the linking using the CGO_LDFLAGS environment, so Go will link your application with the main library.

Pay attention that although Go uses static typing and checks the types in compilation, some C++ methods use variable arguments or share names for different methods. In this case, swig will use the ... interface{} parameter and perform the type check in runtime. If types are wrong, the Go swig wrapper will issue an exception to your application. For example, Binary.SetBin(position, value) requires position to be int64 and value to be byte.

Go uses methods for interface are using Pascal notation, so all class functions in the main library are converted to use first letter capital.

Go does not use constructors and destructors.

You need to use the New'Class' functions and release with Delete'Class'.

You can use the defer statment for the releasing, if the release is due to the same function.

As Go does not provide destructors, MessageBuilder is not a class and it does not call message.clearData() once it is removed. You are advised to call message.clearData() once you build the message, and do not plan to further use the send TLV.

Library content

pmc and phc_ctl tools

The project provides a clone of LinuxPTP;s pmc tool using the libptpmgmt library and phc_ctl using the libptpmgmt library and python wrapper.

Inspiration

The library provides functionality that is provided by the pmc tool of the LinuxPTP project. We wish to thank Richard Cochran and the LinuxPTP contributors for their excellent work.

Packaging

The project comes with packaging:

Licence

The Licence of this project is: