From 06bb6c1703c65878f02c8877f3b8eeca0abbb35f Mon Sep 17 00:00:00 2001 From: aireilly Date: Thu, 20 Jul 2023 13:08:18 +0100 Subject: [PATCH] updates for ptp operator plugin --- ...inuxptp-services-as-grandmaster-clock.adoc | 10 +- ...specific-nic-plugins-for-ptp-operator.adoc | 95 +++++++++ ...-using-hardware-specific-nic-features.adoc | 16 ++ networking/using-ptp.adoc | 6 + snippets/ptp-PtpConfigGmWpc.yaml | 192 ++++++++++++++++++ 5 files changed, 316 insertions(+), 3 deletions(-) create mode 100644 modules/ptp-creating-hardware-specific-nic-plugins-for-ptp-operator.adoc create mode 100644 modules/ptp-using-hardware-specific-nic-features.adoc create mode 100644 snippets/ptp-PtpConfigGmWpc.yaml diff --git a/modules/nw-ptp-configuring-linuxptp-services-as-grandmaster-clock.adoc b/modules/nw-ptp-configuring-linuxptp-services-as-grandmaster-clock.adoc index d8d1f7833833..1704d12f0bdc 100644 --- a/modules/nw-ptp-configuring-linuxptp-services-as-grandmaster-clock.adoc +++ b/modules/nw-ptp-configuring-linuxptp-services-as-grandmaster-clock.adoc @@ -12,8 +12,8 @@ The `ts2phc` utility allows you to synchronize the system clock with the PTP gra [NOTE] ==== -Use the following example `PtpConfig` CR as the basis to configure `linuxptp` services as the grandmaster clock for your particular hardware and environment. -This example CR does not configure PTP fast events. To configure PTP fast events, set appropriate values for `ptp4lOpts`, `ptp4lConf`, and `ptpClockThreshold`. +Use the following example `PtpConfig` CR as the basis to configure `linuxptp` services as the grandmaster clock for an Intel Westport Channel E810 network interface. +To configure PTP fast events, set appropriate values for `ptp4lOpts`, `ptp4lConf`, and `ptpClockThreshold`. `ptpClockThreshold` is used only when events are enabled. See "Configuring the PTP fast event notifications publisher" for more information. ==== @@ -34,7 +34,11 @@ See "Configuring the PTP fast event notifications publisher" for more informatio .. Save the following YAML in the `grandmaster-clock-ptp-config.yaml` file: + -include::snippets/grandmaster-clock-ptp-config.adoc[] +.Recommended PTP grandmaster clock configuration +[source,yaml] +---- +include::snippets/ptp-PtpConfigGmWpc.yaml[] +---- .. Create the CR by running the following command: + diff --git a/modules/ptp-creating-hardware-specific-nic-plugins-for-ptp-operator.adoc b/modules/ptp-creating-hardware-specific-nic-plugins-for-ptp-operator.adoc new file mode 100644 index 000000000000..5d70259a322f --- /dev/null +++ b/modules/ptp-creating-hardware-specific-nic-plugins-for-ptp-operator.adoc @@ -0,0 +1,95 @@ +// Module included in the following assemblies: +// +// * networking/using-ptp.adoc + +:_content-type: PROCEDURE +[id="ptp-creating-hardware-specific-nic-plugins-for-ptp-operator_{context}"] += Creating hardware-specific NIC plugins for use with the PTP Operator + +You can use hardware-specific NIC features with the PTP Operator by using specific hardware plugins in the `PtpConfig` custom resource (CR). + +At a high level, the hardware plugin that you create does the following: + +. Defines a set of Go structs and variables for the data types that you create + +. Has a set of functions that configure the specific hardware based on values present in the `spec.profile.plugins` stanza of the `PtpCOnfig` custom resource (CR) that you deploy in the cluster + +. TODO + +[NOTE] +==== +For {product-title} {product-version}, the PTP Operator provides a plugin for the Intel E810 Westport channel NIC card. +==== + +// https://github.com/k8snetworkplumbingwg/ptp-operator/blob/master/linuxptp-daemon/addons/intel/e810.go + +.Prerequisites + +* You have forked and cloned the link:https://github.com/k8snetworkplumbingwg/ptp-operator[k8snetworkplumbingwg/ptp-operator] repo. + +* You have a list of specific NIC features that you want to configure. + +.Procedure + +. Open a shell prompt at the `/linuxptp-daemon` folder and create a new plugin folder for the NIC manufacturer under `/addons`. For example: ++ +[source,terminal] +---- +$ mkdir -p addons/intel +---- + +. Create the configuration for the hardware plugin. For example, the following Go code defines a plugin for handling PTP configuration for Intel E810 Westport Channel NIC: ++ +[source,go] +---- +include::https://raw.githubusercontent.com/openshift/linuxptp-daemon/release-4.14/addons/intel/e810.go[] +---- + +.E810 plugin structs and variables +[cols=2*, width="90%", options="header"] +|==== +|Struct +|Description + +|`E810Opts` +|Represents options for the E810 plugin, including boolean flags and a map of network device pins. + +|`E810UblxCmds` +|Represents configurations for `ubxtool` commands with a boolean flag and a slice of strings for command arguments. + +|`E810PluginData` +|Holds plugin-specific data used during plugin execution. + +|`EnableE810PTPConfig` +|Variable that has a script to configure pins on the NIC hardware. +|==== + +.E810 plugin functions +[cols=2*, width="90%", options="header"] +|==== +|Function +|Description + +|`OnPTPConfigChangeE810` +|Triggered when a change in the PTP configuration occurs. The function parses the plugin options and applies the required configurations to the network device pins based on the configuration data. + +|`AfterRunPTPCommandE810` +|Executed after running the `gpspipe` PTP command. It processes the plugin options and runs u-blox commands, storing the output in the plugin-specific data. + +|`PopulateHwConfigE810` +|Populates the hardware configuration data with E810-related information and status based on the plugin-specific data. + +|`E810` +|Creates and returns an instance of the E810 plugin. It registers the plugin with the required event handlers and initializes the plugin-specific data. +|==== + +. Commit your changes and have your pull request reviewed and merged. + +. ... + +//How does the PR get merged, and how does the linuxptp daemon get into the PTP Operator? Does the customer have to use a custom version of the PTP Operator? + +.Verification +//Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure. + +Verify that your custom plugin has been deployed in the PTP Operator and the NIC hardware has been configured. diff --git a/modules/ptp-using-hardware-specific-nic-features.adoc b/modules/ptp-using-hardware-specific-nic-features.adoc new file mode 100644 index 000000000000..f5359fd79642 --- /dev/null +++ b/modules/ptp-using-hardware-specific-nic-features.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * networking/using-ptp.adoc + +:_content-type: CONCEPT +[id="ptp-using-hardware-specific-nic-features_{context}"] += Using hardware-specific NIC features with the PTP Operator + +NIC hardware with built-in PTP capabilities sometimes require device-specific configuration. +You can use hardware-specific NIC features for supported hardware with the PTP Operator by configuring a plugin in the `PtpConfig` custom resource (CR). +The `linuxptp-daemon` uses the named parameters in the `plugin` stanza to start `linuxptp` processes (`ptp4l` and `phc2sys`) based on the specific hardware configuration. + +[IMPORTANT] +==== +In {product-title} {product-version}, the Intel E810 NIC is supported with a `PtpConfig` plugin. +==== diff --git a/networking/using-ptp.adoc b/networking/using-ptp.adoc index 26646b2189d0..240f2f6a30aa 100644 --- a/networking/using-ptp.adoc +++ b/networking/using-ptp.adoc @@ -39,6 +39,7 @@ include::modules/nw-ptp-installing-operator-cli.adoc[leveloffset=+1] include::modules/nw-ptp-installing-operator-web-console.adoc[leveloffset=+1] +[id="configuring-ptp-hardware"] == Configuring PTP devices The PTP Operator adds the `NodePtpDevice.ptp.openshift.io` custom resource definition (CRD) to {product-title}. @@ -47,6 +48,10 @@ When installed, the PTP Operator searches your cluster for PTP-capable network d include::modules/nw-ptp-device-discovery.adoc[leveloffset=+2] +include::modules/ptp-using-hardware-specific-nic-features.adoc[leveloffset=+2] + +include::modules/ptp-creating-hardware-specific-nic-plugins-for-ptp-operator.adoc[leveloffset=+3] + include::modules/nw-ptp-configuring-linuxptp-services-as-grandmaster-clock.adoc[leveloffset=+2] [role="_additional-resources"] @@ -89,6 +94,7 @@ include::modules/cnf-configuring-log-filtering-for-linuxptp.adoc[leveloffset=+2] include::modules/cnf-troubleshooting-common-ptp-operator-issues.adoc[leveloffset=+1] +[id="ptp-hardware-fast-event-notifications-framework"] == PTP hardware fast event notifications framework Cloud native applications such as virtual RAN (vRAN) require access to notifications about hardware timing events that are critical to the functioning of the overall network. diff --git a/snippets/ptp-PtpConfigGmWpc.yaml b/snippets/ptp-PtpConfigGmWpc.yaml new file mode 100644 index 000000000000..a86e2805e561 --- /dev/null +++ b/snippets/ptp-PtpConfigGmWpc.yaml @@ -0,0 +1,192 @@ +apiVersion: ptp.openshift.io/v1 +kind: PtpConfig +metadata: + name: grandmaster + namespace: openshift-ptp +spec: + profile: + - name: "grandmaster" + ptp4lOpts: "-2 --summary_interval -4" + phc2sysOpts: -r -u 0 -m -O -37 -N 8 -R 16 -s $iface_master -n 24 + ptpSchedulingPolicy: SCHED_FIFO + ptpSchedulingPriority: 10 + ptpSettings: + logReduce: "true" + plugins: + e810: + enableDefaultConfig: false + pins: + "ens2f1": + "U.FL2": "0 2" + "U.FL1": "0 1" + "SMA2": "0 2" + "SMA1": "0 1" + ublxCmds: + - args: + - "-P" + - "29.20" + - "-z" + - "CFG-HW-ANT_CFG_VOLTCTRL,1" + reportOutput: false + - args: + - "-P" + - "29.20" + - "-e" + - "GPS" + reportOutput: false + - args: + - "-P" + - "29.20" + - "-e" + - "Galileo" + reportOutput: false + - args: + - "-P" + - "29.20" + - "-d" + - "GLONASS" + reportOutput: false + - args: + - "-P" + - "29.20" + - "-d" + - "BeiDou" + reportOutput: false + - args: + - "-P" + - "29.20" + - "-d" + - "SBAS" + reportOutput: false + - args: + - "-p" + - "MON-HW" + reportOutput: true + ts2phcOpts: " " + ts2phcConf: | + [nmea] + ts2phc.master 1 + [global] + use_syslog 0 + verbose 1 + logging_level 7 + ts2phc.pulsewidth 100000000 + #GNSS module - ls /dev/gnss* -al + ts2phc.nmea_serialport /dev/gnss0 + leapfile /usr/share/zoneinfo/leap-seconds.list + [ens2f1] + ts2phc.extts_polarity rising + ts2phc.extts_correction 0 + ptp4lConf: | + [ens2f1] + masterOnly 1 + [ens2f2] + masterOnly 1 + [ens2f3] + masterOnly 1 + [ens2f3] + masterOnly 1 + [global] + # + # Default Data Set + # + twoStepFlag 1 + priority1 128 + priority2 128 + domainNumber 24 + #utc_offset 37 + clockClass 6 + clockAccuracy 0x27 + offsetScaledLogVariance 0xFFFF + free_running 0 + freq_est_interval 1 + dscp_event 0 + dscp_general 0 + dataset_comparison G.8275.x + G.8275.defaultDS.localPriority 128 + # + # Port Data Set + # + logAnnounceInterval -3 + logSyncInterval -4 + logMinDelayReqInterval -4 + logMinPdelayReqInterval 0 + announceReceiptTimeout 3 + syncReceiptTimeout 0 + delayAsymmetry 0 + fault_reset_interval -4 + neighborPropDelayThresh 20000000 + masterOnly 0 + G.8275.portDS.localPriority 128 + # + # Run time options + # + assume_two_step 0 + logging_level 6 + path_trace_enabled 0 + follow_up_info 0 + hybrid_e2e 0 + inhibit_multicast_service 0 + net_sync_monitor 0 + tc_spanning_tree 0 + tx_timestamp_timeout 50 + unicast_listen 0 + unicast_master_table 0 + unicast_req_duration 3600 + use_syslog 1 + verbose 0 + summary_interval -4 + kernel_leap 1 + check_fup_sync 0 + clock_class_threshold 7 + # + # Servo Options + # + pi_proportional_const 0.0 + pi_integral_const 0.0 + pi_proportional_scale 0.0 + pi_proportional_exponent -0.3 + pi_proportional_norm_max 0.7 + pi_integral_scale 0.0 + pi_integral_exponent 0.4 + pi_integral_norm_max 0.3 + step_threshold 2.0 + first_step_threshold 0.00002 + clock_servo pi + sanity_freq_limit 200000000 + ntpshm_segment 0 + # + # Transport options + # + transportSpecific 0x0 + ptp_dst_mac 01:1B:19:00:00:00 + p2p_dst_mac 01:80:C2:00:00:0E + udp_ttl 1 + udp6_scope 0x0E + uds_address /var/run/ptp4l + # + # Default interface options + # + clock_type BC + network_transport L2 + delay_mechanism E2E + time_stamping hardware + tsproc_mode filter + delay_filter moving_median + delay_filter_length 10 + egressLatency 0 + ingressLatency 0 + boundary_clock_jbod 0 + # + # Clock description + # + productDescription ;; + revisionData ;; + manufacturerIdentity 00:00:00 + userDescription ; + timeSource 0x20 + recommend: + - profile: "grandmaster" + priority: 4 + match: + - nodeLabel: "node-role.kubernetes.io/worker"