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

The library is written in C++ and provides a C wrapper.

A notice regarding memory: The classes wrappers provide a free callback which free any memory allocated by the wrapper itself. With one exception: the functions ptpmgmt_json_msg2json and ptpmgmt_json_tlv2json allocate string, which you need to free, in your application! You need to release any memory allocated on your application, as the library and the wrappers do not free them!

As C does not provides namespaces, all global functions and global structures are prefixed with ptpmgmt_ or PTPMGMT_.

C++ and C standards

The libptpmgmt Library uses C++11 with POSIX, GNU extensions and Linux kernel headers.

The C wrapper uses C11.

We try our best to avoid conflicts with newer versions of C++ and C. But if you find a conflict, please notify us.

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

C++ std::vector<> map in Scripts Languages 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 C++ library. During development, you need the Go wrapper and the C++ library development headers, as the Go build compiles 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 C++ 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 in run-time.

For example, Binary.SetBin(position, value) requires position to be int64 and value to be byte.

Go uses methods for interface which use Pascal notation, so all class functions in the C++ 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 in the same function.

Note: as Go syntax is stricter, you may need to update your code with small fixes when you build with a newer version of the Go wrapper of the library. We do our best to retain backward compatible with the C++ library, but NOT with the Go wrapper, which may break!

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:

More Documentation

Licence

The Licence of this project is: