starlingx/docs
Code Issues Proposed changes

PTP GNSS and SyncE Support (dsR6*)

Browse Source 
Updates/additions to:
-System Config PTP section
-Guest Integration
-Admin Tasks
-Updates and Upgrades
Additional examples for T-BC
Incorporated patchset 3 review comments.
Added Limitations section.
Integrated patchset 5 comments.
Remove PTP Instance Removal - moved to RNs.

*Do not pick 100.019 alarm update to r6

Story: 2009130

Signed-off-by: Ron Stone <ronald.stone@windriver.com>
Change-Id: Ibdf449fe1d7282302d9be6d90e1c1b6dd70456b4
This commit is contained in:
Ron Stone 2022-03-18 14:56:18 -04:00
parent a18b20c7fd
commit 3b8299cf2c
22 changed files with 1098 additions and 368 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
doc/source/admintasks/kubernetes/index-admintasks-kub-ebc55fefc368.rst
View File

@ -60,3 +60,14 @@ Metrics Server
kubernetes-admin-tutorials-metrics-server
-----------------
PTP Notifications
-----------------
.. toctree::
:maxdepth: 1
install-ptp-notifications
remove-ptp-notifications
override-default-application-values

61
doc/source/admintasks/kubernetes/install-ptp-notifications.rst Normal file
View File

@ -0,0 +1,61 @@
.. xqd1614091832213
.. _install-ptp-notifications:
=========================
Install PTP Notifications
=========================
|PTP| notification is packaged as a system application and is managed
using the :command:`system application` and :command:`system-helm-override`
commands.
.. rubric:: |context|
|prod| provides the capability for application\(s\) to subscribe to
asynchronous |PTP| status notifications and pull for the |PTP| state on demand.
.. xbooklink :ref:`|prod-long| System Configuration
<system-configuration-management-overview>`:
.. rubric:: |proc|
You must provide helm override values indicating the ``ptp4l`` and ``phc2sys``
instances being tracked by ``ptp-notification``.
You must also remove your existing ``ptp-notification`` application and
upload/apply the new version. Because multiple ``ptp4l`` instances can be
supported on a node, you must specify which instance ``ptp-notification`` is
tracking.
For example:
#. Upload ``ptp-notification``.
.. code-block::
~(keystone_admin)]$ system application-upload <path to application>
#. Edit application overrides.
.. code-block::
cat ~/notification-override.yaml
ptptracking:
ptp4lSocket: /var/run/ptp4l-ptp1
ptp4lServiceName: ptp1
phc2sysServiceName: phc2sys1
#. Apply the overrides.
.. code-block::
~(keystone_admin)]$ system helm-override-update ptp-notification ptp-notification notification --values notification-override.yaml
#. Apply ``ptp-notification``.
.. code-block::
~(keystone_admin)]$ system application-apply ptp-notification

8
doc/source/guest_integration/kubernetes/override-default-application-values.rst → doc/source/admintasks/kubernetes/override-default-application-values.rst
View File

@ -39,7 +39,7 @@ You can override default application values using the commands described in this
.. code-block:: none
~(keystone_admin)]$ system helm-override-update ptp-notification ptp-notification notification -–values <<override.yaml>>
~(keystone_admin)]$ system helm-override-update ptp-notification ptp-notification notification -–values <override.yaml>
.. code-block:: none
@ -50,11 +50,11 @@ You can override default application values using the commands described in this
**simulated**
value must be 'false' for a normal operation \(used only for troubleshooting\).
**holdover\_seconds**
**holdover_seconds**
value is the holdover time provided by the |NIC| specification. The default is 15 seconds.
**poll\_freq\_seconds**
is the frequency that the tracking function monitors the ptp4l to
**poll_freq_seconds**
is the frequency that the tracking function monitors the ``ptp4l`` to
derive the |PTP| sync state. The default is 2 seconds.

0
doc/source/guest_integration/kubernetes/remove-ptp-notifications.rst → doc/source/admintasks/kubernetes/remove-ptp-notifications.rst
View File

28
doc/source/fault-mgmt/kubernetes/100-series-alarm-messages.rst
View File

@ -317,9 +317,23 @@ health of the system.
:header-rows: 0
* - **Alarm ID: 100.119**
- Major: PTP configuration or out-of-tolerance time-stamping conditions.
- <hostname> does not support the provisioned PTP mode
Minor: PTP out-of-tolerance time-stamping condition.
OR
<hostname> PTP clocking is out-of-tolerance
OR
<hostname> is not locked to remote PTP Grand Master
OR
<hostname> GNSS signal loss state:<state>
OR
<hostname> 1PPS signal loss state:<state>
* - Entity Instance
- host=<hostname>.ptp OR host=<hostname>.ptp=no-lock
@ -338,9 +352,17 @@ health of the system.
OR
host=<hostname>.ptp=out-of-tolerance
OR
host=<hostname>.instance=<instance>.ptp=out-of-tolerance
OR
host=<hostname>.interface=<interface>.ptp=signal-loss
* - Degrade Affecting Severity:
- None
* - Severity:
- M or m
* - Proposed Repair Action
- Monitor and, if condition persists, contact next level of support.
- Monitor and, if condition persists, contact next level of support.

3
doc/source/guest_integration/kubernetes/index-guest-kub-5c89ec07e141.rst
View File

@ -16,8 +16,5 @@ PTP Notification
:maxdepth: 1
ptp-notifications-overview
install-ptp-notifications
remove-ptp-notifications
override-default-application-values
integrate-application-with-notification-client-sidecar

131
doc/source/guest_integration/kubernetes/install-ptp-notifications.rst
View File

@ -1,131 +0,0 @@
.. xqd1614091832213
.. _install-ptp-notifications:
=========================
Install PTP Notifications
=========================
|PTP| notification is packaged as an Armada system application and is managed
using the :command:`system application` and :command:`system-helm-override`
commands.
.. rubric:: |context|
|prod| provides the capability for application\(s\) to subscribe to
asynchronous |PTP| status notifications and pull for the |PTP| state on demand.
.. rubric:: |prereq|
.. _install-ptp-notifications-ul-ydy-ggf-t4b:
- The |PTP| port must be configured as Subordinate mode \(Secondary mode\).
For more information, see,
.. xbooklink :ref:`|prod-long| System Configuration
<system-configuration-management-overview>`:
- :ref:`Configuring PTP Service Using Horizon <configuring-ptp-service-using-horizon>`
- :ref:`Configuring PTP Service Using the CLI <configuring-ptp-service-using-the-cli>`
.. rubric:: |proc|
Use the following steps to install the **ptp-notification** application.
#. Label the controller\(s\).
#. Source the platform environment.
.. code-block:: none
$ source /etc/platform/openrc
~(keystone_admin)]$
#. Assign the |PTP| registration label to the controller\(s\).
.. code-block:: none
~(keystone_admin)]$ system host-label-assign controller-0 ptp-registration=true
~(keystone_admin)]$ system host-label-assign controller-1 ptp-registration=true
#. Assign the |PTP| notification label to the node that is configured with
a Secondary |PTP| port. For example:
.. code-block:: none
~(keystone_admin)]$ system host-label-assign controller-0 ptp-notification=true
#. Upload the |PTP| application using the following command:
.. code-block:: none
~(keystone_admin)]$ system application-upload /usr/local/share/applications/helm/ptp-notification-<n.n-nn>.tgz
Where ``<n.n-nn>`` is the version of the .tgz file that you can download from
the |dnload-loc| relevant to your release.
#. Verify the |PTP| application has been uploaded.
.. code-block:: none
~(keystone_admin)]$ system application-list
#. Apply the |PTP| notification application.
.. code-block:: none
$ system application-apply ptp-notification
#. Monitor the status.
.. code-block:: none
$ watch –n 5 system application-list
and/or
.. code-block:: none
$ watch kubectl get pods –n notification
The default configuration for |PTP| notification pod is:
- |PTP|-notification pod:
- Runs as a daemonset \(1 pod per node with label **ptp-notification=true**\)
- Three containers:
- ptp-notification-rabbitmq
- ptp-notification-location
- ptp-notification-ptptracking
- Registration pod:
- Runs as a deployment on nodes labeled with **ptp-registration=true**
- Replica count of 1
- One container: Rabbitmq

11
doc/source/system_configuration/kubernetes/advanced-ptp-configuration-334a08dc50fb.rst Normal file
View File

@ -0,0 +1,11 @@
.. _advanced-ptp-configuration-334a08dc50fb:
==========================
Advanced PTP Configuration
==========================
.. caution::
Parameters are written to the ``ptp4l`` configuration file without error
checking. Caution must be taken to ensure that parameter names and values
are correct as errors will cause ``ptp4l`` launch failures.

114
doc/source/system_configuration/kubernetes/configuring-ptp-service-using-horizon.rst
View File

@ -1,114 +0,0 @@
.. pzk1552673010743
.. _configuring-ptp-service-using-horizon:
===================================
Configure PTP Service Using Horizon
===================================
The |PTP| is a protocol used to synchronize clocks in a network. You can use
the Horizon Web interface to configure these services on the host.
|PTP| provides more accurate time synchronization than |NTP|. |NTP| typically
provides time synchronization accuracy on the order of milliseconds, while
|PTP| provides time synchronization accuracy on the order of microseconds.
.. xbooklink For more information on configuring the PTP service for clock
synchronization, see |node-doc|: `Host Inventory <hosts-tab>`.
A |PTP| master must be present on the |OAM| Network, broadcasting |PTP| time
messages.
.. note::
|NTP| and |PTP| are configured per host. Lock/unlock the host when
updating **clock\_synchronization** for the host.
.. rubric:: |prereq|
Review the Fault Management page and ensure that any existing system alarms
are cleared.
.. rubric:: |proc|
.. _configuring-ptp-service-using-horizon-steps-xfh-24z-5p:
#. In the |prod| Horizon, open the System Configuration page.
The System Configuration page is available
from **Admin** \> **Platform** \> **System Configuration** in the
left-hand pane.
#. Select the |PTP| tab.
The |PTP| page appears.
#. Click **Edit PTP**. Update the configuration of the |PTP| service.
- **PTP Time Stamping Mode**: Hardware time stamping is the default
option, and achieves best time syncing.
- **PTP Network Transport**: Switch between IEEE 802.3 network
transport \(L2\) or |UDP| IPv4/v6 network transport for |PTP|
messaging.
.. note::
L2 is the default option.
If you use |UDP| for |PTP| transport, each |PTP| interface must have
an IP assigned. This is enforced during host unlock, and when
switching |PTP| transport to |UDP|.
- **PTP Delay Mechanism**
Set the |PTP| delay mechanism, the options are:
- E2E: default delay request-response
- P2P: peer delay
#. Click **Save**.
This raises **250.001 Configuration out-of-date** alarms against the
controllers, workers, and storages nodes. You can view the alarms on
the Fault Management page.
#. Lock and unlock the controllers, workers, and storage nodes to apply the
configuration and clear the **Configuration out-of-date** alarms.
Open the Host Inventory page, available
from **Admin** \> **Platform** \> **Host Inventory** in the left-hand
pane, and then select the **Hosts** tab. Hosts requiring attention are
shown with the status **Config out-of-date**.
To lock or unlock a host, click the **Action Menu** down arrow for the
host and then use the menu selections.
#. Lock the standby controller.
Wait for the lock operation to be completed.
#. Unlock the standby controller.
Wait for the host to become available. Its configuration is
updated, and its error message is cleared.
#. Perform a swact on the active controller.
Click **Action Menu \(down arrow\)** \> **Swact Host** \> for
the active controller.
Horizon Web interface access is interrupted, and the |prod| login
screen appears. Wait briefly for the Web service to stabilize, and
then log in again.
#. Lock the original controller \(now in standby mode\).
Wait for the lock operation to be completed.
#. Unlock the original controller.
Wait for it to become available. Its configuration is updated, and
its error message is cleared.
#. Ensure that the **Configuration out-of-date** alarms are cleared for
both controllers.

175
doc/source/system_configuration/kubernetes/configuring-ptp-service-using-the-cli.rst
View File

@ -8,38 +8,17 @@ Configure PTP Service Using the CLI
You can use the CLI to configure |PTP| services.
.. contents::
:local:
:depth: 1
For information on configuring the |PTP| service for clock synchronization
using the Horizon Web interface see
:ref:`Configure PTP Service Using Horizon
<configuring-ptp-service-using-horizon>`.
You can also specify the |PTP| service for **clock_synchronization** using
the |os-prod-hor| interface.
.. xbooklink For more information, see |node-doc|: `Host Inventory <hosts-tab>`.
**PTP Service**
To view the existing |PTP| status, use the following command.
To view the existing |PTP| status, use the following commands.
.. code-block:: none
~(keystone_admin)]$ system ptp-show
+--------------+--------------------------------------+
| Property | Value |
+--------------+--------------------------------------+
| uuid | 4844eca1-13bb-471e-9162-e5f2bb97d650 |
| mode | hardware |
| transport | l2 |
| mechanism | e2e |
| isystem_uuid | a16d7b07-1d42-41cf-b001-04bc25216a2b |
| created_at | 2019-12-09T16:08:34.319374+00:00 |
| updated_at | None |
+--------------+--------------------------------------+
~(keystone_admin)]$ system ptp-instance-list
~(keystone_admin)]$ system host-ptp-instance-list <host>
.. warning::
|NTP| and |PTP| are mutually exclusive on a particular host; only one can be
@ -149,133 +128,105 @@ To view the |PTP| service configuration, use the following command:
.. _configuring-ptp-service-using-the-cli-ul-srp-rnn-3jb:
- **PTP Time Stamping Mode**: |NTP| and |PTP| are configured per host.
Lock/unlock the host when Hardware time stamping is the default
option, and achieves best time synching. Use the following command:
PTP Instance Configuration
==========================
.. code-block:: none
|PTP| instances are the top level configuration unit. The supported instance
types are:
~(keystone_admin)]$ system ptp-modify --mode=<hardware/software/legacy>
``ptp4l``
Represents an instance of ``ptp4l``. A node may have several of these
instances.
- **PTP Network Transport**: Switch between IEEE 802.3 network
transport \(L2\) or |UDP| IPv4/v6 network transport for |PTP|
messaging. Use the following command:
``phc2sys``
Represents an instance of ``phc2sys``. A node will generally only have one
of these.
.. code-block:: none
``ts2phc``
Represents an instance of ``ts2phc``.
~(keystone_admin)]$ system ptp-modify --transport=<l2/UDP>
``clock``
``clock`` is not an daemon or service, but instead an abstract unit used to
hold the interfaces and configuration for setting Westport Channel NIC
control parameters (syncE and PPS transmission).
.. note::
L2 is the default option.
Valid instance level parameters are found in the man pages for each service,
under:
If you use |UDP| for |PTP| transport, each |PTP| interface must have an
IP assigned. This is enforced during host unlock, and when switching
|PTP| transport to |UDP|.
* GLOBAL OPTIONS - ptp4l
- **PTP Delay Mechanism**
* OPTIONS - phc2sys
Set the |PTP| delay mechanism, the options are:
* GLOBAL OPTIONS - ts2phc
- E2E: default delay request-response
* None for clock
- P2P: peer delay
Use the following command:
Set host to use |PTP|:
.. code-block:: none
.. code-block::
~(keystone_admin)]$ system ptp-modify --mechanism=<e2e/p2p>
~(keystone_admin)]$ system host-update controller-0 clock_synchronization=ptp
- **PTP Role**
Create an instance and assigning parameters
-------------------------------------------
|PTP| primary/secondary interfaces are not defined by default. They must be
specified by the administrator for each host.
#. Create an instance by providing a name and type.
The **ptp\_role** option can be added to interfaces, and can be defined for
primary, secondary, and none. This option allows administrators to
configure interfaces that can be used for |PTP| services. The primary and
secondary roles are limited to |OAM|, platform or data interfaces. Any
number of primary and secondary interfaces can be specified per host.
.. code-block::
If a host has **clock_synchronization=ptp**, there must be at least one
host interface with a |PTP| role specified. This is enforced during host
unlock.
~(keystone_admin)]$ system ptp-instance-add myptp1 ptp4l
For example, this service can be specified using the following commands:
#. Add any required instance level parameters.
.. code-block:: none
.. code-block::
~(keystone_admin)]$ system host-if-modify compute-3 ens803f0 -n sriovptp --ptp-role slave
~(keystone_admin)]$ system ptp-instance-parameter-add myptp1 domainNumber=24 slaveOnly=0
To apply changes to hosts, use the following command:
Create an interface and assign to ports
---------------------------------------
.. code-block:: none
#. Create an interface unit by providing a name and assigning it to an instance.
~(keystone_admin)]$ system ptp-apply
.. code-block::
|PTP| changes will be applied to all unlocked hosts configured with ptp
clock\_synchronization.
~(keystone_admin)]$ system ptp-interface-add ptpinterface myptp1
.. _configuring-ptp-service-using-the-cli-section-qn1-p3d-vkb:
#. Add ports to the interface.
----------------------
Advanced Configuration
----------------------
.. code-block::
Using service parameters, you can customize a wide range of linuxptp module
settings to use the system in a much wider range of |PTP| configurations.
~(keystone_admin)]$ system host-if-ptp-assign controller-0 oam0 ptpinterface
.. caution::
These parameters are written to the ptp4l configuration file without error
checking. Caution must be taken to ensure that parameter names and
values are correct as errors will cause ptp4l launch failures.
#. Add interface level parameters as required.
The following service parameters are available:
.. code-block::
**ptp global default_sync=0**
This service parameter disables the selection of a default port by phc2sys.
This option should be used when there are three or more |PTP| ports
configured in order to prevent phc2sys from synchronizing the time across
all ports before they have become synchronized with the primary clock.
~(keystone_admin)]$ system ptp-interface-parameter-add ptpinterface masterOnly=1
**ptp global <name>=<value>**
This service parameter allows you to write or overwrite values found
in the global section of the ptp4l configuration file. For example,
the command
.. note::
.. code-block:: none
Multiple ports may be assigned to an interface in order to simplify
parameter application.
~(keystone_admin)]$ system service-parameter-add ptp global domainNumber=24
.. code-block::
results in the following being written to the configuration file:
~(keystone_admin)]$ system host-if-ptp-assign controller-0 data0 ptpinterface
~(keystone_admin)]$ system ptp-interface-show ptpinterface
.. code-block:: none
domainNumber 24
#. Assign the instance to a host and apply the configuration.
|PTP| global service parameters take precedence over the system |PTP|
values. For example, if the system |PTP| delay mechanism is
**E2E**, and you subsequently run the command
#. Assign the |PTP| instance to a host so that the configuration can be
applied.
.. code-block:: none
.. code-block::
~(keystone_admin)]$ system service-parameter-add ptp global delay_mechanism=P2P
~(keystone_admin)]$ system host-ptp-instance-assign controller-0 myptp1
Then the **P2P** will be used instead.
#. Apply the configuration and verify that it completed.
**ptp phc2sys update-rate=<value>**
This parameter controls the update-rate of the phc2sys service, in
seconds.
.. code-block::
**ptp phc2sys summary-updates=<value>**
This parameter controls the number of clock updates to be included in
summary statistics.
To apply service parameter changes to hosts, use the following command:
.. code-block:: none
~(keystone_admin)]$ system service-parameter-apply ptp
|PTP| changes will be applied to all unlocked hosts configured with
ptp clock\_synchronization.
~(keystone_admin)]$ system ptp-instance-apply
~(keystone_admin)]$ fm alarm-list

BIN
doc/source/system_configuration/kubernetes/figures/ptp-instance-dual-nic-deployment-gnss.PNG Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 56 KiB

BIN
doc/source/system_configuration/kubernetes/figures/ptp-t-bc-configuration.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

111
doc/source/system_configuration/kubernetes/gnss-and-synce-support-62004dc97f3e.rst Normal file
View File

@ -0,0 +1,111 @@
.. _gnss-and-synce-support-62004dc97f3e:
======================
SyncE and Introduction
======================
Intel's Westport Channel NICs support a built-in GNSS module and the ability to
distribute clock via Synchronous Ethernet (SyncE). This feature allows a PPS
signal to be taken in via the GNSS module and redistributed to additional NICs
on the same host or on different hosts. This behavior is configured on |prod|
using the ``clock`` instance type in the |PTP| configuration. Many of the
configuration steps in this section are similar to those in the |PTP|
Configuration section - reference this for additional details if required.
.. important::
Users should reference the user guide for their Westport Channel NIC for
additional information on configuring these features. The intent of this
section is to explain how these parameters can be set, rather than
describing each possible configuration.
Basic 'clock' instance configuration
====================================
General 'clock' information
---------------------------
**Default global parameters**
There are no supported global parameters for the clock type
**Default interface parameters**
NONE
**Required user-supplied parameters**
NONE
**Other requirements**
The clock type instance is a special instance used for configuring the NIC
control parameters of the Westport Channel NIC.
Configure a 'clock' instance
----------------------------
#. Create the instance.
.. code-block::
~(keystone_admin)]$ system ptp-instance-add myclock1 clock
#. Create an interface for ``myclock1``.
.. code-block::
~(keystone_admin)]$ system ptp-interface-add clockint1 myclock1
#. Add a port to the interface.
.. code-block::
~(keystone_admin)]$ system host-if-ptp-assign controller-0 oam0 clockint1
#. Add parameters to the interface.
.. code-block::
~(keystone_admin)]$ system ptp-interface-parameter-add clockint1 sma1=output
#. Assign the instance to a host.
.. code-block::
~(keystone_admin)]$ system host-ptp-instance-assign controller-0 myclock1
#. Apply the configuration.
.. code-block::
~(keystone_admin)]$ system ptp-instance-apply
Clock interface parameters
--------------------------
.. note::
All parameters are scoped to the entire NIC, except for ``synce_rclka`` and
``synce_rclkb``. This means that if ``sma1=input`` is applied to ens1f0 and
``sma1=output`` is applied to ``ens1f2``, they will override each other and
the last one processed by the system will be applied. Only the
``synce_rclka`` and ``synce_rclkb`` parameters can be configured
per-interface. See the NIC user guide document for additional details.
.. note::
The absence of a parameter is treated as disabled.
The following parameters can be applied to the interface of a clock instance.
PTP Parameters:
* sma1=input
* sma1=output
* sma2=input
* sma2=output
* u.fl1=output
* u.fl2=input
* synce_rclka=enabled
* synce_rclkb=enabled

21
doc/source/system_configuration/kubernetes/index-sysconf-kub-78f0e1e9ca5a.rst
View File

@ -48,8 +48,27 @@ PTP Server Configuration
.. toctree::
:maxdepth: 2
configuring-ptp-service-using-horizon
ptp-introduction-d981dd710bda
ptp-limitations-64338c74b415
configuring-ptp-service-using-the-cli
ptp-interfaces-df73e9b43677
instance-specific-considerations-d9d9509c79dd
remove-ptp-configurations-4885c027dfa5
advanced-ptp-configuration-334a08dc50fb
ptp-instance-examples-517dce312f56
ptp-instance-troubleshooting-7a7c576ee57a
----------------------
GNSS and SyncE Support
----------------------
.. toctree::
:maxdepth: 2
gnss-and-synce-support-62004dc97f3e
--------------------
OAM IP Configuration

122
doc/source/system_configuration/kubernetes/instance-specific-considerations-d9d9509c79dd.rst Normal file
View File

@ -0,0 +1,122 @@
.. _instance-specific-considerations-d9d9509c79dd:
================================
Instance Specific Considerations
================================
ptp4l
=====
**Default global parameters**
* tx_timestamp_timeout 20
* summary_interval 6
* clock_servo linreg
* network_transport L2
* time_stamping hardware
* delay_mechanism E2E
* boundary_clock_jbod 1
* uds_address /var/run/ptp4l-<instance name>
* uds_ro_address /var/run/ptp4l-<instance name>ro
**Default interface parameters**
NONE
**Required user-supplied parameters**
``domainNumber <number>``
**Other requirements**
An interface with a port must be assigned to the ``ptp4l`` instance in order
for it to start.
phc2sys
=======
**Default global parameters**
``cmdline_opts '-a -r -R 2 -u 600'``
**Default interface parameters**
NONE
**Required user-supplied parameters**
``domainNumber <number>``
This should match with the associated ``ptp4l`` instance.
``uds_address <path>``
This value needs to be the same as the uds_address for the ``ptp4l``
instance that ``phc2sys`` is tracking.
**Other requirements**
The ``cmdline_opts`` are defaulted to support interaction with ``ptp4l``. If
``phc2sys`` is instead being used with ``ts2phc``, this parameter will have to
be updated. See :ref:`ptp-instance-examples-517dce312f56` for more information.
.. note::
The ``cmdline_opts parameter`` overrides all default command line flags for
the service. This means that when setting ``cmdline_opts``, the full list
of desired flags should be set.
ts2phc
======
**Default global parameters**
* ``ts2phc.pulsewidth 100000000``
* ``leapfile /usr/share/zoneinfo/leap-seconds.list``
* ``cmdline_opts '-s nmea'``
**Default interface parameters**
``ts2phc.extts_polarity rising``
**Required user-supplied parameters**
This value is the path to the GNSS serial port that is connected, it will be
named differently on each system.
``ts2phc.nmea_serialport=/dev/ttyGNSS_BBDD_0``
**Other requirements**
An interface with a port must be assigned to the ``ts2phc`` instance in order
for time to be synced from GNSS to the phc.
clock
=====
**Default global parameters**
There are no supported global parameters for clock type.
**Default interface parameters**
NONE
**Required user-supplied parameters**
NONE
**Other requirements**
The clock type instance is a special instance used for configuring the NIC
control parameters of the Westport Channel NIC clock interface parameters.
These parameters can be applied to the interface of a clock instance |PTP|
parameters:
* sma1 input/output
* sma2 input/output
* u.fl1 output
* u.fl2 input
* synce_rclka enabled
* synce_rclkb enabled

368
doc/source/system_configuration/kubernetes/ptp-instance-examples-517dce312f56.rst Normal file
View File

@ -0,0 +1,368 @@
.. _ptp-instance-examples-517dce312f56:
===================================
Example PTP Instance Configurations
===================================
.. contents:: |minitoc|
:local:
:depth: 2
The following sections provide example configuration steps for two |PTP|
configurations supported by |prod|.
* The first is a Border Clock setup where an external |PTP| GM is providing
a time source for the system. Only ptp4l and phc2sys are used for this
configuration.
* The second shows how to setup a GM node when a time source is available
via a locally connected GNSS signal. The ``ptp4l``, ``phc2sys``,
``ts2phc`` and clock instance types are used for this configuration.
Simple PTP configuration - T-BC
===============================
Using the topology shown, the following examples provide
configurations for each service type:
.. figure:: figures/ptp-t-bc-configuration.png
:scale: 110 %
*T-BC configuration*
ptp4l
-----
#. Create the instance.
.. code-block::
~(keystone_admin)]$ system ptp-instance-add ptp-inst1 ptp4l
#. Create a |PTP| inteface for the instance.
.. code-block::
~(keystone_admin)]$ system ptp-interface-add ptp-iface1 ptp-inst1
#. Assign host interfaces to the |PTP| interface.
.. code-block::
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if0 ptp-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if1 ptp-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if2 ptp-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if3 ptp-iface1
.. note::
The ``if0-if3`` field should be a name listed by the :command:`system
host-if-list <hostname> -a` command.
#. Additionally, assign ports for the second NIC.
.. code-block::
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if4 ptp-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if5 ptp-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if6 ptp-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if7 ptp-iface1
.. note::
The ``if0-if3`` field should be a name listed by the :command:`system
host-if-list <hostname> -a` command.
#. Add a parameter to the instance (e.g. domainNumber=24). Additional
parameters can be added for other functionality.
.. code-block::
~(keystone_admin)]$ system ptp-instance-parameter-add ptp-inst1 domainNumber=24
#. Assign the |PTP| instance to controller-0.
.. code-block::
~(keystone_admin)]$ system host-ptp-instance-assign controller-0 ptp-inst1
#. Apply the configuration.
.. code-block::
~(keystone_admin)]$ system ptp-instance-apply
phc2sys
-------
#. Create the instance.
.. code-block::
~(keystone_admin)]$ system ptp-instance-add phc-inst1 phc2sys
#. Create a |PTP| interface for the instance.
.. code-block::
~(keystone_admin)]$ system ptp-interface-add phc-iface1 phc-inst1
#. Assign host interface(s) to the |PTP| interface.
.. code-block::
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if0 phc-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if1 phc-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if2 phc-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if3 phc-iface1
.. note::
The ``if0-if3`` field should be a name listed by the :command:`system
host-if-list <hostname> -a` command.
#. Assign host interfaces from the second NIC.
.. code-block::
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if4 phc-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if5 phc-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if6 phc-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if7 phc-iface1
.. note::
The ``if0-if3`` field should be a name listed by the :command:`system
host-if-list <hostname> -a` command.
#. Add the required ``uds_address`` and ``domainNumber`` parameters to the
instance.
.. code-block::
~(keystone_admin)]$ system ptp-instance-parameter-add phc-inst1 uds_address=/var/run/ptp4l-ptp-inst1
~(keystone_admin)]$ system ptp-instance-parameter-add phc-inst1 domainNumber=24
.. note::
The path assigned to ``uds_address`` must use the name of the ``ptp4l``
instance that ``phc2sys`` is tracking.
#. Assign the instance to controller-0.
.. code-block::
~(keystone_admin)]$ system host-ptp-instance-assign controller-0 phc-inst1
#. Apply the configuration.
.. code-block::
~(keystone_admin)]$ system ptp-instance-apply
Alternate PTP configuration - T-GM
==================================
Using the topology shown, the following examples provide configurations for each service type.
.. figure:: figures/ptp-instance-dual-nic-deployment-gnss.PNG
:scale: 50 %
*Dual NIC Deployment with GNSS*
ts2phc
------
.. rubric:: |proc|
#. Create an instance.
.. code-block::
~(keystone_admin)]$ system ptp-instance-add ts1 ts2phc
#. Create the interface and assign to ports.
.. code-block::
~(keystone_admin)]$ system ptp-interface-add tsint1 ts1
# This is the port/PHC that we want to sync to GNSS time stamps, could be multiple PHCs if required
~(keystone_admin)]$ system host-if-ptp-assign controller-0 oam0 tsint1
# Assign a port on the second nic as well
~(keystone_admin)]$ system host-if-ptp-assign controller-0 data0 tsint1
This value is the path to the GNSS serial port that is connected, will vary system to system
~(keystone_admin)]$ system ptp-instance-parameter-add ts1 ts2phc.nmea_serialport=/dev/ttyGNSS_BBDD_0
#. Assign the instance to a host.
.. code-block::
~(keystone_admin)]$ system host-ptp-instance-assign controller-0 ts1
#. Apply the configuration.
.. code-block::
~(keystone_admin)]$ system ptp-instance-apply
phc2sys
-------
.. rubric:: |proc|
#. Add the instance.
.. code-block::
~(keystone_admin)]$ system ptp-instance-add phc-inst1 phc2sys
#. Use the interface name that is being synced with ``ts2phc`` above.
For example, if oam0 is on ens1f0, use ens1f0 below.
.. code-block::
~(keystone_admin)]$ system ptp-instance-parameter-add phc-inst1 cmdline_opts='-s <port_name> -O -37'
#. Assign the instance to a host.
.. code-block::
~(keystone_admin)]$ system host-ptp-instance-assign controller-0 phc-inst1
#. Apply the configuration.
.. code-block::
~(keystone_admin)]$ system ptp-instance-apply
ptp4l
-----
.. note::
You must create a second instance for the second NIC and repeat this
process.
.. rubric:: |proc|
#. Create instance.
.. code-block::
~(keystone_admin)]$ system ptp-instance-add ptp-inst1 ptp4l
#. Create an interface for the instance.
.. code-block::
~(keystone_admin)]$ system ptp-interface-add ptp-iface1 ptp-inst1
#. Assign ports to the interface.
.. code-block::
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if0 ptp-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if1 ptp-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if2 ptp-iface1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 if3 ptp-iface1
#. Add parameters to the instance.
.. code-block::
~(keystone_admin)]$ system ptp-instance-parameter-add ptp-inst1 domainNumber=24
#. Assign the |PTP| instance to controller-0.
.. code-block::
~(keystone_admin)]$ system host-ptp-instance-assign controller-0 ptp-inst1
#. Apply the configuration.
.. code-block::
~(keystone_admin)]$ system ptp-instance-apply
clock
-----
.. note::
These parameters are used to enable the UFL/SMA ports, recovered clock
syncE, and so-on. Refer to the user's guide for the Westport Channel NIC for
additional details on how to operate these cards.
The following |PTP| parameters can be applied to the interface of a clock
instance:
* sma1 input/output
* sma2 input/output
* u.fl1 output
* u.fl2 input
* synce_rclka enabled
* synce_rclkb enabled
.. rubric:: |proc|
#. Create the instance.
.. code-block::
~(keystone_admin)]$ system ptp-instance-add cl1 clock
#. Create a |PTP| interface and assign host interfaces to it.
.. code-block::
~(keystone_admin)]$ system ptp-insterface-add clint1 cl1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 oam0 clint1
The parameters are ultimately applied to the whole NIC, so adding multiple
interface from the same NIC will override each other. The exception is the
``synce_rclk`` params, which are specific to the individual port.
#. Add interface parameters.
.. code-block::
~(keystone_admin)]$ system ptp-interface-parameter-add clint1 sma1=output synce_rclka=enabled
#. Assign the instance to a host.
.. code-block::
~(keystone_admin)]$ system host-ptp-instance-assign controller-0 cl1
#. Create a second clock interface to take input on the sma1 port in order to
pass GNSS data to the second NIC.
#. Create a |PTP| interface and assign host interfaces to it.
.. code-block::
~(keystone_admin)]$ system ptp-insterface-add clint2 cl1
~(keystone_admin)]$ system host-if-ptp-assign controller-0 data0 clint2
#. Add interface parameters.
.. code-block::
~(keystone_admin)]$ system ptp-interface-parameter-add clint1 sma1=input synce_rclka=enabled
#. Apply the configuration.
.. code-block::
~(keystone_admin)]$ system ptp-instance-apply

127
doc/source/system_configuration/kubernetes/ptp-instance-troubleshooting-7a7c576ee57a.rst Normal file
View File

@ -0,0 +1,127 @@
.. _ptp-instance-troubleshooting-7a7c576ee57a:
============================
PTP Instance Troubleshooting
============================
The most common error encountered using multi-instance |PTP| is a failure to
start one or more instances after running the :command:`ptp-instance-apply`
command. This is often due to an invalid configuration or missing parameter.
This section provides some troubleshooting steps to assist with determining the
error.
Example
=======
After running the :command:`ptp-instance-apply` command, the 250.001 alarm will
appear if the |PTP| instances could not be created/started properly. The system
may also show the 200.011 alarm if, after an unlock, |PTP| instances were
unable to start.
The following example shows these alarms as they would appear in tabular
terminal output.
.. code-block::
| 250.001 | controller-0 Configuration is out-of-date. | host=controller-0 | major | 2022-02-25T21: |
| | | |
| 200.011 | controller-0 experienced a configuration failure. | host=controller-0 | critical | 2022-02-25T20: |
| | | | | 47:59.561262 |
#. Determine if there was a |PTP|-instance failure by looking at the latest
runtime puppet logs.
.. code-block::
sudo less /var/log/puppet/latest/puppet.log
# Searching for "Error" in the log file shows this entry
2022-02-28T17:26:49.529 ESC[1;31mError: 2022-02-28 17:26:49 +0000 Systemd start for ptp4l@ptp4l-legacy failed!
#. Once the instance has been identified, examine the config file for
configuration errors.
.. code-block::
~(keystone_admin)]$ cat /etc/ptpinstance/ptp4l-ptp4l-legacy.conf
[global]
##
## Default Data Set
##
boundary_clock_jbod 1
clock_servo linreg
delay_mechanism E2E
domainNumber 0
message_tag ptp4l-legacy
network_transport L2
summary_interval 6
time_stamping hardware
tx_timestamp_timeout 20
uds_address /var/run/ptp4l-ptp4l-legacy
uds_ro_address /var/run/ptp4l-ptp4l-legacyro
#. Start the service manually and check for errors.
.. code-block::
~(keystone_admin)]$ ptp4l -f /etc/ptpinstance/ptp4l-ptp4l-legacy.conf
no interface specified
In this example the ``ptp4l`` program indicates that there is no interface
specified, which is confirmed by the contents of the config file above.
#. Check using the relevant ``system`` commands to see if there is an interface
assigned to this instance and add one as required.
Additional tools
================
:command:`PMC`
|PTP| management client.
Used to interact with ptp4l and read/set various |PTP| parameters.
.. code-block::
$ man pmc
# General command format:
sudo pmc -u -b 0 -f <path to ptp4l.conf for targeted instance> -s <path to uds socket for target instance> 'COMMAND GOES HERE'
eg. pmc -u -b 0 -f /etc/ptpinstance/ptp4l-ptp1.conf -s /var/run/ptp4l-ptp1 'get PORT_DATA_SET
:command:`PHC_CTL`
Directly control PHC device clock.
Used to perform operations on the physical hardware clock (phc). PHC_CTL can
be used to set the time on a NIC, check the delta between the NIC and the
system clock, adjust the clock frequency.
.. code-block::
$ man phc_ctl
# Example commands
phc_ctl <ptp_interface> get
phc_ctl <ptp_interface> cmp
# Rhis syncs the NIC clock to the system clock
phc_ctl <ptp_interface> set
:command:`TCPDUMP`
Check if |PTP| traffic is sending or receiving on a given interface.
You can capture L2 ptp traffic by filtering on proto 0x88F7
.. code-block::
sudo tcpdump ether proto 0x88F7 -i <ptp_interface>
# Write it to file
sudo tcpdump ether proto 0x88F7 -i <ptp_interface> -w <output_file.pcap>

19
doc/source/system_configuration/kubernetes/ptp-interfaces-df73e9b43677.rst Normal file
View File

@ -0,0 +1,19 @@
.. _ptp-interfaces-df73e9b43677:
==============
PTP Interfaces
==============
|PTP| interfaces are assigned to an instance. An interface has a name, can have
multiple physical ports assigned to it and can have multiple parameters.
Interface level parameters are applied to all ports in the interface.
Valid interface parameters can be located in the man page for a service under:
* PORT OPTIONS - ptp4l
* SLAVE CLOCK OPTIONS - ts2phc
* None for phc2sys
Clock has a special list of interface parameters, detailed in the clock section
of the document.

98
doc/source/system_configuration/kubernetes/ptp-introduction-d981dd710bda.rst Normal file
View File

@ -0,0 +1,98 @@
.. _ptp-introduction-d981dd710bda:
================
PTP Introduction
================
As an alternative to |NTP| services, |PTP| can be used by |prod| nodes to
synchronize clocks in a network. It provides:
* more accurate clock synchronization
* the ability to extend the clock synchronization, not only to |prod| hosts
(controllers, workers, and storage nodes), but also to hosted applications
on |prod| hosts.
When used in conjunction with hardware support on the |OAM| and Management
network interface cards, |PTP| is capable of sub-microsecond accuracy. |prod|
supports the configuration of three services that are used for various |PTP|
configurations: ``ptp4l``, ``phc2sys`` and ``ts2phc``.
|prod| also supports a 'clock' service is used to manage specific NIC
parameters related to Synchronous Ethernet (SyncE) and Pulse Per Second (PPS)
support. Please see :ref:`gnss-and-synce-support-62004dc97f3e` for information
on the 'clock' service. The ``ptp4l``, ``phc2sys`` and ``ts2phc`` services are
part of the linuxptp project (https://sourceforge.net/projects/linuxptp/).
``ptp4l``
ptp4l is the implementation of Precision Time Protocol according to the IEEE
standard 1588 for Linux. It handles communication between |PTP| nodes as
well as setting the |PTP| Hardware Clock (PHC) on the NIC. See man ptp4l for
a complete list of configuration parameters.
``phc2sys``
phc2sys is used to synchronize the system time with a PHC. The PHC may be
set by either ``ptp4l`` or ``ts2phc``, depending on the system
configuration. Refer to the man pages (:command:`man phc2sys`) for a
complete list of configuration parameters.
``ts2phc``
ts2phc synchronizes |PTP| Hardware Clocks (PHC) to external time stamp
signals, such as those coming from GNSS. A single source may be used to
distribute time to one or more PHC devices. Refer to the man pages
(:command:`man ts2phc`) for a complete list of configuration parameters.
Overview of the |prod| configuration units
==========================================
* Instances
* Each instance represents a service of type ``ptp4l``, ``phc2sys`` or
``ts2phc``. There may be multiple instances of each type of service
depending on the required configuration.
* Interfaces
* An interface is assigned to an instance. One or more physical ports on a
system may be assigned to an interface. Assigning multiple ports to the
same interface allows for them to share the same configuration.
* Parameters
* Parameters are key/value pairs that represent various program options. The
key should exactly match an option from one of the service man pages, but
this is not enforced. It is possible to enter invalid parameters which
could prevent a service from starting.
* Parameters are scoped to an instance or an interface. The commands system
ptp-instance-parameter-add and system ptp-interface-parameter-add are used
to assign these respectively.
* A special instance level parameter called ``cmdline_opts`` is provided to
allow certain parameters to be set which do not have a long name option
supported in the configuration file.
General information
===================
The relevant system locations for |PTP| instance configuration files are:
``/etc/ptpinstance/``
Application configuration files, one per instance (excluding clock type).
``/etc/sysconfig/ptpinstance``
Environment variable files, one per instance
``/etc/systemd/system/ptpinstance/``
systemd service files, one per instance type (excluding clock type).
``/var/log/user.log``
log output for |PTP| instance services.
Instances provide several default parameters that can be overwritten by
setting a parameter with the same key.
|org| recommends using the :command:`system ptp-instance-apply`` command to
validate your configuration prior to performing any system host-lock/unlock
actions, as a bad |PTP| configuration could result in a configuration
failure and trigger additional reboots as the system tries to recover.

22
doc/source/system_configuration/kubernetes/ptp-limitations-64338c74b415.rst Normal file
View File

@ -0,0 +1,22 @@
.. _ptp-limitations-64338c74b415:
===============
PTP Limitations
===============
NICs using the Intel ICE NIC driver may report the following in the `ptp4l``
logs, which might coincide with a |PTP| port switching to ``FAULTY`` before
re-initializing.
.. code-block:: none
ptp4l[80330.489]: timed out while polling for tx timestamp
ptp4l[80330.489]: increasing tx_timestamp_timeout may correct this issue, but it is likely caused by a driver bug
This is due to a limitation of the Intel ICE driver. The recommended workaround
is to set the ``tx_timestamp_timeout`` parameter to 700 (ms) in the ``ptp4l``
config.
.. code-block:: none
~(keystone_admin)]$ system ptp-instance-parameter-add ptp-inst1 tx_timestamp_timeout=700

34
doc/source/system_configuration/kubernetes/remove-ptp-configurations-4885c027dfa5.rst Normal file
View File

@ -0,0 +1,34 @@
.. _remove-ptp-configurations-4885c027dfa5:
=========================
Remove PTP Configurations
=========================
Disable a PTP instance
======================
To disable a |PTP| instance without removing any configuration, simply remove
the association with a given host. This can be useful for troubleshooting or
testing different configurations.
#. Remove the host association.
.. code-block::
~(keystone_admin)]$ system host-ptp-instance-remove <hostname> <ptp-instance-name>
#. Apply the configuration.
.. code-block::
~(keystone_admin)]$ system ptp-instance-apply
Remove a PTP Instance
=====================
Instances, interfaces and parameters can all be removed with associated
``-delete`` commands. In some cases, the system will alert that a unit cannot
be deleted because a dependent unit is still associated with it. For example,
a |PTP| instance cannot be deleted if there are still interfaces assigned to
it, so the interfaces must be removed first. In such cases, remove the
dependent unit first.

2
doc/source/updates/kubernetes/index-updates-kub-03d4d10fa0be.rst
View File

@ -136,3 +136,5 @@ Orchestrated Platform component upgrade
orchestration-upgrade-overview
performing-an-orchestrated-upgrade
performing-an-orchestrated-upgrade-using-the-cli