| # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) | |
| --- | |
| name: dpll | |
| doc: DPLL subsystem. | |
| definitions: | |
| - | |
| type: enum | |
| name: mode | |
| doc: | | |
| working modes a dpll can support, differentiates if and how dpll selects | |
| one of its inputs to syntonize with it, valid values for DPLL_A_MODE | |
| attribute | |
| entries: | |
| - | |
| name: manual | |
| doc: input can be only selected by sending a request to dpll | |
| value: 1 | |
| - | |
| name: automatic | |
| doc: highest prio input pin auto selected by dpll | |
| render-max: true | |
| - | |
| type: enum | |
| name: lock-status | |
| doc: | | |
| provides information of dpll device lock status, valid values for | |
| DPLL_A_LOCK_STATUS attribute | |
| entries: | |
| - | |
| name: unlocked | |
| doc: | | |
| dpll was not yet locked to any valid input (or forced by setting | |
| DPLL_A_MODE to DPLL_MODE_DETACHED) | |
| value: 1 | |
| - | |
| name: locked | |
| doc: | | |
| dpll is locked to a valid signal, but no holdover available | |
| - | |
| name: locked-ho-acq | |
| doc: | | |
| dpll is locked and holdover acquired | |
| - | |
| name: holdover | |
| doc: | | |
| dpll is in holdover state - lost a valid lock or was forced | |
| by disconnecting all the pins (latter possible only | |
| when dpll lock-state was already DPLL_LOCK_STATUS_LOCKED_HO_ACQ, | |
| if dpll lock-state was not DPLL_LOCK_STATUS_LOCKED_HO_ACQ, the | |
| dpll's lock-state shall remain DPLL_LOCK_STATUS_UNLOCKED) | |
| render-max: true | |
| - | |
| type: enum | |
| name: lock-status-error | |
| doc: | | |
| if previous status change was done due to a failure, this provides | |
| information of dpll device lock status error. | |
| Valid values for DPLL_A_LOCK_STATUS_ERROR attribute | |
| entries: | |
| - | |
| name: none | |
| doc: | | |
| dpll device lock status was changed without any error | |
| value: 1 | |
| - | |
| name: undefined | |
| doc: | | |
| dpll device lock status was changed due to undefined error. | |
| Driver fills this value up in case it is not able | |
| to obtain suitable exact error type. | |
| - | |
| name: media-down | |
| doc: | | |
| dpll device lock status was changed because of associated | |
| media got down. | |
| This may happen for example if dpll device was previously | |
| locked on an input pin of type PIN_TYPE_SYNCE_ETH_PORT. | |
| - | |
| name: fractional-frequency-offset-too-high | |
| doc: | | |
| the FFO (Fractional Frequency Offset) between the RX and TX | |
| symbol rate on the media got too high. | |
| This may happen for example if dpll device was previously | |
| locked on an input pin of type PIN_TYPE_SYNCE_ETH_PORT. | |
| render-max: true | |
| - | |
| type: enum | |
| name: clock-quality-level | |
| doc: | | |
| level of quality of a clock device. This mainly applies when | |
| the dpll lock-status is DPLL_LOCK_STATUS_HOLDOVER. | |
| The current list is defined according to the table 11-7 contained | |
| in ITU-T G.8264/Y.1364 document. One may extend this list freely | |
| by other ITU-T defined clock qualities, or different ones defined | |
| by another standardization body (for those, please use | |
| different prefix). | |
| entries: | |
| - | |
| name: itu-opt1-prc | |
| value: 1 | |
| - | |
| name: itu-opt1-ssu-a | |
| - | |
| name: itu-opt1-ssu-b | |
| - | |
| name: itu-opt1-eec1 | |
| - | |
| name: itu-opt1-prtc | |
| - | |
| name: itu-opt1-eprtc | |
| - | |
| name: itu-opt1-eeec | |
| - | |
| name: itu-opt1-eprc | |
| render-max: true | |
| - | |
| type: const | |
| name: temp-divider | |
| value: 1000 | |
| doc: | | |
| temperature divider allowing userspace to calculate the | |
| temperature as float with three digit decimal precision. | |
| Value of (DPLL_A_TEMP / DPLL_TEMP_DIVIDER) is integer part of | |
| temperature value. | |
| Value of (DPLL_A_TEMP % DPLL_TEMP_DIVIDER) is fractional part of | |
| temperature value. | |
| - | |
| type: enum | |
| name: type | |
| doc: type of dpll, valid values for DPLL_A_TYPE attribute | |
| entries: | |
| - | |
| name: pps | |
| doc: dpll produces Pulse-Per-Second signal | |
| value: 1 | |
| - | |
| name: eec | |
| doc: dpll drives the Ethernet Equipment Clock | |
| - | |
| name: generic | |
| doc: generic dpll type for devices outside PPS/EEC classes | |
| render-max: true | |
| - | |
| type: enum | |
| name: pin-type | |
| doc: | | |
| defines possible types of a pin, valid values for DPLL_A_PIN_TYPE | |
| attribute | |
| entries: | |
| - | |
| name: mux | |
| doc: aggregates another layer of selectable pins | |
| value: 1 | |
| - | |
| name: ext | |
| doc: external input | |
| - | |
| name: synce-eth-port | |
| doc: ethernet port PHY's recovered clock | |
| - | |
| name: int-oscillator | |
| doc: device internal oscillator | |
| - | |
| name: gnss | |
| doc: GNSS recovered clock | |
| - | |
| name: int-nco | |
| doc: | | |
| Device internal numerically controlled oscillator. | |
| When connected as a DPLL input, the DPLL enters NCO mode | |
| where the output frequency is adjusted by the host via | |
| the PTP clock interface. | |
| render-max: true | |
| - | |
| type: enum | |
| name: pin-direction | |
| doc: | | |
| defines possible direction of a pin, valid values for | |
| DPLL_A_PIN_DIRECTION attribute | |
| entries: | |
| - | |
| name: input | |
| doc: pin used as a input of a signal | |
| value: 1 | |
| - | |
| name: output | |
| doc: pin used to output the signal | |
| render-max: true | |
| - | |
| type: const | |
| name: pin-frequency-1-hz | |
| value: 1 | |
| - | |
| type: const | |
| name: pin-frequency-10-khz | |
| value: 10000 | |
| - | |
| type: const | |
| name: pin-frequency-77-5-khz | |
| value: 77500 | |
| - | |
| type: const | |
| name: pin-frequency-10-mhz | |
| value: 10000000 | |
| - | |
| type: enum | |
| name: pin-state | |
| doc: | | |
| defines possible states of a pin, valid values for | |
| DPLL_A_PIN_STATE attribute | |
| entries: | |
| - | |
| name: connected | |
| doc: pin connected, active input of phase locked loop | |
| value: 1 | |
| - | |
| name: disconnected | |
| doc: pin disconnected, not considered as a valid input | |
| - | |
| name: selectable | |
| doc: pin enabled for automatic input selection | |
| render-max: true | |
| - | |
| type: enum | |
| name: pin-operstate | |
| doc: | | |
| defines possible operational states of a pin with respect to its | |
| parent DPLL device, valid values for DPLL_A_PIN_OPERSTATE attribute | |
| entries: | |
| - | |
| name: active | |
| doc: pin is qualified and actively used by the DPLL | |
| value: 1 | |
| - | |
| name: standby | |
| doc: pin is qualified but not actively used by the DPLL | |
| - | |
| name: no-signal | |
| doc: pin does not have a valid signal | |
| - | |
| name: qual-failed | |
| doc: pin signal failed qualification (e.g. frequency or phase monitor) | |
| render-max: true | |
| - | |
| type: flags | |
| name: pin-capabilities | |
| doc: | | |
| defines possible capabilities of a pin, valid flags on | |
| DPLL_A_PIN_CAPABILITIES attribute | |
| entries: | |
| - | |
| name: direction-can-change | |
| doc: pin direction can be changed | |
| - | |
| name: priority-can-change | |
| doc: pin priority can be changed | |
| - | |
| name: state-can-change | |
| doc: pin state can be changed | |
| - | |
| name: state-connected-override | |
| doc: | | |
| pin state can be set to connected regardless of current | |
| DPLL device mode, overriding the active input selection. | |
| Requires state-can-change to be set as well. | |
| - | |
| type: const | |
| name: phase-offset-divider | |
| value: 1000 | |
| doc: | | |
| phase offset divider allows userspace to calculate a value of | |
| measured signal phase difference between a pin and dpll device | |
| as a fractional value with three digit decimal precision. | |
| Value of (DPLL_A_PHASE_OFFSET / DPLL_PHASE_OFFSET_DIVIDER) is an | |
| integer part of a measured phase offset value. | |
| Value of (DPLL_A_PHASE_OFFSET % DPLL_PHASE_OFFSET_DIVIDER) is a | |
| fractional part of a measured phase offset value. | |
| - | |
| type: const | |
| name: pin-measured-frequency-divider | |
| value: 1000 | |
| doc: | | |
| pin measured frequency divider allows userspace to calculate | |
| a value of measured input frequency as a fractional value with | |
| three digit decimal precision (millihertz). | |
| Value of (DPLL_A_PIN_MEASURED_FREQUENCY / | |
| DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is an integer part of | |
| a measured frequency value. | |
| Value of (DPLL_A_PIN_MEASURED_FREQUENCY % | |
| DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is a fractional part of | |
| a measured frequency value. | |
| - | |
| type: enum | |
| name: feature-state | |
| doc: | | |
| Allow control (enable/disable) and status checking over features. | |
| entries: | |
| - | |
| name: disable | |
| doc: | | |
| feature shall be disabled | |
| - | |
| name: enable | |
| doc: | | |
| feature shall be enabled | |
| attribute-sets: | |
| - | |
| name: dpll | |
| enum-name: dpll_a | |
| attributes: | |
| - | |
| name: id | |
| type: u32 | |
| - | |
| name: module-name | |
| type: string | |
| - | |
| name: pad | |
| type: pad | |
| - | |
| name: clock-id | |
| type: u64 | |
| - | |
| name: mode | |
| type: u32 | |
| enum: mode | |
| - | |
| name: mode-supported | |
| type: u32 | |
| enum: mode | |
| multi-attr: true | |
| - | |
| name: lock-status | |
| type: u32 | |
| enum: lock-status | |
| - | |
| name: temp | |
| type: s32 | |
| - | |
| name: type | |
| type: u32 | |
| enum: type | |
| - | |
| name: lock-status-error | |
| type: u32 | |
| enum: lock-status-error | |
| - | |
| name: clock-quality-level | |
| type: u32 | |
| enum: clock-quality-level | |
| multi-attr: true | |
| doc: | | |
| Level of quality of a clock device. This mainly applies when | |
| the dpll lock-status is DPLL_LOCK_STATUS_HOLDOVER. This could | |
| be put to message multiple times to indicate possible parallel | |
| quality levels (e.g. one specified by ITU option 1 and another | |
| one specified by option 2). | |
| - | |
| name: phase-offset-monitor | |
| type: u32 | |
| enum: feature-state | |
| doc: Receive or request state of phase offset monitor feature. | |
| If enabled, dpll device shall monitor and notify all currently | |
| available inputs for changes of their phase offset against the | |
| dpll device. | |
| - | |
| name: phase-offset-avg-factor | |
| type: u32 | |
| doc: Averaging factor applied to calculation of reported phase offset. | |
| - | |
| name: frequency-monitor | |
| type: u32 | |
| enum: feature-state | |
| doc: Current or desired state of the frequency monitor feature. | |
| If enabled, dpll device shall measure all currently available | |
| inputs for their actual input frequency. | |
| - | |
| name: pin | |
| enum-name: dpll_a_pin | |
| attributes: | |
| - | |
| name: id | |
| type: u32 | |
| - | |
| name: parent-id | |
| type: u32 | |
| - | |
| name: module-name | |
| type: string | |
| - | |
| name: pad | |
| type: pad | |
| - | |
| name: clock-id | |
| type: u64 | |
| - | |
| name: board-label | |
| type: string | |
| - | |
| name: panel-label | |
| type: string | |
| - | |
| name: package-label | |
| type: string | |
| - | |
| name: type | |
| type: u32 | |
| enum: pin-type | |
| - | |
| name: direction | |
| type: u32 | |
| enum: pin-direction | |
| - | |
| name: frequency | |
| type: u64 | |
| - | |
| name: frequency-supported | |
| type: nest | |
| multi-attr: true | |
| nested-attributes: frequency-range | |
| - | |
| name: frequency-min | |
| type: u64 | |
| - | |
| name: frequency-max | |
| type: u64 | |
| - | |
| name: prio | |
| type: u32 | |
| - | |
| name: state | |
| type: u32 | |
| enum: pin-state | |
| - | |
| name: capabilities | |
| type: u32 | |
| enum: pin-capabilities | |
| - | |
| name: parent-device | |
| type: nest | |
| multi-attr: true | |
| nested-attributes: pin-parent-device | |
| - | |
| name: parent-pin | |
| type: nest | |
| multi-attr: true | |
| nested-attributes: pin-parent-pin | |
| - | |
| name: phase-adjust-min | |
| type: s32 | |
| - | |
| name: phase-adjust-max | |
| type: s32 | |
| - | |
| name: phase-adjust | |
| type: s32 | |
| - | |
| name: phase-offset | |
| type: s64 | |
| - | |
| name: fractional-frequency-offset | |
| type: sint | |
| doc: | | |
| The FFO (Fractional Frequency Offset) of the pin. | |
| At top level this represents the RX vs TX symbol rate | |
| offset on the media associated with the pin. Inside | |
| the pin-parent-device nest it represents the frequency | |
| offset between the pin and its parent DPLL device. | |
| For pins of type PIN_TYPE_INT_NCO this represents | |
| the DPLL's current output frequency offset from its | |
| nominal frequency. | |
| Value is in PPM (parts per million). | |
| This is a lower-precision version of | |
| fractional-frequency-offset-ppt. | |
| - | |
| name: esync-frequency | |
| type: u64 | |
| doc: | | |
| Frequency of Embedded SYNC signal. If provided, the pin is configured | |
| with a SYNC signal embedded into its base clock frequency. | |
| - | |
| name: esync-frequency-supported | |
| type: nest | |
| multi-attr: true | |
| nested-attributes: frequency-range | |
| doc: | | |
| If provided a pin is capable of embedding a SYNC signal (within given | |
| range) into its base frequency signal. | |
| - | |
| name: esync-pulse | |
| type: u32 | |
| doc: | | |
| A ratio of high to low state of a SYNC signal pulse embedded | |
| into base clock frequency. Value is in percents. | |
| - | |
| name: reference-sync | |
| type: nest | |
| multi-attr: true | |
| nested-attributes: reference-sync | |
| doc: | | |
| Capable pin provides list of pins that can be bound to create a | |
| reference-sync pin pair. | |
| - | |
| name: phase-adjust-gran | |
| type: u32 | |
| doc: | | |
| Granularity of phase adjustment, in picoseconds. The value of | |
| phase adjustment must be a multiple of this granularity. | |
| - | |
| name: fractional-frequency-offset-ppt | |
| type: sint | |
| doc: | | |
| The FFO (Fractional Frequency Offset) of the pin. | |
| At top level this represents the RX vs TX symbol rate | |
| offset on the media associated with the pin. Inside | |
| the pin-parent-device nest it represents the frequency | |
| offset between the pin and its parent DPLL device. | |
| For pins of type PIN_TYPE_INT_NCO this represents | |
| the DPLL's current output frequency offset from its | |
| nominal frequency. | |
| Value is in PPT (parts per trillion, 10^-12). | |
| This is a higher-precision version of | |
| fractional-frequency-offset. | |
| - | |
| name: measured-frequency | |
| type: u64 | |
| doc: | | |
| The measured frequency of the input pin in millihertz (mHz). | |
| Value of (DPLL_A_PIN_MEASURED_FREQUENCY / | |
| DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is an integer part (Hz) | |
| of a measured frequency value. | |
| Value of (DPLL_A_PIN_MEASURED_FREQUENCY % | |
| DPLL_PIN_MEASURED_FREQUENCY_DIVIDER) is a fractional part | |
| of a measured frequency value. | |
| - | |
| name: operstate | |
| type: u32 | |
| enum: pin-operstate | |
| doc: | | |
| Operational state of the pin with respect to its parent DPLL | |
| device. Unlike state (which reflects the administrative intent), | |
| operstate reflects the actual hardware status. | |
| - | |
| name: pin-parent-device | |
| subset-of: pin | |
| attributes: | |
| - | |
| name: parent-id | |
| - | |
| name: direction | |
| - | |
| name: prio | |
| - | |
| name: state | |
| - | |
| name: operstate | |
| - | |
| name: phase-offset | |
| - | |
| name: fractional-frequency-offset | |
| - | |
| name: fractional-frequency-offset-ppt | |
| - | |
| name: pin-parent-pin | |
| subset-of: pin | |
| attributes: | |
| - | |
| name: parent-id | |
| - | |
| name: state | |
| - | |
| name: frequency-range | |
| subset-of: pin | |
| attributes: | |
| - | |
| name: frequency-min | |
| - | |
| name: frequency-max | |
| - | |
| name: reference-sync | |
| subset-of: pin | |
| attributes: | |
| - | |
| name: id | |
| - | |
| name: state | |
| operations: | |
| enum-name: dpll_cmd | |
| list: | |
| - | |
| name: device-id-get | |
| doc: | | |
| Get id of dpll device that matches given attributes | |
| attribute-set: dpll | |
| flags: [admin-perm] | |
| do: | |
| pre: dpll-lock-doit | |
| post: dpll-unlock-doit | |
| request: | |
| attributes: | |
| - module-name | |
| - clock-id | |
| - type | |
| reply: | |
| attributes: | |
| - id | |
| - | |
| name: device-get | |
| doc: | | |
| Get list of DPLL devices (dump) or attributes of a single dpll device | |
| attribute-set: dpll | |
| flags: [admin-perm] | |
| do: | |
| pre: dpll-pre-doit | |
| post: dpll-post-doit | |
| request: | |
| attributes: | |
| - id | |
| reply: &dev-attrs | |
| attributes: | |
| - id | |
| - module-name | |
| - mode | |
| - mode-supported | |
| - lock-status | |
| - lock-status-error | |
| - temp | |
| - clock-id | |
| - type | |
| - phase-offset-monitor | |
| - phase-offset-avg-factor | |
| - frequency-monitor | |
| dump: | |
| reply: *dev-attrs | |
| - | |
| name: device-set | |
| doc: Set attributes for a DPLL device | |
| attribute-set: dpll | |
| flags: [admin-perm] | |
| do: | |
| pre: dpll-pre-doit | |
| post: dpll-post-doit | |
| request: | |
| attributes: | |
| - id | |
| - mode | |
| - phase-offset-monitor | |
| - phase-offset-avg-factor | |
| - frequency-monitor | |
| - | |
| name: device-create-ntf | |
| doc: Notification about device appearing | |
| notify: device-get | |
| mcgrp: monitor | |
| - | |
| name: device-delete-ntf | |
| doc: Notification about device disappearing | |
| notify: device-get | |
| mcgrp: monitor | |
| - | |
| name: device-change-ntf | |
| doc: Notification about device configuration being changed | |
| notify: device-get | |
| mcgrp: monitor | |
| - | |
| name: pin-id-get | |
| doc: | | |
| Get id of a pin that matches given attributes | |
| attribute-set: pin | |
| flags: [admin-perm] | |
| do: | |
| pre: dpll-lock-doit | |
| post: dpll-unlock-doit | |
| request: | |
| attributes: | |
| - module-name | |
| - clock-id | |
| - board-label | |
| - panel-label | |
| - package-label | |
| - type | |
| reply: | |
| attributes: | |
| - id | |
| - | |
| name: pin-get | |
| doc: | | |
| Get list of pins and its attributes. | |
| - dump request without any attributes given - list all the pins in the | |
| system | |
| - dump request with target dpll - list all the pins registered with | |
| a given dpll device | |
| - do request with target dpll and target pin - single pin attributes | |
| attribute-set: pin | |
| flags: [admin-perm] | |
| do: | |
| pre: dpll-pin-pre-doit | |
| post: dpll-pin-post-doit | |
| request: | |
| attributes: | |
| - id | |
| reply: &pin-attrs | |
| attributes: | |
| - id | |
| - module-name | |
| - clock-id | |
| - board-label | |
| - panel-label | |
| - package-label | |
| - type | |
| - frequency | |
| - frequency-supported | |
| - capabilities | |
| - parent-device | |
| - parent-pin | |
| - phase-adjust-gran | |
| - phase-adjust-min | |
| - phase-adjust-max | |
| - phase-adjust | |
| - fractional-frequency-offset | |
| - fractional-frequency-offset-ppt | |
| - esync-frequency | |
| - esync-frequency-supported | |
| - esync-pulse | |
| - reference-sync | |
| - measured-frequency | |
| dump: | |
| request: | |
| attributes: | |
| - id | |
| reply: *pin-attrs | |
| - | |
| name: pin-set | |
| doc: Set attributes of a target pin | |
| attribute-set: pin | |
| flags: [admin-perm] | |
| do: | |
| pre: dpll-pin-pre-doit | |
| post: dpll-pin-post-doit | |
| request: | |
| attributes: | |
| - id | |
| - frequency | |
| - direction | |
| - prio | |
| - state | |
| - parent-device | |
| - parent-pin | |
| - phase-adjust | |
| - esync-frequency | |
| - reference-sync | |
| - | |
| name: pin-create-ntf | |
| doc: Notification about pin appearing | |
| notify: pin-get | |
| mcgrp: monitor | |
| - | |
| name: pin-delete-ntf | |
| doc: Notification about pin disappearing | |
| notify: pin-get | |
| mcgrp: monitor | |
| - | |
| name: pin-change-ntf | |
| doc: Notification about pin configuration being changed | |
| notify: pin-get | |
| mcgrp: monitor | |
| mcast-groups: | |
| list: | |
| - | |
| name: monitor |