@item Layer 1 Syntonization (L1Sync) - specified in Annex O of @sc{ieee} 1588-2019.
@end itemize
@end indentedblock
White Rabbit extension is the default choice when building for one of the
WR architectures. Nothing in PPSi
prevents our fellow developers to support their own @i{ptp} extension
using PPSi.
Each extension lives in a subdirectory called @t{proto-ext-}@i{name}.
Source files in that directory may override the implementation for the
standard protocol (which lives in @t{proto-standard}) to provide their
own functionalities. To simplify writing extensions, the @i{proto-standard}
own functionalities. There is also a subdirectory @t{proto-ext-common}
which holds common code for all available extensions.
To simplify writing extensions, the @i{proto-standard}
functions already provide @i{hooks} so the extension itself can provide
callbacks while still using the basic @sc{ptp} engine.
The set of callbacks is currently based on the needs of
WR, but we are willing to accept patches to provide more hooks as
WR and L1Sync, but we are willing to accept patches to provide more hooks as
needed.
If you plan to write your own protocol extension within PPSi, please
...
...
@@ -258,7 +274,7 @@ easily port the daemon to your own timing primitives.
The subdirectories named @i{time-xxxx} are used to implement timing
functions; timing includes the methods that are part of two data
structures: @i{pp_time_operations} and @i{pp_network_operations}. The
former structure deals with getting and setting system time, while the
former structure deals with getting and setting system/WR time, while the
latter deals with frame tx and rx. Network operations are concerned
with timestamping the actual I/O, and that's why they are considered
part of the ``timing'' of PPSi.
...
...
@@ -286,7 +302,7 @@ not include your own hardware support.
@section Features
This is a summary of current and planned features for the PPSi
package. As said, we are still working on it, so the following
package. As said, we are continuously improving it, so the following
list may be not up to date with software developments by the time you
read it.
...
...
@@ -311,18 +327,19 @@ unfair to hide them.
implementation, and our only freestanding environment is @i{wrpc},
running on an LM32 processor.
@item Support multi-link operation.
@item Support multi-PTP link operation.
The daemon manages several links at the same time, being master
slave or auto-detect independently on each link.
The @i{best master clock} algorithm is run globally,
The daemon manages several PTP links at the same time, being configured
as master/slave or auto-detecting its role on each link using
@i{best master clock algorithm} (BMCA).
The @i{BMCA} is run globally,
but communication and timeouts are managed per-link.
@item Support both @sc{udp} and raw Ethernet.
We already do that. We use the multi-link operation to
We already do that. We use the multi-PTP link operation to
support both @sc{udp} and raw Ethernet on the same network
interface. Also, we support @sc{udp} in the WR switch,
interface (physical port). We added support of @sc{udp} in the WR switch
to allow progressive and seamless migration to WR if you already
support @sc{ptp} in your network with a @sc{udp}-only implementation.
...
...
@@ -335,6 +352,7 @@ unfair to hide them.
@item Support hardware timestamping where available.
Hardware timestamping is supported in WR devices.
This is not yet implemented for the generic protocol, but we
plan to add at least @i{time-linux-tstamp} soon.
...
...
@@ -365,6 +383,17 @@ unfair to hide them.
when you run more than a pair of interfaces and have problems
on some of the links but not all of them.
@item Runtime re-configuratin
Currently, the configuration of PPSi is provided at startup and
it cannot be changed. It would be very useful to be able to
change some of the @sc{ptp} and extensions configuration without
the need of restarting PPSi (and resynchronizing). Such runtime
re-configuration could include ClockClass priority, packet rate
or enable/allowed extensions. Implementing runtime reconfiguration
ins on our todo list.
@end table
...
...
@@ -389,7 +418,7 @@ As of 2013-05 the project suffers from these known bugs:
@node Configuration
@chapter Configuration
PPSi support configuration files and individual configuration items
PPSi supports configuration files and individual configuration items
passed on the command line. Such support is currently not available
for freestanding architectures (the @i{bare} ones and @i{wrpc-sw}).
...
...
@@ -401,7 +430,7 @@ semicolon as a separator.
If no configuration file is specified, the program reads the default
one, which is architecture-specific (thus, the default configuration
file is processed after all the command line configuration items. The
file is processed after all the command line configuration items). The
default file name is @t{/etc/ppsi.conf}. The source tree of PPSi includes
two example configuration files in its own @t{/etc} subdirectory.
...
...
@@ -445,8 +474,8 @@ following 'port-specific' keywords will be associated to this port until
a new keyword 'port' or 'link' appears.
@anchor{arg-types}
An option is a key/value(s) pair separated by at least a space character '@t{key value(s)}'. The '@t{value{s}}' entry
depends on the option type. Few types are supported by PPSi:
An option is a key/value(s) pair separated by at least a space character, e.g.: '@t{key value(s)}'. The '@t{value{s}}' entry
depends on the option type. The following value types are supported by PPSi:
@table @code
...
...
@@ -460,7 +489,7 @@ This is a 64 bits integer value in the range from -9 223 372 036 854 775 808 to
This is an array of 2 Int16.
@item Double
This is a 64 bit floating point in the range 1.7E +/- 308 (15 digits).
A value can be expressed using this two available notations:
A value can be expressed using two available notations:
- E notation: 1.6E-1
- Decimal notation: 0.16
@item Boolean
...
...
@@ -469,36 +498,38 @@ and '@t{f/false/0/off/n/no}' for 'False'.
@item String
This is free text.
@item TextList
The option value has to be select in a list of predefined text. For each choice we can also use different way
to refer to the same choice.
For example, the selection of the delay mechanism allows 2 choices (peer-to-peer or end-to-end) but for each choice
we are free to use a different text for the selection :
This is a list of predefined choices specified with predefined text.
For each choice, we can use more than one predefined text.
For example, the selection of the delay mechanism allows 2 predefined choices (peer-to-peer or end-to-end) but for each choice we are free to use a number of different texts for the selection:
@example
. end-to_end: "request-response","delay","e2e"
. peer-to-peer: "peer-delay","pdelay","p2p"
end-to_end: "request-response","delay","e2e"
peer-to-peer: "peer-delay","pdelay","p2p"
@end example
@end table
For some options, multiple keyword names can be used ( e.g. "mechanism", "dm"). New keyword names have been added
to be more explicit but at the same time old key names have not been suppressed just to keep the backward compatibility.
For some options, multiple keyword names (@t{key}) can be used, e.g. "mechanism", "dm". New keyword names have been added
to be more explicit but at the same time old keyword names have not been suppressed just to keep the backward compatibility.
Some old keywords will be marked '@i{(deprecated)}', and will be removed in the future.
@heading List of global options
@heading List of global options (i.e. keywords)
@table @code
@item @b{clock-class} @i{[Int32]}
An attribute defining the TAI traceability, synchronization state and
expected performance of the time or frequency distributed by a
Boundary Clock or Ordinary Clock.
For more details please refer to the IEEE 1588 standard
@item @b{clock-accuracy} @i{[Int32]}
An attribute defining the accuracy of the Local Clock (e.g. local
oscillator) of a Boundary Clock or Ordinary Clock.
For more details please refer to the IEEE 1588 standard.
@item @b{clock-allan-variance} @i{[Int32]}
An attribute defining the stability of the Local Clock of a
Boundary Clock or Ordinary Clock.
For more details please refer to the IEEE 1588 standard
@item @b{time-source} @i{[Int32]}
The source of time used by the grandmaster (or free-running master).
...
...
@@ -508,27 +539,31 @@ Some old keywords will be marked '@i{(deprecated)}', and will be removed in the
other as defined by the PTP protocol. A domain defines the scope of
PTP message communication, state, operations, data sets, and
timescale. PTP devices may participate in multiple domains.
For more details please refer to the IEEE 1588-2020 standard.
For more details please refer to the IEEE 1588 standard.
@item @b{priority1} @i{[Int32]}
A user configurable designation that a clock belongs to an ordered
set of PTP devices from which a PTP Master is selected.
For more details please refer to the IEEE 1588-2020 standard.
For more details please refer to the IEEE 1588 standard.
@item @b{priority2} @i{[Int32]}
A user configurable designation that provides finer grained ordering
among otherwise equivalent PTP devices.
For more details please refer to the IEEE 1588-2020 standard.
For more details please refer to the IEEE 1588 standard.
@item @b{forcePpsGen} @i{[Boolean]}
Configuration of the PPS output. By default, the PPS is generated
only when the clock class is set to 6(Grand master) or to 193(Free Running master.
Configuration of the PPS output. By default, the PPS is generated
only when the clock class is set to 6 (Grandmaster), or to 193
(Free-running master), or when the PTP device is a PTP Slave, i.e.
it is synchronized via port in Slave state to a PTP Master.
When this option is set, the PPS is always generated.
@item @b{ptpFallbackPpsGen} @i{[Boolean]}
if activated, enables the PPS generation if a slave instance
programmed to use an extension protocol (WR, L1Sync, ...) is falling back
to PTP communication only.
If set, PPS is generated even if a PTP Device with enabled
protocol extension (WR, L1Sync, ...) is synchronized using standard
PTP communication only. Note: by default, a PTP device that is a
a PTP slave and has protocol extension enabled will generate PPS
only if the protocol extension is active on the Slave port.
@item @b{ptpPpsThresholdMs} @i{[Int32]}
This option defines the threshold corresponding to the offset from the
...
...
@@ -540,22 +575,23 @@ Some old keywords will be marked '@i{(deprecated)}', and will be removed in the
than the threshold value + 20%.
@item @b{gmDelayToGenPpsSec} @i{[Int32]}
If this option is set to a value greater than 0, it allows the PPS generation
when the device becomes Grand-Master by BMCA. The value represent a delay in seconds to respect before
to start the PPS generation.
If this option is set to a value greater than 0, it allows PPS generation
when the PTP device becomes Grandmaster by BMCA (i.e. it is configured to be
a Boundary Clock). The value represent a delay in seconds between the
moment the PTP Device becomes Grandmaster and the start of PPS generation.
