← Back
Editing: dpll.yaml
# 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 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 - 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. 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. 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
Save File
Cancel