[PATCH net-next v12 00/12] dpll: add SiTime SiT9531x DPLL clock driver

[PATCH net-next v12 00/12] dpll: add SiTime SiT9531x DPLL clock driver

[Ali Rouhi]

This series adds a DPLL subsystem driver for the SiTime SiT95316 and
SiT95317 I2C clock generators. Each device integrates four PLLs with
automatic reference selection and on-chip TDC phase-offset measurement,
and is used for synchronization in telecom, networking, and data-center
timing.

Patch 1 of v11 was applied to net-next as commit 45ad84d2800e
("dt-bindings: dpll: allow hex unit addresses on output pins"). This
series is the remaining twelve patches rebased on it, so the count
falling from thirteen to twelve is this commit. What
is left is the device-tree binding, the driver under
drivers/dpll/sit9531x/, and the MAINTAINERS entry.

v1: https://lore.kernel.org/netdev/20260511211143.19792-1-arouhi@sitime.com/
v2: https://lore.kernel.org/netdev/20260520191943.73938-1-arouhi@sitime.com/
v3: https://lore.kernel.org/netdev/20260731180951.65725-1-arouhi@sitime.com/
v4: https://lore.kernel.org/netdev/20260806232439.27551-1-arouhi@sitime.com/
v5: https://lore.kernel.org/netdev/20260810230439.22866-1-arouhi@sitime.com/
v6: https://lore.kernel.org/netdev/20260812175337.18155-1-arouhi@sitime.com/
v7: https://lore.kernel.org/netdev/20260815221919.64226-1-arouhi@sitime.com/
v8: https://lore.kernel.org/netdev/20260902214030.20955-1-arouhi@sitime.com/
v9: https://lore.kernel.org/netdev/20260915000015.80480-1-arouhi@sitime.com/
v10: https://lore.kernel.org/netdev/20260921201108.42676-1-arouhi@sitime.com/
v11: https://lore.kernel.org/netdev/20260930233714.87679-1-arouhi@sitime.com/

The review of v11 raised fifty-five points across eleven messages.
Forty-three are fixed here, one is fixed in part, and eleven are
answered on the thread. Every fix is folded into the patch that
introduces the code rather than added as a follow-up, so each patch
still reads as the one change it describes. The replies go out with
this series.

  1     bindings: vendor prefix
  2     bindings: the device schema
  3     basic support: paged regmap, variant detection, probe
  4     DPLL types and pin properties from system firmware
  5     register the DPLL devices and pins, and keep their state
  6     input pin state and operational state on a DPLL
  7     input pin priority
  8     pin frequency, both directions
  9     output pin state (mute)
  10    output phase adjust
  11    phase offset through the TDC
  12    the inter-PLL sync net as a pair of pins

The two bindings patches come first, so the driver never matches on a
compatible string before the schema that describes it is in the tree.

Each of the ten driver patches builds and links on its own: no patch
calls something a later patch introduces, so a bisect cannot land on a
tree that fails to compile. That was re-checked for this posting patch
by patch with W=1 and with sparse. checkpatch --strict is clean except
for the "does MAINTAINERS need updating?" hint on patches 4 and 5,
which add files under drivers/dpll/sit9531x/ -- patch 3 already covers
that directory with an F: entry.

Four things are worth reading before the changelog.

The first is that the reporting limitation the v11 cover letter
described is gone.

v11 said that when the device fails over on its own to another source
in its priority table, the registers the driver read did not name the
source it had moved to, so no pin was reported active. The driver now
reads the PLL's debug status bus, which names the source the input
subsystem feeds the PLL. A pin is reported active when the status bus
names it, the PLL is locked to it with its outer loop running and not
frozen, and that lane's monitor reports signal. After an autonomous
failover the pin the PLL moved to reports active and the one it left
reports no signal, so userspace gets identity and not just a change
notification. The status bus names what is fed to the PLL rather than
what the PLL has locked to, which is why the lane monitor has to agree.
It is read only for a PLL that is tracking a reference, six transfers
per such PLL per poll tick.

The second is the one High finding, which was a real bug.

sit9531x_dpll_pin_unregister() cleared a pin's core handle and then
blocked on the DPLL core lock, while the output state setter read that
handle more than a hundred milliseconds of I2C transfers after
validating it, with no NULL test in between. Dereferencing it during
teardown would have oopsed with the core lock held, which takes every
later DPLL netlink call with it. The clear and the read are now a
WRITE_ONCE/READ_ONCE pair and the setter sends no notification when the
handle is gone. The poll's own notifications need no guard: the poll is
cancelled before any pin is unregistered.

The third is an arithmetic trap on the same class of input.

A feedback divider of less than one cycle yields a derived VCO rate
small enough that the picosecond conversions in the phase code and the
TDC path overflow their 64-bit divide, which traps on x86 and returns a
nonsense quotient elsewhere. Such a rate is not a programmed VCO rate
at all, so sit9531x_get_fvco() now reports no data below the low band
and nothing downstream divides by it. Separately, a frequency set
computed against a rate outside the PLL's band is refused with -EINVAL
rather than programmed and reported as success.

The fourth is the binding, which now describes the power supplies.

With unevaluatedProperties: false the schema did not merely omit the
rails, it rejected any board that tried to describe them. The supplies
are named by their pins: vdd-supply for the PLL core rail, vddin-supply
for the input receivers and dividers, vdds-supply for the GPIO rail the
SiT95317 has, and one per output-driver pin -- vddo0 to vddo7 on the
SiT95317, and vddo0_1, vddo2 through vddo9 and vddo10_11 on the
SiT95316, where the two shared pins each power the pair of outputs they
are named after. The variant conditional refuses the names the other
part does not have. The driver does not enable them; the binding gives
a board with switchable rails a way to describe them.

Changes in v12:

  - The active input pin is reported from the device's routed
    reference rather than from the selection the driver last wrote,
    as described above.

  - The priority table commit's error paths. A failed write on a PLL
    whose table was empty keeps the forced holdover rather than
    releasing it and leaving the PLL following a source every pin
    reports disconnected. A forced-holdover write that fails goes to
    the release path instead of returning, because the write may have
    landed. A release that fails after the write and the latch is owed
    and retried from the poll until it lands. A monitor read that
    fails rolls the commit back rather than letting the selection be
    picked from loss-of-signal state that may be a poll period old.
    The rollback restores the register whose write failed as well as
    the ones before it. The configured priority and its known flag are
    saved before the apply and put back when it fails, so nothing
    reports a priority the device never took.

  - A forced holdover the driver did not set -- one found set with a
    non-empty table, so placed by the loaded configuration or by a
    tool -- is left alone by a table write. Only the hold the driver
    itself set for an empty table is released.

  - When the driver forced holdover for an empty table and the device
    has not marked its holdover estimate valid, the lock status is
    UNLOCKED rather than HOLDOVER, which is what the uAPI text asks
    for. Holdover freeze is now tested before the lock bit, matching
    the order the pin-state contract uses.

  - Baselines are taken at registration. The device's lock status and
    each pin's state, operational state and priority are seeded under
    the device lock when the object is registered, rather than by the
    first poll tick, so a change between the probe-time fetch and that
    tick is reported instead of absorbed. The per-pin "seen" flag is
    gone with it.

  - An input the firmware gives no rate for has no frequency attribute
    rather than reporting 0 Hz, through an ops table without the
    getter. The core abandons a whole pin dump on an error from one
    pin, which is why the attribute is left out rather than failed.

  - Output state. A request for the state an output already has reads
    the Hi-Z pair first and returns without entering the programming
    state. A change whose read-back failed is announced as well as one
    whose cached state moved, so a subscriber is not left holding the
    old value.

  - Phase. The fold of a requested delay into one output period is
    counted in VCO cycles modulo the output divider, which is exactly
    the period, instead of modulo a period truncated to whole
    picoseconds; 100 us on a 128 MHz output of a 5.12 GHz VCO now
    folds to zero. The quantizer evaluates one cycle fewer, the floor
    and one cycle more, each with the fine steps capped, so 210 ps at
    5 GHz encodes exactly. A bus error from the divider read fails the
    read-back instead of being treated as "no divider programmed". A
    flush that failed after the delay was committed is remembered in
    its own flag that the setter honors, since the core drops a repeat
    request whose bytes match the cache. A delay the loaded
    configuration left beyond the advertised window is reported
    clamped and not armed, so a later rate change cannot write the
    clamp into the device. A rate change on an output with a
    programmed delay re-times the delay inside the rate change's own
    programming window, one sequence and one flush instead of two of
    each, and when the commit fails after the divider was written an
    armed delay is marked stale.

  - The phase-flush error paths: a failed source select restores the
    original source, a sibling is marked parked before it is cleared,
    and a failed arm disarms rather than unparks. A failed entry into
    the programming state now leaves the device the way a commit
    leaves it rather than issuing a bare loop lock.

  - Phase offset. An output whose cached state is marked stale is read
    back from the device before it counts as driving. The lane
    monitors are read live before the pin is judged active, so a lane
    that lost its clock after the last poll cannot have a sample
    credited to it. The conversion keeps the fraction of a picosecond
    the converter resolves.

  - The inter-PLL sync net. A destination pin whose net no PLL drives
    reports no signal rather than standby, as an external input that
    lost its clock does. A failure of the final per-PLL latch no
    longer restores the global enable, and the rollback of a failed
    enable uses a variant that does not restore it either, so a failed
    enable cannot leave a global bit no PLL owns. A source whose
    enable, rollback and rescan all failed is recorded as a partial
    owner, so a retry re-runs the enable instead of being refused as
    busy. The restore write is followed by the page-0 small update and
    its settle, as every other write to that register is. A failed
    request that moved the owner is announced. Resume re-detects the
    net's owner and reads every output's mute back from the device.

  - Binding. The power supplies, described above. The input pins'
    supported-frequencies-hz now carries a description stating that
    the property names the rate wired to the input, as a single entry;
    maxItems: 1 would have been the stronger form, but dtschema types
    every -hz property as a uint32 matrix, so the example's single
    /bits/ 64 value reads as two cells to the tooling and the
    constraint fails dt_binding_check.

  - Comment and commit-message corrections where the text did not
    describe the code: "qualified" where the predicate means "has
    signal", "only the named pin changes" where the claim is about
    priorities, a retry that named the wrong latch, a kernel-doc that
    promised the advance form of a phase read-back unconditionally,
    and a comment asserting the fine field tops out below one VCO
    period when it does not.

  - Tags. Patch 1 keeps Conor's Acked-by. Rob Herring reviewed the
    device schema as it stood in v11; that patch is 2 here and it has
    changed since, by thirty-eight lines of schema and a commit-message
    paragraph, all of it the power supplies. He has not seen that
    construction, so the tag is not carried and another look would be
    welcome.

Two rounds of changes in this series answer reports from Carolina
Jubran. The probe path that accepts a clock-frequency property when
firmware exposes no oscillator through the clock framework, now patch
3, came from her report against v8; the input-handling work that went
into v10
-- emptying the priority table when the last reference is disconnected,
giving a meaning to every slot code including the input pair this part
does not have, and reporting connected as selected rather than locked
-- came from her report against v9. Both came by private mail. The v10
and v11 cover letters carried this credit, and neither series was taken
into the tree, so it is restated here.

Four items from earlier rounds are unchanged and are repeated so they
are not re-raised.

The selection moves only when the priority table is written. The device
re-runs its own selection when the source it follows loses signal; it
does not notice a table rewrite. Each move the driver makes is a
re-selection, which takes the PLL through holdover and unlocks it for
about ten seconds, so a priority change further down the table, or the
removal of a source the PLL is not on, must not move it. The rule is
therefore to move only when the highest-priority live source is a
different one than before. What that leaves open is the case where the
preferred source recovers, or a newly enabled receiver qualifies after
the pick ran, and nothing re-selects: the device's own revertive
switching returns only to the source the selection register names, so
the driver would have to re-pick from the poll, paying the unlock on a
timer rather than on a request. Whether to take that under AUTOMATIC or
to document the behavior as non-revertive is still open. The commit
message states the rule as implemented and the open point; the
mechanism follows in a later revision.

The phase-adjust granularity stays at 1 ps rather than the 30 ps fine
step. The delays this device can reach are not multiples of 30 ps: a
request is split between a coarse delay counted in VCO cycles and a
three-bit fine field of 30 ps steps, and the two are added, so the
spacing depends on the VCO period in force. Advertising 30 would name a
step the device does not have. A request is accepted at 1 ps and
rounded to the nearest delay the registers can hold, and the getter
reports what they hold rather than what was asked for, so a caller that
needs the exact figure reads it back.

A frequency request of 0 Hz is still refused with -EINVAL rather than
treated as a request to stop the output. Nothing in the ABI says zero
means off, and this device already has a mute control that says so
explicitly.

The u64 truncation in dpll_pin_freq_set() is still there and is still
not ours to fix in this series: the requested frequency is read as a
u64 and validated through a helper that takes a u32, so a rate of
U32_MAX + 1 + N is accepted as N against ranges that are themselves
u64. That affects every driver behind the interface. It will be posted
as its own patch against the core rather than buried here; this driver
range-checks its own input in the meantime.

Ali Rouhi (2):
  dt-bindings: vendor-prefixes: add SiTime Corporation
  dt-bindings: dpll: add SiTime SiT95316 clock generator

Oleg Zadorozhnyi (10):
  dpll: add basic SiTime SiT9531x support
  dpll: sit9531x: read DPLL types and pin properties from system
    firmware
  dpll: sit9531x: register DPLL devices and pins
  dpll: sit9531x: implement input pin state on a DPLL
  dpll: sit9531x: add support to get and set priority on input pins
  dpll: sit9531x: add support to get and set frequency on pins
  dpll: sit9531x: implement output pin state on a DPLL
  dpll: sit9531x: add support to adjust output phase
  dpll: sit9531x: add support to get phase offset on the connected input
    pin
  dpll: sit9531x: model the inter-PLL sync net as a pair of pins

 .../bindings/dpll/sitime,sit95316.yaml        |  213 +
 .../devicetree/bindings/vendor-prefixes.yaml  |    2 +
 MAINTAINERS                                   |    7 +
 drivers/dpll/Kconfig                          |    2 +
 drivers/dpll/Makefile                         |    1 +
 drivers/dpll/sit9531x/Kconfig                 |   17 +
 drivers/dpll/sit9531x/Makefile                |    4 +
 drivers/dpll/sit9531x/core.c                  | 5298 +++++++++++++++++
 drivers/dpll/sit9531x/core.h                  |  453 ++
 drivers/dpll/sit9531x/dpll.c                  | 1731 ++++++
 drivers/dpll/sit9531x/dpll.h                  |   70 +
 drivers/dpll/sit9531x/prop.c                  |  472 ++
 drivers/dpll/sit9531x/prop.h                  |   37 +
 drivers/dpll/sit9531x/regs.h                  |  425 ++
 14 files changed, 8732 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/dpll/sitime,sit95316.yaml
 create mode 100644 drivers/dpll/sit9531x/Kconfig
 create mode 100644 drivers/dpll/sit9531x/Makefile
 create mode 100644 drivers/dpll/sit9531x/core.c
 create mode 100644 drivers/dpll/sit9531x/core.h
 create mode 100644 drivers/dpll/sit9531x/dpll.c
 create mode 100644 drivers/dpll/sit9531x/dpll.h
 create mode 100644 drivers/dpll/sit9531x/prop.c
 create mode 100644 drivers/dpll/sit9531x/prop.h
 create mode 100644 drivers/dpll/sit9531x/regs.h


base-commit: 45ad84d2800e4a092fb8d96006a533b2d0ab13f6
-- 
2.39.2 (Apple Git-143)

[PATCH net-next v12 01/12] dt-bindings: vendor-prefixes: add SiTime Corporation

[Ali Rouhi]

Add vendor prefix for SiTime Corporation, manufacturer of
programmable clock generators and MEMS oscillators.

Signed-off-by: Ali Rouhi <arouhi@sitime.com>
Acked-by: Conor Dooley <conor.dooley@microchip.com>
---
 Documentation/devicetree/bindings/vendor-prefixes.yaml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml
index ba2002969373..65da27d6e84d 100644
--- a/Documentation/devicetree/bindings/vendor-prefixes.yaml
+++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml
@@ -1563,6 +1563,8 @@ patternProperties:
     description: SiRF Technology, Inc.
   "^sis,.*":
     description: Silicon Integrated Systems Corp.
+  "^sitime,.*":
+    description: SiTime Corporation
   "^sitronix,.*":
     description: Sitronix Technology Corporation
   "^skov,.*":
-- 
2.39.2 (Apple Git-143)

[PATCH net-next v12 02/12] dt-bindings: dpll: add SiTime SiT95316 clock generator

[Ali Rouhi]

Add a binding for the SiTime SiT9531x family of clock generators: an
I2C-controlled device with four independent PLLs, up to eight input
clocks and up to twelve outputs, described as a DPLL provider.

The XO is given either as a clock or, for firmware that describes the
oscillator as a property rather than as a clock provider, such as ACPI,
as clock-frequency.

The supplies are described by their pin names: the core and input rails,
the GPIO rail the SiT95317 has, and one per output-driver pin -- VDDO0 to
VDDO7 on the SiT95317, VDDO0_1, VDDO2 to VDDO9 and VDDO10_11 on the
SiT95316.  The driver does not enable them, since the boards so far
power the part permanently; describing them gives a board with
switchable rails a way to say so.

Signed-off-by: Ali Rouhi <arouhi@sitime.com>
---
 .../bindings/dpll/sitime,sit95316.yaml        | 213 ++++++++++++++++++
 MAINTAINERS                                   |   6 +
 2 files changed, 219 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/dpll/sitime,sit95316.yaml

diff --git a/Documentation/devicetree/bindings/dpll/sitime,sit95316.yaml b/Documentation/devicetree/bindings/dpll/sitime,sit95316.yaml
new file mode 100644
index 000000000000..200b9f709a57
--- /dev/null
+++ b/Documentation/devicetree/bindings/dpll/sitime,sit95316.yaml
@@ -0,0 +1,213 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dpll/sitime,sit95316.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: SiTime SiT95316/SiT95317 DPLL Clock Generator
+
+maintainers:
+  - Ali Rouhi <arouhi@sitime.com>
+
+description: |
+  SiTime SiT95316 and SiT95317 are I2C-controlled programmable clock
+  generators with integrated DPLL for synchronization applications.  Both
+  variants contain four PLLs with automatic/manual reference selection,
+  DCO frequency adjustment, and phase offset measurement via an on-chip
+  TDC (Time-to-Digital Converter).
+
+  Both parts have 4 differential input pairs whose lanes can also be
+  driven independently as single-ended references, so 8 inputs are
+  individually selectable.  SiT95317 drives 8 outputs, SiT95316
+  drives 12.
+
+  Pin numbering.  An input pin's reg is its lane: 2k is INkP and 2k + 1
+  is INkN, 0 to 7.  A pair the loaded configuration runs differential is
+  one input, described at 2k.  An output pin's reg is its physical output
+  OUTn, 0 to 11; the SiT95317 bonds out OUT0, OUT3, OUT4, OUT5, OUT7, OUT8,
+  OUT9 and OUT11.
+
+properties:
+  compatible:
+    enum:
+      - sitime,sit95316
+      - sitime,sit95317
+
+  reg:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+
+  clock-names:
+    items:
+      - const: xtal
+
+  clock-frequency:
+    description:
+      XO rate in Hz feeding XIN/XO_CLK, for firmware that describes the
+      oscillator as a property rather than as a clock provider, such as
+      ACPI.  Use either this or "clocks", not both.
+
+  reset-gpios:
+    maxItems: 1
+    description:
+      GPIO connected to the chip's active-low reset pin (RESETB).
+
+  interrupts:
+    maxItems: 1
+    description:
+      Interrupt from the chip's active-low INTRB output.  Asserted when
+      the device detects a status change such as lock acquisition or loss.
+
+  dpll-types:
+    maxItems: 4
+
+  vdd-supply:
+    description: Core supply of the PLLs, 1.8 V (the VDD pins).
+
+  vddin-supply:
+    description:
+      Supply of the input receivers and dividers, 3.3 V (VDDIN).
+
+  vdds-supply:
+    description:
+      Supply of the two GPIO pins that have their own rail (VDDS).  The
+      SiT95316 has no such pin.
+
+  input-pins:
+    type: object
+    patternProperties:
+      "^pin@[0-9a-f]+$":
+        type: object
+        properties:
+          reg:
+            maximum: 7
+
+          supported-frequencies-hz:
+            description:
+              The rate wired to the input, in Hz, as a single entry.  An
+              input runs at the rate the board feeds it and has no
+              frequency to select, so that entry is what the pin reports
+              as its frequency.
+
+patternProperties:
+  "^vddo([0-9]|1[01]|0_1|10_11)-supply$":
+    description: |
+      Supply of an output driver, named after its VDDO pin.  The SiT95317
+      has one per output, VDDO0 to VDDO7, numbered as that part's
+      datasheet numbers its outputs; in the pin numbering of this binding
+      those are outputs 0, 3, 4, 5, 7, 8, 9 and 11, in that order.  The
+      SiT95316 has VDDO0_1, VDDO2 to VDDO9 and VDDO10_11, the two shared
+      pins each powering the pair of outputs they are named after.
+
+required:
+  - compatible
+  - reg
+
+dependencies:
+  clocks: [ clock-names ]
+
+oneOf:
+  - required:
+      - clocks
+  - required:
+      - clock-frequency
+
+allOf:
+  - $ref: /schemas/dpll/dpll-device.yaml#
+  - if:
+      properties:
+        compatible:
+          const: sitime,sit95317
+    then:
+      properties:
+        output-pins:
+          patternProperties:
+            "^pin@[0-9a-f]+$":
+              properties:
+                reg:
+                  enum: [0, 3, 4, 5, 7, 8, 9, 11]
+      patternProperties:
+        "^vddo(8|9|1[01]|0_1|10_11)-supply$": false
+    else:
+      properties:
+        vdds-supply: false
+        output-pins:
+          patternProperties:
+            "^pin@[0-9a-f]+$":
+              properties:
+                reg:
+                  maximum: 11
+      patternProperties:
+        "^vddo(1[01]|[01])-supply$": false
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+    #include <dt-bindings/interrupt-controller/irq.h>
+
+    i2c {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        dpll@68 {
+            compatible = "sitime,sit95316";
+            reg = <0x68>;
+            clocks = <&xo2>;
+            clock-names = "xtal";
+            reset-gpios = <&gpio 78 GPIO_ACTIVE_LOW>;
+            interrupts = <12 IRQ_TYPE_LEVEL_LOW>;
+            vdd-supply = <&reg_1v8>;
+            vddin-supply = <&reg_3v3>;
+            vddo0_1-supply = <&reg_3v3>;
+            vddo10_11-supply = <&reg_1v8>;
+            dpll-types = "eec", "eec", "eec", "eec";
+
+            input-pins {
+                #address-cells = <1>;
+                #size-cells = <0>;
+
+                /* IN0P and IN0N: pair 0 runs single-ended */
+                pin@0 {
+                    reg = <0>;
+                    label = "clkin0";
+                    connection-type = "ext";
+                    supported-frequencies-hz = /bits/ 64 <10000000>;
+                };
+
+                pin@1 {
+                    reg = <1>;
+                    label = "clkin1";
+                    connection-type = "synce";
+                    supported-frequencies-hz = /bits/ 64 <156250000>;
+                };
+            };
+
+            output-pins {
+                #address-cells = <1>;
+                #size-cells = <0>;
+
+                pin@0 {
+                    reg = <0>;
+                    label = "clkout0";
+                    supported-frequencies-hz = /bits/ 64 <156250000>;
+                };
+
+                pin@1 {
+                    reg = <1>;
+                    label = "clkout1";
+                    supported-frequencies-hz = /bits/ 64 <25000000>;
+                };
+
+                pin@a {
+                    reg = <10>;
+                    label = "clkout10";
+                    supported-frequencies-hz = /bits/ 64 <10000000>;
+                };
+            };
+        };
+    };
+...
diff --git a/MAINTAINERS b/MAINTAINERS
index 72ca3aab2106..858fe1c4332c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -25182,6 +25182,12 @@ S:	Maintained
 W:	http://www.winischhofer.at/linuxsisusbvga.shtml
 F:	drivers/usb/misc/sisusbvga/
 
+SITIME SIT9531X DPLL DRIVER
+M:	Ali Rouhi <arouhi@sitime.com>
+L:	netdev@vger.kernel.org
+S:	Maintained
+F:	Documentation/devicetree/bindings/dpll/sitime,sit95316.yaml
+
 SL28 CPLD MFD DRIVER
 M:	Michael Walle <mwalle@kernel.org>
 S:	Maintained
-- 
2.39.2 (Apple Git-143)

[PATCH net-next v12 03/12] dpll: add basic SiTime SiT9531x support

[Ali Rouhi]

From: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>

The SiT9531x is an I2C clock generator with four independent PLLs, up to
eight input clocks and up to twelve outputs.  Later patches register the
PLLs with the DPLL subsystem and expose the clocks as pins; this one adds
only what is needed to reach the device.

The register space is paged: 32 pages of 256 registers, selected by
writing the page number to offset 0xFF, which is present in every page.
A regmap range configuration describes that window, so the rest of the
driver addresses a register as a page and an offset and never touches the
selector itself.  Pages come in pairs for the PLLs (0x0A/0x1A for PLLA,
and so on).

Probe reads the rate of the crystal feeding XIN, since every frequency
the driver later computes derives from it; takes the optional reset line
and leaves it deasserted, because the device configuration comes from
efuse or from a blob applied before probe and a reset would discard it;
then identifies the variant from the single byte at page 0 offset 0x02
and refuses to bind on anything unknown.

Suggested-by: Ivan Vecera <ivecera@redhat.com>
Signed-off-by: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
Assisted-by: LLM
Signed-off-by: Ali Rouhi <arouhi@sitime.com>
---
 MAINTAINERS                    |   1 +
 drivers/dpll/Kconfig           |   2 +
 drivers/dpll/Makefile          |   1 +
 drivers/dpll/sit9531x/Kconfig  |  13 ++
 drivers/dpll/sit9531x/Makefile |   4 +
 drivers/dpll/sit9531x/core.c   | 320 +++++++++++++++++++++++++++++++++
 drivers/dpll/sit9531x/core.h   |  91 ++++++++++
 drivers/dpll/sit9531x/regs.h   |  44 +++++
 8 files changed, 476 insertions(+)
 create mode 100644 drivers/dpll/sit9531x/Kconfig
 create mode 100644 drivers/dpll/sit9531x/Makefile
 create mode 100644 drivers/dpll/sit9531x/core.c
 create mode 100644 drivers/dpll/sit9531x/core.h
 create mode 100644 drivers/dpll/sit9531x/regs.h

diff --git a/MAINTAINERS b/MAINTAINERS
index 858fe1c4332c..64e15831055e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -25187,6 +25187,7 @@ M:	Ali Rouhi <arouhi@sitime.com>
 L:	netdev@vger.kernel.org
 S:	Maintained
 F:	Documentation/devicetree/bindings/dpll/sitime,sit95316.yaml
+F:	drivers/dpll/sit9531x/
 
 SL28 CPLD MFD DRIVER
 M:	Michael Walle <mwalle@kernel.org>
diff --git a/drivers/dpll/Kconfig b/drivers/dpll/Kconfig
index be98969f040a..f8f7ca121b93 100644
--- a/drivers/dpll/Kconfig
+++ b/drivers/dpll/Kconfig
@@ -23,6 +23,8 @@ config DPLL_REFCNT_TRACKER
 
 	  If unsure, say N.
 
+source "drivers/dpll/sit9531x/Kconfig"
+
 source "drivers/dpll/zl3073x/Kconfig"
 
 endmenu
diff --git a/drivers/dpll/Makefile b/drivers/dpll/Makefile
index 9e7a3a3e592e..4adc50d748d4 100644
--- a/drivers/dpll/Makefile
+++ b/drivers/dpll/Makefile
@@ -8,4 +8,5 @@ dpll-y                  += dpll_core.o
 dpll-y                  += dpll_netlink.o
 dpll-y                  += dpll_nl.o
 
+obj-$(CONFIG_SIT9531X_DPLL)	+= sit9531x/
 obj-$(CONFIG_ZL3073X)	+= zl3073x/
diff --git a/drivers/dpll/sit9531x/Kconfig b/drivers/dpll/sit9531x/Kconfig
new file mode 100644
index 000000000000..ac5b7f31a034
--- /dev/null
+++ b/drivers/dpll/sit9531x/Kconfig
@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: GPL-2.0-only
+
+config SIT9531X_DPLL
+	tristate "SiTime SiT9531x DPLL driver"
+	depends on I2C && NET
+	select DPLL
+	select REGMAP_I2C
+	help
+	  Driver for SiTime SiT9531x family clock generators
+	  (SiT95317, SiT95316).
+
+	  To compile this driver as a module, choose M here: the
+	  module will be called sit9531x.
diff --git a/drivers/dpll/sit9531x/Makefile b/drivers/dpll/sit9531x/Makefile
new file mode 100644
index 000000000000..a221fe55386a
--- /dev/null
+++ b/drivers/dpll/sit9531x/Makefile
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: GPL-2.0-only
+
+obj-$(CONFIG_SIT9531X_DPLL) += sit9531x.o
+sit9531x-y := core.o
diff --git a/drivers/dpll/sit9531x/core.c b/drivers/dpll/sit9531x/core.c
new file mode 100644
index 000000000000..c7c14442df92
--- /dev/null
+++ b/drivers/dpll/sit9531x/core.c
@@ -0,0 +1,320 @@
+// SPDX-License-Identifier: GPL-2.0
+/*
+ * SiTime SiT9531x DPLL core driver
+ *
+ * Copyright (C) 2026 SiTime Corp.
+ * Author: Ali Rouhi <arouhi@sitime.com>
+ * Author: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
+ *
+ * I2C probe, paged regmap configuration and register access helpers.
+ */
+
+#include <linux/bits.h>
+#include <linux/clk.h>
+#include <linux/delay.h>
+#include <linux/dev_printk.h>
+#include <linux/device.h>
+#include <linux/gpio/consumer.h>
+#include <linux/i2c.h>
+#include <linux/kernel.h>
+#include <linux/module.h>
+#include <linux/property.h>
+#include <linux/regmap.h>
+
+#include "core.h"
+#include "regs.h"
+
+#define SIT9531X_CHIP(_id, _nin, _nout, _name, _map) \
+	{ .id = (_id), .num_inputs = (_nin), .num_outputs = (_nout), \
+	  .name = (_name), .clkout_map = (_map) }
+
+/* Per-variant output index -> physical slot mapping */
+static const u8 clkout_map_95317[] = {0, 3, 4, 5, 7, 8, 9, 11};
+static const u8 clkout_map_95316[] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11};
+
+static const struct sit9531x_chip_info sit9531x_chip_ids[] = {
+	SIT9531X_CHIP(SIT9531X_VARIANT_ID_95317, 8, 8, "SiT95317",
+		      clkout_map_95317),
+	SIT9531X_CHIP(SIT9531X_VARIANT_ID_95316, 8, 12, "SiT95316",
+		      clkout_map_95316),
+};
+
+#define SIT9531X_RANGE_OFFSET	SIT9531X_PAGE_SIZE
+
+/*
+ * Everything the device holds can change without the driver writing it,
+ * so nothing here is cacheable except the page selector.  Caching that
+ * one spares a read of it before every access: the range code selects
+ * the page through a read-modify-write, and with no cache that read goes
+ * to the bus each time.
+ *
+ * The cached value is only as good as the last transfer, though.  A
+ * transfer that fails can leave the part on another page than the cache
+ * records, so every accessor drops the entry on an error and the next
+ * access reads the selector again.
+ */
+static bool sit9531x_volatile_reg(struct device *dev __maybe_unused,
+				  unsigned int reg)
+{
+	return reg != SIT9531X_PAGE_SEL;
+}
+
+static const struct regmap_range_cfg sit9531x_regmap_range = {
+	.range_min	= SIT9531X_RANGE_OFFSET,
+	.range_max	= SIT9531X_RANGE_OFFSET +
+			  (SIT9531X_NUM_PAGES * SIT9531X_PAGE_SIZE) - 1,
+	.selector_reg	= SIT9531X_PAGE_SEL,
+	.selector_mask	= GENMASK(7, 0),
+	.selector_shift	= 0,
+	.window_start	= 0,
+	.window_len	= SIT9531X_PAGE_SIZE,
+};
+
+const struct regmap_config sit9531x_regmap_config = {
+	.reg_bits	= 8,
+	.val_bits	= 8,
+	.max_register	= SIT9531X_RANGE_OFFSET +
+			  (SIT9531X_NUM_PAGES * SIT9531X_PAGE_SIZE) - 1,
+	.ranges		= &sit9531x_regmap_range,
+	.num_ranges	= 1,
+	.volatile_reg	= sit9531x_volatile_reg,
+	.cache_type	= REGCACHE_MAPLE,
+};
+
+static void sit9531x_page_cache_drop(struct sit9531x_dev *sitdev)
+{
+	regcache_drop_region(sitdev->regmap, SIT9531X_PAGE_SEL,
+			     SIT9531X_PAGE_SEL);
+}
+
+/*
+ * sit9531x_read_u8 - read an 8-bit register
+ * @reg:	register in SIT9531X_REG(page, offset) form
+ * @val:	output value
+ */
+int sit9531x_read_u8(struct sit9531x_dev *sitdev, unsigned int reg,
+		     u8 *val)
+{
+	unsigned int vreg, tmp;
+	int rc;
+
+	vreg = (SIT9531X_REG_PAGE(reg) * SIT9531X_PAGE_SIZE) +
+	       SIT9531X_REG_OFFSET(reg) + SIT9531X_RANGE_OFFSET;
+
+	rc = regmap_read(sitdev->regmap, vreg, &tmp);
+	if (rc) {
+		sit9531x_page_cache_drop(sitdev);
+		dev_err(sitdev->dev,
+			"Failed to read page 0x%02x reg 0x%02x: %d\n",
+			SIT9531X_REG_PAGE(reg), SIT9531X_REG_OFFSET(reg), rc);
+	} else {
+		*val = (u8)tmp;
+	}
+
+	return rc;
+}
+
+/*
+ * sit9531x_write_u8 - write an 8-bit register
+ * @reg:	register in SIT9531X_REG(page, offset) form
+ * @val:	value to write
+ */
+int sit9531x_write_u8(struct sit9531x_dev *sitdev, unsigned int reg,
+		      u8 val)
+{
+	unsigned int vreg;
+	int rc;
+
+	vreg = (SIT9531X_REG_PAGE(reg) * SIT9531X_PAGE_SIZE) +
+	       SIT9531X_REG_OFFSET(reg) + SIT9531X_RANGE_OFFSET;
+
+	rc = regmap_write(sitdev->regmap, vreg, val);
+	if (rc) {
+		sit9531x_page_cache_drop(sitdev);
+		dev_err(sitdev->dev,
+			"Failed to write page 0x%02x reg 0x%02x: %d\n",
+			SIT9531X_REG_PAGE(reg), SIT9531X_REG_OFFSET(reg), rc);
+	}
+
+	return rc;
+}
+
+/*
+ * sit9531x_read_pll_u8 - read a register on a PLL page
+ * @val:	output value
+ */
+int sit9531x_read_pll_u8(struct sit9531x_dev *sitdev, u8 pll_idx,
+			 u8 offset, u8 *val)
+{
+	u8 page = sit9531x_pll_page(pll_idx);
+
+	return sit9531x_read_u8(sitdev, SIT9531X_REG(page, offset), val);
+}
+
+/*
+ * sit9531x_write_pll_u8 - write a register on a PLL page
+ * @val:	value to write
+ */
+int sit9531x_write_pll_u8(struct sit9531x_dev *sitdev, u8 pll_idx,
+			  u8 offset, u8 val)
+{
+	u8 page = sit9531x_pll_page(pll_idx);
+
+	return sit9531x_write_u8(sitdev, SIT9531X_REG(page, offset), val);
+}
+
+/*
+ * sit9531x_update_pll_u8 - read-modify-write a register on a PLL page
+ * @mask:	bits to modify
+ * @val:	new value for masked bits
+ */
+int sit9531x_update_pll_u8(struct sit9531x_dev *sitdev, u8 pll_idx,
+			   u8 offset, u8 mask, u8 val)
+{
+	u8 page = sit9531x_pll_page(pll_idx);
+	unsigned int vreg;
+	int rc;
+
+	vreg = (page * SIT9531X_PAGE_SIZE) + offset + SIT9531X_RANGE_OFFSET;
+
+	/*
+	 * A read-modify-write is a read and a write, and either can leave
+	 * the cached page selector wrong, so fail the way the single
+	 * accessors do.
+	 */
+	rc = regmap_update_bits(sitdev->regmap, vreg, mask, val);
+	if (rc) {
+		sit9531x_page_cache_drop(sitdev);
+		dev_err(sitdev->dev,
+			"Failed to update page 0x%02x reg 0x%02x: %d\n",
+			page, offset, rc);
+	}
+
+	return rc;
+}
+
+static int sit9531x_read_variant_id(struct sit9531x_dev *sitdev, u8 *id)
+{
+	return sit9531x_read_u8(sitdev, SIT9531X_REG_VARIANT_ID, id);
+}
+
+static const struct sit9531x_chip_info *sit9531x_match_variant(u8 id)
+{
+	unsigned int i;
+
+	for (i = 0; i < ARRAY_SIZE(sit9531x_chip_ids); i++) {
+		if (sit9531x_chip_ids[i].id == id)
+			return &sit9531x_chip_ids[i];
+	}
+
+	return NULL;
+}
+
+int sit9531x_dev_probe(struct sit9531x_dev *sitdev)
+{
+	struct clk *xtal_clk;
+	u8 variant_id;
+	int rc;
+
+	/*
+	 * Fvco = Fref * (DIVN + frac/2^32) with Fref derived from the XO
+	 * feeding XIN/XO_CLK, so the rate is needed before anything can be
+	 * computed from a divider.  The rate normally comes from a "clocks"
+	 * phandle (clock-names = "xtal").  On platforms where the firmware
+	 * does not expose the XO through the clock framework, fall back to
+	 * a "clock-frequency" device property.
+	 */
+	xtal_clk = devm_clk_get_optional_enabled(sitdev->dev, "xtal");
+	if (IS_ERR(xtal_clk))
+		return dev_err_probe(sitdev->dev, PTR_ERR(xtal_clk),
+				     "Failed to get xtal clock\n");
+	sitdev->xtal_freq = clk_get_rate(xtal_clk);
+	if (!sitdev->xtal_freq) {
+		u32 freq;
+
+		if (!device_property_read_u32(sitdev->dev, "clock-frequency",
+					      &freq))
+			sitdev->xtal_freq = freq;
+	}
+	if (!sitdev->xtal_freq)
+		return dev_err_probe(sitdev->dev, -EINVAL,
+				     "no xtal rate: provide clocks=<&xo> + clock-names=\"xtal\", or a clock-frequency property\n");
+
+	/*
+	 * Held deasserted, never pulsed: the chip configuration comes from
+	 * efuse or an NVM blob applied before probe, and a reset would
+	 * discard it.  Must precede the first I2C access, as a board that
+	 * powers up asserted keeps the chip unreachable until released.
+	 */
+	sitdev->reset_gpio = devm_gpiod_get_optional(sitdev->dev, "reset",
+						     GPIOD_OUT_LOW);
+	if (IS_ERR(sitdev->reset_gpio))
+		return dev_err_probe(sitdev->dev, PTR_ERR(sitdev->reset_gpio),
+				     "Failed to request reset gpio\n");
+	if (sitdev->reset_gpio)
+		fsleep(10000);	/* internal boot after release */
+
+	rc = sit9531x_read_variant_id(sitdev, &variant_id);
+	if (rc)
+		return rc;
+
+	sitdev->info = sit9531x_match_variant(variant_id);
+	if (!sitdev->info)
+		return dev_err_probe(sitdev->dev, -ENODEV,
+				     "Unknown variant ID: 0x%02x\n",
+				     variant_id);
+
+	rc = devm_mutex_init(sitdev->dev, &sitdev->multiop_lock);
+	if (rc)
+		return dev_err_probe(sitdev->dev, rc,
+				     "Failed to initialize mutex\n");
+
+	dev_info(sitdev->dev, "%s detected, %u inputs, %u outputs\n",
+		 sitdev->info->name, sitdev->info->num_inputs,
+		 sitdev->info->num_outputs);
+
+	return 0;
+}
+
+static int sit9531x_i2c_probe(struct i2c_client *client)
+{
+	struct sit9531x_dev *sitdev;
+	struct regmap *regmap;
+
+	regmap = devm_regmap_init_i2c(client, &sit9531x_regmap_config);
+	if (IS_ERR(regmap))
+		return dev_err_probe(&client->dev, PTR_ERR(regmap),
+				     "Failed to initialize regmap\n");
+
+	sitdev = devm_kzalloc(&client->dev, sizeof(*sitdev), GFP_KERNEL);
+	if (!sitdev)
+		return -ENOMEM;
+
+	sitdev->dev = &client->dev;
+	sitdev->client = client;
+	sitdev->regmap = regmap;
+	i2c_set_clientdata(client, sitdev);
+
+	return sit9531x_dev_probe(sitdev);
+}
+
+static const struct of_device_id sit9531x_of_match[] = {
+	{ .compatible = "sitime,sit95316" },
+	{ .compatible = "sitime,sit95317" },
+	{ }
+};
+MODULE_DEVICE_TABLE(of, sit9531x_of_match);
+
+static struct i2c_driver sit9531x_i2c_driver = {
+	.driver			= {
+		.name		= "sit9531x",
+		.of_match_table	= sit9531x_of_match,
+	},
+	.probe		= sit9531x_i2c_probe,
+};
+module_i2c_driver(sit9531x_i2c_driver);
+
+MODULE_AUTHOR("Ali Rouhi <arouhi@sitime.com>");
+MODULE_AUTHOR("Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>");
+MODULE_DESCRIPTION("SiTime SiT9531x DPLL subsystem driver");
+MODULE_LICENSE("GPL");
diff --git a/drivers/dpll/sit9531x/core.h b/drivers/dpll/sit9531x/core.h
new file mode 100644
index 000000000000..76a2632f0ce4
--- /dev/null
+++ b/drivers/dpll/sit9531x/core.h
@@ -0,0 +1,91 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/*
+ * SiTime SiT9531x DPLL core driver
+ *
+ * Copyright (C) 2026 SiTime Corp.
+ * Author: Ali Rouhi <arouhi@sitime.com>
+ * Author: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
+ *
+ * Device structure, register access helpers, and core function
+ * declarations.
+ */
+
+#ifndef _SIT9531X_CORE_H
+#define _SIT9531X_CORE_H
+
+#include <linux/gpio/consumer.h>
+#include <linux/i2c.h>
+#include <linux/mutex.h>
+#include <linux/regmap.h>
+#include <linux/types.h>
+
+#include "regs.h"
+
+#define SIT9531X_NUM_PLLS		4
+#define SIT9531X_MAX_INPUTS		8
+#define SIT9531X_MAX_OUTPUTS		12
+
+/*
+ * struct sit9531x_chip_info - chip variant identification
+ * @id:		variant ID byte read from register
+ * @num_inputs:	number of input clock pins
+ * @num_outputs: number of output clock pins
+ * @name:	human-readable variant name
+ * @clkout_map:	per-output slot mapping (output index -> physical slot)
+ */
+struct sit9531x_chip_info {
+	u8		id;
+	u8		num_inputs;
+	u8		num_outputs;
+	const char	*name;
+	const u8	*clkout_map;
+};
+
+/*
+ * struct sit9531x_dev - SiT9531x device instance
+ * @dev:		parent device
+ * @client:		I2C client
+ * @regmap:		paged register map
+ * @info:		detected chip variant info
+ * @multiop_lock:	serializes multi-register sequences
+ * @xtal_freq:		crystal oscillator frequency in Hz
+ * @reset_gpio:		optional reset line (DT "reset-gpios"), NULL if absent
+ */
+struct sit9531x_dev {
+	struct device			*dev;
+	struct i2c_client		*client;
+	struct regmap			*regmap;
+	const struct sit9531x_chip_info	*info;
+	/* Serializes multi-step register sequences */
+	struct mutex			multiop_lock;
+
+	u32			xtal_freq;
+
+	struct gpio_desc	*reset_gpio;
+};
+
+/*
+ * sit9531x_pll_page - get register page for PLL index
+ * @pll_idx: PLL index (0 = PLLA, 3 = PLLD)
+ */
+static inline u8 sit9531x_pll_page(u8 pll_idx)
+{
+	return SIT9531X_PAGE_PLLA + pll_idx;
+}
+
+extern const struct regmap_config sit9531x_regmap_config;
+
+/* ---- Core lifecycle ---- */
+int  sit9531x_dev_probe(struct sit9531x_dev *sitdev);
+
+/* ---- Register access ---- */
+int sit9531x_read_u8(struct sit9531x_dev *sitdev, unsigned int reg, u8 *val);
+int sit9531x_write_u8(struct sit9531x_dev *sitdev, unsigned int reg, u8 val);
+int sit9531x_read_pll_u8(struct sit9531x_dev *sitdev, u8 pll_idx, u8 offset,
+			 u8 *val);
+int sit9531x_write_pll_u8(struct sit9531x_dev *sitdev, u8 pll_idx, u8 offset,
+			  u8 val);
+int sit9531x_update_pll_u8(struct sit9531x_dev *sitdev, u8 pll_idx, u8 offset,
+			   u8 mask, u8 val);
+
+#endif /* _SIT9531X_CORE_H */
diff --git a/drivers/dpll/sit9531x/regs.h b/drivers/dpll/sit9531x/regs.h
new file mode 100644
index 000000000000..67077d112653
--- /dev/null
+++ b/drivers/dpll/sit9531x/regs.h
@@ -0,0 +1,44 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/*
+ * SiTime SiT9531x register definitions
+ *
+ * Copyright (C) 2026 SiTime Corp.
+ * Author: Ali Rouhi <arouhi@sitime.com>
+ * Author: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
+ */
+
+#ifndef _SIT9531X_REGS_H
+#define _SIT9531X_REGS_H
+
+/*
+ * I2C register model:
+ *   - Page select register at offset 0xFF, present in every page
+ *   - Each page has 256 registers (0x00-0xFF)
+ *   - Some pages are paired (e.g. 0x0A/0x1A for PLLA)
+ */
+#define SIT9531X_PAGE_SEL		0xFF
+#define SIT9531X_PAGE_SIZE		0x100
+#define SIT9531X_NUM_PAGES		32
+
+/* Helper macros for page:offset addressing */
+#define SIT9531X_REG(_page, _offset)		(((_page) << 8) | (_offset))
+#define SIT9531X_REG_PAGE(_reg)		((_reg) >> 8)
+#define SIT9531X_REG_OFFSET(_reg)		((_reg) & 0xFF)
+
+#define SIT9531X_PAGE_OUTSYS0		0x03
+#define SIT9531X_PAGE_OUTSYS1		0x04
+#define SIT9531X_PAGE_PLLA			0x0A
+#define SIT9531X_PAGE_PLLA_EXT		0x1A
+
+/*
+ * VARIANT_ID is a single byte at page 0 reg 0x02 (95317 = 0x17, 95316 = 0x31).
+ * Reg 0x03 carries an unrelated revision byte and must not be combined into
+ * the variant identifier.
+ */
+#define SIT9531X_REG_VARIANT_ID		SIT9531X_REG(0x00, 0x02)
+
+/* Variant ID values (page 0 reg 0x02) */
+#define SIT9531X_VARIANT_ID_95317	0x17
+#define SIT9531X_VARIANT_ID_95316	0x31
+
+#endif /* _SIT9531X_REGS_H */
-- 
2.39.2 (Apple Git-143)

[PATCH net-next v12 04/12] dpll: sit9531x: read DPLL types and pin properties from system firmware

[Ali Rouhi]

From: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>

The DPLL core wants a type per device and a property set per pin: a
label, the direction, the capabilities, and the frequencies the pin
supports.  None of that can be read from the chip -- which frequencies a
board actually presents on a given input is a board fact -- so they come
from the firmware node, with defaults for a node that does not describe
them.

Input pins are interleaved P and N lanes of four differential pairs, so a
logical index maps to a pair and a lane, and a pair configured
single-ended presents two independent inputs where a differential one
presents one.  The labels follow from that, and the two extra input
positions -- the crystal and the inter-PLL sync net -- are named
separately.

One of the advertised properties is worth naming.  An output whose node
lists no supported frequencies is advertised as a continuous range rather
than nothing at all, since those pins do accept a frequency set; a
request inside the range that the integer output divider cannot produce
is refused when it is made.

Kept in its own file, and introduced before anything is registered, so
the registration code that follows has nothing to say about firmware.

Signed-off-by: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
Assisted-by: LLM
Signed-off-by: Ali Rouhi <arouhi@sitime.com>
---
 drivers/dpll/sit9531x/Makefile |   2 +-
 drivers/dpll/sit9531x/core.h   |  68 ++++++
 drivers/dpll/sit9531x/prop.c   | 427 +++++++++++++++++++++++++++++++++
 drivers/dpll/sit9531x/prop.h   |  37 +++
 4 files changed, 533 insertions(+), 1 deletion(-)
 create mode 100644 drivers/dpll/sit9531x/prop.c
 create mode 100644 drivers/dpll/sit9531x/prop.h

diff --git a/drivers/dpll/sit9531x/Makefile b/drivers/dpll/sit9531x/Makefile
index a221fe55386a..819af61123f5 100644
--- a/drivers/dpll/sit9531x/Makefile
+++ b/drivers/dpll/sit9531x/Makefile
@@ -1,4 +1,4 @@
 # SPDX-License-Identifier: GPL-2.0-only
 
 obj-$(CONFIG_SIT9531X_DPLL) += sit9531x.o
-sit9531x-y := core.o
+sit9531x-y := core.o prop.o
diff --git a/drivers/dpll/sit9531x/core.h b/drivers/dpll/sit9531x/core.h
index 76a2632f0ce4..4b4f72c8622b 100644
--- a/drivers/dpll/sit9531x/core.h
+++ b/drivers/dpll/sit9531x/core.h
@@ -23,7 +23,17 @@
 
 #define SIT9531X_NUM_PLLS		4
 #define SIT9531X_MAX_INPUTS		8
+#define SIT9531X_NUM_INPUT_PAIRS	(SIT9531X_MAX_INPUTS / 2)
 #define SIT9531X_MAX_OUTPUTS		12
+/*
+ * INTSYNC (the inter-PLL sync net) is modeled as two pins.  The
+ * destination PLL that locks to INTSYNC sees an input pin
+ * (SIT9531X_INTSYNC_PIN_ID, in the input id namespace after the physical
+ * inputs and the xtal); the source PLL that drives INTSYNC sees an output
+ * pin (SIT9531X_INTSYNC_OUT_PIN_ID, appended after the physical outputs).
+ */
+#define SIT9531X_INTSYNC_PIN_ID		(SIT9531X_MAX_INPUTS + 1)
+#define SIT9531X_INTSYNC_OUT_PIN_ID	SIT9531X_MAX_OUTPUTS
 
 /*
  * struct sit9531x_chip_info - chip variant identification
@@ -41,6 +51,35 @@ struct sit9531x_chip_info {
 	const u8	*clkout_map;
 };
 
+/*
+ * enum sit9531x_signal_mode - input signal electrical mode
+ * @SIT9531X_MODE_SE: single-ended
+ * @SIT9531X_MODE_DE: differential
+ */
+enum sit9531x_signal_mode {
+	SIT9531X_MODE_SE = 0,
+	SIT9531X_MODE_DE,
+};
+
+/*
+ * struct sit9531x_ref - input reference state
+ * @freq:		configured frequency in Hz
+ * @sig_mode:		signal mode of the pair this lane belongs to
+ *			(detected from CLKINx_INPUT_MODE at probe)
+ */
+struct sit9531x_ref {
+	u64		freq;
+	enum sit9531x_signal_mode	sig_mode;
+};
+
+/*
+ * struct sit9531x_out - output state
+ * @freq:		configured frequency in Hz
+ */
+struct sit9531x_out {
+	u64		freq;
+};
+
 /*
  * struct sit9531x_dev - SiT9531x device instance
  * @dev:		parent device
@@ -48,6 +87,8 @@ struct sit9531x_chip_info {
  * @regmap:		paged register map
  * @info:		detected chip variant info
  * @multiop_lock:	serializes multi-register sequences
+ * @ref:		array of input reference states
+ * @out:		array of output states
  * @xtal_freq:		crystal oscillator frequency in Hz
  * @reset_gpio:		optional reset line (DT "reset-gpios"), NULL if absent
  */
@@ -59,11 +100,38 @@ struct sit9531x_dev {
 	/* Serializes multi-step register sequences */
 	struct mutex			multiop_lock;
 
+	/* Hardware state */
+	struct sit9531x_ref	ref[SIT9531X_MAX_INPUTS + 1]; /* +1 for xtal */
+	struct sit9531x_out	out[SIT9531X_MAX_OUTPUTS];
 	u32			xtal_freq;
 
 	struct gpio_desc	*reset_gpio;
 };
 
+/*
+ * Logical input pins are interleaved: even index = P lane, odd
+ * index = N lane of pair index/2 (IN0P, IN0N, IN1P, IN1N, ...).
+ * Index SIT9531X_MAX_INPUTS is the XO input.
+ */
+
+/*
+ * sit9531x_input_pair - get input pair number for a logical input index
+ * @index: logical input pin index
+ */
+static inline u8 sit9531x_input_pair(u8 index)
+{
+	return index >> 1;
+}
+
+/*
+ * sit9531x_input_is_n - check if a logical input index is an N lane
+ * @index: logical input pin index
+ */
+static inline bool sit9531x_input_is_n(u8 index)
+{
+	return index & 1;
+}
+
 /*
  * sit9531x_pll_page - get register page for PLL index
  * @pll_idx: PLL index (0 = PLLA, 3 = PLLD)
diff --git a/drivers/dpll/sit9531x/prop.c b/drivers/dpll/sit9531x/prop.c
new file mode 100644
index 000000000000..3635ea497e41
--- /dev/null
+++ b/drivers/dpll/sit9531x/prop.c
@@ -0,0 +1,427 @@
+// SPDX-License-Identifier: GPL-2.0
+/*
+ * SiTime SiT9531x firmware node property parsing
+ *
+ * Copyright (C) 2026 SiTime Corp.
+ * Author: Ali Rouhi <arouhi@sitime.com>
+ * Author: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
+ *
+ * Retrieves pin properties from Device Tree firmware nodes (or
+ * applies defaults when no firmware node exists).
+ */
+
+#include <linux/dev_printk.h>
+#include <linux/dpll.h>
+#include <linux/err.h>
+#include <linux/fwnode.h>
+#include <linux/property.h>
+#include <linux/slab.h>
+#include <linux/string.h>
+
+#include "core.h"
+#include "prop.h"
+
+/*
+ * sit9531x_input_pin_label - fill the package label for an input pin
+ *
+ * Split out so input-naming changes stay local to this helper.
+ */
+static void sit9531x_input_pin_label(struct sit9531x_dev *sitdev,
+				     struct sit9531x_pin_props *props, u8 id)
+{
+	u8 pair = sit9531x_input_pair(id);
+
+	if (sitdev->ref[id].sig_mode == SIT9531X_MODE_DE)
+		snprintf(props->package_label,
+			 sizeof(props->package_label), "IN%u", pair);
+	else
+		snprintf(props->package_label,
+			 sizeof(props->package_label), "IN%u%c", pair,
+			 sit9531x_input_is_n(id) ? 'N' : 'P');
+}
+
+/*
+ * sit9531x_prop_pin_package_label_set - generate package label
+ * @dir:	pin direction
+ * @id:		pin index
+ *
+ * Generates a package label string.  Output pins are named "OUT0",
+ * "OUT1", ...  Input pins are named after the physical pair and lane:
+ * "IN0P", "IN0N", "IN1P", ... for single-ended lanes, or "IN0",
+ * "IN1", ... when the pair is configured differential (the N lane is
+ * not registered in that case).
+ */
+static void
+sit9531x_prop_pin_package_label_set(struct sit9531x_dev *sitdev,
+				    struct sit9531x_pin_props *props,
+				    enum dpll_pin_direction dir, u8 id)
+{
+	/* The internal INTSYNC pin has a fixed label */
+	if (dir == DPLL_PIN_DIRECTION_INPUT &&
+	    id == SIT9531X_INTSYNC_PIN_ID) {
+		strscpy(props->package_label, "INTSYNC",
+			sizeof(props->package_label));
+		props->dpll_props.package_label = props->package_label;
+		return;
+	}
+
+	/* The internal XO reference has a fixed label */
+	if (dir == DPLL_PIN_DIRECTION_INPUT && id == SIT9531X_MAX_INPUTS) {
+		strscpy(props->package_label, "XO",
+			sizeof(props->package_label));
+		props->dpll_props.package_label = props->package_label;
+		return;
+	}
+
+	/* The internal INTSYNC source (output) pin has a fixed label */
+	if (dir == DPLL_PIN_DIRECTION_OUTPUT &&
+	    id == SIT9531X_INTSYNC_OUT_PIN_ID) {
+		strscpy(props->package_label, "SYNCOUT",
+			sizeof(props->package_label));
+		props->dpll_props.package_label = props->package_label;
+		return;
+	}
+
+	if (dir == DPLL_PIN_DIRECTION_INPUT)
+		sit9531x_input_pin_label(sitdev, props, id);
+	else
+		/*
+		 * Name the chip pin, not the driver's index for it.  The
+		 * two differ on the variant whose outputs are bonded out
+		 * from a subset of the twelve slots, and a package label
+		 * that named the index would point at a pin that is not
+		 * the one being driven.
+		 */
+		snprintf(props->package_label, sizeof(props->package_label),
+			 "OUT%u", sitdev->info->clkout_map[id]);
+
+	props->dpll_props.package_label = props->package_label;
+}
+
+/*
+ * sit9531x_prop_pin_fwnode_get - find firmware node for a pin
+ * @dir:	pin direction
+ * @id:		pin index
+ *
+ * Searches for input-pins/output-pins child nodes in DT, looking for a
+ * child whose "reg" property matches the pin.  The binding describes reg
+ * as the hardware index, so an output is matched by the chip slot it
+ * drives rather than by the driver's index for it: on the variant where
+ * the two differ, a board describing the pin it wired would otherwise
+ * have its properties applied to a different one.
+ *
+ * Return: 0 on success, -ENOENT if no firmware node exists
+ */
+static int
+sit9531x_prop_pin_fwnode_get(struct sit9531x_dev *sitdev,
+			     struct sit9531x_pin_props *props,
+			     enum dpll_pin_direction dir, u8 id)
+{
+	struct fwnode_handle *pins_node, *pin_node;
+	const char *node_name;
+
+	if (dir == DPLL_PIN_DIRECTION_INPUT) {
+		node_name = "input-pins";
+	} else {
+		node_name = "output-pins";
+		if (id < sitdev->info->num_outputs)
+			id = sitdev->info->clkout_map[id];
+	}
+
+	pins_node = device_get_named_child_node(sitdev->dev, node_name);
+	if (!pins_node) {
+		dev_dbg(sitdev->dev, "'%s' sub-node is missing\n", node_name);
+		return -ENOENT;
+	}
+
+	/* Enumerate child pin nodes and find the requested one */
+	fwnode_for_each_child_node(pins_node, pin_node) {
+		u32 reg;
+
+		if (fwnode_property_read_u32(pin_node, "reg", &reg))
+			continue;
+
+		if (id == reg)
+			break;
+	}
+
+	fwnode_handle_put(pins_node);
+
+	props->fwnode = pin_node;
+
+	dev_dbg(sitdev->dev, "Firmware node for %s %sfound\n",
+		props->package_label, pin_node ? "" : "NOT ");
+
+	return pin_node ? 0 : -ENOENT;
+}
+
+/*
+ * sit9531x_pin_props_get - get pin properties for a given pin
+ * @dir:	pin direction (INPUT or OUTPUT)
+ * @index:	pin index
+ *
+ * Allocates a pin properties structure, generates a package label,
+ * looks up the firmware node if available, and reads optional
+ * properties (label, connection-type, supported-frequencies-hz).
+ *
+ * Call sit9531x_pin_props_put() to free the returned structure.
+ *
+ * Return: pointer to pin properties on success, error pointer on error
+ */
+struct sit9531x_pin_props *
+sit9531x_pin_props_get(struct sit9531x_dev *sitdev,
+		       enum dpll_pin_direction dir, u8 index)
+{
+	struct dpll_pin_frequency *ranges;
+	struct sit9531x_pin_props *props;
+	int i, j, num_freqs = 0, rc;
+	u64 *freqs = NULL;
+	const char *type;
+	u64 curr_freq;
+
+	props = kzalloc_obj(*props, GFP_KERNEL);
+	if (!props)
+		return ERR_PTR(-ENOMEM);
+
+	if (dir == DPLL_PIN_DIRECTION_INPUT &&
+	    index == SIT9531X_INTSYNC_PIN_ID) {
+		/*
+		 * INTSYNC destination pin: a PLL locks to the INTSYNC net as a
+		 * reference, so it can be connected.
+		 */
+		props->dpll_props.type = DPLL_PIN_TYPE_INT_OSCILLATOR;
+		props->dpll_props.capabilities =
+			DPLL_PIN_CAPABILITIES_STATE_CAN_CHANGE;
+		curr_freq = 0;
+	} else if (dir == DPLL_PIN_DIRECTION_OUTPUT &&
+		   index == SIT9531X_INTSYNC_OUT_PIN_ID) {
+		/*
+		 * INTSYNC source pin: a PLL drives the INTSYNC net.  It can be
+		 * connected/disconnected but carries no priority (driving the
+		 * net is not a reference selection) and no frequency.
+		 */
+		props->dpll_props.type = DPLL_PIN_TYPE_INT_OSCILLATOR;
+		props->dpll_props.capabilities =
+			DPLL_PIN_CAPABILITIES_STATE_CAN_CHANGE;
+		curr_freq = 0;
+	} else if (dir == DPLL_PIN_DIRECTION_INPUT &&
+		   index == SIT9531X_MAX_INPUTS) {
+		/* The XO reference is fixed: no state or priority control. */
+		props->dpll_props.type = DPLL_PIN_TYPE_INT_OSCILLATOR;
+		props->dpll_props.capabilities = 0;
+		sitdev->ref[index].freq = sitdev->xtal_freq;
+		curr_freq = sitdev->xtal_freq;
+	} else if (dir == DPLL_PIN_DIRECTION_INPUT) {
+		props->dpll_props.type = DPLL_PIN_TYPE_EXT;
+		props->dpll_props.capabilities =
+			DPLL_PIN_CAPABILITIES_STATE_CAN_CHANGE;
+		curr_freq = sitdev->ref[index].freq;
+	} else {
+		/*
+		 * A synthesized clock output is an external connection with
+		 * no more specific meaning; a board that knows better says
+		 * so through the pin's connection-type property below.
+		 */
+		props->dpll_props.type = DPLL_PIN_TYPE_EXT;
+		props->dpll_props.capabilities =
+			DPLL_PIN_CAPABILITIES_STATE_CAN_CHANGE;
+		curr_freq = sitdev->out[index].freq;
+	}
+
+	/* Generate package label */
+	sit9531x_prop_pin_package_label_set(sitdev, props, dir, index);
+
+	/*
+	 * Both INTSYNC pins are internal to the chip and have no board-level
+	 * wiring, so they take no properties from the firmware node.
+	 */
+	if (dir == DPLL_PIN_DIRECTION_INPUT &&
+	    (index == SIT9531X_INTSYNC_PIN_ID ||
+	     index == SIT9531X_MAX_INPUTS))
+		goto skip_fwnode_props;
+	if (dir == DPLL_PIN_DIRECTION_OUTPUT &&
+	    index == SIT9531X_INTSYNC_OUT_PIN_ID)
+		goto skip_fwnode_props;
+
+	rc = sit9531x_prop_pin_fwnode_get(sitdev, props, dir, index);
+	if (rc)
+		goto skip_fwnode_props;
+
+	/* Look for "label" property -> board label */
+	fwnode_property_read_string(props->fwnode, "label",
+				    &props->dpll_props.board_label);
+
+	/* Look for "connection-type" property -> pin type enum */
+	if (!fwnode_property_read_string(props->fwnode, "connection-type",
+					 &type)) {
+		if (!strcmp(type, "ext"))
+			props->dpll_props.type = DPLL_PIN_TYPE_EXT;
+		else if (!strcmp(type, "gnss"))
+			props->dpll_props.type = DPLL_PIN_TYPE_GNSS;
+		else if (!strcmp(type, "int"))
+			props->dpll_props.type = DPLL_PIN_TYPE_INT_OSCILLATOR;
+		else if (!strcmp(type, "synce"))
+			props->dpll_props.type = DPLL_PIN_TYPE_SYNCE_ETH_PORT;
+		else if (!strcmp(type, "mux"))
+			props->dpll_props.type = DPLL_PIN_TYPE_MUX;
+		else
+			dev_warn(sitdev->dev,
+				 "Unknown pin type '%s'\n", type);
+	}
+
+	num_freqs = fwnode_property_count_u64(props->fwnode,
+					      "supported-frequencies-hz");
+	if (num_freqs <= 0) {
+		num_freqs = 0;
+		goto skip_fwnode_props;
+	}
+
+	freqs = kcalloc(num_freqs, sizeof(*freqs), GFP_KERNEL);
+	if (!freqs) {
+		rc = -ENOMEM;
+		goto err_alloc_freqs;
+	}
+
+	rc = fwnode_property_read_u64_array(props->fwnode,
+					    "supported-frequencies-hz",
+					    freqs, num_freqs);
+	if (rc) {
+		dev_warn(sitdev->dev,
+			 "failed to parse supported-frequencies-hz for %s: %d\n",
+			 props->package_label, rc);
+		goto err_alloc_ranges;
+	}
+
+	/*
+	 * Seed an input's runtime ref->freq with the first DT-listed
+	 * supported frequency: for an input the board lists the rate that is
+	 * physically wired to it first.  An output's current rate is what its
+	 * divider produces, not an entry of the list it may be set to.
+	 */
+	if (num_freqs > 0 && dir == DPLL_PIN_DIRECTION_INPUT &&
+	    index != SIT9531X_MAX_INPUTS)
+		curr_freq = freqs[0];
+
+skip_fwnode_props:
+	/* Neither INTSYNC pin carries a frequency attribute */
+	if (dir == DPLL_PIN_DIRECTION_INPUT &&
+	    index == SIT9531X_INTSYNC_PIN_ID)
+		return props;
+	if (dir == DPLL_PIN_DIRECTION_OUTPUT &&
+	    index == SIT9531X_INTSYNC_OUT_PIN_ID)
+		return props;
+
+	/*
+	 * Advertise only concrete values from firmware plus current runtime
+	 * value. For outputs without a firmware list, publish one wide range as
+	 * an explicit fallback because those pins do support frequency_set.
+	 */
+	ranges = kcalloc(num_freqs + 2, sizeof(*ranges), GFP_KERNEL);
+	if (!ranges) {
+		rc = -ENOMEM;
+		goto err_alloc_ranges;
+	}
+
+	/*
+	 * Publish the seeded rate only once the pin is certain to be built.
+	 * The allocation above is the last thing that can fail, and a call
+	 * that reports failure must not leave the device's cached rate
+	 * changed behind it.
+	 */
+	if (curr_freq) {
+		if (dir == DPLL_PIN_DIRECTION_INPUT)
+			sitdev->ref[index].freq = curr_freq;
+		else
+			sitdev->out[index].freq = curr_freq;
+	}
+
+	j = 0;
+
+	/* Current frequency first, when known. */
+	if (curr_freq) {
+		struct dpll_pin_frequency f = DPLL_PIN_FREQUENCY(curr_freq);
+
+		ranges[j++] = f;
+	}
+
+	for (i = 0; i < num_freqs; i++) {
+		struct dpll_pin_frequency freq = DPLL_PIN_FREQUENCY(freqs[i]);
+
+		if (freqs[i] == curr_freq)
+			continue;
+		ranges[j++] = freq;
+	}
+
+	if (dir == DPLL_PIN_DIRECTION_OUTPUT && num_freqs == 0) {
+		ranges[j].min = 1;
+		ranges[j].max = 1000000000ULL; /* 1 GHz */
+		j++;
+	}
+
+	if (j > 0) {
+		props->dpll_props.freq_supported = ranges;
+		props->dpll_props.freq_supported_num = j;
+	} else {
+		kfree(ranges);
+		props->dpll_props.freq_supported = NULL;
+		props->dpll_props.freq_supported_num = 0;
+	}
+
+	kfree(freqs);
+
+	return props;
+
+err_alloc_ranges:
+	kfree(freqs);
+err_alloc_freqs:
+	fwnode_handle_put(props->fwnode);
+	kfree(props);
+
+	return ERR_PTR(rc);
+}
+
+/*
+ * sit9531x_pin_props_put - release pin properties
+ * @props:	pin properties to free
+ */
+void sit9531x_pin_props_put(struct sit9531x_pin_props *props)
+{
+	kfree(props->dpll_props.freq_supported);
+
+	if (props->fwnode)
+		fwnode_handle_put(props->fwnode);
+
+	kfree(props);
+}
+
+/*
+ * sit9531x_prop_dpll_type_get - get DPLL channel type from firmware
+ * @index:	DPLL channel index (0-3)
+ *
+ * Reads the "dpll-types" string array property from the firmware node
+ * and returns the corresponding DPLL type enum.
+ *
+ * Return: DPLL type for the given channel (default: DPLL_TYPE_PPS)
+ */
+enum dpll_type
+sit9531x_prop_dpll_type_get(struct sit9531x_dev *sitdev, u8 index)
+{
+	const char *types[SIT9531X_NUM_PLLS];
+	int count;
+
+	count = device_property_read_string_array(sitdev->dev, "dpll-types",
+						  types, ARRAY_SIZE(types));
+
+	if (index >= count)
+		return DPLL_TYPE_PPS;
+
+	if (!strcmp(types[index], "pps"))
+		return DPLL_TYPE_PPS;
+	else if (!strcmp(types[index], "eec"))
+		return DPLL_TYPE_EEC;
+
+	dev_warn(sitdev->dev, "Unknown DPLL type '%s', using default\n",
+		 types[index]);
+
+	return DPLL_TYPE_PPS;
+}
diff --git a/drivers/dpll/sit9531x/prop.h b/drivers/dpll/sit9531x/prop.h
new file mode 100644
index 000000000000..a65efdfd9ef8
--- /dev/null
+++ b/drivers/dpll/sit9531x/prop.h
@@ -0,0 +1,37 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/*
+ * SiTime SiT9531x firmware node property parsing
+ *
+ * Copyright (C) 2026 SiTime Corp.
+ * Author: Ali Rouhi <arouhi@sitime.com>
+ * Author: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
+ */
+
+#ifndef _SIT9531X_PROP_H
+#define _SIT9531X_PROP_H
+
+#include <linux/dpll.h>
+#include <linux/fwnode.h>
+
+struct sit9531x_dev;
+
+/*
+ * struct sit9531x_pin_props - pin properties from firmware
+ * @fwnode:		firmware node handle (NULL if no DT node)
+ * @dpll_props:		DPLL core pin properties
+ * @package_label:	pin package label (e.g. "IN0", "OUT3")
+ */
+struct sit9531x_pin_props {
+	struct fwnode_handle		*fwnode;
+	struct dpll_pin_properties	dpll_props;
+	char				package_label[8];
+};
+
+enum dpll_type sit9531x_prop_dpll_type_get(struct sit9531x_dev *sitdev,
+					   u8 index);
+struct sit9531x_pin_props *sit9531x_pin_props_get(struct sit9531x_dev *sitdev,
+						  enum dpll_pin_direction dir,
+						  u8 index);
+void sit9531x_pin_props_put(struct sit9531x_pin_props *props);
+
+#endif /* _SIT9531X_PROP_H */
-- 
2.39.2 (Apple Git-143)

[PATCH net-next v12 05/12] dpll: sit9531x: register DPLL devices and pins

[Ali Rouhi]

From: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>

Register each of the four on-chip PLLs as a DPLL device, and the crystal
that feeds them as a pin on each.  The inputs and the outputs need a
state callback the core insists on before it will take a pin, so they are
registered by the patches that add theirs; what this patch builds is the
device, the pin machinery around it, and the one pin whose state never
changes.

The callbacks a device needs from the start come with it -- lock status
and the operating mode -- along with the direction of each pin.  The rest
of the pin operations follow in later patches.  The device selects its
reference by priority, so automatic is the one mode advertised.  A
profile that sets manual active select is still reported as automatic,
since nothing in the driver drives a manual selection, and probe warns
about it.

Both need somewhere to read from.  The chip reports its state across
several pages, and a netlink call must not turn into a burst of I2C
transactions, so a kthread worker polls the interesting registers twice a
second into a per-input and per-PLL cache, and the callbacks answer from
it.  Output state is not polled: it changes only through a request, and
the getter reads the device again when one could not be confirmed.  The
same tick compares the new state against the old and notifies the core
only on a change; the first tick takes the baseline.  Where a board wires
INTRB, the interrupt schedules that tick immediately rather than
replacing it: the poll stays as the fallback, since this device gives no
way to be sure an edge was not missed.

Which PLL drives an output is read from the PLLs' output-enable masks,
which PLLC and PLLD keep in mirrored bit order.  An output two masks
claim goes to the first PLL, with a warning.

The clock_id that keys a device in the DPLL core is built from the SiTime
OUI and the part's position: sixteen bits of the I2C bus number and the
address.  Bus numbers are not bounded by the number of adapters -- a DT
alias or a mux child can number a bus 256 or above on a board with a
handful of them -- so the bus gets the width; the variant needs no field,
since one address on one bus holds one part.

Signed-off-by: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
Assisted-by: LLM
Signed-off-by: Ali Rouhi <arouhi@sitime.com>
---
 drivers/dpll/sit9531x/Kconfig  |    4 +
 drivers/dpll/sit9531x/Makefile |    2 +-
 drivers/dpll/sit9531x/core.c   | 1763 ++++++++++++++++++++++++++++++--
 drivers/dpll/sit9531x/core.h   |  258 ++++-
 drivers/dpll/sit9531x/dpll.c   |  411 ++++++++
 drivers/dpll/sit9531x/dpll.h   |   68 ++
 drivers/dpll/sit9531x/regs.h   |  259 ++++-
 7 files changed, 2671 insertions(+), 94 deletions(-)
 create mode 100644 drivers/dpll/sit9531x/dpll.c
 create mode 100644 drivers/dpll/sit9531x/dpll.h

diff --git a/drivers/dpll/sit9531x/Kconfig b/drivers/dpll/sit9531x/Kconfig
index ac5b7f31a034..47aea8674327 100644
--- a/drivers/dpll/sit9531x/Kconfig
+++ b/drivers/dpll/sit9531x/Kconfig
@@ -9,5 +9,9 @@ config SIT9531X_DPLL
 	  Driver for SiTime SiT9531x family clock generators
 	  (SiT95317, SiT95316).
 
+	  This driver registers each on-chip PLL as a DPLL device
+	  and exposes input/output clocks as DPLL pins, providing
+	  runtime configuration via Generic Netlink.
+
 	  To compile this driver as a module, choose M here: the
 	  module will be called sit9531x.
diff --git a/drivers/dpll/sit9531x/Makefile b/drivers/dpll/sit9531x/Makefile
index 819af61123f5..b97d2656a460 100644
--- a/drivers/dpll/sit9531x/Makefile
+++ b/drivers/dpll/sit9531x/Makefile
@@ -1,4 +1,4 @@
 # SPDX-License-Identifier: GPL-2.0-only
 
 obj-$(CONFIG_SIT9531X_DPLL) += sit9531x.o
-sit9531x-y := core.o prop.o
+sit9531x-y := core.o dpll.o prop.o
diff --git a/drivers/dpll/sit9531x/core.c b/drivers/dpll/sit9531x/core.c
index c7c14442df92..d2a863ceeb26 100644
--- a/drivers/dpll/sit9531x/core.c
+++ b/drivers/dpll/sit9531x/core.c
@@ -6,9 +6,11 @@
  * Author: Ali Rouhi <arouhi@sitime.com>
  * Author: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
  *
- * I2C probe, paged regmap configuration and register access helpers.
+ * Core I2C probe, regmap configuration, hardware state management,
+ * and periodic work thread.
  */
 
+#include <linux/bitfield.h>
 #include <linux/bits.h>
 #include <linux/clk.h>
 #include <linux/delay.h>
@@ -16,14 +18,31 @@
 #include <linux/device.h>
 #include <linux/gpio/consumer.h>
 #include <linux/i2c.h>
+#include <linux/interrupt.h>
 #include <linux/kernel.h>
+#include <linux/kthread.h>
 #include <linux/module.h>
+#include <linux/pm.h>
 #include <linux/property.h>
 #include <linux/regmap.h>
+#include <linux/slab.h>
+#include <linux/string.h>
 
 #include "core.h"
+#include "dpll.h"
+#include "prop.h"
 #include "regs.h"
 
+/*
+ * Number of input + output pin positions for pin index allocation.  The two
+ * extra input positions are the crystal and the INTSYNC destination, the
+ * extra output position is the INTSYNC source.
+ */
+#define SIT9531X_NUM_INPUT_PINS		(SIT9531X_MAX_INPUTS + 2)
+#define SIT9531X_NUM_OUTPUT_PINS	(SIT9531X_MAX_OUTPUTS + 1)
+#define SIT9531X_NUM_PINS_TOTAL		(SIT9531X_NUM_INPUT_PINS + \
+					 SIT9531X_NUM_OUTPUT_PINS)
+
 #define SIT9531X_CHIP(_id, _nin, _nout, _name, _map) \
 	{ .id = (_id), .num_inputs = (_nin), .num_outputs = (_nout), \
 	  .name = (_name), .clkout_map = (_map) }
@@ -50,8 +69,9 @@ static const struct sit9531x_chip_info sit9531x_chip_ids[] = {
  *
  * The cached value is only as good as the last transfer, though.  A
  * transfer that fails can leave the part on another page than the cache
- * records, so every accessor drops the entry on an error and the next
- * access reads the selector again.
+ * records, and a part that lost power across suspend is back on page 0.
+ * Every accessor drops the entry on an error and resume drops it too, so
+ * the next access reads the selector again.
  */
 static bool sit9531x_volatile_reg(struct device *dev __maybe_unused,
 				  unsigned int reg)
@@ -193,109 +213,1675 @@ int sit9531x_update_pll_u8(struct sit9531x_dev *sitdev, u8 pll_idx,
 	return rc;
 }
 
-static int sit9531x_read_variant_id(struct sit9531x_dev *sitdev, u8 *id)
+/*
+ * sit9531x_input_get_regs - get force mask and state register addresses
+ * @index:	logical input index
+ * @force_reg:	output force mask register address
+ * @state_reg:	output state register address
+ *
+ * Selects the correct Page 0x02 register pair based on the pair's
+ * signal mode and the lane (P/N) the index refers to.
+ */
+static void sit9531x_input_get_regs(const struct sit9531x_dev *sitdev,
+				    u8 index,
+				    unsigned int *force_reg,
+				    unsigned int *state_reg)
 {
-	return sit9531x_read_u8(sitdev, SIT9531X_REG_VARIANT_ID, id);
+	if (sitdev->ref[index].sig_mode == SIT9531X_MODE_DE) {
+		*force_reg = SIT9531X_REG_IN_DE_FORCE;
+		*state_reg = SIT9531X_REG_IN_DE_STATE;
+	} else if (sit9531x_input_is_n(index)) {
+		*force_reg = SIT9531X_REG_IN_SEN_FORCE;
+		*state_reg = SIT9531X_REG_IN_SEN_STATE;
+	} else {
+		*force_reg = SIT9531X_REG_IN_SEP_FORCE;
+		*state_reg = SIT9531X_REG_IN_SEP_STATE;
+	}
 }
 
-static const struct sit9531x_chip_info *sit9531x_match_variant(u8 id)
+/*
+ * Output enable / disable (Hi-Z control)
+ *
+ * SiT9531x outputs can be configured as differential (DIFF) or
+ * single-ended (CMOS) depending on the factory blob.  Each output slot
+ * has THREE Hi-Z force/state register pairs on Page 0x03: one for the
+ * differential path and one for each CMOS pad, OutP and OutN.
+ *
+ * A mute writes all three so the output goes quiet however it is wired.
+ * That includes both CMOS pads, as SiTime's Output_Disable_Control_HiZ.py
+ * does: the register map names bit 3 of ODRn_MISC0 CMOS_ENP and bit 2
+ * CMOS_ENN, while its table of values gives 0100 as CMOS on OutP, so the
+ * one pad a single-ended configuration drives cannot be told from it.
+ *
+ *   slot 0-7 :
+ *     DIFF 0xF2/0xF3   CMOS OutP 0xF8/0xF9   CMOS OutN 0xF6/0xF7
+ *   slot 8-11:
+ *     DIFF 0xF4/0xF5 bits 3:0   CMOS OutP 0xFA/0xFB
+ *     CMOS OutN 0xF4/0xF5 bits 7:4
+ *
+ * MASK bit = 1  -> driver takes control of that output's Hi-Z state
+ * STATE bit = 0 -> output is forced to Hi-Z (muted)
+ * STATE bit = 1 -> output is driven (active)
+ *
+ * The output "index" in the driver is logical; the physical slot comes
+ * from info->clkout_map[].
+ */
+
+enum {
+	SIT9531X_HIZ_DIFF,
+	SIT9531X_HIZ_CMOS_P,
+	SIT9531X_HIZ_CMOS_N,
+	SIT9531X_HIZ_PAIRS,
+};
+
+struct sit9531x_hiz_pair {
+	unsigned int mask;
+	unsigned int state;
+	u8 bit;
+};
+
+static void sit9531x_output_get_hiz_regs(u8 slot,
+					 struct sit9531x_hiz_pair *p)
 {
-	unsigned int i;
+	struct sit9531x_hiz_pair *diff = &p[SIT9531X_HIZ_DIFF];
+	struct sit9531x_hiz_pair *cmos_p = &p[SIT9531X_HIZ_CMOS_P];
+	struct sit9531x_hiz_pair *cmos_n = &p[SIT9531X_HIZ_CMOS_N];
 
-	for (i = 0; i < ARRAY_SIZE(sit9531x_chip_ids); i++) {
-		if (sit9531x_chip_ids[i].id == id)
-			return &sit9531x_chip_ids[i];
+	if (slot <= 7) {
+		diff->mask = SIT9531X_REG_HIZ_DIFF_07_MASK;
+		diff->state = SIT9531X_REG_HIZ_DIFF_07_STATE;
+		diff->bit = slot;
+		cmos_p->mask = SIT9531X_REG_HIZ_SE_07_MASK;
+		cmos_p->state = SIT9531X_REG_HIZ_SE_07_STATE;
+		cmos_p->bit = slot;
+		cmos_n->mask = SIT9531X_REG_HIZ_SEN_07_MASK;
+		cmos_n->state = SIT9531X_REG_HIZ_SEN_07_STATE;
+		cmos_n->bit = slot;
+	} else {
+		diff->mask = SIT9531X_REG_HIZ_DIFF_811_MASK;
+		diff->state = SIT9531X_REG_HIZ_DIFF_811_STATE;
+		diff->bit = slot - 8;
+		cmos_p->mask = SIT9531X_REG_HIZ_SE_811_MASK;
+		cmos_p->state = SIT9531X_REG_HIZ_SE_811_STATE;
+		cmos_p->bit = slot - 8;
+		cmos_n->mask = SIT9531X_REG_HIZ_DIFF_811_MASK;
+		cmos_n->state = SIT9531X_REG_HIZ_DIFF_811_STATE;
+		cmos_n->bit = slot - 8 + SIT9531X_HIZ_SEN_811_SHIFT;
 	}
+}
 
-	return NULL;
+/*
+ * sit9531x_output_mode_fetch - read how an output is wired
+ *
+ * The Hi-Z force is a separate register pair for the differential path
+ * and for each CMOS pad, and only the pairs belonging to the way the
+ * output is actually wired say anything about whether it is quiet.  The
+ * others hold whatever the loaded configuration left in them.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static int sit9531x_output_mode_fetch(struct sit9531x_dev *sitdev, u8 out_idx)
+{
+	const struct sit9531x_chip_info *info = sitdev->info;
+	u8 slot, page, reg, val;
+	int rc;
+
+	slot = info->clkout_map[out_idx];
+	page = (slot > SIT9531X_PAGE_OUTSYS0_SLOT_MAX) ?
+		SIT9531X_PAGE_OUTSYS1 : SIT9531X_PAGE_OUTSYS0;
+	reg = SIT9531X_OUT_MISC0_BASE +
+	      SIT9531X_OUT_MISC0_STRIDE * (slot % 6);
+
+	rc = sit9531x_read_u8(sitdev, SIT9531X_REG(page, reg), &val);
+	if (rc)
+		return rc;
+
+	sitdev->out[out_idx].cmos = !!(val & (SIT9531X_OUT_CMOS_ENP |
+					      SIT9531X_OUT_CMOS_ENN));
+
+	return 0;
 }
 
-int sit9531x_dev_probe(struct sit9531x_dev *sitdev)
+static int sit9531x_hiz_pair_forced(struct sit9531x_dev *sitdev,
+				    const struct sit9531x_hiz_pair *p,
+				    bool *forced)
 {
-	struct clk *xtal_clk;
-	u8 variant_id;
+	u8 mask, state;
+	int rc;
+
+	rc = sit9531x_read_u8(sitdev, p->mask, &mask);
+	if (rc)
+		return rc;
+	rc = sit9531x_read_u8(sitdev, p->state, &state);
+	if (rc)
+		return rc;
+
+	*forced = (mask & BIT(p->bit)) && !(state & BIT(p->bit));
+
+	return 0;
+}
+
+/*
+ * Report whether a slot is currently forced into Hi-Z, i.e. the driver
+ * (or the loaded profile) took control of the pin (MASK bit set) and
+ * forces it to Hi-Z (STATE bit clear).  Only the pairs that match how
+ * the output is wired are read: that is what controls the pad.  A CMOS
+ * output reads as muted only when both of its pads are forced, since
+ * which one the configuration drives cannot be told (see above).
+ */
+static int sit9531x_output_forced_hiz(struct sit9531x_dev *sitdev,
+				      u8 out_idx, bool *muted)
+{
+	struct sit9531x_hiz_pair p[SIT9531X_HIZ_PAIRS];
 	int rc;
 
+	sit9531x_output_get_hiz_regs(sitdev->info->clkout_map[out_idx], p);
+
 	/*
-	 * Fvco = Fref * (DIVN + frac/2^32) with Fref derived from the XO
-	 * feeding XIN/XO_CLK, so the rate is needed before anything can be
-	 * computed from a divider.  The rate normally comes from a "clocks"
-	 * phandle (clock-names = "xtal").  On platforms where the firmware
-	 * does not expose the XO through the clock framework, fall back to
-	 * a "clock-frequency" device property.
+	 * Testing a pair the output is not wired through and taking it as
+	 * proof of a mute answers from a register nothing drives, and
+	 * disagrees with itself when a mute lands on one pair and fails
+	 * on another.
 	 */
-	xtal_clk = devm_clk_get_optional_enabled(sitdev->dev, "xtal");
-	if (IS_ERR(xtal_clk))
-		return dev_err_probe(sitdev->dev, PTR_ERR(xtal_clk),
-				     "Failed to get xtal clock\n");
-	sitdev->xtal_freq = clk_get_rate(xtal_clk);
-	if (!sitdev->xtal_freq) {
-		u32 freq;
+	if (!sitdev->out[out_idx].cmos)
+		return sit9531x_hiz_pair_forced(sitdev,
+						&p[SIT9531X_HIZ_DIFF], muted);
 
-		if (!device_property_read_u32(sitdev->dev, "clock-frequency",
-					      &freq))
-			sitdev->xtal_freq = freq;
+	rc = sit9531x_hiz_pair_forced(sitdev, &p[SIT9531X_HIZ_CMOS_P], muted);
+	if (rc || !*muted)
+		return rc;
+
+	return sit9531x_hiz_pair_forced(sitdev, &p[SIT9531X_HIZ_CMOS_N],
+					muted);
+}
+
+/*
+ * Input priority selection
+ *
+ * The SiT9531x has an 11-slot priority table per PLL on Page 1.  Each
+ * register holds two slots nibble-packed: the earlier (even, 2n) slot
+ * in [7:4] and the later (odd, 2n+1) slot in [3:0].
+ *
+ * The procedure:
+ *   1. Force PLL into holdover (PLL page reg 0x6F bit 4)
+ *   2. Write priority slots on Page 1
+ *   3. Small change update (Page 0 reg 0x0F bit 1)
+ *   4. Release holdover
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+
+/* Page-1 register holding priority slot @slot of @pll_idx. */
+static u16 sit9531x_prio_reg(u8 pll_idx, u8 slot)
+{
+	return SIT9531X_REG(SIT9531X_PAGE_PRIOSYS,
+			    SIT9531X_PRIO_BASE_REG +
+			    SIT9531X_PRIO_REGS_PER_PLL * pll_idx +
+			    slot / SIT9531X_PRIO_SLOTS_PER_REG);
+}
+
+/*
+ * Extract priority slot @slot from its register value.  The register
+ * holding slots 2n and 2n+1 keeps the earlier slot in the high nibble
+ * (CLK_SPARE<2n>SEL) and the later one in the low nibble.
+ */
+static u8 sit9531x_prio_slot_get(u8 val, u8 slot)
+{
+	if (slot & 1)
+		return val & SIT9531X_PRIO_NIBBLE_MASK;
+
+	return val >> SIT9531X_PRIO_HI_SHIFT;
+}
+
+/*
+ * Rebuild a PLL's membership mask from the source codes of its priority
+ * table.  The mask is what the pin state getters test, so it is refreshed
+ * from exactly the values the table holds -- here after a write, and once
+ * per poll from the read-back in sit9531x_chan_state_fetch().
+ */
+static void sit9531x_prio_mask_build(struct sit9531x_dev *sitdev, u8 pll_idx,
+				     const u8 *srcs)
+{
+	u16 mask = 0;
+	u8 slot;
+
+	for (slot = 0; slot < SIT9531X_PRIO_MAX_SLOTS; slot++) {
+		u8 src = srcs[slot] & SIT9531X_PRIO_NIBBLE_MASK;
+
+		if (sit9531x_prio_src_usable(src))
+			mask |= BIT(src);
 	}
-	if (!sitdev->xtal_freq)
-		return dev_err_probe(sitdev->dev, -EINVAL,
-				     "no xtal rate: provide clocks=<&xo> + clock-names=\"xtal\", or a clock-frequency property\n");
+
+	sitdev->chan[pll_idx].prio_mask = mask;
+}
+
+/*
+ * sit9531x_prio_table_read - read a PLL's priority-table source codes
+ * @srcs:	output array of SIT9531X_PRIO_MAX_SLOTS source codes
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static int sit9531x_prio_table_read(struct sit9531x_dev *sitdev, u8 pll_idx,
+				    u8 *srcs)
+{
+	u8 val, slot;
+	int rc;
+
+	for (slot = 0; slot < SIT9531X_PRIO_MAX_SLOTS; slot++) {
+		rc = sit9531x_read_u8(sitdev,
+				      sit9531x_prio_reg(pll_idx, slot), &val);
+		if (rc)
+			return rc;
+
+		srcs[slot] = sit9531x_prio_slot_get(val, slot);
+	}
+
+	return 0;
+}
+
+/* XO doubler register */
+#define SIT9531X_REG_XO2_GENERIC		SIT9531X_REG(0x00, 0x2D)
+#define SIT9531X_XO_DOUBLER_ENB_BIT		7   /* inverted: 0 = enabled */
+
+/* VCO frequency bands (Hz) */
+#define SIT9531X_FVCO_LOWBAND_MIN		4915200000ULL
+#define SIT9531X_FVCO_LOWBAND_MAX		5898240000ULL
+#define SIT9531X_FVCO_HIGHBAND_MIN		6875000000ULL
+#define SIT9531X_FVCO_HIGHBAND_MAX		7812500000ULL
+
+/* The output divider is a 34-bit field */
+#define SIT9531X_DIVO_MAX			GENMASK_ULL(33, 0)
+
+/*
+ * Phase adjust (PRG_RST_DELAY register-based).
+ *
+ * The chip exposes a per-output 34-bit coarse delay measured in VCO
+ * clock periods plus a 3-bit fine delay in fixed 30 ps steps.  The
+ * five bytes PROG6..PROG2 hold the field across registers:
+ *   base + 0  PROG6  [7:5] OPSTG_VCASC_BUMP (preserved via RMW)
+ *                    [4:2] PRG_RST_FINE_DELAY
+ *                    [1:0] PRG_RST_DELAY[33:32]
+ *   base + 1  PROG5  PRG_RST_DELAY[31:24]
+ *   base + 2  PROG4  PRG_RST_DELAY[23:16]
+ *   base + 3  PROG3  PRG_RST_DELAY[15:8]
+ *   base + 4  PROG2  PRG_RST_DELAY[7:0]
+ *
+ * Outputs 0-5 live on Page 3, outputs 6-11 on Page 4, with each
+ * output's block at base = 0x15 + 16 * (out_idx % 6).
+ *
+ * The chip only supports unsigned positive delay.  A negative phase
+ * adjustment (advance) is wrapped to (T_out - |phase|) modulo one
+ * output period, which is identical for a periodic signal.
+ */
+
+/*
+ * sit9531x_clear_notifications - clear all notification registers
+ *
+ * Clears all write-1-to-clear notification registers:
+ *   - PLL outer LOL notification (Page 0, reg 0x07)
+ *   - PLL holdover freeze notification (Page 0, reg 0x0B)
+ *   - PLL inner LOL notification (Page 0, reg 0x93)
+ *   - Clock monitor XO/PLL notification (Page 0, reg 0x9E)
+ *   - Clock input notifications (Page 6, regs 0x03/0x07/0x93/0x97)
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+int sit9531x_clear_notifications(struct sit9531x_dev *sitdev)
+{
+	int rc;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	/* Page 0x00 W1C notification registers */
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_OUTER_LOL_NOTIF, 0xFF);
+	if (rc)
+		return rc;
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_HO_FREEZE_NOTIF, 0xFF);
+	if (rc)
+		return rc;
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_PLL_INNER_LOL_NOTIF, 0xFF);
+	if (rc)
+		return rc;
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_CMON_NOTIF, 0xFF);
+	if (rc)
+		return rc;
+
+	/* Page 0x06 clock input monitor notifications */
+	rc = sit9531x_write_u8(sitdev, SIT9531X_CLKMON_P_NOTIF_01, 0xFF);
+	if (rc)
+		return rc;
+	rc = sit9531x_write_u8(sitdev, SIT9531X_CLKMON_P_NOTIF_23, 0xFF);
+	if (rc)
+		return rc;
+	rc = sit9531x_write_u8(sitdev, SIT9531X_CLKMON_N_NOTIF_01, 0xFF);
+	if (rc)
+		return rc;
+	rc = sit9531x_write_u8(sitdev, SIT9531X_CLKMON_N_NOTIF_23, 0xFF);
+	if (rc)
+		return rc;
+
+	dev_dbg(sitdev->dev, "All notification registers cleared\n");
+	return 0;
+}
+
+/*
+ * sit9531x_ref_state_fetch - read input reference status from hardware
+ * @index:	logical input index
+ *
+ * Reads whether the lane's receiver is on, from the Page 0x02 force and
+ * state bits.
+ */
+static int sit9531x_ref_state_fetch(struct sit9531x_dev *sitdev, u8 index)
+{
+	unsigned int force_reg, state_reg;
+	u8 pair, force, state;
+	struct sit9531x_ref *ref;
+	int rc;
 
 	/*
-	 * Held deasserted, never pulsed: the chip configuration comes from
-	 * efuse or an NVM blob applied before probe, and a reset would
-	 * discard it.  Must precede the first I2C access, as a board that
-	 * powers up asserted keeps the chip unreachable until released.
+	 * The XTAL/XO reference (index SIT9531X_MAX_INPUTS) is the on-chip
+	 * oscillator that feeds every PLL.  It cannot be routed or deselected,
+	 * so its pin is modeled as permanently connected (see
+	 * sit9531x_dpll_xo_pin_ops) and has no receiver to gate.  Only the
+	 * routable per-lane inputs (0..num_inputs-1) are polled here.
 	 */
-	sitdev->reset_gpio = devm_gpiod_get_optional(sitdev->dev, "reset",
-						     GPIOD_OUT_LOW);
-	if (IS_ERR(sitdev->reset_gpio))
-		return dev_err_probe(sitdev->dev, PTR_ERR(sitdev->reset_gpio),
-				     "Failed to request reset gpio\n");
-	if (sitdev->reset_gpio)
-		fsleep(10000);	/* internal boot after release */
+	if (index >= SIT9531X_MAX_INPUTS)
+		return -EINVAL;
 
-	rc = sit9531x_read_variant_id(sitdev, &variant_id);
+	ref = &sitdev->ref[index];
+	pair = sit9531x_input_pair(index);
+
+	/*
+	 * Whether the receiver is on.  This has to come from the chip: it
+	 * is the loaded configuration that decides, and without reading it
+	 * back every input would look disabled until something called
+	 * sit9531x_input_enable().  A lane counts as disabled only while
+	 * the force bit overrides it to the off state; with the force bit
+	 * clear it follows the configuration, which is the enabled case.
+	 */
+	sit9531x_input_get_regs(sitdev, index, &force_reg, &state_reg);
+
+	rc = sit9531x_read_u8(sitdev, force_reg, &force);
+	if (rc)
+		return rc;
+	rc = sit9531x_read_u8(sitdev, state_reg, &state);
 	if (rc)
 		return rc;
 
-	sitdev->info = sit9531x_match_variant(variant_id);
-	if (!sitdev->info)
-		return dev_err_probe(sitdev->dev, -ENODEV,
-				     "Unknown variant ID: 0x%02x\n",
-				     variant_id);
+	ref->enabled = !((force & BIT(pair)) && !(state & BIT(pair)));
 
-	rc = devm_mutex_init(sitdev->dev, &sitdev->multiop_lock);
+	return 0;
+}
+
+/*
+ * sit9531x_input_mode_fetch - detect SE/DE configuration of an input pair
+ * @pair:	input pair number (0-3)
+ *
+ * Reads CLKINx_INPUT_MODE and stores the detected signal mode on both
+ * lanes of the pair.  A pair with neither SE lane enabled is running
+ * differential.
+ */
+static int sit9531x_input_mode_fetch(struct sit9531x_dev *sitdev, u8 pair)
+{
+	enum sit9531x_signal_mode sig_mode;
+	u8 mode;
+	int rc;
+
+	rc = sit9531x_read_u8(sitdev, SIT9531X_REG_IN_MODE(pair), &mode);
 	if (rc)
-		return dev_err_probe(sitdev->dev, rc,
-				     "Failed to initialize mutex\n");
+		return rc;
 
-	dev_info(sitdev->dev, "%s detected, %u inputs, %u outputs\n",
-		 sitdev->info->name, sitdev->info->num_inputs,
-		 sitdev->info->num_outputs);
+	if (mode & (SIT9531X_IN_MODE_SE_P_EN | SIT9531X_IN_MODE_SE_N_EN))
+		sig_mode = SIT9531X_MODE_SE;
+	else
+		sig_mode = SIT9531X_MODE_DE;
+
+	sitdev->ref[pair * 2].sig_mode = sig_mode;
+	sitdev->ref[pair * 2 + 1].sig_mode = sig_mode;
+
+	dev_dbg(sitdev->dev, "CLKIN%u mode reg 0x%02x -> %s\n", pair, mode,
+		sig_mode == SIT9531X_MODE_DE ? "differential" : "single-ended");
 
 	return 0;
 }
 
-static int sit9531x_i2c_probe(struct i2c_client *client)
+/* Read the PLL active-state bit (PLL page reg 0x02 bit 0). */
+static int sit9531x_pll_is_active(struct sit9531x_dev *sitdev, u8 pll_idx,
+				  bool *active)
 {
-	struct sit9531x_dev *sitdev;
-	struct regmap *regmap;
+	u8 v;
+	int rc;
 
-	regmap = devm_regmap_init_i2c(client, &sit9531x_regmap_config);
-	if (IS_ERR(regmap))
-		return dev_err_probe(&client->dev, PTR_ERR(regmap),
-				     "Failed to initialize regmap\n");
+	rc = sit9531x_read_pll_u8(sitdev, pll_idx, SIT9531X_PLL_REG_ACTIVE, &v);
+	if (rc)
+		return rc;
 
-	sitdev = devm_kzalloc(&client->dev, sizeof(*sitdev), GFP_KERNEL);
-	if (!sitdev)
-		return -ENOMEM;
+	*active = !!(v & SIT9531X_PLL_ACTIVE_BIT);
 
-	sitdev->dev = &client->dev;
-	sitdev->client = client;
-	sitdev->regmap = regmap;
-	i2c_set_clientdata(client, sitdev);
+	return 0;
+}
 
-	return sit9531x_dev_probe(sitdev);
+/*
+ * sit9531x_chan_state_fetch - read PLL channel status from hardware
+ *
+ * Reads whether the PLL runs, its lock and holdover state, its mode, the
+ * active selection and its priority table.
+ */
+static int sit9531x_chan_state_fetch(struct sit9531x_dev *sitdev, u8 pll_idx)
+{
+	u8 status, outer_lol, input_sel, inner_lol, ho_freeze, activesel_reg;
+	struct sit9531x_chan *chan = &sitdev->chan[pll_idx];
+	u8 srcs[SIT9531X_PRIO_MAX_SLOTS];
+	u8 pll_status_1;
+	bool active;
+	int rc;
+
+	/*
+	 * Whether the PLL is running at all.  The loss-of-lock bit read
+	 * below is driven by the PLL itself, so on one the loaded
+	 * configuration leaves unused it simply stays clear and would
+	 * otherwise read as a lock.
+	 */
+	rc = sit9531x_pll_is_active(sitdev, pll_idx, &active);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+				  SIT9531X_PLL_REG_STATUS, &status);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_read_u8(sitdev, SIT9531X_REG_OUTER_LOL_STATUS,
+			      &outer_lol);
+	if (rc)
+		return rc;
+
+	/*
+	 * Read the input source the PLL has currently selected as its
+	 * active reference.  This lives in the low nibble of the last
+	 * register of the PLL's page-1 priority block (CLK_ACTIVESEL_PLL),
+	 * not on the PLL page -- PLL-page 0x29 is a config register.
+	 */
+	activesel_reg = SIT9531X_PRIO_BASE_REG +
+			SIT9531X_PRIO_REGS_PER_PLL * pll_idx +
+			SIT9531X_PRIO_ACTIVESEL_OFF;
+	rc = sit9531x_read_u8(sitdev,
+			      SIT9531X_REG(SIT9531X_PAGE_PRIOSYS,
+					   activesel_reg),
+			      &input_sel);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_read_u8(sitdev, SIT9531X_REG_PLL_INNER_LOL_STATUS,
+			      &inner_lol);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_read_u8(sitdev, SIT9531X_REG_HO_FREEZE_STATUS,
+			      &ho_freeze);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_read_pll_u8(sitdev, pll_idx, SIT9531X_PLL_REG_STATUS_1,
+				  &pll_status_1);
+	if (rc)
+		return rc;
+
+	/*
+	 * Which sources this PLL may select.  The table is configuration and
+	 * changes only through the driver, but reading it back keeps the
+	 * membership the pin state getters report tied to the hardware
+	 * instead of to a value the driver maintains on the side.
+	 */
+	rc = sit9531x_prio_table_read(sitdev, pll_idx, srcs);
+	if (rc)
+		return rc;
+
+	sit9531x_prio_mask_build(sitdev, pll_idx, srcs);
+
+	/* STATUS_1_GENERIC reports loss of lock, so invert it. */
+	chan->active = active;
+	chan->locked = active && !(outer_lol & BIT(pll_idx));
+	chan->mode = !!(status & SIT9531X_PLL_STATUS_OUTER_DIS);
+	chan->selected_ref =
+		sit9531x_hw_src_input(input_sel & SIT9531X_PRIO_NIBBLE_MASK);
+	chan->inner_lol = !!(inner_lol & BIT(pll_idx));
+	chan->ho_freeze = !!(ho_freeze & BIT(pll_idx));
+	chan->ho_valid = !!(pll_status_1 & SIT9531X_PLL_STATUS_1_HO_VALID);
+
+	return 0;
+}
+
+/*
+ * sit9531x_out_state_fetch - read output status from hardware
+ *
+ * Takes the output PLL association from the PLL page output map
+ * registers into out->routed / out->pll_idx, and the current drive state
+ * from the Hi-Z force bits into out->enabled.  The two are separate:
+ * routing decides whether the output gets a DPLL pin at all,
+ * while a muted but routed output keeps its pin and reports
+ * DPLL_PIN_STATE_DISCONNECTED until it is un-muted.
+ */
+static int sit9531x_out_state_fetch(struct sit9531x_dev *sitdev, u8 index)
+{
+	struct sit9531x_out *out = &sitdev->out[index];
+	u8 map_lo, map_hi, slot, bit, claimed;
+	int pll_idx;
+	u16 mask;
+	bool muted;
+	int rc;
+
+	slot = sitdev->info->clkout_map[index];
+
+	rc = sit9531x_output_mode_fetch(sitdev, index);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_output_forced_hiz(sitdev, index, &muted);
+	if (rc)
+		return rc;
+
+	/*
+	 * Each PLL page holds the PLL's output-enable mask, twelve bits:
+	 * bits 0-7 in OUT_MAP_LO and bits 8-11 in OUT_MAP_HI[3:0].  PLLA and
+	 * PLLB keep OUTn at bit n; PLLC and PLLD keep the outputs in mirrored
+	 * order, OUTn at bit 11 - n, as SiTime's procedure scripts read
+	 * them.  The index is the physical output the pin drives, not
+	 * the driver's logical one (translated above via the chip-info
+	 * clkout_map[]: identity on SiT95316, non-contiguous on SiT95317).
+	 *
+	 * An output belongs to one PLL.  Take the first that claims it, and
+	 * say so if another does too.
+	 */
+	claimed = 0;
+	for (pll_idx = 0; pll_idx < SIT9531X_NUM_PLLS; pll_idx++) {
+		rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+					  SIT9531X_PLL_REG_OUT_MAP_LO, &map_lo);
+		if (rc)
+			return rc;
+
+		rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+					  SIT9531X_PLL_REG_OUT_MAP_HI, &map_hi);
+		if (rc)
+			return rc;
+
+		mask = map_lo | (map_hi & GENMASK(3, 0)) << 8;
+		bit = pll_idx < 2 ? slot : SIT9531X_MAX_OUTPUTS - 1 - slot;
+		if (mask & BIT(bit))
+			claimed |= BIT(pll_idx);
+	}
+
+	if (!claimed) {
+		/* Output not mapped to any PLL */
+		out->pll_idx = 0;
+		out->routed = false;
+		out->enabled = false;
+		return 0;
+	}
+
+	out->pll_idx = __ffs(claimed);
+	out->routed = true;
+	out->enabled = !muted;
+
+	if (claimed & (claimed - 1))
+		dev_warn(sitdev->dev,
+			 "OUT%u is in the output-enable mask of more than one PLL (0x%x); taking PLL%c\n",
+			 slot, claimed, 'A' + out->pll_idx);
+
+	return 0;
+}
+
+/*
+ * sit9531x_ref_pll_mask_fetch - seed the input-to-PLL usage masks
+ *
+ * ref->pll_mask is the refcount the disconnect path uses to decide when
+ * an input receiver may be powered down: the physical input is only
+ * disabled once the last DPLL has released it.  It therefore has to
+ * start out matching the hardware.  Without this pass every mask starts
+ * at zero, and disconnecting an input from one DPLL drops the mask to
+ * zero and disables a receiver the other DPLLs are still locked to.
+ *
+ * An input is counted for a PLL when it appears in that PLL's Page-1
+ * priority table, which is exactly the condition the connect and
+ * disconnect callbacks maintain.  Sources that are not physical inputs
+ * (OCXO, INTSYNC) and reserved codes are skipped.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static int sit9531x_ref_pll_mask_fetch(struct sit9531x_dev *sitdev)
+{
+	u8 srcs[SIT9531X_PRIO_MAX_SLOTS];
+	u8 pll_idx, slot, index;
+	int rc;
+
+	for (pll_idx = 0; pll_idx < SIT9531X_NUM_PLLS; pll_idx++) {
+		rc = sit9531x_prio_table_read(sitdev, pll_idx, srcs);
+		if (rc)
+			return rc;
+
+		for (slot = 0; slot < SIT9531X_PRIO_MAX_SLOTS; slot++) {
+			index = sit9531x_hw_src_input(srcs[slot]);
+			if (index >= sitdev->info->num_inputs)
+				continue;
+
+			/*
+			 * On a differentially configured pair only the P lane
+			 * has a DPLL pin, so that is the lane the connect and
+			 * disconnect callbacks account for.  Fold an N-lane
+			 * table entry onto its P lane, otherwise the count
+			 * would land on a lane nothing ever releases.  The
+			 * signaling mode is already known here:
+			 * sit9531x_input_mode_fetch() runs first.
+			 */
+			if (sit9531x_input_is_n(index) &&
+			    sitdev->ref[index].sig_mode == SIT9531X_MODE_DE)
+				index--;
+
+			sitdev->ref[index].pll_mask |= BIT(pll_idx);
+		}
+	}
+
+	return 0;
+}
+
+/*
+ * sit9531x_dev_state_fetch - read all hardware state at startup
+ *
+ * Called once during probe to populate the initial state cache.
+ */
+static int sit9531x_dev_state_fetch(struct sit9531x_dev *sitdev)
+{
+	int rc;
+	u8 i;
+
+	/* Detect SE/DE configuration before any per-lane access */
+	for (i = 0; i < sitdev->info->num_inputs / 2; i++) {
+		rc = sit9531x_input_mode_fetch(sitdev, i);
+		if (rc) {
+			dev_err(sitdev->dev,
+				"Failed to fetch CLKIN%u mode: %d\n", i, rc);
+			return rc;
+		}
+	}
+
+	for (i = 0; i < sitdev->info->num_inputs; i++) {
+		rc = sit9531x_ref_state_fetch(sitdev, i);
+		if (rc) {
+			dev_err(sitdev->dev,
+				"Failed to fetch input %u state: %d\n", i, rc);
+			return rc;
+		}
+	}
+
+	/*
+	 * The priority-table read walks the Page-1 registers, so it runs
+	 * with multiop_lock held like every other multi-register sequence.
+	 * Nothing can race with it here -- the DPLLs are not registered and
+	 * the monitor is not running yet -- but the page handling stays
+	 * serialized the same way as at runtime.
+	 */
+	mutex_lock(&sitdev->multiop_lock);
+	rc = sit9531x_ref_pll_mask_fetch(sitdev);
+	mutex_unlock(&sitdev->multiop_lock);
+	if (rc) {
+		dev_err(sitdev->dev,
+			"Failed to fetch input priority tables: %d\n", rc);
+		return rc;
+	}
+
+	for (i = 0; i < sitdev->info->num_outputs; i++) {
+		rc = sit9531x_out_state_fetch(sitdev, i);
+		if (rc) {
+			dev_err(sitdev->dev,
+				"Failed to fetch output %u state: %d\n", i, rc);
+			return rc;
+		}
+	}
+
+	for (i = 0; i < SIT9531X_NUM_PLLS; i++) {
+		rc = sit9531x_chan_state_fetch(sitdev, i);
+		if (rc) {
+			dev_err(sitdev->dev,
+				"Failed to fetch PLL%c state: %d\n",
+				'A' + i, rc);
+			return rc;
+		}
+	}
+
+	return 0;
+}
+
+static void sit9531x_dev_ref_states_update(struct sit9531x_dev *sitdev)
+{
+	int i, rc;
+
+	for (i = 0; i < sitdev->info->num_inputs; i++) {
+		rc = sit9531x_ref_state_fetch(sitdev, i);
+		if (rc)
+			dev_warn(sitdev->dev,
+				 "Failed to get REF%u status: %d\n", i, rc);
+	}
+}
+
+static void sit9531x_dev_chan_states_update(struct sit9531x_dev *sitdev)
+{
+	int i, rc;
+
+	for (i = 0; i < SIT9531X_NUM_PLLS; i++) {
+		rc = sit9531x_chan_state_fetch(sitdev, i);
+		if (rc)
+			dev_warn(sitdev->dev,
+				 "Failed to get PLL%c state: %d\n",
+				 'A' + i, rc);
+	}
+}
+
+/*
+ * sit9531x_dev_periodic_work - periodic hardware state polling
+ * @work:	kthread_work pointer
+ *
+ * Polls hardware state at SIT9531X_STATUS_POLL_MS intervals.
+ * Updates reference and channel states, then delegates change
+ * detection to sit9531x_dpll_changes_check() for each registered DPLL.
+ */
+static void sit9531x_dev_periodic_work(struct kthread_work *work)
+{
+	struct sit9531x_dev *sitdev = container_of(work, struct sit9531x_dev,
+						   work.work);
+	struct sit9531x_dpll *sitdpll;
+	int rc;
+
+	/*
+	 * Update the cached ref[]/chan[] arrays under multiop_lock so the
+	 * fetches are serialized against the DPLL callbacks that read
+	 * these fields and against the chip's page selector.
+	 *
+	 * The lock is then dropped before sit9531x_dpll_changes_check(),
+	 * which calls dpll_pin_change_ntf() / dpll_device_change_ntf().
+	 * Those notification helpers take DPLL-subsystem locks that are
+	 * already held when our callbacks are invoked from netlink
+	 * context, and nesting multiop_lock around them would invert the
+	 * lock order.  changes_check() reads the cache published above,
+	 * which is already consistent.
+	 */
+	mutex_lock(&sitdev->multiop_lock);
+	sit9531x_dev_ref_states_update(sitdev);
+	sit9531x_dev_chan_states_update(sitdev);
+	mutex_unlock(&sitdev->multiop_lock);
+
+	list_for_each_entry(sitdpll, &sitdev->dplls, list)
+		sit9531x_dpll_changes_check(sitdpll);
+
+	/*
+	 * Acknowledge the chip's notification latches after the tick has
+	 * read and acted on them.  Without this, the W1C bits remain set
+	 * and -- on boards that wire INTRB -- the line stays asserted,
+	 * re-firing the threaded handler back to back.  The helper writes
+	 * W1C bits across page 0 and page 6 and must run under
+	 * multiop_lock to serialize the page selector against userspace
+	 * dpll ops.  Failure is non-fatal: status was already consumed
+	 * for this tick and the next tick re-processes whatever stayed
+	 * latched.
+	 */
+	mutex_lock(&sitdev->multiop_lock);
+	rc = sit9531x_clear_notifications(sitdev);
+	mutex_unlock(&sitdev->multiop_lock);
+	if (rc)
+		dev_warn_ratelimited(sitdev->dev,
+				     "Failed to clear notifications: %d\n",
+				     rc);
+
+	/* Run twice a second */
+	kthread_queue_delayed_work(sitdev->kworker, &sitdev->work,
+				   msecs_to_jiffies(SIT9531X_STATUS_POLL_MS));
+}
+
+/*
+ * sit9531x_irq_thread_fn - threaded IRQ handler for the chip's INTRB line
+ *
+ * Triggered when the chip asserts INTRB (and only when DT wires up the
+ * client interrupt; absent property == handler never installed).  The
+ * action mirrors a periodic-work tick: queue an immediate run so status
+ * registers are read and DPLL changes_check fires without waiting for
+ * the next poll deadline.  Polling continues to run as a fallback.
+ */
+static irqreturn_t sit9531x_irq_thread_fn(int irq, void *data)
+{
+	struct sit9531x_dev *sitdev = data;
+	int rc;
+
+	/*
+	 * Acknowledge the chip's notification latches from the threaded
+	 * handler itself.  With IRQF_ONESHOT the line is unmasked on
+	 * return, so deferring the W1C clear to the async kworker would
+	 * let a still-asserted INTRB re-fire immediately (interrupt storm).
+	 * Clear here, then kick the poll worker to read state and run
+	 * changes_check.
+	 */
+	mutex_lock(&sitdev->multiop_lock);
+	rc = sit9531x_clear_notifications(sitdev);
+	mutex_unlock(&sitdev->multiop_lock);
+	if (rc) {
+		dev_warn_ratelimited(sitdev->dev,
+				     "IRQ: failed to clear notifications: %d\n",
+				     rc);
+		/*
+		 * The latch was not acknowledged, so with IRQF_ONESHOT the
+		 * still-asserted line re-enters this handler as soon as it
+		 * returns.  Returning IRQ_NONE leaves that to the spurious
+		 * detector, which needs roughly 100000 interrupts and resets
+		 * its count every tenth of a second -- unreachable when each
+		 * pass costs an I2C timeout.  Give up on the line instead:
+		 * the periodic poll reads the same state without it, so the
+		 * driver keeps working on a board whose INTRB cannot be
+		 * acknowledged.
+		 */
+		if (++sitdev->irq_ack_fails < SIT9531X_IRQ_ACK_TRIES)
+			return IRQ_NONE;
+
+		dev_err(sitdev->dev,
+			"IRQ %d disabled: notifications cannot be cleared, polling only\n",
+			irq);
+		disable_irq_nosync(irq);
+		return IRQ_NONE;
+	}
+
+	sitdev->irq_ack_fails = 0;
+
+	kthread_mod_delayed_work(sitdev->kworker, &sitdev->work, 0);
+	return IRQ_HANDLED;
+}
+
+/*
+ * The driver reports every PLL as selecting by priority.  A profile can
+ * put a PLL in manual active select instead (PLL_CONFIG1F_PLL bit 6), and
+ * the mode userspace sees would then be wrong; say so rather than
+ * reconfigure what the profile chose.  The warning also says what the PLL
+ * then follows: its active selection, or with MISCINNER_PLL bit 5 the
+ * manual input select -- the input-select pins, or the input code that
+ * GPIO_INPUT_FUNC_CTRL5..8 holds when its bit 4 is set.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static void sit9531x_manual_sel_report(struct sit9531x_dev *sitdev)
+{
+	u8 cfg, misc, sel, i;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	for (i = 0; i < SIT9531X_NUM_PLLS; i++) {
+		if (sit9531x_read_pll_u8(sitdev, i, SIT9531X_PLL_REG_CONFIG1F,
+					 &cfg))
+			return;
+		if (!(cfg & SIT9531X_PLL_CONFIG1F_MANUAL_SEL))
+			continue;
+
+		if (sit9531x_read_pll_u8(sitdev, i, SIT9531X_PLL_REG_MISCINNER,
+					 &misc))
+			return;
+		if (!(misc & SIT9531X_PLL_MISCINNER_MAN_IN_SEL)) {
+			dev_warn(sitdev->dev,
+				 "PLL%c: the profile selects its reference manually, following its active selection; it is reported as automatic\n",
+				 'A' + i);
+			continue;
+		}
+
+		if (sit9531x_read_u8(sitdev, SIT9531X_REG_MAN_IN_SEL(i), &sel))
+			return;
+		if (sel & SIT9531X_MAN_IN_SEL_FROM_REG) {
+			sel = FIELD_GET(SIT9531X_MAN_IN_SEL_MASK, sel);
+			dev_warn(sitdev->dev,
+				 "PLL%c: the profile selects its reference manually, input code %u from the register; it is reported as automatic\n",
+				 'A' + i, sel);
+		} else {
+			dev_warn(sitdev->dev,
+				 "PLL%c: the profile selects its reference manually, from the input-select pins; it is reported as automatic\n",
+				 'A' + i);
+		}
+	}
+}
+
+/*
+ * Report what the device loaded from its EEPROM, and warn if it does not
+ * look like a healthy load.
+ *
+ * A profile that failed to load leaves the part running something other
+ * than what the board was designed around -- dividers, output routing
+ * and priority tables all differ -- while every register still reads
+ * back a plausible value.  Naming the profile and saying whether the
+ * load was clean turns that into something visible at startup instead of
+ * something inferred from measurements later.
+ *
+ * This only reports.  Boards in this family may have their
+ * configuration pushed over I2C rather than held in an EEPROM, and there
+ * the CRC pair means nothing, so a mismatch is not grounds for refusing
+ * to drive the device.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static void sit9531x_eeprom_state_report(struct sit9531x_dev *sitdev)
+{
+	u32 rec_crc = 0, cal_crc = 0, prof_id = 0;
+	u8 notif, v;
+	int rc, i;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	/* Profile id: three bytes, least significant first. */
+	for (i = 2; i >= 0; i--) {
+		rc = sit9531x_read_u8(sitdev, SIT9531X_REG_PROFILE_ID + i, &v);
+		if (rc)
+			return;
+		prof_id = prof_id << 8 | v;
+	}
+
+	dev_info(sitdev->dev, "profile id %u\n", prof_id);
+
+	/* Both CRCs: four bytes, most significant first. */
+	for (i = 0; i < 4; i++) {
+		rc = sit9531x_read_u8(sitdev, SIT9531X_REG_REC_CRC + i, &v);
+		if (rc)
+			return;
+		rec_crc = rec_crc << 8 | v;
+
+		rc = sit9531x_read_u8(sitdev, SIT9531X_REG_CAL_CRC + i, &v);
+		if (rc)
+			return;
+		cal_crc = cal_crc << 8 | v;
+	}
+
+	rc = sit9531x_read_u8(sitdev, SIT9531X_REG_EEPROM_NOTIF, &notif);
+	if (rc)
+		return;
+
+	/*
+	 * A clean load leaves the read-done bit set and every defect bit
+	 * clear.  Both CRCs zero means no EEPROM read happened at all:
+	 * boards in this family may take their configuration over I2C
+	 * instead of an EEPROM, and there the CRC pair means nothing, so
+	 * that case is not a mismatch worth warning about.
+	 */
+	if (!rec_crc && !cal_crc)
+		dev_dbg(sitdev->dev,
+			"no EEPROM profile (configuration pushed over I2C)\n");
+	else if (rec_crc != cal_crc)
+		dev_warn(sitdev->dev,
+			 "EEPROM CRC mismatch: stored %08x, computed %08x\n",
+			 rec_crc, cal_crc);
+	else if (notif != SIT9531X_EEPROM_READ_DONE)
+		dev_warn(sitdev->dev,
+			 "EEPROM read reported defects (notify %02x)\n",
+			 notif);
+	else
+		dev_dbg(sitdev->dev, "EEPROM profile loaded, CRC %08x\n",
+			cal_crc);
+}
+
+/*
+ * Report which PLLs came up, and flag the one case that is a real
+ * inconsistency rather than a configuration choice.
+ *
+ * A PLL the loaded configuration leaves unused never reaches its active
+ * state, which is normal and not worth a warning.  A PLL that has
+ * outputs routed to it and is still not active is different: something
+ * that is meant to be generating clocks is not running, and every value
+ * read from it -- lock state, phase, frequency offset -- describes a
+ * stopped loop.  Say so once at startup rather than leaving it to be
+ * discovered through measurements that quietly read as zero.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static void sit9531x_pll_states_report(struct sit9531x_dev *sitdev)
+{
+	unsigned int idx, i;
+	bool routed;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	for (i = 0; i < SIT9531X_NUM_PLLS; i++) {
+		if (sitdev->chan[i].active) {
+			dev_dbg(sitdev->dev, "PLL%c active\n", 'A' + i);
+			continue;
+		}
+
+		routed = false;
+		for (idx = 0; idx < sitdev->info->num_outputs; idx++) {
+			const struct sit9531x_out *out;
+
+			out = sit9531x_out_state_get(sitdev, idx);
+			if (out->routed && out->pll_idx == i) {
+				routed = true;
+				break;
+			}
+		}
+
+		if (routed)
+			dev_warn(sitdev->dev,
+				 "PLL%c drives outputs but is not in its active state\n",
+				 'A' + i);
+		else
+			dev_dbg(sitdev->dev, "PLL%c unused by the loaded configuration\n",
+				'A' + i);
+	}
+}
+
+/*
+ * sit9531x_dev_start - start normal operation
+ *
+ * Fetches initial hardware state, registers all DPLL devices and
+ * their pins, and starts the periodic monitoring thread.
+ */
+int sit9531x_dev_start(struct sit9531x_dev *sitdev)
+{
+	struct sit9531x_dpll *sitdpll;
+	int rc;
+
+	/* Fetch device state */
+	rc = sit9531x_dev_state_fetch(sitdev);
+	if (rc)
+		return rc;
+
+	mutex_lock(&sitdev->multiop_lock);
+	sit9531x_eeprom_state_report(sitdev);
+	sit9531x_manual_sel_report(sitdev);
+	sit9531x_pll_states_report(sitdev);
+	mutex_unlock(&sitdev->multiop_lock);
+
+	list_for_each_entry(sitdpll, &sitdev->dplls, list) {
+		rc = sit9531x_dpll_register(sitdpll);
+		if (rc) {
+			dev_err_probe(sitdev->dev, rc,
+				      "Failed to register DPLL%u\n",
+				      sitdpll->id);
+			goto err_unregister;
+		}
+	}
+
+	kthread_queue_delayed_work(sitdev->kworker, &sitdev->work, 0);
+
+	return 0;
+
+err_unregister:
+	/*
+	 * Unregister what did register.  The caller frees the list on this
+	 * path, so leaving a DPLL registered would hand the subsystem a
+	 * pointer to freed memory.
+	 */
+	list_for_each_entry_continue_reverse(sitdpll, &sitdev->dplls, list)
+		sit9531x_dpll_unregister(sitdpll);
+
+	return rc;
+}
+
+/*
+ * sit9531x_dev_stop - stop normal operation
+ *
+ * Cancels the monitoring thread and unregisters all DPLL devices
+ * and their pins.
+ */
+void sit9531x_dev_stop(struct sit9531x_dev *sitdev)
+{
+	struct sit9531x_dpll *sitdpll;
+
+	kthread_cancel_delayed_work_sync(&sitdev->work);
+
+	list_for_each_entry(sitdpll, &sitdev->dplls, list) {
+		if (sitdpll->dpll_dev)
+			sit9531x_dpll_unregister(sitdpll);
+	}
+}
+
+static struct sit9531x_dpll_pin *
+sit9531x_dpll_pin_alloc(struct sit9531x_dpll *sitdpll,
+			enum dpll_pin_direction dir, u8 id)
+{
+	struct sit9531x_dpll_pin *pin;
+
+	pin = kzalloc_obj(*pin, GFP_KERNEL);
+	if (!pin)
+		return ERR_PTR(-ENOMEM);
+
+	pin->dpll = sitdpll;
+	pin->dir = dir;
+	pin->id = id;
+
+	return pin;
+}
+
+/*
+ * sit9531x_dpll_pin_register - register a DPLL pin with the subsystem
+ * @index:	absolute pin index for clock_id namespace
+ *
+ * Gets pin properties from firmware, creates or gets a dpll_pin,
+ * and registers it with the parent DPLL device.
+ */
+static int sit9531x_dpll_pin_register(struct sit9531x_dpll_pin *pin,
+				      u32 index)
+{
+	struct sit9531x_dpll *sitdpll = pin->dpll;
+	struct sit9531x_pin_props *props;
+	const struct dpll_pin_ops *ops;
+	int rc;
+
+	props = sit9531x_pin_props_get(sitdpll->dev, pin->dir, pin->id);
+	if (IS_ERR(props))
+		return PTR_ERR(props);
+
+	strscpy(pin->label, props->package_label, sizeof(pin->label));
+	pin->fwnode = fwnode_handle_get(props->fwnode);
+
+	pin->dpll_pin = dpll_pin_get(sitdpll->dev->clock_id, index,
+				     THIS_MODULE, &props->dpll_props,
+				     &pin->tracker);
+	if (IS_ERR(pin->dpll_pin)) {
+		rc = PTR_ERR(pin->dpll_pin);
+		goto err_pin_get;
+	}
+	dpll_pin_fwnode_set(pin->dpll_pin, props->fwnode);
+
+	ops = sit9531x_dpll_pin_ops_get(pin);
+
+	rc = dpll_pin_register(sitdpll->dpll_dev, pin->dpll_pin, ops, pin);
+	if (rc)
+		goto err_register;
+
+	sit9531x_pin_props_put(props);
+
+	return 0;
+
+err_register:
+	dpll_pin_put(pin->dpll_pin, &pin->tracker);
+err_pin_get:
+	/* dpll_pin_get() left an ERR_PTR here. */
+	pin->dpll_pin = NULL;
+	fwnode_handle_put(pin->fwnode);
+	pin->fwnode = NULL;
+	sit9531x_pin_props_put(props);
+
+	return rc;
+}
+
+static void sit9531x_dpll_pin_unregister(struct sit9531x_dpll_pin *pin)
+{
+	struct sit9531x_dpll *sitdpll = pin->dpll;
+	struct dpll_pin *dpll_pin = pin->dpll_pin;
+	const struct dpll_pin_ops *ops;
+
+	ops = sit9531x_dpll_pin_ops_get(pin);
+
+	/*
+	 * Clear the pointer before the subsystem is told to drop the pin.
+	 * A callback tests this field to tell a pin on its way out from a
+	 * live one, and it runs under the subsystem's device lock, which
+	 * dpll_pin_unregister() takes as well.  Clearing first means such a
+	 * callback either sees NULL and leaves the pin alone, or still sees
+	 * the pin and finishes before the unregister can proceed.  Clearing
+	 * afterwards leaves a window where the field still reads as live
+	 * and the pin behind it is already gone.
+	 */
+	pin->dpll_pin = NULL;
+
+	dpll_pin_unregister(sitdpll->dpll_dev, dpll_pin, ops, pin);
+	dpll_pin_put(dpll_pin, &pin->tracker);
+
+	fwnode_handle_put(pin->fwnode);
+	pin->fwnode = NULL;
+}
+
+static void sit9531x_dpll_pins_unregister(struct sit9531x_dpll *sitdpll)
+{
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	struct sit9531x_dpll_pin *pin, *next;
+	LIST_HEAD(dead);
+
+	/*
+	 * Take the pins out of the subsystem first.  That call takes the
+	 * DPLL device lock, which the driver's own callbacks are already
+	 * under when they take multiop_lock, so it must not run with
+	 * multiop_lock held or the two orders cross.
+	 */
+	list_for_each_entry(pin, &sitdpll->pins, list)
+		sit9531x_dpll_pin_unregister(pin);
+
+	/*
+	 * Then detach the list under multiop_lock, which every callback that
+	 * walks it holds, so once the splice returns no callback can reach
+	 * these nodes.  The poll walks the list as well without holding the
+	 * lock throughout, but it is not running here: sit9531x_dev_stop()
+	 * cancels it before unregistering, and the IRQ that could queue it
+	 * again is released before that, its devm action having been added
+	 * after the DPLLs were set up.  On the registration error path the
+	 * poll has not been queued yet.  So the nodes are safe to free.
+	 */
+	mutex_lock(&sitdev->multiop_lock);
+	list_splice_init(&sitdpll->pins, &dead);
+	mutex_unlock(&sitdev->multiop_lock);
+
+	list_for_each_entry_safe(pin, next, &dead, list) {
+		list_del(&pin->list);
+		kfree(pin);
+	}
+}
+
+/*
+ * sit9531x_dpll_pin_is_registrable - check if a pin should be registered
+ * @dir:	pin direction
+ * @index:	pin hardware index
+ *
+ * Only the XO pin has a complete pin-op table in this patch, so only
+ * the XO pin is registrable here.  Other pin classes are registered
+ * once their state callbacks land in the following patches.
+ *
+ * Return: true if pin should be registered, false otherwise
+ */
+static bool sit9531x_dpll_pin_is_registrable(struct sit9531x_dpll *sitdpll,
+					     enum dpll_pin_direction dir,
+					     u8 index)
+{
+	/*
+	 * Only the XO pin has a complete pin-op table in this patch.
+	 * Other pin classes are registered once their state callbacks
+	 * land in the following patches.
+	 */
+	if (dir != DPLL_PIN_DIRECTION_INPUT)
+		return false;
+
+	return index == SIT9531X_MAX_INPUTS;
+}
+
+/*
+ * sit9531x_dpll_pins_register - register all registrable pins
+ *
+ * Enumerates all possible input and output pins, checks registrability,
+ * and registers each one.  Input pins come first, then output pins,
+ * with input pins first, then output pins.
+ */
+static int sit9531x_dpll_pins_register(struct sit9531x_dpll *sitdpll)
+{
+	struct sit9531x_dpll_pin *pin;
+	enum dpll_pin_direction dir;
+	u8 id, index;
+	int rc;
+
+	for (index = 0; index < SIT9531X_NUM_PINS_TOTAL; index++) {
+		if (index < SIT9531X_NUM_INPUT_PINS) {
+			id = index;
+			dir = DPLL_PIN_DIRECTION_INPUT;
+		} else {
+			id = index - SIT9531X_NUM_INPUT_PINS;
+			dir = DPLL_PIN_DIRECTION_OUTPUT;
+		}
+
+		if (!sit9531x_dpll_pin_is_registrable(sitdpll, dir, id))
+			continue;
+
+		pin = sit9531x_dpll_pin_alloc(sitdpll, dir, id);
+		if (IS_ERR(pin)) {
+			rc = PTR_ERR(pin);
+			goto error;
+		}
+
+		rc = sit9531x_dpll_pin_register(pin, index);
+		if (rc) {
+			kfree(pin);
+			goto error;
+		}
+
+		/*
+		 * Pins registered before this one are already reachable from
+		 * netlink, and the walks over this list run under
+		 * multiop_lock, so the insertion does too.
+		 */
+		mutex_lock(&sitdpll->dev->multiop_lock);
+		list_add(&pin->list, &sitdpll->pins);
+		mutex_unlock(&sitdpll->dev->multiop_lock);
+	}
+
+	return 0;
+
+error:
+	sit9531x_dpll_pins_unregister(sitdpll);
+	return rc;
+}
+
+static int sit9531x_dpll_device_register(struct sit9531x_dpll *sitdpll)
+{
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	int rc;
+
+	sitdpll->ops = sit9531x_dpll_device_ops;
+
+	sitdpll->dpll_dev = dpll_device_get(sitdev->clock_id, sitdpll->id,
+					    THIS_MODULE, &sitdpll->tracker);
+	if (IS_ERR(sitdpll->dpll_dev)) {
+		rc = PTR_ERR(sitdpll->dpll_dev);
+		sitdpll->dpll_dev = NULL;
+		return rc;
+	}
+
+	rc = dpll_device_register(sitdpll->dpll_dev,
+				  sit9531x_prop_dpll_type_get(sitdev,
+							      sitdpll->id),
+				  &sitdpll->ops, sitdpll);
+	if (rc) {
+		dpll_device_put(sitdpll->dpll_dev, &sitdpll->tracker);
+		sitdpll->dpll_dev = NULL;
+	}
+
+	return rc;
+}
+
+static void sit9531x_dpll_device_unregister(struct sit9531x_dpll *sitdpll)
+{
+	dpll_device_unregister(sitdpll->dpll_dev, &sitdpll->ops, sitdpll);
+	dpll_device_put(sitdpll->dpll_dev, &sitdpll->tracker);
+	sitdpll->dpll_dev = NULL;
+}
+
+/*
+ * sit9531x_dpll_alloc - allocate a DPLL device structure
+ * @sitdev:	parent device
+ * @ch:		PLL channel number (0-3)
+ *
+ * Return: pointer to allocated DPLL on success, error pointer on error
+ */
+struct sit9531x_dpll *sit9531x_dpll_alloc(struct sit9531x_dev *sitdev, u8 ch)
+{
+	struct sit9531x_dpll *sitdpll;
+
+	sitdpll = kzalloc_obj(*sitdpll, GFP_KERNEL);
+	if (!sitdpll)
+		return ERR_PTR(-ENOMEM);
+
+	sitdpll->dev = sitdev;
+	sitdpll->id = ch;
+	sitdpll->lock_status = DPLL_LOCK_STATUS_UNLOCKED;
+	sitdpll->lock_status_error = DPLL_LOCK_STATUS_ERROR_NONE;
+	INIT_LIST_HEAD(&sitdpll->pins);
+
+	return sitdpll;
+}
+
+/*
+ * sit9531x_dpll_free - deallocate a DPLL device structure
+ * @sitdpll:	DPLL to free
+ */
+void sit9531x_dpll_free(struct sit9531x_dpll *sitdpll)
+{
+	kfree(sitdpll);
+}
+
+/*
+ * sit9531x_dpll_register - register DPLL device and all its pins
+ *
+ * Registers the DPLL device with the subsystem and then registers
+ * all input and output pins that are connected to this PLL.
+ */
+int sit9531x_dpll_register(struct sit9531x_dpll *sitdpll)
+{
+	int rc;
+
+	rc = sit9531x_dpll_device_register(sitdpll);
+	if (rc)
+		return rc;
+
+	sit9531x_dpll_lock_status_baseline(sitdpll);
+
+	rc = sit9531x_dpll_pins_register(sitdpll);
+	if (rc) {
+		sit9531x_dpll_device_unregister(sitdpll);
+		return rc;
+	}
+
+	return 0;
+}
+
+/* sit9531x_dpll_unregister - unregister DPLL device and its pins */
+void sit9531x_dpll_unregister(struct sit9531x_dpll *sitdpll)
+{
+	sit9531x_dpll_pins_unregister(sitdpll);
+	sit9531x_dpll_device_unregister(sitdpll);
+}
+
+static void sit9531x_dpll_list_free(struct sit9531x_dev *sitdev)
+{
+	struct sit9531x_dpll *sitdpll, *next;
+
+	list_for_each_entry_safe(sitdpll, next, &sitdev->dplls, list) {
+		list_del(&sitdpll->list);
+		sit9531x_dpll_free(sitdpll);
+	}
+}
+
+/* Runs only once the device is fully started, see the caller. */
+static void sit9531x_dev_dpll_fini(void *ptr)
+{
+	struct sit9531x_dev *sitdev = ptr;
+
+	sit9531x_dev_stop(sitdev);
+	kthread_destroy_worker(sitdev->kworker);
+	sit9531x_dpll_list_free(sitdev);
+}
+
+static int sit9531x_devm_dpll_init(struct sit9531x_dev *sitdev)
+{
+	struct kthread_worker *kworker;
+	struct sit9531x_dpll *sitdpll;
+	unsigned int i;
+	int rc;
+
+	INIT_LIST_HEAD(&sitdev->dplls);
+	kthread_init_delayed_work(&sitdev->work, sit9531x_dev_periodic_work);
+
+	for (i = 0; i < SIT9531X_NUM_PLLS; i++) {
+		sitdpll = sit9531x_dpll_alloc(sitdev, i);
+		if (IS_ERR(sitdpll)) {
+			rc = dev_err_probe(sitdev->dev, PTR_ERR(sitdpll),
+					   "Failed to alloc DPLL%u\n", i);
+			goto err_free_dplls;
+		}
+
+		list_add_tail(&sitdpll->list, &sitdev->dplls);
+	}
+
+	kworker = kthread_run_worker(0, "sit9531x-%s", dev_name(sitdev->dev));
+	if (IS_ERR(kworker)) {
+		rc = PTR_ERR(kworker);
+		goto err_free_dplls;
+	}
+	sitdev->kworker = kworker;
+
+	rc = sit9531x_dev_start(sitdev);
+	if (rc) {
+		rc = dev_err_probe(sitdev->dev, rc, "Failed to start device\n");
+		goto err_destroy_worker;
+	}
+
+	/*
+	 * Only now is every field the cleanup touches valid, so this is the
+	 * first point at which the action may be registered.  On failure it
+	 * runs the action itself, which is correct here and only here.
+	 */
+	return devm_add_action_or_reset(sitdev->dev, sit9531x_dev_dpll_fini,
+					sitdev);
+
+err_destroy_worker:
+	kthread_destroy_worker(sitdev->kworker);
+err_free_dplls:
+	sit9531x_dpll_list_free(sitdev);
+
+	return rc;
+}
+
+/*
+ * sit9531x_read_variant_id - read chip variant ID byte from hardware
+ * @id:		output variant ID byte
+ *
+ * Reads the single-byte variant identification register from Page 0
+ * reg 0x02 (95317 = 0x17, 95316 = 0x31).  Reg 0x03 holds a separate
+ * revision byte and is intentionally not consumed here.
+ */
+static int sit9531x_read_variant_id(struct sit9531x_dev *sitdev, u8 *id)
+{
+	return sit9531x_read_u8(sitdev, SIT9531X_REG_VARIANT_ID, id);
+}
+
+static const struct sit9531x_chip_info *sit9531x_match_variant(u8 id)
+{
+	unsigned int i;
+
+	for (i = 0; i < ARRAY_SIZE(sit9531x_chip_ids); i++) {
+		if (sit9531x_chip_ids[i].id == id)
+			return &sit9531x_chip_ids[i];
+	}
+
+	return NULL;
+}
+
+/*
+ * sit9531x_derive_clock_id - build EUI-64 clock identifier
+ *
+ * Generates a deterministic 64-bit identifier from the SiTime OUI,
+ * the I2C bus number and the I2C address.  The bus number
+ * disambiguates two same-variant parts at the same address on
+ * different adapters (or behind a mux), which the DPLL core would
+ * otherwise fold onto one set of objects; DT bus aliases keep the
+ * numbering, and with it the clock_id, stable across reboots.
+ *
+ * Return: 64-bit clock identifier
+ */
+static u64 sit9531x_derive_clock_id(struct sit9531x_dev *sitdev)
+{
+	u64 clkid;
+	int adap;
+
+	adap = i2c_adapter_id(sitdev->client->adapter);
+
+	/*
+	 * The OUI with its EUI-64 filler takes the top 40 bits.  Bus numbers
+	 * are not bounded by the number of adapters -- a DT alias or a mux
+	 * child can number a bus 256 or above on a board with a handful of
+	 * them -- so the bus gets 16 bits.  The variant does not need a
+	 * field: one address on one bus holds one part.
+	 */
+	clkid  = SIT9531X_OUI << 24;
+	clkid |= (u64)(adap & 0xffff) << 8;
+	clkid |= (u64)sitdev->client->addr;
+
+	return clkid;
+}
+
+int sit9531x_dev_probe(struct sit9531x_dev *sitdev)
+{
+	struct clk *xtal_clk;
+	u8 variant_id;
+	int rc;
+
+	/*
+	 * Fvco = Fref * (DIVN + frac/2^32) with Fref = xtal_freq << doubler,
+	 * so every freq_set and phase_adjust path divides by a rate derived
+	 * from the XO feeding XIN/XO_CLK.  The rate normally comes from a
+	 * "clocks" phandle (clock-names = "xtal").  On platforms where the
+	 * firmware does not expose the XO through the clock framework, fall
+	 * back to a "clock-frequency" device property.
+	 */
+	xtal_clk = devm_clk_get_optional_enabled(sitdev->dev, "xtal");
+	if (IS_ERR(xtal_clk))
+		return dev_err_probe(sitdev->dev, PTR_ERR(xtal_clk),
+				     "Failed to get xtal clock\n");
+	sitdev->xtal_freq = clk_get_rate(xtal_clk);
+	if (!sitdev->xtal_freq) {
+		u32 freq;
+
+		if (!device_property_read_u32(sitdev->dev, "clock-frequency",
+					      &freq))
+			sitdev->xtal_freq = freq;
+	}
+	if (!sitdev->xtal_freq)
+		return dev_err_probe(sitdev->dev, -EINVAL,
+				     "no xtal rate: provide clocks=<&xo> + clock-names=\"xtal\", or a clock-frequency property\n");
+
+	/*
+	 * Held deasserted, never pulsed: the chip configuration comes from
+	 * efuse or an NVM blob applied before probe, and a reset would
+	 * discard it.  Must precede the first I2C access, as a board that
+	 * powers up asserted keeps the chip unreachable until released.
+	 */
+	sitdev->reset_gpio = devm_gpiod_get_optional(sitdev->dev, "reset",
+						     GPIOD_OUT_LOW);
+	if (IS_ERR(sitdev->reset_gpio))
+		return dev_err_probe(sitdev->dev, PTR_ERR(sitdev->reset_gpio),
+				     "Failed to request reset gpio\n");
+	if (sitdev->reset_gpio)
+		fsleep(10000);	/* internal boot after release */
+
+	rc = sit9531x_read_variant_id(sitdev, &variant_id);
+	if (rc)
+		return rc;
+
+	sitdev->info = sit9531x_match_variant(variant_id);
+	if (!sitdev->info)
+		return dev_err_probe(sitdev->dev, -ENODEV,
+				     "Unknown variant ID: 0x%02x\n",
+				     variant_id);
+
+	sitdev->clock_id = sit9531x_derive_clock_id(sitdev);
+	sitdev->intsync_src = -1;
+
+	rc = devm_mutex_init(sitdev->dev, &sitdev->multiop_lock);
+	if (rc)
+		return dev_err_probe(sitdev->dev, rc,
+				     "Failed to initialize mutex\n");
+
+	dev_info(sitdev->dev, "%s detected, %u inputs, %u outputs\n",
+		 sitdev->info->name, sitdev->info->num_inputs,
+		 sitdev->info->num_outputs);
+
+	/*
+	 * Before the IRQ: the handler reaches sitdev->kworker through
+	 * kthread_mod_delayed_work(), so the worker has to exist before an
+	 * INTRB assertion can land.
+	 */
+	rc = sit9531x_devm_dpll_init(sitdev);
+	if (rc)
+		return rc;
+
+	/* Absent "interrupts" leaves client->irq 0 and the poll in charge. */
+	sitdev->irq = sitdev->client ? sitdev->client->irq : 0;
+	if (sitdev->irq > 0) {
+		rc = devm_request_threaded_irq(sitdev->dev, sitdev->irq,
+					       NULL, sit9531x_irq_thread_fn,
+					       IRQF_ONESHOT,
+					       dev_name(sitdev->dev), sitdev);
+		if (rc)
+			return dev_err_probe(sitdev->dev, rc,
+					     "Failed to request IRQ %d\n",
+					     sitdev->irq);
+	}
+
+	return 0;
+}
+
+static int sit9531x_i2c_probe(struct i2c_client *client)
+{
+	struct sit9531x_dev *sitdev;
+	struct regmap *regmap;
+
+	regmap = devm_regmap_init_i2c(client, &sit9531x_regmap_config);
+	if (IS_ERR(regmap))
+		return dev_err_probe(&client->dev, PTR_ERR(regmap),
+				     "Failed to initialize regmap\n");
+
+	sitdev = devm_kzalloc(&client->dev, sizeof(*sitdev), GFP_KERNEL);
+	if (!sitdev)
+		return -ENOMEM;
+
+	sitdev->dev = &client->dev;
+	sitdev->client = client;
+	sitdev->regmap = regmap;
+	i2c_set_clientdata(client, sitdev);
+
+	return sit9531x_dev_probe(sitdev);
 }
 
 static const struct of_device_id sit9531x_of_match[] = {
@@ -305,10 +1891,45 @@ static const struct of_device_id sit9531x_of_match[] = {
 };
 MODULE_DEVICE_TABLE(of, sit9531x_of_match);
 
+/*
+ * The poll worker is not freezable and would keep issuing paged I2C
+ * transfers into a suspended adapter, where i2c_transfer() fails and a
+ * tick landing mid-suspend could tear a paged sequence between the
+ * page-selector write and the register access.  Park the worker (and
+ * the IRQ that kicks it) across suspend and take a fresh sample on
+ * resume.
+ */
+static int sit9531x_suspend(struct device *dev)
+{
+	struct sit9531x_dev *sitdev = dev_get_drvdata(dev);
+
+	if (sitdev->irq > 0)
+		disable_irq(sitdev->irq);
+	kthread_cancel_delayed_work_sync(&sitdev->work);
+
+	return 0;
+}
+
+static int sit9531x_resume(struct device *dev)
+{
+	struct sit9531x_dev *sitdev = dev_get_drvdata(dev);
+
+	sit9531x_page_cache_drop(sitdev);
+	if (sitdev->irq > 0)
+		enable_irq(sitdev->irq);
+	kthread_queue_delayed_work(sitdev->kworker, &sitdev->work, 0);
+
+	return 0;
+}
+
+static DEFINE_SIMPLE_DEV_PM_OPS(sit9531x_pm_ops,
+				sit9531x_suspend, sit9531x_resume);
+
 static struct i2c_driver sit9531x_i2c_driver = {
 	.driver			= {
 		.name		= "sit9531x",
 		.of_match_table	= sit9531x_of_match,
+		.pm		= pm_sleep_ptr(&sit9531x_pm_ops),
 	},
 	.probe		= sit9531x_i2c_probe,
 };
diff --git a/drivers/dpll/sit9531x/core.h b/drivers/dpll/sit9531x/core.h
index 4b4f72c8622b..28fc99f50063 100644
--- a/drivers/dpll/sit9531x/core.h
+++ b/drivers/dpll/sit9531x/core.h
@@ -15,6 +15,8 @@
 
 #include <linux/gpio/consumer.h>
 #include <linux/i2c.h>
+#include <linux/kthread.h>
+#include <linux/list.h>
 #include <linux/mutex.h>
 #include <linux/regmap.h>
 #include <linux/types.h>
@@ -34,6 +36,15 @@
  */
 #define SIT9531X_INTSYNC_PIN_ID		(SIT9531X_MAX_INPUTS + 1)
 #define SIT9531X_INTSYNC_OUT_PIN_ID	SIT9531X_MAX_OUTPUTS
+#define SIT9531X_STATUS_POLL_MS		500
+
+/* selected_ref value when the active source is not a registered input */
+#define SIT9531X_REF_INVALID		0xFF
+
+/* SiTime IEEE OUI for EUI-64 generation */
+#define SIT9531X_OUI			0x0090C2FFFEULL
+
+struct sit9531x_dpll;
 
 /*
  * struct sit9531x_chip_info - chip variant identification
@@ -64,33 +75,105 @@ enum sit9531x_signal_mode {
 /*
  * struct sit9531x_ref - input reference state
  * @freq:		configured frequency in Hz
+ * @enabled:		the lane's receiver is on
+ * @pll_mask:		bitmask of PLLs this input feeds (bit 0 = PLLA)
  * @sig_mode:		signal mode of the pair this lane belongs to
  *			(detected from CLKINx_INPUT_MODE at probe)
  */
 struct sit9531x_ref {
 	u64		freq;
+	bool		enabled;
+	u8		pll_mask;
 	enum sit9531x_signal_mode	sig_mode;
 };
 
 /*
  * struct sit9531x_out - output state
- * @freq:		configured frequency in Hz
+ * @freq:		rate the output is running at, in Hz
+ * @enabled:		output is driving, i.e. not forced into Hi-Z
+ * @cmos:		output is wired single-ended; the Hi-Z pairs that
+ *			speak for it are the two CMOS pad ones, not the
+ *			differential
+ * @routed:		output is mapped to @pll_idx by the initial
+ *			configuration; an unrouted output has no DPLL pin
+ * @pll_idx:		PLL driving this output (0-3)
  */
 struct sit9531x_out {
 	u64		freq;
+	bool		enabled;
+	bool		cmos;
+	bool		routed;
+	u8		pll_idx;
+};
+
+/*
+ * struct sit9531x_chan - per-PLL channel state
+ * @active:		PLL has reached its active state; a PLL the loaded
+ *			configuration leaves unused never does, and its
+ *			loss-of-lock bit stays clear because nothing drives it
+ * @locked:		PLL is active and its outer loop reports lock
+ * @mode:		0 = sync (outer loop enabled), 1 = free-run
+ * @selected_ref:	logical input index of the currently selected
+ *			reference (the INTSYNC net maps to
+ *			SIT9531X_INTSYNC_PIN_ID), or SIT9531X_REF_INVALID
+ *			when the hardware source encoding is reserved
+ * @inner_lol:		PLL inner loop loss-of-lock detected
+ * @ho_freeze:		holdover freeze active
+ * @ho_valid:		holdover memory acquired, i.e. the holdover window
+ *			holds a valid estimate to fall back on
+ * @prio_mask:		bit per hardware source code present in this PLL's
+ *			priority table, i.e. the sources it may select.  Read
+ *			back from the table by the periodic worker and
+ *			refreshed by every table write, so it tracks the
+ *			hardware rather than the driver's intent
+ * @cfg_prio:		priority configured for each canonical source,
+ *			whether or not it is in the table; the table is
+ *			built from it, so taking a source out and putting it
+ *			back does not change anyone's priority
+ * @cfg_known:		bit per canonical source that has a @cfg_prio
+ * @seen_srcs:		the table as the driver last wrote or seeded
+ *			@cfg_prio from; a read-back that differs means
+ *			something else rewrote it, and @cfg_prio is
+ *			re-seeded from the hardware
+ * @seen_valid:		@seen_srcs holds a table
+ */
+struct sit9531x_chan {
+	bool		active;
+	bool		locked;
+	u8		mode;
+	u8		selected_ref;
+	bool		inner_lol;
+	bool		ho_freeze;
+	bool		ho_valid;
+	u16		prio_mask;
+	u8		cfg_prio[SIT9531X_PRIO_NUM_SRC];
+	u16		cfg_known;
+	u8		seen_srcs[SIT9531X_PRIO_MAX_SLOTS];
+	bool		seen_valid;
 };
 
 /*
  * struct sit9531x_dev - SiT9531x device instance
- * @dev:		parent device
- * @client:		I2C client
- * @regmap:		paged register map
  * @info:		detected chip variant info
- * @multiop_lock:	serializes multi-register sequences
+ * @dev:		parent device
+ * @client:		I2C client backing @regmap
+ * @regmap:		paged register map of the device
+ * @dplls:		DPLL devices registered for this chip
+ * @multiop_lock:	mutex for multi-register atomic operations
  * @ref:		array of input reference states
  * @out:		array of output states
+ * @chan:		array of per-PLL channel states
  * @xtal_freq:		crystal oscillator frequency in Hz
+ * @kworker:		kthread worker for periodic polling
+ * @work:		delayed work for periodic state checks
+ * @clock_id:		IEEE 1588 EUI-64 clock identifier
  * @reset_gpio:		optional reset line (DT "reset-gpios"), NULL if absent
+ * @irq:		optional INTRB IRQ number (from DT "interrupts" via the
+ *			I2C client), 0 if no IRQ is wired
+ * @intsync_src:	PLL index currently sourcing inter-PLL
+ *			synchronization (INTSYNC), or -1 when disabled
+ * @irq_ack_fails:	consecutive failures to acknowledge the
+ *			notification latches from the interrupt handler
  */
 struct sit9531x_dev {
 	struct device			*dev;
@@ -101,13 +184,78 @@ struct sit9531x_dev {
 	struct mutex			multiop_lock;
 
 	/* Hardware state */
+	u8			irq_ack_fails;
 	struct sit9531x_ref	ref[SIT9531X_MAX_INPUTS + 1]; /* +1 for xtal */
 	struct sit9531x_out	out[SIT9531X_MAX_OUTPUTS];
+	struct sit9531x_chan	chan[SIT9531X_NUM_PLLS];
 	u32			xtal_freq;
 
+	/* DPLL channels */
+	struct list_head	dplls;
+
+	/* Monitor */
+	struct kthread_worker		*kworker;
+	struct kthread_delayed_work	work;
+
+	/* Device identity */
+	u64			clock_id;
+
+	/* Optional DT-described GPIO / IRQ lines */
 	struct gpio_desc	*reset_gpio;
+	int			irq;
+
+	/* Inter-PLL synchronization state */
+	s8			intsync_src;
+
 };
 
+extern const struct regmap_config sit9531x_regmap_config;
+
+/* ---- Core lifecycle ---- */
+int  sit9531x_dev_probe(struct sit9531x_dev *sitdev);
+int  sit9531x_dev_start(struct sit9531x_dev *sitdev);
+void sit9531x_dev_stop(struct sit9531x_dev *sitdev);
+
+/* ---- Register access ---- */
+int sit9531x_read_u8(struct sit9531x_dev *sitdev, unsigned int reg,
+		     u8 *val);
+int sit9531x_write_u8(struct sit9531x_dev *sitdev, unsigned int reg,
+		      u8 val);
+int sit9531x_read_pll_u8(struct sit9531x_dev *sitdev, u8 pll_idx,
+			 u8 offset, u8 *val);
+int sit9531x_write_pll_u8(struct sit9531x_dev *sitdev, u8 pll_idx,
+			  u8 offset, u8 val);
+int sit9531x_update_pll_u8(struct sit9531x_dev *sitdev, u8 pll_idx,
+			   u8 offset, u8 mask, u8 val);
+
+/* ---- Input enable/disable ---- */
+
+/* ---- Input priority ---- */
+
+/* ---- Output enable/disable (Hi-Z control) ---- */
+
+/* ---- Output frequency ---- */
+
+/* ---- Output phase adjust (PRG_RST_DELAY register-based) ---- */
+
+/* ---- Notification clear ---- */
+int sit9531x_clear_notifications(struct sit9531x_dev *sitdev);
+
+/* ---- INTSYNC (inter-PLL synchronization) ---- */
+
+/* ---- Phase offset (TDC readback) ---- */
+
+/* ---- State helpers ---- */
+
+/*
+ * sit9531x_pll_page - get register page for PLL index
+ * @pll_idx: PLL index (0 = PLLA, 3 = PLLD)
+ */
+static inline u8 sit9531x_pll_page(u8 pll_idx)
+{
+	return SIT9531X_PAGE_PLLA + pll_idx;
+}
+
 /*
  * Logical input pins are interleaved: even index = P lane, odd
  * index = N lane of pair index/2 (IN0P, IN0N, IN1P, IN1N, ...).
@@ -133,27 +281,95 @@ static inline bool sit9531x_input_is_n(u8 index)
 }
 
 /*
- * sit9531x_pll_page - get register page for PLL index
- * @pll_idx: PLL index (0 = PLLA, 3 = PLLD)
+ * sit9531x_input_hw_src - translate logical input index to source encoding
+ * @index: logical input pin index
+ *
+ * The priority table and CLK_ACTIVESEL registers use a non-contiguous
+ * source encoding: 0-3 = CLK0P..CLK3P, 5 = OCXO, 6 = INTSYNC,
+ * 7-10 = CLK0N..CLK3N.
  */
-static inline u8 sit9531x_pll_page(u8 pll_idx)
+static inline u8 sit9531x_input_hw_src(u8 index)
 {
-	return SIT9531X_PAGE_PLLA + pll_idx;
+	if (index == SIT9531X_MAX_INPUTS)
+		return SIT9531X_PRIO_SRC_OCXO;
+	if (index == SIT9531X_INTSYNC_PIN_ID)
+		return SIT9531X_PRIO_SRC_INTSYNC;
+	if (sit9531x_input_is_n(index))
+		return SIT9531X_PRIO_SRC_N_BASE + sit9531x_input_pair(index);
+	return sit9531x_input_pair(index);
 }
 
-extern const struct regmap_config sit9531x_regmap_config;
+/*
+ * sit9531x_hw_src_input - translate source encoding to logical input index
+ * @src: 4-bit hardware source encoding
+ *
+ * Return: logical input index (INTSYNC maps to SIT9531X_INTSYNC_PIN_ID),
+ * or SIT9531X_REF_INVALID if @src is a reserved value
+ */
+static inline u8 sit9531x_hw_src_input(u8 src)
+{
+	if (src < SIT9531X_NUM_INPUT_PAIRS)
+		return src * 2;
+	if (src == SIT9531X_PRIO_SRC_OCXO)
+		return SIT9531X_MAX_INPUTS;
+	if (src == SIT9531X_PRIO_SRC_INTSYNC)
+		return SIT9531X_INTSYNC_PIN_ID;
+	if (src >= SIT9531X_PRIO_SRC_N_BASE &&
+	    src < SIT9531X_PRIO_SRC_N_BASE + SIT9531X_NUM_INPUT_PAIRS)
+		return (src - SIT9531X_PRIO_SRC_N_BASE) * 2 + 1;
+	return SIT9531X_REF_INVALID;
+}
 
-/* ---- Core lifecycle ---- */
-int  sit9531x_dev_probe(struct sit9531x_dev *sitdev);
+/*
+ * sit9531x_prio_src_usable - does a priority slot name a reference?
+ * @src: 4-bit hardware source encoding held in a table slot
+ *
+ * Codes 4 and 11 address a fifth input pair this part does not have, and
+ * a value outside the encoding is not a source either, so a slot holding
+ * one of them names nothing the device can select.  Canonicalizing an N
+ * lane to its pair first would not change the answer -- both lanes are
+ * references -- so this needs no device state.
+ *
+ * Return: true when the code resolves to a reference the device can use
+ */
+static inline bool sit9531x_prio_src_usable(u8 src)
+{
+	return sit9531x_hw_src_input(src) != SIT9531X_REF_INVALID;
+}
 
-/* ---- Register access ---- */
-int sit9531x_read_u8(struct sit9531x_dev *sitdev, unsigned int reg, u8 *val);
-int sit9531x_write_u8(struct sit9531x_dev *sitdev, unsigned int reg, u8 val);
-int sit9531x_read_pll_u8(struct sit9531x_dev *sitdev, u8 pll_idx, u8 offset,
-			 u8 *val);
-int sit9531x_write_pll_u8(struct sit9531x_dev *sitdev, u8 pll_idx, u8 offset,
-			  u8 val);
-int sit9531x_update_pll_u8(struct sit9531x_dev *sitdev, u8 pll_idx, u8 offset,
-			   u8 mask, u8 val);
+/*
+ * sit9531x_ref_state_get - get reference state by index
+ * @index:	logical input index
+ *
+ * Return: pointer to the cached input reference state
+ */
+static inline const struct sit9531x_ref *
+sit9531x_ref_state_get(const struct sit9531x_dev *sitdev, u8 index)
+{
+	return &sitdev->ref[index];
+}
+
+/*
+ * sit9531x_out_state_get - get output state by index
+ * @index:	logical output index
+ *
+ * Return: pointer to the cached output state
+ */
+static inline const struct sit9531x_out *
+sit9531x_out_state_get(const struct sit9531x_dev *sitdev, u8 index)
+{
+	return &sitdev->out[index];
+}
+
+/*
+ * sit9531x_chan_state_get - get channel state by PLL index
+ *
+ * Return: pointer to the cached per-PLL channel state
+ */
+static inline const struct sit9531x_chan *
+sit9531x_chan_state_get(const struct sit9531x_dev *sitdev, u8 pll_idx)
+{
+	return &sitdev->chan[pll_idx];
+}
 
 #endif /* _SIT9531X_CORE_H */
diff --git a/drivers/dpll/sit9531x/dpll.c b/drivers/dpll/sit9531x/dpll.c
new file mode 100644
index 000000000000..e88fa4e29bdf
--- /dev/null
+++ b/drivers/dpll/sit9531x/dpll.c
@@ -0,0 +1,411 @@
+// SPDX-License-Identifier: GPL-2.0
+/*
+ * SiTime SiT9531x DPLL subsystem callbacks and registration
+ *
+ * Copyright (C) 2026 SiTime Corp.
+ * Author: Ali Rouhi <arouhi@sitime.com>
+ * Author: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
+ *
+ * DPLL device ops, pin ops (separate input/output), pin registration,
+ * and periodic change detection.
+ */
+
+#include <linux/dpll.h>
+#include <linux/err.h>
+#include <linux/kthread.h>
+#include <linux/list.h>
+#include <linux/netlink.h>
+#include <linux/slab.h>
+
+#include "core.h"
+#include "dpll.h"
+#include "prop.h"
+#include "regs.h"
+
+static bool sit9531x_dpll_is_input_pin(const struct sit9531x_dpll_pin *pin)
+{
+	return pin->dir == DPLL_PIN_DIRECTION_INPUT;
+}
+
+static bool
+sit9531x_dpll_is_xo_pin(const struct sit9531x_dpll_pin *pin)
+{
+	return sit9531x_dpll_is_input_pin(pin) &&
+	       pin->id == SIT9531X_MAX_INPUTS;
+}
+
+/*
+ * The cached state this reports comes from the outer loss-of-lock byte
+ * (page 0, reg 0x06), the PLL mode bit (PLL page, reg 0x31), inner LOL
+ * (reg 0x92), the holdover freeze byte (reg 0x0A) and the per-PLL
+ * holdover-valid bit (PLL page, reg 0x06).
+ */
+static int
+sit9531x_dpll_lock_status_get(const struct dpll_device *dpll, void *dpll_priv,
+			      enum dpll_lock_status *status,
+			      enum dpll_lock_status_error *status_error,
+			      struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	const struct sit9531x_chan *chan;
+
+	if (status_error)
+		*status_error = DPLL_LOCK_STATUS_ERROR_NONE;
+
+	chan = sit9531x_chan_state_get(sitdev, sitdpll->id);
+
+	mutex_lock(&sitdev->multiop_lock);
+
+	if (!chan->active) {
+		/*
+		 * A PLL the loaded configuration leaves unused never reaches
+		 * its active state.  Nothing drives its loss-of-lock bit, so
+		 * without this it would report a lock it does not have.
+		 */
+		*status = DPLL_LOCK_STATUS_UNLOCKED;
+	} else if (chan->inner_lol) {
+		/*
+		 * The core publishes the error detail only for the unlocked
+		 * and holdover states, so an inner loss of lock reported
+		 * under a locked status would never reach userspace.  An
+		 * inner loop that is not locked is not a locked PLL.
+		 */
+		*status = chan->ho_freeze ? DPLL_LOCK_STATUS_HOLDOVER :
+					    DPLL_LOCK_STATUS_UNLOCKED;
+	} else if (chan->mode) {
+		/*
+		 * Free-run: the outer loop is disabled, so the PLL tracks no
+		 * reference at all and its loss-of-lock bit means nothing.
+		 * That is what UNLOCKED describes -- "not yet locked to any
+		 * valid input (or was forced by user)".
+		 */
+		*status = DPLL_LOCK_STATUS_UNLOCKED;
+	} else if (chan->ho_freeze) {
+		/*
+		 * Tested before the lock: the freeze and the outer
+		 * loss-of-lock bit are read independently, and a PLL frozen
+		 * in holdover is not tracking a reference whatever its
+		 * loss-of-lock bit says -- the pin-state contract below
+		 * counts a frozen PLL as tracking nothing for the same
+		 * reason.
+		 */
+		*status = DPLL_LOCK_STATUS_HOLDOVER;
+	} else if (chan->locked) {
+		/*
+		 * HO_ACQ is locked *and* holdover memory acquired, so it needs
+		 * the holdover-valid bit rather than following from the lock.
+		 */
+		if (chan->ho_valid)
+			*status = DPLL_LOCK_STATUS_LOCKED_HO_ACQ;
+		else
+			*status = DPLL_LOCK_STATUS_LOCKED;
+	} else {
+		*status = DPLL_LOCK_STATUS_UNLOCKED;
+	}
+
+	/* Report inner LOL as an error condition */
+	if (status_error && chan->inner_lol)
+		*status_error = DPLL_LOCK_STATUS_ERROR_UNDEFINED;
+
+	mutex_unlock(&sitdev->multiop_lock);
+
+	return 0;
+}
+
+/*
+ * sit9531x_dpll_lock_status_baseline - seed the status the poll compares to
+ *
+ * Called once the device is registered.  The create notification carried
+ * the lock status the cache holds, so that is the baseline the first tick
+ * compares against; taken from the placeholder the allocation left, every
+ * PLL that is locked or in holdover would look like it had just changed.
+ */
+void sit9531x_dpll_lock_status_baseline(struct sit9531x_dpll *sitdpll)
+{
+	sit9531x_dpll_lock_status_get(sitdpll->dpll_dev, sitdpll,
+				      &sitdpll->lock_status,
+				      &sitdpll->lock_status_error, NULL);
+}
+
+/*
+ * Mode
+ * ====
+ * enum dpll_mode differentiates how a DPLL selects an input: AUTOMATIC
+ * has the device pick the highest-priority one, MANUAL has userspace
+ * request one.  The device only implements the former through this
+ * driver, so AUTOMATIC is the only mode advertised.
+ *
+ * With a single mode there is nothing to switch, so no .mode_set: the core
+ * answers a mode request with -EOPNOTSUPP.  Free-run -- the outer loop
+ * disabled through PLL page reg 0x31[5] -- is not a mode in those terms,
+ * because no input is selected either way.  It is reported through lock
+ * status instead, and entered and left through the chip-specific tool
+ * rather than over netlink.
+ *
+ * The device could implement real MANUAL: PLL_CONFIG1F_PLL (PLL page reg
+ * 0x1F) bit 6 switches a PLL from priority-based to manual active select,
+ * and with MISCINNER_PLL (reg 0x18) bit 5 the PLL follows a manual input
+ * select -- the input-select pins, or with GPIO_INPUT_FUNC_CTRL5..8
+ * (page 0, regs 0xE8-0xEB) bit 4 the register's own low nibble -- which
+ * pins one reference while the loop keeps running.  Wiring that up would
+ * let .state_on_dpll_set() accept CONNECTED, but regs 0x18 and 0x1F carry
+ * GUI-generated configuration in their other bits, so it is left out.
+ * Advertising MANUAL and then refusing the one request MANUAL exists for
+ * is the worse of the two incomplete answers, and after merge it would be
+ * ABI.  A profile that sets manual select anyway is reported at probe,
+ * since the mode this driver reports would then be wrong.
+ */
+static int
+sit9531x_dpll_mode_get(const struct dpll_device *dpll, void *dpll_priv,
+		       enum dpll_mode *mode, struct netlink_ext_ack *extack)
+{
+	*mode = DPLL_MODE_AUTOMATIC;
+
+	return 0;
+}
+
+static int
+sit9531x_dpll_supported_modes_get(const struct dpll_device *dpll,
+				  void *dpll_priv, unsigned long *modes,
+				  struct netlink_ext_ack *extack)
+{
+	__set_bit(DPLL_MODE_AUTOMATIC, modes);
+
+	return 0;
+}
+
+const struct dpll_device_ops sit9531x_dpll_device_ops = {
+	.lock_status_get	= sit9531x_dpll_lock_status_get,
+	.mode_get		= sit9531x_dpll_mode_get,
+	.supported_modes_get	= sit9531x_dpll_supported_modes_get,
+	/* temp_get not available -- SiT9531x has no on-die temp sensor */
+};
+
+/*
+ * Pin-state contract
+ * ==================
+ * The five pin ops tables below fall into three roles, and only the first
+ * has a selection state machine.  Each state_on_dpll callback implements
+ * the rules for its role and nothing else, so the tables cannot drift
+ * apart the way five independent encodings of this did.
+ *
+ * SELECTION role -- physical input pins, INTSYNC destination pin.
+ *   The state is what userspace asked for; what the device is doing with
+ *   the pin is the operational state.  Predicates, all evaluated under
+ *   multiop_lock:
+ *     M  source is present in THIS PLL's hardware priority table
+ *     S  chan->selected_ref == this pin's id (the active selection)
+ *     L  chan->locked && !chan->mode && !chan->ho_freeze
+ *        (tracking a reference: outer loop running, locked, not frozen)
+ *     N  the input lane's clock monitor reports loss of signal
+ *     Q  the lane's monitor reports a frequency drift, with signal
+ *   state get:
+ *     SELECTABLE    M
+ *     DISCONNECTED  !M
+ *   operstate get:
+ *     ACTIVE        S && L && !N
+ *     NO_SIGNAL     N
+ *     QUAL_FAILED   !N && Q && !(S && L)
+ *     STANDBY       otherwise
+ *   set:
+ *     DISCONNECTED  remove from this PLL's table; a physical input also
+ *                   releases this DPLL's claim and powers the shared
+ *                   receiver down on the last release
+ *     SELECTABLE    add to this PLL's table; a physical input powers the
+ *                   receiver up and takes the claim, in that order
+ *     CONNECTED     -EOPNOTSUPP -- the device selects by priority and has
+ *                   no mode that pins one reference (see "Mode" above)
+ *     other         -EINVAL
+ *
+ *   The ACTIVE test needs L as well as S because the selection is what the
+ *   driver last wrote or the device last chose, not proof the loop uses
+ *   it: a free-running, frozen or unlocked PLL follows nothing.  It needs
+ *   !N because a PLL whose selection names a lane without signal has
+ *   fallen back to another listed source on its own, and no register
+ *   says which -- no pin is reported active then.  The INTSYNC destination
+ *   has no monitor, so N and Q never hold for it.
+ *
+ *   M is read from the hardware priority table, not from ref->pll_mask,
+ *   which is only the shared-receiver refcount and says nothing about one
+ *   DPLL's eligibility.  Priority is kept by the driver per source and
+ *   PLL, independent of M, so a pin reports the same priority whether it
+ *   is connected or not.
+ *
+ * DRIVE role -- output pins, INTSYNC source pin.
+ *   Is this pin or net being driven?  Nothing is selected here, so:
+ *     CONNECTED     pin or net is driven
+ *     DISCONNECTED  pin is muted (Hi-Z), or this PLL does not drive it
+ *     SELECTABLE    -EINVAL on set, never reported by get
+ *
+ * FIXED role -- XO pin.  Always CONNECTED; it cannot be routed.
+ */
+
+static int
+sit9531x_dpll_input_pin_direction_get(const struct dpll_pin *pin,
+				      void *pin_priv,
+				      const struct dpll_device *dpll,
+				      void *dpll_priv,
+				      enum dpll_pin_direction *direction,
+				      struct netlink_ext_ack *extack)
+{
+	*direction = DPLL_PIN_DIRECTION_INPUT;
+	return 0;
+}
+
+static const struct dpll_pin_ops sit9531x_dpll_input_pin_ops = {
+	.direction_get		= sit9531x_dpll_input_pin_direction_get,
+};
+
+/*
+ * INTSYNC pin ops
+ *
+ * INTSYNC is the chip's inter-PLL sync net: one PLL drives it and other
+ * PLLs may lock to it instead of to an external reference.  The two
+ * roles are exposed as two separate pins so neither overloads the other:
+ *
+ *   - a source (output) pin registered on every DPLL.  Connecting it on a
+ *     DPLL makes that DPLL drive INTSYNC; only one DPLL may drive it at a
+ *     time.  It has no priority ops -- driving the net is not a reference
+ *     selection.
+ *   - a destination (input) pin registered on every DPLL.  Connecting it
+ *     on a DPLL makes that DPLL eligible to lock to INTSYNC as a
+ *     reference, so it carries the priority ops.
+ */
+
+/* ---- INTSYNC source (output) pin ---- */
+
+/* The INTSYNC source pin is an output; its direction_get is defined below. */
+static int
+sit9531x_dpll_output_pin_direction_get(const struct dpll_pin *pin,
+				       void *pin_priv,
+				       const struct dpll_device *dpll,
+				       void *dpll_priv,
+				       enum dpll_pin_direction *direction,
+				       struct netlink_ext_ack *extack);
+
+/* ---- INTSYNC destination (input) pin ---- */
+
+/*
+ * XO (crystal oscillator) pin ops
+ *
+ * The XO is the chip's internal reference oscillator that feeds every
+ * PLL.  It is exposed so userspace can see the on-chip reference, but it
+ * cannot be routed or disconnected, so it is reported permanently
+ * connected and offers no state_on_dpll_set / prio ops.
+ */
+
+static int
+sit9531x_dpll_xo_pin_state_on_dpll_get(const struct dpll_pin *pin,
+				       void *pin_priv,
+				       const struct dpll_device *dpll,
+				       void *dpll_priv,
+				       enum dpll_pin_state *state,
+				       struct netlink_ext_ack *extack)
+{
+	*state = DPLL_PIN_STATE_CONNECTED;
+	return 0;
+}
+
+static const struct dpll_pin_ops sit9531x_dpll_xo_pin_ops = {
+	.direction_get		= sit9531x_dpll_input_pin_direction_get,
+	.state_on_dpll_get	= sit9531x_dpll_xo_pin_state_on_dpll_get,
+};
+
+static int
+sit9531x_dpll_output_pin_direction_get(const struct dpll_pin *pin,
+				       void *pin_priv,
+				       const struct dpll_device *dpll,
+				       void *dpll_priv,
+				       enum dpll_pin_direction *direction,
+				       struct netlink_ext_ack *extack)
+{
+	*direction = DPLL_PIN_DIRECTION_OUTPUT;
+	return 0;
+}
+
+static const struct dpll_pin_ops sit9531x_dpll_output_pin_ops = {
+	.direction_get		= sit9531x_dpll_output_pin_direction_get,
+};
+
+const struct dpll_pin_ops *
+sit9531x_dpll_pin_ops_get(const struct sit9531x_dpll_pin *pin)
+{
+	if (!sit9531x_dpll_is_input_pin(pin))
+		return &sit9531x_dpll_output_pin_ops;
+	if (sit9531x_dpll_is_xo_pin(pin))
+		return &sit9531x_dpll_xo_pin_ops;
+	return &sit9531x_dpll_input_pin_ops;
+}
+
+/*
+ * sit9531x_dpll_changes_check - check for state changes and notify
+ *
+ * Called from sit9531x_dev_periodic_work().  Compares current hardware
+ * state against cached values and sends netlink notifications on changes.
+ */
+void sit9531x_dpll_changes_check(struct sit9531x_dpll *sitdpll)
+{
+	enum dpll_lock_status_error status_error = DPLL_LOCK_STATUS_ERROR_NONE;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	enum dpll_lock_status lock_status;
+	struct sit9531x_dpll_pin *pin;
+	int rc;
+
+	rc = sit9531x_dpll_lock_status_get(sitdpll->dpll_dev, sitdpll,
+					   &lock_status, &status_error, NULL);
+	if (rc) {
+		dev_err(sitdev->dev, "Failed to get DPLL%u lock status: %d\n",
+			sitdpll->id, rc);
+		return;
+	}
+
+	/*
+	 * The core publishes the error detail alongside the status, so a
+	 * change in either is a change subscribers have to be told about:
+	 * an inner loss of lock appearing or clearing while the status
+	 * stays UNLOCKED would otherwise be visible only to a later GET.
+	 */
+	if (sitdpll->lock_status != lock_status ||
+	    sitdpll->lock_status_error != status_error) {
+		sitdpll->lock_status = lock_status;
+		sitdpll->lock_status_error = status_error;
+		dpll_device_change_ntf(sitdpll->dpll_dev);
+	}
+
+	list_for_each_entry(pin, &sitdpll->pins, list) {
+		const struct dpll_pin_ops *ops;
+		enum dpll_pin_state state;
+		bool changed;
+
+		/*
+		 * Poll input pins whose state can change autonomously: regular
+		 * references and the INTSYNC destination pin.  Outputs (incl.
+		 * the INTSYNC source) change only through their own set
+		 * callback and the XO is permanently connected, so skip those.
+		 * Each pin's state_on_dpll_get resolves to the right getter.
+		 */
+		if (!sit9531x_dpll_is_input_pin(pin) ||
+		    sit9531x_dpll_is_xo_pin(pin))
+			continue;
+
+		ops = sit9531x_dpll_pin_ops_get(pin);
+		rc = ops->state_on_dpll_get(pin->dpll_pin, pin,
+					    sitdpll->dpll_dev, sitdpll,
+					    &state, NULL);
+		if (rc)
+			continue;
+
+		/*
+		 * The first pass only takes the baseline: the pin was
+		 * registered with this state, so nothing has changed yet.
+		 */
+		changed = pin->seen && state != pin->pin_state;
+		pin->pin_state = state;
+		pin->seen = true;
+		if (changed) {
+			dev_dbg(sitdev->dev, "%s state changed\n", pin->label);
+			dpll_pin_change_ntf(pin->dpll_pin);
+		}
+	}
+}
diff --git a/drivers/dpll/sit9531x/dpll.h b/drivers/dpll/sit9531x/dpll.h
new file mode 100644
index 000000000000..9eb26505f94e
--- /dev/null
+++ b/drivers/dpll/sit9531x/dpll.h
@@ -0,0 +1,68 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/*
+ * SiTime SiT9531x DPLL subsystem interface
+ *
+ * Copyright (C) 2026 SiTime Corp.
+ * Author: Ali Rouhi <arouhi@sitime.com>
+ * Author: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
+ *
+ * DPLL device and pin structures, and function declarations for
+ * the DPLL registration and callback layer.
+ */
+
+#ifndef _SIT9531X_DPLL_H
+#define _SIT9531X_DPLL_H
+
+#include <linux/dpll.h>
+#include <linux/list.h>
+#include <linux/types.h>
+
+struct sit9531x_dev;
+
+/* Per-pin DPLL state. */
+struct sit9531x_dpll_pin {
+	struct list_head		list;
+	struct sit9531x_dpll		*dpll;
+	struct dpll_pin			*dpll_pin;
+	dpll_tracker			tracker;
+	struct fwnode_handle		*fwnode;
+	char				label[8];	/* "IN0", "OUT3" */
+	enum dpll_pin_direction		dir;
+	u8				id;		/* hardware index */
+	u8				prio;
+	enum dpll_pin_state		pin_state;
+	bool				seen;	/* baseline taken by the poll */
+};
+
+/* Per-PLL DPLL device state. */
+struct sit9531x_dpll {
+	struct list_head		list;
+	struct sit9531x_dev		*dev;
+	struct dpll_device		*dpll_dev;
+	dpll_tracker			tracker;
+	struct dpll_device_ops		ops;	/* per-instance copy */
+	struct list_head		pins;
+	u8				id;	/* 0 = PLLA .. 3 = PLLD */
+	enum dpll_lock_status		lock_status;
+	enum dpll_lock_status_error	lock_status_error;
+};
+
+/* ---- DPLL allocation and registration ---- */
+/*
+ * The callback tables stay with the callbacks; the registration code that
+ * hands them to the subsystem lives next to probe() in core.c.
+ */
+extern const struct dpll_device_ops sit9531x_dpll_device_ops;
+const struct dpll_pin_ops *
+sit9531x_dpll_pin_ops_get(const struct sit9531x_dpll_pin *pin);
+
+struct sit9531x_dpll *sit9531x_dpll_alloc(struct sit9531x_dev *sitdev, u8 ch);
+void sit9531x_dpll_free(struct sit9531x_dpll *sitdpll);
+int  sit9531x_dpll_register(struct sit9531x_dpll *sitdpll);
+void sit9531x_dpll_unregister(struct sit9531x_dpll *sitdpll);
+
+/* ---- Periodic change detection ---- */
+void sit9531x_dpll_lock_status_baseline(struct sit9531x_dpll *sitdpll);
+void sit9531x_dpll_changes_check(struct sit9531x_dpll *sitdpll);
+
+#endif /* _SIT9531X_DPLL_H */
diff --git a/drivers/dpll/sit9531x/regs.h b/drivers/dpll/sit9531x/regs.h
index 67077d112653..9349ec722569 100644
--- a/drivers/dpll/sit9531x/regs.h
+++ b/drivers/dpll/sit9531x/regs.h
@@ -37,7 +37,264 @@
  */
 #define SIT9531X_REG_VARIANT_ID		SIT9531X_REG(0x00, 0x02)
 
-/* Variant ID values (page 0 reg 0x02) */
+/* DCO trigger pulse timing: minimum 6 ns required by hardware */
+
+/* Page 0 -- PLL inner loop loss-of-lock */
+#define SIT9531X_REG_PLL_INNER_LOL_STATUS	SIT9531X_REG(0x00, 0x92)
+#define SIT9531X_REG_PLL_INNER_LOL_NOTIF	SIT9531X_REG(0x00, 0x93)
+
+/* Page 0 -- Clock monitor PLL / XO status */
+#define SIT9531X_REG_CMON_NOTIF		SIT9531X_REG(0x00, 0x9E)
+
+/* Page 0 -- PLL outer-loop loss-of-lock */
+#define SIT9531X_REG_OUTER_LOL_STATUS	SIT9531X_REG(0x00, 0x06)
+#define SIT9531X_REG_OUTER_LOL_NOTIF		SIT9531X_REG(0x00, 0x07)
+
+/* Page 0 -- PLL holdover freeze status */
+#define SIT9531X_REG_HO_FREEZE_STATUS	SIT9531X_REG(0x00, 0x0A)
+#define SIT9531X_REG_HO_FREEZE_NOTIF	SIT9531X_REG(0x00, 0x0B)
+
+/* Page 0 -- INTSYNC (inter-PLL synchronization) global enable */
+#define SIT9531X_REG_INTSYNC_GLOBAL		SIT9531X_REG(0x00, 0x40)
+#define SIT9531X_INTSYNC_EN_BIT		6
+
+/*
+ * Priority table: 6 registers per PLL, each holds two priority slots
+ * nibble-packed.  The register holding slots 2n and 2n+1 keeps the
+ * earlier slot (CLK_SPARE<2n>SEL_PLL) in [7:4] and the later one in
+ * [3:0].
+ *
+ * Base registers for PLLA: 0x16-0x1B (slots 0-10 plus the
+ * active-reference nibble).
+ * For PLL N:  base + 6 * N  (e.g. PLLB starts at 0x1C).
+ *
+ * Input source encoding (4-bit value):
+ *   0=IN0P, 1=IN1P, 2=IN2P, 3=IN3P,
+ *   5=OCXO, 6=INTSYNC,
+ *   7=IN0N, 8=IN1N, 9=IN2N, 10=IN3N
+ *
+ * Codes 4 and 11 address a fifth input pair that this part does
+ * not have.  They read back as no valid reference.
+ */
+#define SIT9531X_PAGE_PRIOSYS		0x01
+#define SIT9531X_PRIO_BASE_REG		0x16
+#define SIT9531X_PRIO_REGS_PER_PLL		6
+#define SIT9531X_PRIO_SLOTS_PER_REG		2
+/*
+ * 11 priority slots, CLK_SPARE0SEL_PLL through CLK_SPARE10SEL_PLL.
+ * The twelfth nibble of the block is not a slot: it is
+ * CLK_ACTIVESEL_PLL, see SIT9531X_PRIO_ACTIVESEL_OFF below.
+ */
+#define SIT9531X_PRIO_MAX_SLOTS		11
+/* Number of source encodings (0-11), unrelated to the slot count */
+#define SIT9531X_PRIO_NUM_SRC		12
+#define SIT9531X_PRIO_NIBBLE_MASK		0x0F
+#define SIT9531X_PRIO_HI_SHIFT		4
+/* Input source encoding values (see table above) */
+/*
+ * Either of the two codes for the absent fifth pair works as "no source";
+ * the driver writes this one when it empties a slot.
+ */
+#define SIT9531X_PRIO_SRC_NONE			4
+#define SIT9531X_PRIO_SRC_OCXO		5
+#define SIT9531X_PRIO_SRC_INTSYNC		6
+#define SIT9531X_PRIO_SRC_N_BASE		7
+/*
+ * The last register of each PLL's priority block holds, in its low
+ * nibble, the input source the PLL has currently selected as its
+ * active reference (CLK_ACTIVESEL_PLL, same 4-bit encoding as above).
+ */
+#define SIT9531X_PRIO_ACTIVESEL_OFF		5
+
+/*
+ * Page 0 -- PRG_Directives_GENERIC_0, the main system's programming
+ * directive register.  Every page carries its own copy of this
+ * register at offset 0x0F with the same bit layout:
+ *
+ *   bit 6  proceed to loop lock / active state from the PRG_CMD state
+ *   bit 4  update the NVM bank from the efuse contents
+ *   bit 3  read the efuse into the volatile registers
+ *   bit 2  program the efuse
+ *   bit 1  small change update (SIT9531X_SMALL_UPDATE_CMD)
+ *   bit 0  escape to the PRG_CMD state
+ *
+ * The NVM bank is a volatile shadow, so bits 4 and 1 are both fine in
+ * a runtime path: bit 1 for a change made in the active state, bit 4
+ * to close a PRG_CMD sequence.  Only bit 2 writes non-volatile
+ * storage, and the driver never issues it.
+ */
+#define SIT9531X_REG_GLOBAL_UPDATE		SIT9531X_REG(0x00, 0x0F)
+#define SIT9531X_SMALL_UPDATE_CMD		0x02
+
+/* One bit per input PAIR (bit 0 = CLKIN0, ..., bit 3 = CLKIN3) */
+#define SIT9531X_REG_IN_DE_FORCE		SIT9531X_REG(0x02, 0xE8)
+#define SIT9531X_REG_IN_DE_STATE		SIT9531X_REG(0x02, 0xE9)
+#define SIT9531X_REG_IN_SEP_FORCE		SIT9531X_REG(0x02, 0xEA)
+#define SIT9531X_REG_IN_SEP_STATE		SIT9531X_REG(0x02, 0xEB)
+#define SIT9531X_REG_IN_SEN_FORCE		SIT9531X_REG(0x02, 0xF2)
+#define SIT9531X_REG_IN_SEN_STATE		SIT9531X_REG(0x02, 0xF3)
+
+/*
+ * One register per input pair at 0x1B + 0x10 * pair
+ * (CLKIN0 = 0x1B, CLKIN1 = 0x2B, CLKIN2 = 0x3B, CLKIN3 = 0x4B).
+ * SE_P_EN/SE_N_EN set means the corresponding lane is configured
+ * single-ended; both clear means the pair runs differential.
+ */
+#define SIT9531X_REG_IN_MODE(_pair)		\
+	SIT9531X_REG(0x02, 0x1B + 0x10 * (_pair))
+#define SIT9531X_IN_MODE_SE_P_EN		BIT(0)
+#define SIT9531X_IN_MODE_SE_N_EN		BIT(1)
+
+/* ---- Page 0x03 (Output System) registers -- Hi-Z control ---- */
+#define SIT9531X_REG_HIZ_DIFF_07_MASK	SIT9531X_REG(0x03, 0xF2)
+#define SIT9531X_REG_HIZ_DIFF_07_STATE	SIT9531X_REG(0x03, 0xF3)
+#define SIT9531X_REG_HIZ_DIFF_811_MASK	SIT9531X_REG(0x03, 0xF4)
+#define SIT9531X_REG_HIZ_DIFF_811_STATE	SIT9531X_REG(0x03, 0xF5)
+#define SIT9531X_REG_HIZ_SE_07_MASK		SIT9531X_REG(0x03, 0xF8)
+#define SIT9531X_REG_HIZ_SE_07_STATE		SIT9531X_REG(0x03, 0xF9)
+#define SIT9531X_REG_HIZ_SE_811_MASK		SIT9531X_REG(0x03, 0xFA)
+#define SIT9531X_REG_HIZ_SE_811_STATE	SIT9531X_REG(0x03, 0xFB)
+/*
+ * The SE pairs above force the OutP pad of a CMOS output.  The OutN pad
+ * has its own: 0xF6/0xF7 for slots 0-7, and for slots 8-11 the upper
+ * nibble of the differential pair, 0xF4/0xF5 bits 7:4.
+ */
+#define SIT9531X_REG_HIZ_SEN_07_MASK	SIT9531X_REG(0x03, 0xF6)
+#define SIT9531X_REG_HIZ_SEN_07_STATE	SIT9531X_REG(0x03, 0xF7)
+#define SIT9531X_HIZ_SEN_811_SHIFT		4
+
+/*
+ * Output driver configuration.  Either CMOS enable means the output
+ * is wired single-ended -- one lane, or both driven as CMOS; with
+ * neither set it is a differential pair.
+ */
+#define SIT9531X_OUT_MISC0_BASE		0x1E
+#define SIT9531X_OUT_MISC0_STRIDE		0x10
+#define SIT9531X_OUT_CMOS_ENP		BIT(3)
+#define SIT9531X_OUT_CMOS_ENN		BIT(2)
+
+/*
+ * Output divider registers in Pages 3/4.  Each output has a 34-bit
+ * integer divider mapped to 5 bytes (LSB at base reg, MSB at base-4).
+ * Outputs 0-5 are on Page 3, outputs 6-11 are on Page 4.
+ *
+ * The base register for slot N within a page is:
+ *   clkout_odr_divn_base[slot] = { 0x14, 0x24, 0x34, 0x44, 0x54, 0x64 }
+ *
+ * Layout: base=LSB, base-1, base-2, base-3, base-4[1:0]=MSB.
+ *
+ * Per-chip clkout_map[] translates output index to slot position.
+ */
+#define SIT9531X_PAGE_OUTSYS0_SLOT_MAX	5   /* slots 0-5 on Page 0x03 */
+
+/* Misc output system registers */
+#define SIT9531X_REG_PRG_DIR_GEN		SIT9531X_REG(0x03, 0x0F)
+#define SIT9531X_PRG_CMD_STATE		0x01
+#define SIT9531X_UPDATE_NVM			0x10
+#define SIT9531X_LOOP_LOCK			0x40
+
+/* Debug register (same offset, per-page) */
+#define SIT9531X_REG_OUTSYS_DEBUG		SIT9531X_REG(0x03, 0xBD)
+#define SIT9531X_DEBUG_UNLOCK_VAL		0xC3
+
+/*
+ * On-demand phase-flush fired from a register rather than a GPIO pin.
+ * DIVO_PHASE_SEL_REG selects the in-register trigger source and
+ * DIVO_PHASE_TRIG flushes the output phase when pulsed high then low.
+ * The unrelated OEb trigger pair in bits [7:6] must be preserved.
+ */
+#define SIT9531X_REG_GPIO_FUNC_CTRL1	SIT9531X_REG(0x00, 0x65)
+#define SIT9531X_DIVO_PHASE_SEL_REG	BIT(5)
+#define SIT9531X_DIVO_PHASE_TRIG	BIT(4)
+
+/* ---- PLL page registers (apply to pages 0x0A-0x0D) ---- */
+#define SIT9531X_PLL_REG_SMALL_UPDATE	0x0F
+
+/*
+ * Loop-filter coefficients on PLL_PAGE regs 0x10-0x15 (3 normal +
+ * 3 fast-lock) are GUI/NVM-generated by the timing configurator and must not be
+ * reprogrammed at runtime; the register map flags them as
+ * "GUI generated configuration should not change manually".
+ */
+
+/*
+ * Output-enable mask, twelve bits: bits 0-7 in LO, bits 8-11 in HI[3:0].
+ * OUTn is bit n on PLLA and PLLB and bit 11 - n on PLLC and PLLD.
+ */
+#define SIT9531X_PLL_REG_OUT_MAP_HI		0x27
+#define SIT9531X_PLL_REG_OUT_MAP_LO		0x28
+#define SIT9531X_PLL_REG_STATUS		0x31
+
+#define SIT9531X_PLL_REG_ACTIVE		0x02
+#define SIT9531X_PLL_ACTIVE_BIT		BIT(0)  /* PLL reached active state */
+
+#define SIT9531X_PLL_STATUS_OUTER_DIS	BIT(5)
+
+/*
+ * PLL_CONFIG1F_PLL: bit 6 puts the PLL in manual active select, where it
+ * no longer arbitrates by priority.  The other bits are GUI-generated
+ * configuration.
+ */
+#define SIT9531X_PLL_REG_CONFIG1F		0x1F
+#define SIT9531X_PLL_CONFIG1F_MANUAL_SEL	BIT(6)
+
+/*
+ * MISCINNER_PLL: in manual active select, bit 5 makes the PLL follow the
+ * manual input select instead of its active selection.  The other bits
+ * are GUI-generated configuration.
+ */
+#define SIT9531X_PLL_REG_MISCINNER		0x18
+#define SIT9531X_PLL_MISCINNER_MAN_IN_SEL	BIT(5)
+
+/*
+ * GPIO_INPUT_FUNC_CTRL5..8 (page 0), one per PLL: the manual input
+ * select.  With bit 4 set the input is the low nibble of this register,
+ * otherwise it comes from the input-select pins.  Bits 6:5 are the
+ * active/spare choice of an indirect selection (bit 6 enables bit 5,
+ * which picks the active or the spare clock) and are not decoded here.
+ */
+#define SIT9531X_REG_MAN_IN_SEL(_pll)	SIT9531X_REG(0x00, 0xE8 + (_pll))
+#define SIT9531X_MAN_IN_SEL_FROM_REG		BIT(4)
+#define SIT9531X_MAN_IN_SEL_MASK		GENMASK(3, 0)
+
+/*
+ * Per-PLL status register.  HO_VALID says the holdover window holds a
+ * valid frequency estimate, i.e. holdover memory has been acquired; it is
+ * not the same as HO_FREEZE (page 0, reg 0x0A), which says the PLL has
+ * already switched over to holdover.
+ */
+#define SIT9531X_PLL_REG_STATUS_1		0x06
+#define SIT9531X_PLL_STATUS_1_HO_VALID	BIT(2)
+
+#define SIT9531X_CLKMON_P_NOTIF_01		SIT9531X_REG(0x06, 0x03)
+#define SIT9531X_CLKMON_P_NOTIF_23		SIT9531X_REG(0x06, 0x07)
+
+#define SIT9531X_CLKMON_N_NOTIF_01		SIT9531X_REG(0x06, 0x93)
+#define SIT9531X_CLKMON_N_NOTIF_23		SIT9531X_REG(0x06, 0x97)
+
+/* Per-input bit offsets within clock monitor nibble */
+
+/*
+ * EEPROM profile load, page 0.  The device compares the CRC stored in the
+ * EEPROM against the one it computes from what it read; a mismatch means
+ * the profile on the part is not the profile the board expects.
+ * NOTIFY_4 collects the read-done bit and the defect bits, all sticky, so
+ * a healthy load leaves exactly the read-done bit set.
+ */
+/* 4 bytes each, MSB first */
+#define SIT9531X_REG_REC_CRC		SIT9531X_REG(0x00, 0x8A)
+#define SIT9531X_REG_CAL_CRC		SIT9531X_REG(0x00, 0x8E)
+#define SIT9531X_REG_EEPROM_NOTIF		SIT9531X_REG(0x00, 0x97)
+#define SIT9531X_EEPROM_READ_DONE		BIT(0)
+
+/* Profile identifier the loaded configuration carries, page 1, 24 bits */
+/* 3 bytes, LSB first */
+#define SIT9531X_REG_PROFILE_ID		SIT9531X_REG(0x01, 0x44)
+
+/* Consecutive failed INTRB acknowledgements before the line is given up */
+#define SIT9531X_IRQ_ACK_TRIES			8
+
+/* ---- Variant ID values (one byte at SIT9531X_REG_VARIANT_ID) ---- */
 #define SIT9531X_VARIANT_ID_95317	0x17
 #define SIT9531X_VARIANT_ID_95316	0x31
 
-- 
2.39.2 (Apple Git-143)

[PATCH net-next v12 06/12] dpll: sit9531x: implement input pin state on a DPLL

[Ali Rouhi]

From: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>

Report and set whether an input takes part in a PLL's reference
selection.  The device selects its reference itself from a priority
table, so membership of that table is what the state means here: an input
in the table is selectable, one absent from it is disconnected.  Setting
the state adds the input to the table or removes it, and membership is
read back from the device rather than remembered.  CONNECTED would ask
for this input and no other, which the device cannot be told to do, so it
is refused.  A physical input's receiver is shared by the four PLLs and is
powered down only when the last of them lets go of it.

What the device does with an input is its operational state.  The pin
reported active is the one the device says it feeds the PLL, read from
the PLL's debug status bus, while the PLL is locked to it -- outer loop
running, not frozen -- and its lane has signal.  It is not the active
selection: that names the source the driver asked for, and when that
source loses its signal the device falls back to another listed source
on its own and leaves the selection naming the dead one, so after such a
failover the pin the PLL moved to reports active and the one it left
does not.  The status bus names what is fed to the PLL, not what the PLL
is locked to, so the lane's monitor has to agree.  It is read only while
the PLL tracks a reference, six transfers per such PLL per tick; in
free-run the PLL is fed nothing.  The poll reads every lane's clock
monitor: an input whose monitor reports loss of signal is no-signal, one
that reports a frequency drift is qual-failed, any other is standby.

The table is built from a priority the driver keeps per source and PLL,
seeded from the table the device loaded: members in priority order, the
slots past the last one naming no source.  The four-bit slot encoding
has two codes for a fifth input pair this part does not have, and one of
them serves as that.  A disconnected input keeps its priority for when it
comes back, and a table that would come out as the device already holds
it is not written.

The last register of the table also carries the device's active
selection.  After a table write the PLL goes to the source it names, and
leaves it on its own only when that source loses its signal, so every
write names a source the PLL can use.  When the priorities put a
different source with signal first, the selection goes to it -- the
highest-priority valid input, which is how the DPLL interface defines
automatic mode.  A write that only changes the table below that source
leaves the selection where it is while it is still listed and has
signal, so an edit there does not pull a PLL off a healthy reference;
failing that, it goes to the first listed source that has signal.

Removing the last input is allowed.  The selection then has nothing to
name, and left as it is it would keep the PLL following its old source
for as long as that has signal, so the PLL stays in the forced holdover
the write sequence uses -- the one state in which it follows no input.
The next write that lists a source releases it.  A holdover the driver
did not force -- set by the loaded configuration or by a tool -- is left
in place by such a write; only the hold the driver itself set for an
empty table is released.

The pins fall into three roles and only the first answers this question,
so the contract for all of them is written above the operations rather
than left to be inferred: inputs and the inter-PLL sync destination take
part in selection; an output and the sync source are driven by the PLL and
report whether they carry a signal; the crystal is fixed and always
connected, since a PLL cannot be told to stop using it.

Probe also warns about a firmware pin node whose reg names no pin the
device can have -- a lane or an output the variant lacks, or the N lane
of a pair the configuration runs differential -- since nodes are looked
up from the pins and such a node would otherwise be dropped silently.

Rewriting the table means forcing the PLL into holdover, waiting for it to
take, writing every slot and releasing holdover again, all under the
device lock -- ten to twenty milliseconds.  The device has no way to
change one slot in isolation, and holdover is what keeps the loop from
chasing a table that is momentarily inconsistent, so the sequence is the
cost of doing it correctly.  Its error paths leave the device where the
request found it: a failed write is rolled back through the register
that failed, a force that failed is released all the same since the
write may have landed, the hold stays when the table the device holds
afterwards lists no source, and the selection is never picked from a
monitor read that failed.  A release that fails after the table was
written and latched is owed, and the poll retries it until it lands.
A hold with no source listed and no valid holdover memory reports the
PLL unlocked, as the interface asks, rather than in holdover.

Signed-off-by: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
Assisted-by: LLM
Signed-off-by: Ali Rouhi <arouhi@sitime.com>
---
 drivers/dpll/sit9531x/core.c | 1145 ++++++++++++++++++++++++++++++++--
 drivers/dpll/sit9531x/core.h |   42 +-
 drivers/dpll/sit9531x/dpll.c |  320 +++++++++-
 drivers/dpll/sit9531x/regs.h |   41 ++
 4 files changed, 1483 insertions(+), 65 deletions(-)

diff --git a/drivers/dpll/sit9531x/core.c b/drivers/dpll/sit9531x/core.c
index d2a863ceeb26..999a6583853d 100644
--- a/drivers/dpll/sit9531x/core.c
+++ b/drivers/dpll/sit9531x/core.c
@@ -239,6 +239,99 @@ static void sit9531x_input_get_regs(const struct sit9531x_dev *sitdev,
 	}
 }
 
+/*
+ * sit9531x_input_disable - disable an input reference
+ * @index:	logical input index (0-N)
+ *
+ * Sets the force mask bit and clears the state bit for the given
+ * input, effectively disabling it.  Register selection depends on
+ * the pair's signal mode (SE/DE) and the lane (P/N); the bit within
+ * each register addresses the input pair.
+ *
+ * Both writes are attempted even when the first fails, and the first
+ * error is returned.  Neither is rolled back: the force and state bits
+ * only mean something together, so a transient bus error can leave the
+ * force bit asserted over a state bit that was never programmed, and the
+ * error is what says the override is not to be trusted.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+int sit9531x_input_disable(struct sit9531x_dev *sitdev, u8 index)
+{
+	unsigned int force_reg, state_reg;
+	struct sit9531x_ref *ref;
+	u8 pair, val;
+	int rc, ret;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (index >= SIT9531X_MAX_INPUTS)
+		return -EINVAL;
+
+	ref = &sitdev->ref[index];
+	pair = sit9531x_input_pair(index);
+	sit9531x_input_get_regs(sitdev, index, &force_reg, &state_reg);
+
+	rc = sit9531x_read_u8(sitdev, force_reg, &val);
+	if (!rc)
+		rc = sit9531x_write_u8(sitdev, force_reg, val | BIT(pair));
+
+	ret = sit9531x_read_u8(sitdev, state_reg, &val);
+	if (!ret)
+		ret = sit9531x_write_u8(sitdev, state_reg, val & ~BIT(pair));
+	if (ret && !rc)
+		rc = ret;
+
+	/*
+	 * Drop the claim even when the pair could not be programmed.  The
+	 * force bit may be asserted over a state bit that never reached the
+	 * device, so the receiver cannot be relied on; leaving the cache
+	 * saying it is on makes the next enable skip itself and report a
+	 * success the signal does not back.  Clearing the force bit again
+	 * is harmless, so the worst this costs is one redundant write.
+	 */
+	ref->enabled = false;
+
+	return rc;
+}
+
+/*
+ * sit9531x_input_enable - enable an input reference
+ * @index:	logical input index (0-N)
+ *
+ * Clears the force mask bit for the given input, returning it to
+ * hardware default (enabled).
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+int sit9531x_input_enable(struct sit9531x_dev *sitdev, u8 index)
+{
+	unsigned int force_reg, state_reg;
+	struct sit9531x_ref *ref;
+	u8 pair, val;
+	int rc;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (index >= SIT9531X_MAX_INPUTS)
+		return -EINVAL;
+
+	ref = &sitdev->ref[index];
+	pair = sit9531x_input_pair(index);
+	sit9531x_input_get_regs(sitdev, index, &force_reg, &state_reg);
+
+	rc = sit9531x_read_u8(sitdev, force_reg, &val);
+	if (rc)
+		return rc;
+	rc = sit9531x_write_u8(sitdev, force_reg, val & ~BIT(pair));
+	if (rc)
+		return rc;
+
+	ref->enabled = true;
+
+	return 0;
+}
+
 /*
  * Output enable / disable (Hi-Z control)
  *
@@ -406,7 +499,8 @@ static int sit9531x_output_forced_hiz(struct sit9531x_dev *sitdev,
  *   1. Force PLL into holdover (PLL page reg 0x6F bit 4)
  *   2. Write priority slots on Page 1
  *   3. Small change update (Page 0 reg 0x0F bit 1)
- *   4. Release holdover
+ *   4. Release holdover, unless it was forced before step 1 by something
+ *      other than this driver
  *
  * Caller must hold sitdev->multiop_lock.
  */
@@ -433,26 +527,595 @@ static u8 sit9531x_prio_slot_get(u8 val, u8 slot)
 	return val >> SIT9531X_PRIO_HI_SHIFT;
 }
 
+/* Place source @src in priority slot @slot of a register value. */
+static u8 sit9531x_prio_slot_set(u8 val, u8 slot, u8 src)
+{
+	if (slot & 1)
+		return (val & (SIT9531X_PRIO_NIBBLE_MASK <<
+			       SIT9531X_PRIO_HI_SHIFT)) |
+		       (src & SIT9531X_PRIO_NIBBLE_MASK);
+
+	return (val & SIT9531X_PRIO_NIBBLE_MASK) |
+	       ((src & SIT9531X_PRIO_NIBBLE_MASK) <<
+		SIT9531X_PRIO_HI_SHIFT);
+}
+
+/*
+ * Commit a priority-table programming sequence through the Page-0
+ * programming directive register.
+ *
+ * A small change update is all the table needs.  The NVM-bank and
+ * loop-lock directives that the output system issues do not belong
+ * here: the former programs non-volatile storage from the efuse and
+ * the latter only means anything after an escape to the PRG_CMD
+ * state.  This matches the documented input_priority_sel() procedure.
+ */
+static int sit9531x_prio_prg_commit(struct sit9531x_dev *sitdev)
+{
+	int rc;
+
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_GLOBAL_UPDATE,
+			       SIT9531X_SMALL_UPDATE_CMD);
+	if (rc)
+		return rc;
+
+	usleep_range(1000, 2000);
+
+	return 0;
+}
+
+/*
+ * sit9531x_input_mon_fetch - read the clock monitor status of every lane
+ *
+ * Four registers carry a nibble per lane.  Loss of signal and frequency
+ * drift are what separate an input the device could lock to from one it
+ * could not, which the priority commit uses to choose the active
+ * selection and the pins report as their operational state.
+ *
+ * Caller must hold sitdev->multiop_lock, or run before registration.
+ */
+static int sit9531x_input_mon_fetch(struct sit9531x_dev *sitdev)
+{
+	static const unsigned int regs[] = {
+		SIT9531X_CLKMON_P_STATUS_01, SIT9531X_CLKMON_P_STATUS_23,
+		SIT9531X_CLKMON_N_STATUS_01, SIT9531X_CLKMON_N_STATUS_23,
+	};
+	u8 val[ARRAY_SIZE(regs)], i, pair, nib;
+	int rc;
+
+	for (i = 0; i < ARRAY_SIZE(regs); i++) {
+		rc = sit9531x_read_u8(sitdev, regs[i], &val[i]);
+		if (rc)
+			return rc;
+	}
+
+	for (i = 0; i < sitdev->info->num_inputs; i++) {
+		struct sit9531x_ref *ref = &sitdev->ref[i];
+
+		/* Lane 2k is INkP, 2k + 1 INkN; a register holds two pairs. */
+		pair = sit9531x_input_pair(i);
+		nib = val[(sit9531x_input_is_n(i) ? 2 : 0) + pair / 2];
+		nib = (pair & 1) ? nib >> 4 : nib & 0x0F;
+
+		ref->los = !!(nib & SIT9531X_CLKMON_LOSS);
+		ref->qual_fail = !ref->los &&
+				 !!(nib & (SIT9531X_CLKMON_FINE_DRIFT |
+					   SIT9531X_CLKMON_COARSE_DRIFT));
+	}
+
+	return 0;
+}
+
+/*
+ * Can the device lock to this source now?  Only the input lanes have a
+ * monitor; the on-chip oscillator and the inter-PLL net are taken as
+ * present.  A differential pair is watched through its P lane, which is
+ * the one its table entries are canonicalised to.
+ */
+static bool sit9531x_prio_src_live(const struct sit9531x_dev *sitdev, u8 src)
+{
+	u8 index = sit9531x_hw_src_input(src);
+
+	if (index >= sitdev->info->num_inputs)
+		return true;
+
+	return !sitdev->ref[index].los;
+}
+
 /*
- * Rebuild a PLL's membership mask from the source codes of its priority
- * table.  The mask is what the pin state getters test, so it is refreshed
- * from exactly the values the table holds -- here after a write, and once
- * per poll from the read-back in sit9531x_chan_state_fetch().
+ * Fold a source code to the lane a DPLL pin actually represents.
+ *
+ * Differential input pairs expose only the P lane as a DPLL pin.  A
+ * priority table entry encoded as an N lane for such a pair must map to
+ * the P-lane source for pin-facing operations (membership, priority slots,
+ * add/remove/set lookups), matching sit9531x_ref_pll_mask_fetch().
+ */
+static u8 sit9531x_prio_src_canon(const struct sit9531x_dev *sitdev, u8 src)
+{
+	u8 index = sit9531x_hw_src_input(src);
+
+	if (index >= sitdev->info->num_inputs)
+		return src;
+
+	if (sit9531x_input_is_n(index) &&
+	    sitdev->ref[index].sig_mode == SIT9531X_MODE_DE)
+		return sit9531x_input_hw_src(index - 1);
+
+	return src;
+}
+
+/*
+ * sit9531x_input_prio_present - is a source listed in a PLL's priority table
+ * @input_idx:	input source in hardware encoding (see
+ *		sit9531x_input_hw_src())
+ *
+ * Answers from the membership mask that every table write and every poll
+ * refreshes, which is what the pin state getters test.  The priority slot
+ * cannot answer this: a source that is not in the table reports the lowest
+ * slot, so the slot value alone does not separate absent from last.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+bool sit9531x_input_prio_present(struct sit9531x_dev *sitdev, u8 pll_idx,
+				 u8 input_idx)
+{
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (pll_idx >= SIT9531X_NUM_PLLS)
+		return false;
+
+	input_idx = sit9531x_prio_src_canon(sitdev, input_idx);
+	if (input_idx >= SIT9531X_PRIO_NUM_SRC)
+		return false;
+
+	return !!(sitdev->chan[pll_idx].prio_mask & BIT(input_idx));
+}
+
+/*
+ * Take the configured priorities from a table the hardware holds: each
+ * listed source gets the first slot it occupies.  A source the table does
+ * not list keeps whatever it had, so a disconnected input comes back with
+ * its old priority.
+ */
+static void sit9531x_prio_cfg_seed(struct sit9531x_dev *sitdev, u8 pll_idx,
+				   const u8 *srcs)
+{
+	struct sit9531x_chan *chan = &sitdev->chan[pll_idx];
+	u16 seeded = 0;
+	u8 slot, src;
+
+	for (slot = 0; slot < SIT9531X_PRIO_MAX_SLOTS; slot++) {
+		src = srcs[slot] & SIT9531X_PRIO_NIBBLE_MASK;
+		if (!sit9531x_prio_src_usable(src))
+			continue;
+		src = sit9531x_prio_src_canon(sitdev, src);
+		if (seeded & BIT(src))
+			continue;
+		seeded |= BIT(src);
+		chan->cfg_prio[src] = slot;
+		chan->cfg_known |= BIT(src);
+	}
+
+	/*
+	 * A source this PLL has never listed gets the lowest slot, the value
+	 * it reports and the one it is connected at, so its priority does not
+	 * change when its state does.
+	 */
+	for (src = 0; src < SIT9531X_PRIO_NUM_SRC; src++) {
+		if (chan->cfg_known & BIT(src))
+			continue;
+		chan->cfg_prio[src] = SIT9531X_PRIO_MAX_SLOTS - 1;
+		chan->cfg_known |= BIT(src);
+	}
+
+	memcpy(chan->seen_srcs, srcs, sizeof(chan->seen_srcs));
+	chan->seen_valid = true;
+}
+
+/*
+ * Build the table for a set of member sources: ordered by configured
+ * priority, ties kept in the order the hardware table has them, the slots
+ * past the last member naming no source.  Filling them with the code for
+ * no source rather than with copies of the last member keeps every
+ * source in exactly one slot, so the order the table encodes is the
+ * order the priorities say.
+ */
+static void sit9531x_prio_table_build(struct sit9531x_dev *sitdev, u8 pll_idx,
+				      u16 members, u8 *srcs)
+{
+	const struct sit9531x_chan *chan = &sitdev->chan[pll_idx];
+	u8 order[SIT9531X_PRIO_NUM_SRC], n = 0, i, j, src;
+
+	for (src = 0; src < SIT9531X_PRIO_NUM_SRC; src++)
+		if (members & BIT(src))
+			order[n++] = src;
+
+	/* Insertion sort: at most a dozen entries. */
+	for (i = 1; i < n; i++) {
+		u8 cur = order[i];
+
+		for (j = i; j > 0; j--) {
+			u8 prev = order[j - 1];
+			u16 kc, kp;
+
+			kc = (chan->cfg_known & BIT(cur)) ?
+			     chan->cfg_prio[cur] : U8_MAX;
+			kp = (chan->cfg_known & BIT(prev)) ?
+			     chan->cfg_prio[prev] : U8_MAX;
+			if (kc == kp) {
+				/* Keep the hardware order among equals. */
+				kc = chan->prio_last[cur] ?: U8_MAX;
+				kp = chan->prio_last[prev] ?: U8_MAX;
+			}
+			if (kp <= kc)
+				break;
+			order[j] = prev;
+		}
+		order[j] = cur;
+	}
+
+	for (i = 0; i < SIT9531X_PRIO_MAX_SLOTS; i++)
+		srcs[i] = i < n ? order[i] : SIT9531X_PRIO_SRC_NONE;
+}
+
+/*
+ * Refresh a PLL's cached view of its priority table from the source codes
+ * the table holds -- here after a write, and once per poll from the
+ * read-back in sit9531x_chan_state_fetch().
+ *
+ * The membership mask is what the pin state getters test, the per-slot
+ * copy is what a rewrite compares against, and the first-slot array
+ * orders sources of equal priority, so none of them costs a register read
+ * per pin.
  */
 static void sit9531x_prio_mask_build(struct sit9531x_dev *sitdev, u8 pll_idx,
 				     const u8 *srcs)
 {
+	struct sit9531x_chan *chan = &sitdev->chan[pll_idx];
+	u8 first[SIT9531X_PRIO_NUM_SRC] = { 0 };
 	u16 mask = 0;
-	u8 slot;
+	u8 slot, src, src_canon;
 
 	for (slot = 0; slot < SIT9531X_PRIO_MAX_SLOTS; slot++) {
-		u8 src = srcs[slot] & SIT9531X_PRIO_NIBBLE_MASK;
+		src = srcs[slot];
+		src &= SIT9531X_PRIO_NIBBLE_MASK;
+		chan->prio_srcs[slot] = src;
+		src_canon = sit9531x_prio_src_canon(sitdev, src);
+		if (!sit9531x_prio_src_usable(src))
+			continue;
+
+		mask |= BIT(src_canon);
+		if (!first[src_canon])
+			first[src_canon] = slot + 1;
+	}
+
+	/*
+	 * Assign unconditionally: a source that has left the table has no
+	 * slot, and leaving its old one behind would keep reporting it as
+	 * listed for as long as the device runs.
+	 */
+	for (src = 0; src < SIT9531X_PRIO_NUM_SRC; src++)
+		chan->prio_last[src] = first[src];
+
+	chan->prio_mask = mask;
+}
+
+/* Attempts to release a forced holdover before reporting it stuck. */
+#define SIT9531X_HO_CLEAR_TRIES		3
+
+static int sit9531x_prio_table_read(struct sit9531x_dev *sitdev, u8 pll_idx,
+				    u8 *srcs);
+
+/*
+ * First source in a table that the device could lock to now, compared as
+ * canonical codes, or SIT9531X_PRIO_SRC_NONE when no listed source has a
+ * signal.
+ */
+static u8 sit9531x_prio_top_live(const struct sit9531x_dev *sitdev,
+				 const u8 *srcs)
+{
+	u8 i, src;
+
+	for (i = 0; i < SIT9531X_PRIO_MAX_SLOTS; i++) {
+		src = srcs[i] & SIT9531X_PRIO_NIBBLE_MASK;
+		src = sit9531x_prio_src_canon(sitdev, src);
+		if (sit9531x_prio_src_usable(src) &&
+		    sit9531x_prio_src_live(sitdev, src))
+			return src;
+	}
+
+	return SIT9531X_PRIO_SRC_NONE;
+}
+
+/*
+ * Choose the active selection for a table about to be latched.  After a
+ * table write the PLL goes to the source the selection names; it moves to
+ * another on its own only when that source loses its signal, which is an
+ * event, not a state.  So the selection has to name a source the PLL can
+ * use, and it follows the priorities the way the DPLL interface defines
+ * automatic mode -- the highest-priority valid input:
+ *
+ * - When the highest-priority source with signal is not the one the
+ *   table held before, the priorities now put another source first, and
+ *   the selection goes to it.
+ * - Otherwise the write only reorders sources below it, or removes one
+ *   the PLL is not on, and the selection stays where it is while that
+ *   source is still listed and has signal: a change further down the
+ *   table must not pull a PLL off a healthy reference.
+ * - Otherwise the first listed source with signal; with none alive the
+ *   first listed one is as good as any.
+ *
+ * A selection that is still listed but has lost its signal is moved too.
+ * The PLL has then fallen back on its own and the selection still names
+ * the dead source; left alone, the next table write sends the PLL back to
+ * it and it unlocks.  The device falls back to the best listed source
+ * that has signal, which is the one chosen here, so moving the selection
+ * there does not move the PLL.
+ *
+ * @old is the table the device holds before this write.
+ */
+static u8 sit9531x_prio_activesel_pick(struct sit9531x_dev *sitdev,
+				       const u8 *old, const u8 *srcs, u8 cur)
+{
+	u8 top, i;
+
+	top = sit9531x_prio_top_live(sitdev, srcs);
+	if (top != SIT9531X_PRIO_SRC_NONE &&
+	    top != sit9531x_prio_top_live(sitdev, old))
+		return top;
+
+	/*
+	 * The table is built from canonical codes, so compare in the same
+	 * terms: a differential pair selected through its N-lane code is the
+	 * P-lane entry.
+	 */
+	cur = sit9531x_prio_src_canon(sitdev, cur & SIT9531X_PRIO_NIBBLE_MASK);
+
+	if (sit9531x_prio_src_usable(cur) &&
+	    sit9531x_prio_src_live(sitdev, cur))
+		for (i = 0; i < SIT9531X_PRIO_MAX_SLOTS; i++)
+			if (srcs[i] == cur)
+				return cur;
+
+	if (top != SIT9531X_PRIO_SRC_NONE)
+		return top;
+
+	return srcs[0];
+}
+
+static int sit9531x_prio_table_commit(struct sit9531x_dev *sitdev, u8 pll_idx,
+				      const u8 *srcs)
+{
+	struct sit9531x_chan *chan = &sitdev->chan[pll_idx];
+	u8 val, last_old, slot, attempt, written = 0, restored = 0;
+	u8 now[SIT9531X_PRIO_MAX_SLOTS];
+	int rc = 0, prg_rc, ho_rc = 0;
+	bool empty, ho_foreign;
+	u16 reg;
+
+	empty = !sit9531x_prio_src_usable(srcs[0]);
+
+	/*
+	 * A forced holdover already in place is this driver's own when the
+	 * table lists nothing -- the hold an empty table keeps -- or when a
+	 * release is still owed from an earlier write.  Any other was put
+	 * there by the loaded configuration or by a tool, and a table write
+	 * is no reason to lift it: the sequence runs under it and leaves it
+	 * as found.
+	 */
+	rc = sit9531x_read_pll_u8(sitdev, pll_idx, SIT9531X_PLL_REG_HO_CTRL,
+				  &val);
+	if (rc)
+		return rc;
+
+	ho_foreign = (val & BIT(SIT9531X_PLL_HO_FORCE_BIT)) &&
+		     chan->prio_mask && !chan->ho_release_pending;
+
+	/*
+	 * A write that reports an error may still have reached the part, so
+	 * a failure here does not prove the bit stayed clear: nothing is
+	 * written to the table, but the release below still runs.
+	 */
+	rc = sit9531x_write_pll_u8(sitdev, pll_idx, SIT9531X_PLL_REG_HO_CTRL,
+				   val | BIT(SIT9531X_PLL_HO_FORCE_BIT));
+	if (rc)
+		goto release;
+
+	usleep_range(10000, 12000);
+
+	/*
+	 * Two slots share a register, and this writes every slot, so both
+	 * nibbles are known for every register but the last -- build those
+	 * bytes outright.  Reading first would raise the question of what a
+	 * read returns between the write and the latch, and the answer does
+	 * not matter if nothing is read.
+	 */
+	for (slot = 0; slot + 1 < SIT9531X_PRIO_MAX_SLOTS; slot += 2) {
+		reg = sit9531x_prio_reg(pll_idx, slot);
+
+		val = sit9531x_prio_slot_set(0, slot, srcs[slot]);
+		val = sit9531x_prio_slot_set(val, slot + 1, srcs[slot + 1]);
+
+		/*
+		 * Counted before the write: a write that reports an error
+		 * may still have reached the part, so the rollback has to
+		 * cover that register too.
+		 */
+		written = slot + 2;
+		rc = sit9531x_write_u8(sitdev, reg, val);
+		if (rc)
+			goto rollback;
+	}
+
+	/*
+	 * The last register carries slot 10 in its high nibble and the
+	 * device's active selection in its low one; see
+	 * sit9531x_prio_activesel_pick() for how the selection is chosen.
+	 * It needs the signal state now, not as of the last poll.
+	 *
+	 * The slot setter picks its nibble by parity, so the selection is
+	 * addressed as the slot past the last one.  This register has not
+	 * been written yet in this sequence, so the read returns what the
+	 * device is running with, and that byte is what a rollback puts
+	 * back.
+	 *
+	 * A table naming no source at all is what removing the last one
+	 * asks for.  There is nothing to point the selection at -- the code
+	 * for no source is not one the selection takes -- so the nibble is
+	 * left alone and the PLL is kept in holdover below instead.
+	 */
+	reg = sit9531x_prio_reg(pll_idx, slot);
+
+	rc = sit9531x_read_u8(sitdev, reg, &last_old);
+	if (rc)
+		goto rollback;
+
+	val = sit9531x_prio_slot_set(last_old, slot, srcs[slot]);
+
+	if (!empty) {
+		u8 sel = sit9531x_prio_slot_get(val, slot + 1);
+
+		/*
+		 * Without a fresh read the pick would run on the last
+		 * poll's monitor state, up to a poll period old.  A source
+		 * that lost its signal since would still look live, and a
+		 * selection naming a dead source sends the PLL to it and it
+		 * unlocks, so no selection is written without the read: the
+		 * slots written so far are rolled back and the request
+		 * fails.
+		 */
+		rc = sit9531x_input_mon_fetch(sitdev);
+		if (rc)
+			goto rollback;
+		sel = sit9531x_prio_activesel_pick(sitdev, chan->prio_srcs,
+						   srcs, sel);
+		val = sit9531x_prio_slot_set(val, slot + 1, sel);
+	}
+
+	written = SIT9531X_PRIO_MAX_SLOTS;
+	rc = sit9531x_write_u8(sitdev, reg, val);
+	if (rc)
+		goto rollback;
+
+rollback:
+	if (rc && written) {
+		/*
+		 * Put the slots that may have reached the device back the
+		 * way they were, the register whose write reported the error
+		 * included.  Latching a table that is neither the previous
+		 * order nor the requested one hands the reference selection
+		 * loop a priority list nobody asked for.  The cache is the
+		 * table as last read, which is what those slots held; the
+		 * last register also carries the selection, so it goes back
+		 * as it was read above.
+		 */
+		for (slot = 0; slot < written; slot += 2) {
+			u8 old;
+
+			if (slot + 1 < SIT9531X_PRIO_MAX_SLOTS) {
+				old = sit9531x_prio_slot_set(0, slot,
+							     chan->prio_srcs[slot]);
+				old = sit9531x_prio_slot_set(old, slot + 1,
+							     chan->prio_srcs[slot + 1]);
+			} else {
+				old = last_old;
+			}
+			if (sit9531x_write_u8(sitdev,
+					      sit9531x_prio_reg(pll_idx, slot),
+					      old))
+				break;
 
-		if (sit9531x_prio_src_usable(src))
-			mask |= BIT(src);
+			restored = slot + 2;
+		}
+		written = restored;
 	}
 
-	sitdev->chan[pll_idx].prio_mask = mask;
+	/*
+	 * Latch unconditionally: the slots that reached the device are in
+	 * the table regardless, so the latch keeps hardware and the cache
+	 * refresh below consistent with what was actually written.
+	 */
+	prg_rc = sit9531x_prio_prg_commit(sitdev);
+	if (prg_rc && !rc)
+		rc = prg_rc;
+
+	/*
+	 * Refresh the cache so a get that follows a set does not have to
+	 * wait for the next poll.  After a complete write that is the table
+	 * just written.  After a failure it is whatever the device holds
+	 * now -- part request, part restore -- so read it back rather than
+	 * piece it together: the membership test decides what a failed
+	 * request rolls back, and it must not answer for writes that did not
+	 * land.  A read-back that fails too leaves the next poll to do it.
+	 */
+	if (!rc) {
+		sit9531x_prio_mask_build(sitdev, pll_idx, srcs);
+		memcpy(chan->seen_srcs, srcs, sizeof(chan->seen_srcs));
+		chan->seen_valid = true;
+	} else if (!sit9531x_prio_table_read(sitdev, pll_idx, now)) {
+		sit9531x_prio_mask_build(sitdev, pll_idx, now);
+		memcpy(chan->seen_srcs, now, sizeof(chan->seen_srcs));
+		chan->seen_valid = true;
+	}
+
+release:
+	/*
+	 * A table that names no source keeps the PLL in the holdover forced
+	 * above: that is the one state in which it follows no input, which
+	 * is what disconnecting every input asks for.  The selection nibble
+	 * alone would not do it -- it still names the old source, and the
+	 * PLL keeps following that one for as long as it has signal.  The
+	 * next table write that lists a source releases it.
+	 *
+	 * Judged on the table the device holds now, as the refresh above
+	 * read it, not on the one requested: a write that failed on a PLL
+	 * listing nothing leaves it listing nothing, and releasing the hold
+	 * then would hand the PLL back to the source the selection still
+	 * names while every pin reports disconnected.  An empty table whose
+	 * latch failed is the same case from the other side.
+	 */
+	if (!chan->prio_mask) {
+		dev_dbg(sitdev->dev,
+			"PLL%c: no source listed, holdover kept\n",
+			'A' + pll_idx);
+		chan->ho_release_pending = false;
+		return rc;
+	}
+
+	if (ho_foreign) {
+		dev_dbg(sitdev->dev,
+			"PLL%c: holdover was forced before the write, left in place\n",
+			'A' + pll_idx);
+		return rc;
+	}
+
+	/*
+	 * Release the forced holdover.  Apart from an empty table, nothing
+	 * in the driver keeps this bit set, and a retry of the same request
+	 * finds the table already as asked and does not come back here, so
+	 * a PLL left with it would report holdover until some unrelated
+	 * table write on the same PLL cleared it.  Retry before giving up;
+	 * if it stays set, say so and leave the release owed to the poll,
+	 * which retries it every tick until it lands.
+	 */
+	for (attempt = 0; attempt < SIT9531X_HO_CLEAR_TRIES; attempt++) {
+		ho_rc = sit9531x_update_pll_u8(sitdev, pll_idx,
+					       SIT9531X_PLL_REG_HO_CTRL,
+					       BIT(SIT9531X_PLL_HO_FORCE_BIT),
+					       0);
+		if (!ho_rc)
+			break;
+		usleep_range(1000, 2000);
+	}
+	if (ho_rc) {
+		dev_err(sitdev->dev, "PLL%c left in forced holdover: %d\n",
+			'A' + pll_idx, ho_rc);
+		if (!rc)
+			rc = ho_rc;
+	}
+	chan->ho_release_pending = !!ho_rc;
+
+	return rc;
 }
 
 /*
@@ -479,6 +1142,155 @@ static int sit9531x_prio_table_read(struct sit9531x_dev *sitdev, u8 pll_idx,
 	return 0;
 }
 
+/*
+ * Rewrite a PLL's table for a new member set, unless it would come out as
+ * the table already holds: every write forces the PLL into holdover for
+ * the length of the sequence, so one that changes nothing is a
+ * disturbance nobody asked for.
+ */
+static int sit9531x_prio_table_apply(struct sit9531x_dev *sitdev, u8 pll_idx,
+				     u16 members)
+{
+	u8 srcs[SIT9531X_PRIO_MAX_SLOTS];
+
+	if (hweight16(members) > SIT9531X_PRIO_MAX_SLOTS)
+		return -ENOSPC;
+
+	sit9531x_prio_table_build(sitdev, pll_idx, members, srcs);
+	if (!memcmp(srcs, sitdev->chan[pll_idx].prio_srcs, sizeof(srcs)))
+		return 0;
+
+	return sit9531x_prio_table_commit(sitdev, pll_idx, srcs);
+}
+
+/*
+ * sit9531x_input_prio_set - set an input's priority on a PLL
+ * @input_idx:	input source in hardware encoding (0-11, see
+ *		sit9531x_input_hw_src())
+ * @prio:	priority, lower is preferred
+ *
+ * Records the priority and, when the source is in the PLL's table,
+ * rebuilds the table from the configured priorities.  A source that is
+ * not in the table keeps the priority for when it is connected: that is
+ * the pin's state, and it belongs to the state setter.  Other sources
+ * keep theirs either way, so no sibling's priority moves.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ *
+ * Return: 0 on success, -EINVAL for a bad PLL or source, <0 on error
+ */
+int sit9531x_input_prio_set(struct sit9531x_dev *sitdev, u8 pll_idx,
+			    u8 input_idx, u8 prio)
+{
+	struct sit9531x_chan *chan;
+	u8 old_prio;
+	u16 old_known;
+	int rc;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (pll_idx >= SIT9531X_NUM_PLLS)
+		return -EINVAL;
+	input_idx = sit9531x_prio_src_canon(sitdev, input_idx);
+	if (input_idx >= SIT9531X_PRIO_NUM_SRC)
+		return -EINVAL;
+
+	chan = &sitdev->chan[pll_idx];
+	old_prio = chan->cfg_prio[input_idx];
+	old_known = chan->cfg_known;
+	chan->cfg_prio[input_idx] = prio;
+	chan->cfg_known |= BIT(input_idx);
+
+	if (!(chan->prio_mask & BIT(input_idx)))
+		return 0;
+
+	/*
+	 * The table is built from the configured priority, so it has to be
+	 * recorded before the rebuild; a rebuild that failed takes the
+	 * record back with it.  Left in place, a refused priority would be
+	 * reported by the getter, notified by the poll, and written by the
+	 * next rebuild for any other reason.
+	 */
+	rc = sit9531x_prio_table_apply(sitdev, pll_idx, chan->prio_mask);
+	if (rc) {
+		chan->cfg_prio[input_idx] = old_prio;
+		chan->cfg_known = old_known;
+	}
+
+	return rc;
+}
+
+/*
+ * sit9531x_input_prio_remove - drop an input from a PLL's priority table
+ * @input_idx:	input source in hardware encoding
+ *
+ * Rebuilds the table without the source, which makes a disconnected
+ * input ineligible for automatic reference selection, not just gated at
+ * the input buffer.  The source keeps its configured priority for when it
+ * comes back.  Removing a source that is absent succeeds without touching
+ * the table.  Removing the last one leaves a table that names no source;
+ * the commit then keeps the PLL in holdover, which is what disconnecting
+ * every input asks for.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ *
+ * Return: 0 on success, <0 on error
+ */
+int sit9531x_input_prio_remove(struct sit9531x_dev *sitdev, u8 pll_idx,
+			       u8 input_idx)
+{
+	struct sit9531x_chan *chan;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (pll_idx >= SIT9531X_NUM_PLLS)
+		return -EINVAL;
+	input_idx = sit9531x_prio_src_canon(sitdev, input_idx);
+	if (input_idx >= SIT9531X_PRIO_NUM_SRC)
+		return -EINVAL;
+
+	chan = &sitdev->chan[pll_idx];
+	if (!(chan->prio_mask & BIT(input_idx)))
+		return 0;
+
+	return sit9531x_prio_table_apply(sitdev, pll_idx,
+					 chan->prio_mask & ~BIT(input_idx));
+}
+
+/*
+ * sit9531x_input_prio_add - make an input eligible in a PLL's table
+ * @input_idx:	input source in hardware encoding
+ *
+ * Puts the source back into the table at its configured priority; one the
+ * PLL never listed has the lowest slot (see sit9531x_prio_cfg_seed()).  A
+ * source that is already listed leaves the table untouched.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ *
+ * Return: 0 on success, -ENOSPC when the table cannot hold another
+ * source, <0 on error
+ */
+int sit9531x_input_prio_add(struct sit9531x_dev *sitdev, u8 pll_idx,
+			    u8 input_idx)
+{
+	struct sit9531x_chan *chan;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (pll_idx >= SIT9531X_NUM_PLLS)
+		return -EINVAL;
+	input_idx = sit9531x_prio_src_canon(sitdev, input_idx);
+	if (input_idx >= SIT9531X_PRIO_NUM_SRC)
+		return -EINVAL;
+
+	chan = &sitdev->chan[pll_idx];
+	if (chan->prio_mask & BIT(input_idx))
+		return 0;
+
+	return sit9531x_prio_table_apply(sitdev, pll_idx,
+					 chan->prio_mask | BIT(input_idx));
+}
+
 /* XO doubler register */
 #define SIT9531X_REG_XO2_GENERIC		SIT9531X_REG(0x00, 0x2D)
 #define SIT9531X_XO_DOUBLER_ENB_BIT		7   /* inverted: 0 = enabled */
@@ -569,7 +1381,8 @@ int sit9531x_clear_notifications(struct sit9531x_dev *sitdev)
  * @index:	logical input index
  *
  * Reads whether the lane's receiver is on, from the Page 0x02 force and
- * state bits.
+ * state bits.  Signal status comes from sit9531x_input_mon_fetch(),
+ * which reads every lane's clock monitor in one pass.
  */
 static int sit9531x_ref_state_fetch(struct sit9531x_dev *sitdev, u8 index)
 {
@@ -661,6 +1474,73 @@ static int sit9531x_pll_is_active(struct sit9531x_dev *sitdev, u8 pll_idx,
 	return 0;
 }
 
+/*
+ * Read the reference the device feeds a PLL.
+ *
+ * The active selection names the source the PLL was told to follow.  The
+ * input subsystem feeds the PLL that source while it has signal and falls
+ * back to another listed source on its own when it does not, without
+ * touching the selection, so after such a fallback the selection no
+ * longer says which reference the PLL runs on.  The debug status bus
+ * does: addressed at the routed reference, it returns the source code
+ * the input subsystem currently feeds the PLL.
+ *
+ * This names the source and nothing more.  Whether the PLL is locked to
+ * it is read from the outer-loop lock and the lane's clock monitor; in
+ * free-run the PLL is fed nothing and the bus is not consulted, so the
+ * caller checks the mode first.
+ *
+ * @ref is the logical input index, SIT9531X_INTSYNC_PIN_ID for the
+ * inter-PLL sync net, or SIT9531X_REF_INVALID when the code names no
+ * registered input.  Caller must hold sitdev->multiop_lock.
+ */
+static int sit9531x_chan_routed_ref_read(struct sit9531x_dev *sitdev,
+					 u8 pll_idx, u8 *ref)
+{
+	int rc, lock_rc;
+	u8 v, i;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	rc = sit9531x_write_pll_u8(sitdev, pll_idx, SIT9531X_PLL_REG_DEBUG,
+				   SIT9531X_PLL_DEBUG_UNLOCK);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_write_pll_u8(sitdev, pll_idx,
+				   SIT9531X_PLL_REG_DBG_STATUS_ADDR,
+				   SIT9531X_DBG_STATUS_ROUTED_SRC);
+	if (rc)
+		goto relock;
+
+	/* The first reads return earlier latches; the last is current. */
+	for (i = 0; i < SIT9531X_DBG_STATUS_READS; i++) {
+		rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+					  SIT9531X_PLL_REG_DBG_STATUS_DATA,
+					  &v);
+		if (rc)
+			goto relock;
+	}
+
+	/*
+	 * Canonicalise like the table entries: a differential pair fed
+	 * through its N-lane code is the P-lane pin.
+	 */
+	v = sit9531x_prio_src_canon(sitdev, v & SIT9531X_DBG_ROUTED_SRC_MASK);
+	*ref = sit9531x_hw_src_input(v);
+
+relock:
+	/*
+	 * Lock the debug registers again.  A read that failed is reported
+	 * ahead of a lock that did; a lock that failed on its own leaves the
+	 * page open to a stray write and is reported too.
+	 */
+	lock_rc = sit9531x_write_pll_u8(sitdev, pll_idx, SIT9531X_PLL_REG_DEBUG,
+					SIT9531X_PLL_DEBUG_LOCK);
+
+	return rc ? rc : lock_rc;
+}
+
 /*
  * sit9531x_chan_state_fetch - read PLL channel status from hardware
  *
@@ -669,11 +1549,11 @@ static int sit9531x_pll_is_active(struct sit9531x_dev *sitdev, u8 pll_idx,
  */
 static int sit9531x_chan_state_fetch(struct sit9531x_dev *sitdev, u8 pll_idx)
 {
-	u8 status, outer_lol, input_sel, inner_lol, ho_freeze, activesel_reg;
 	struct sit9531x_chan *chan = &sitdev->chan[pll_idx];
+	u8 status, outer_lol, inner_lol, ho_freeze, pll_status_1;
 	u8 srcs[SIT9531X_PRIO_MAX_SLOTS];
-	u8 pll_status_1;
-	bool active;
+	u8 routed = SIT9531X_REF_INVALID;
+	bool active, tracking;
 	int rc;
 
 	/*
@@ -696,22 +1576,6 @@ static int sit9531x_chan_state_fetch(struct sit9531x_dev *sitdev, u8 pll_idx)
 	if (rc)
 		return rc;
 
-	/*
-	 * Read the input source the PLL has currently selected as its
-	 * active reference.  This lives in the low nibble of the last
-	 * register of the PLL's page-1 priority block (CLK_ACTIVESEL_PLL),
-	 * not on the PLL page -- PLL-page 0x29 is a config register.
-	 */
-	activesel_reg = SIT9531X_PRIO_BASE_REG +
-			SIT9531X_PRIO_REGS_PER_PLL * pll_idx +
-			SIT9531X_PRIO_ACTIVESEL_OFF;
-	rc = sit9531x_read_u8(sitdev,
-			      SIT9531X_REG(SIT9531X_PAGE_PRIOSYS,
-					   activesel_reg),
-			      &input_sel);
-	if (rc)
-		return rc;
-
 	rc = sit9531x_read_u8(sitdev, SIT9531X_REG_PLL_INNER_LOL_STATUS,
 			      &inner_lol);
 	if (rc)
@@ -722,6 +1586,21 @@ static int sit9531x_chan_state_fetch(struct sit9531x_dev *sitdev, u8 pll_idx)
 	if (rc)
 		return rc;
 
+	/*
+	 * The reference the device feeds the PLL, read only while the PLL
+	 * tracks one -- running, locked, outer loop on, not frozen -- which
+	 * is the only case the pin state reports it.  In free-run the PLL
+	 * is fed nothing and the status bus is not consulted.
+	 */
+	tracking = active && !(outer_lol & BIT(pll_idx)) &&
+		   !(status & SIT9531X_PLL_STATUS_OUTER_DIS) &&
+		   !(ho_freeze & BIT(pll_idx));
+	if (tracking) {
+		rc = sit9531x_chan_routed_ref_read(sitdev, pll_idx, &routed);
+		if (rc)
+			return rc;
+	}
+
 	rc = sit9531x_read_pll_u8(sitdev, pll_idx, SIT9531X_PLL_REG_STATUS_1,
 				  &pll_status_1);
 	if (rc)
@@ -739,12 +1618,21 @@ static int sit9531x_chan_state_fetch(struct sit9531x_dev *sitdev, u8 pll_idx)
 
 	sit9531x_prio_mask_build(sitdev, pll_idx, srcs);
 
+	/*
+	 * The configured priorities come from the table the first time it
+	 * is read, and again whenever it no longer matches what the driver
+	 * last wrote: something else -- a profile reload, a direct I2C
+	 * tool -- rewrote it, and that table is now the configuration.
+	 */
+	if (!chan->seen_valid ||
+	    memcmp(srcs, chan->seen_srcs, sizeof(chan->seen_srcs)))
+		sit9531x_prio_cfg_seed(sitdev, pll_idx, srcs);
+
 	/* STATUS_1_GENERIC reports loss of lock, so invert it. */
 	chan->active = active;
 	chan->locked = active && !(outer_lol & BIT(pll_idx));
 	chan->mode = !!(status & SIT9531X_PLL_STATUS_OUTER_DIS);
-	chan->selected_ref =
-		sit9531x_hw_src_input(input_sel & SIT9531X_PRIO_NIBBLE_MASK);
+	chan->routed_ref = routed;
 	chan->inner_lol = !!(inner_lol & BIT(pll_idx));
 	chan->ho_freeze = !!(ho_freeze & BIT(pll_idx));
 	chan->ho_valid = !!(pll_status_1 & SIT9531X_PLL_STATUS_1_HO_VALID);
@@ -913,6 +1801,13 @@ static int sit9531x_dev_state_fetch(struct sit9531x_dev *sitdev)
 		}
 	}
 
+	rc = sit9531x_input_mon_fetch(sitdev);
+	if (rc) {
+		dev_err(sitdev->dev,
+			"Failed to read the input clock monitors: %d\n", rc);
+		return rc;
+	}
+
 	/*
 	 * The priority-table read walks the Page-1 registers, so it runs
 	 * with multiop_lock held like every other multi-register sequence.
@@ -938,14 +1833,22 @@ static int sit9531x_dev_state_fetch(struct sit9531x_dev *sitdev)
 		}
 	}
 
+	/*
+	 * The channel fetch walks the priority table and the debug status
+	 * bus, multi-register sequences that expect the lock; nothing races
+	 * with them yet, but they are serialized the same way as at runtime.
+	 */
+	mutex_lock(&sitdev->multiop_lock);
 	for (i = 0; i < SIT9531X_NUM_PLLS; i++) {
 		rc = sit9531x_chan_state_fetch(sitdev, i);
-		if (rc) {
-			dev_err(sitdev->dev,
-				"Failed to fetch PLL%c state: %d\n",
-				'A' + i, rc);
-			return rc;
-		}
+		if (rc)
+			break;
+	}
+	mutex_unlock(&sitdev->multiop_lock);
+	if (rc) {
+		dev_err(sitdev->dev, "Failed to fetch PLL%c state: %d\n",
+			'A' + i, rc);
+		return rc;
 	}
 
 	return 0;
@@ -961,6 +1864,71 @@ static void sit9531x_dev_ref_states_update(struct sit9531x_dev *sitdev)
 			dev_warn(sitdev->dev,
 				 "Failed to get REF%u status: %d\n", i, rc);
 	}
+
+	rc = sit9531x_input_mon_fetch(sitdev);
+	if (rc)
+		dev_warn(sitdev->dev,
+			 "Failed to read the input clock monitors: %d\n", rc);
+}
+
+/*
+ * sit9531x_ref_pll_mask_rebuild - re-derive the input receiver refcounts
+ *
+ * ref->pll_mask decides when an input receiver may be powered down, and
+ * the connect and disconnect paths maintain it by hand.  A request that
+ * failed part way through leaves it describing a table the device does
+ * not hold, and nothing else corrected it: a later disconnect could then
+ * drop the count to zero and gate an input another PLL is still locked
+ * to.  Re-derive every mask from the tables the poll has just read.  No
+ * extra bus traffic -- sit9531x_chan_state_fetch() refreshed the masks
+ * this reads immediately before.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static void sit9531x_ref_pll_mask_rebuild(struct sit9531x_dev *sitdev)
+{
+	u8 pll_idx, src, index;
+
+	for (index = 0; index < sitdev->info->num_inputs; index++)
+		sitdev->ref[index].pll_mask = 0;
+
+	for (pll_idx = 0; pll_idx < SIT9531X_NUM_PLLS; pll_idx++) {
+		u16 mask = sitdev->chan[pll_idx].prio_mask;
+
+		for (src = 0; src < SIT9531X_PRIO_NUM_SRC; src++) {
+			if (!(mask & BIT(src)))
+				continue;
+
+			index = sit9531x_hw_src_input(src);
+			if (index < sitdev->info->num_inputs)
+				sitdev->ref[index].pll_mask |= BIT(pll_idx);
+		}
+	}
+}
+
+/*
+ * Release a forced holdover that a table write owes.  The write forces
+ * holdover and releases it at the end; when the release failed, nothing
+ * else in the driver clears the bit -- a retry of the same request finds
+ * the table already as asked and does not run the sequence again -- so
+ * the poll retries it each tick until it lands.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static void sit9531x_ho_release_retry(struct sit9531x_dev *sitdev, u8 pll_idx)
+{
+	struct sit9531x_chan *chan = &sitdev->chan[pll_idx];
+
+	if (!chan->ho_release_pending)
+		return;
+
+	if (sit9531x_update_pll_u8(sitdev, pll_idx, SIT9531X_PLL_REG_HO_CTRL,
+				   BIT(SIT9531X_PLL_HO_FORCE_BIT), 0))
+		return;
+
+	chan->ho_release_pending = false;
+	dev_info(sitdev->dev, "PLL%c: forced holdover released\n",
+		 'A' + pll_idx);
 }
 
 static void sit9531x_dev_chan_states_update(struct sit9531x_dev *sitdev)
@@ -968,12 +1936,15 @@ static void sit9531x_dev_chan_states_update(struct sit9531x_dev *sitdev)
 	int i, rc;
 
 	for (i = 0; i < SIT9531X_NUM_PLLS; i++) {
+		sit9531x_ho_release_retry(sitdev, i);
 		rc = sit9531x_chan_state_fetch(sitdev, i);
 		if (rc)
 			dev_warn(sitdev->dev,
 				 "Failed to get PLL%c state: %d\n",
 				 'A' + i, rc);
 	}
+
+	sit9531x_ref_pll_mask_rebuild(sitdev);
 }
 
 /*
@@ -1265,6 +2236,84 @@ static void sit9531x_pll_states_report(struct sit9531x_dev *sitdev)
 	}
 }
 
+/*
+ * sit9531x_input_pin_is_registrable - check if an input pin is registrable
+ *
+ * Split out so input-model changes stay local to this helper.
+ *
+ * Return: true if the input pin should be registered, false otherwise
+ */
+static bool sit9531x_input_pin_is_registrable(struct sit9531x_dev *sitdev,
+					      u8 index)
+{
+	if (index >= sitdev->info->num_inputs)
+		return false;
+
+	/*
+	 * The N lane of a differentially-configured pair is not a
+	 * standalone input and is skipped (zl3073x model).
+	 */
+	if (sit9531x_input_is_n(index) &&
+	    sitdev->ref[index].sig_mode == SIT9531X_MODE_DE)
+		return false;
+
+	return true;
+}
+
+/*
+ * Warn about a pin node in the firmware description whose reg names no
+ * pin this device can have: an input lane or an output the variant does
+ * not have, or the N lane of a pair the configuration runs differential.
+ * Nodes are looked up from the pins (sit9531x_pin_props_get()), so such a
+ * node would otherwise have its label and frequencies dropped without a
+ * word.  The binding bounds reg per variant; this catches what reaches
+ * the driver unvalidated, and the pair mode, which only the loaded
+ * configuration decides.  An output that exists but that no PLL drives
+ * gets no pin either and is not reported: which outputs a configuration
+ * uses is not a fault in the description.
+ */
+static void sit9531x_pin_nodes_check(struct sit9531x_dev *sitdev)
+{
+	struct fwnode_handle *pins, *node;
+	bool found;
+	u32 reg;
+	u8 i;
+
+	pins = device_get_named_child_node(sitdev->dev, "input-pins");
+	fwnode_for_each_child_node(pins, node) {
+		if (fwnode_property_read_u32(node, "reg", &reg))
+			continue;
+		if (reg < sitdev->info->num_inputs &&
+		    sit9531x_input_pin_is_registrable(sitdev, reg))
+			continue;
+		dev_warn(sitdev->dev,
+			 "input-pins/%pfwP: reg %u is %s, node ignored\n",
+			 node, reg,
+			 reg < sitdev->info->num_inputs ?
+			 "the N lane of a differential pair" :
+			 "not an input lane");
+	}
+	fwnode_handle_put(pins);
+
+	pins = device_get_named_child_node(sitdev->dev, "output-pins");
+	fwnode_for_each_child_node(pins, node) {
+		if (fwnode_property_read_u32(node, "reg", &reg))
+			continue;
+		found = false;
+		for (i = 0; i < sitdev->info->num_outputs; i++) {
+			if (sitdev->info->clkout_map[i] == reg) {
+				found = true;
+				break;
+			}
+		}
+		if (!found)
+			dev_warn(sitdev->dev,
+				 "output-pins/%pfwP: reg %u is not an output of %s, node ignored\n",
+				 node, reg, sitdev->info->name);
+	}
+	fwnode_handle_put(pins);
+}
+
 /*
  * sit9531x_dev_start - start normal operation
  *
@@ -1287,6 +2336,8 @@ int sit9531x_dev_start(struct sit9531x_dev *sitdev)
 	sit9531x_pll_states_report(sitdev);
 	mutex_unlock(&sitdev->multiop_lock);
 
+	sit9531x_pin_nodes_check(sitdev);
+
 	list_for_each_entry(sitdpll, &sitdev->dplls, list) {
 		rc = sit9531x_dpll_register(sitdpll);
 		if (rc) {
@@ -1468,9 +2519,9 @@ static void sit9531x_dpll_pins_unregister(struct sit9531x_dpll *sitdpll)
  * @dir:	pin direction
  * @index:	pin hardware index
  *
- * Only the XO pin has a complete pin-op table in this patch, so only
- * the XO pin is registrable here.  Other pin classes are registered
- * once their state callbacks land in the following patches.
+ * For input pins: delegate to sit9531x_input_pin_is_registrable().
+ * A pin class whose state callback the tree does not have yet is not
+ * registrable: the core refuses a pin without one.
  *
  * Return: true if pin should be registered, false otherwise
  */
@@ -1478,15 +2529,15 @@ static bool sit9531x_dpll_pin_is_registrable(struct sit9531x_dpll *sitdpll,
 					     enum dpll_pin_direction dir,
 					     u8 index)
 {
-	/*
-	 * Only the XO pin has a complete pin-op table in this patch.
-	 * Other pin classes are registered once their state callbacks
-	 * land in the following patches.
-	 */
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+
 	if (dir != DPLL_PIN_DIRECTION_INPUT)
 		return false;
 
-	return index == SIT9531X_MAX_INPUTS;
+	if (index == SIT9531X_MAX_INPUTS)
+		return true;
+
+	return sit9531x_input_pin_is_registrable(sitdev, index);
 }
 
 /*
diff --git a/drivers/dpll/sit9531x/core.h b/drivers/dpll/sit9531x/core.h
index 28fc99f50063..cf4dd5f82d05 100644
--- a/drivers/dpll/sit9531x/core.h
+++ b/drivers/dpll/sit9531x/core.h
@@ -38,7 +38,7 @@
 #define SIT9531X_INTSYNC_OUT_PIN_ID	SIT9531X_MAX_OUTPUTS
 #define SIT9531X_STATUS_POLL_MS		500
 
-/* selected_ref value when the active source is not a registered input */
+/* routed_ref value when the PLL is fed no registered input */
 #define SIT9531X_REF_INVALID		0xFF
 
 /* SiTime IEEE OUI for EUI-64 generation */
@@ -77,6 +77,9 @@ enum sit9531x_signal_mode {
  * @freq:		configured frequency in Hz
  * @enabled:		the lane's receiver is on
  * @pll_mask:		bitmask of PLLs this input feeds (bit 0 = PLLA)
+ * @los:		the clock monitor reports loss of signal on the lane
+ * @qual_fail:		the clock monitor reports a frequency drift on the
+ *			lane while it still has signal
  * @sig_mode:		signal mode of the pair this lane belongs to
  *			(detected from CLKINx_INPUT_MODE at probe)
  */
@@ -84,6 +87,8 @@ struct sit9531x_ref {
 	u64		freq;
 	bool		enabled;
 	u8		pll_mask;
+	bool		los;
+	bool		qual_fail;
 	enum sit9531x_signal_mode	sig_mode;
 };
 
@@ -113,15 +118,25 @@ struct sit9531x_out {
  *			loss-of-lock bit stays clear because nothing drives it
  * @locked:		PLL is active and its outer loop reports lock
  * @mode:		0 = sync (outer loop enabled), 1 = free-run
- * @selected_ref:	logical input index of the currently selected
- *			reference (the INTSYNC net maps to
- *			SIT9531X_INTSYNC_PIN_ID), or SIT9531X_REF_INVALID
- *			when the hardware source encoding is reserved
+ * @routed_ref:		logical input index of the reference the device
+ *			feeds the PLL while it tracks one (the INTSYNC net
+ *			maps to SIT9531X_INTSYNC_PIN_ID); SIT9531X_REF_INVALID
+ *			when the PLL tracks nothing -- free-run, frozen,
+ *			unlocked -- or the source code names no registered
+ *			input
  * @inner_lol:		PLL inner loop loss-of-lock detected
  * @ho_freeze:		holdover freeze active
  * @ho_valid:		holdover memory acquired, i.e. the holdover window
  *			holds a valid estimate to fall back on
- * @prio_mask:		bit per hardware source code present in this PLL's
+ * @ho_release_pending:	a table write forced holdover and could not release
+ *			it; the poll retries the release until it lands
+ * @prio_srcs:		cached copy of the priority table, one source code
+ *			per slot; refreshed together with @prio_mask, it is
+ *			what a rebuilt table is compared against
+ * @prio_last:		first slot each source occupies, plus one (0 = the
+ *			source is not in the table); refreshed from the same
+ *			scan as @prio_mask, so the two never disagree
+ * @prio_mask:		bit per canonical source present in this PLL's
  *			priority table, i.e. the sources it may select.  Read
  *			back from the table by the periodic worker and
  *			refreshed by every table write, so it tracks the
@@ -141,10 +156,13 @@ struct sit9531x_chan {
 	bool		active;
 	bool		locked;
 	u8		mode;
-	u8		selected_ref;
+	u8		routed_ref;
 	bool		inner_lol;
 	bool		ho_freeze;
 	bool		ho_valid;
+	bool		ho_release_pending;
+	u8		prio_srcs[SIT9531X_PRIO_MAX_SLOTS];
+	u8		prio_last[SIT9531X_PRIO_NUM_SRC];
 	u16		prio_mask;
 	u8		cfg_prio[SIT9531X_PRIO_NUM_SRC];
 	u16		cfg_known;
@@ -229,8 +247,18 @@ int sit9531x_update_pll_u8(struct sit9531x_dev *sitdev, u8 pll_idx,
 			   u8 offset, u8 mask, u8 val);
 
 /* ---- Input enable/disable ---- */
+int sit9531x_input_disable(struct sit9531x_dev *sitdev, u8 index);
+int sit9531x_input_enable(struct sit9531x_dev *sitdev, u8 index);
 
 /* ---- Input priority ---- */
+bool sit9531x_input_prio_present(struct sit9531x_dev *sitdev,
+				 u8 pll_idx, u8 input_idx);
+int sit9531x_input_prio_set(struct sit9531x_dev *sitdev, u8 pll_idx,
+			    u8 input_idx, u8 prio);
+int sit9531x_input_prio_remove(struct sit9531x_dev *sitdev, u8 pll_idx,
+			       u8 input_idx);
+int sit9531x_input_prio_add(struct sit9531x_dev *sitdev, u8 pll_idx,
+			    u8 input_idx);
 
 /* ---- Output enable/disable (Hi-Z control) ---- */
 
diff --git a/drivers/dpll/sit9531x/dpll.c b/drivers/dpll/sit9531x/dpll.c
index e88fa4e29bdf..4c7cae4ce93e 100644
--- a/drivers/dpll/sit9531x/dpll.c
+++ b/drivers/dpll/sit9531x/dpll.c
@@ -34,11 +34,31 @@ sit9531x_dpll_is_xo_pin(const struct sit9531x_dpll_pin *pin)
 	       pin->id == SIT9531X_MAX_INPUTS;
 }
 
+/*
+ * Status of a PLL whose outer loop is frozen in holdover.
+ *
+ * The interface has a PLL report holdover for a hold forced by
+ * disconnecting every input only when it was LOCKED_HO_ACQ before, that
+ * is, when it has a valid holdover estimate to run on; without one it
+ * stays UNLOCKED.  Removing the last source from a PLL's table forces
+ * exactly that hold, so a frozen PLL that lists no source is in holdover
+ * only while its memory is valid.  A PLL frozen with sources still listed
+ * lost its lock, and is in holdover on the device's say-so.
+ */
+static enum dpll_lock_status
+sit9531x_dpll_frozen_status(const struct sit9531x_chan *chan)
+{
+	if (!chan->prio_mask && !chan->ho_valid)
+		return DPLL_LOCK_STATUS_UNLOCKED;
+
+	return DPLL_LOCK_STATUS_HOLDOVER;
+}
+
 /*
  * The cached state this reports comes from the outer loss-of-lock byte
  * (page 0, reg 0x06), the PLL mode bit (PLL page, reg 0x31), inner LOL
- * (reg 0x92), the holdover freeze byte (reg 0x0A) and the per-PLL
- * holdover-valid bit (PLL page, reg 0x06).
+ * (reg 0x92), the holdover freeze byte (reg 0x0A), the per-PLL
+ * holdover-valid bit (PLL page, reg 0x06) and the priority table.
  */
 static int
 sit9531x_dpll_lock_status_get(const struct dpll_device *dpll, void *dpll_priv,
@@ -71,7 +91,7 @@ sit9531x_dpll_lock_status_get(const struct dpll_device *dpll, void *dpll_priv,
 		 * under a locked status would never reach userspace.  An
 		 * inner loop that is not locked is not a locked PLL.
 		 */
-		*status = chan->ho_freeze ? DPLL_LOCK_STATUS_HOLDOVER :
+		*status = chan->ho_freeze ? sit9531x_dpll_frozen_status(chan) :
 					    DPLL_LOCK_STATUS_UNLOCKED;
 	} else if (chan->mode) {
 		/*
@@ -90,7 +110,7 @@ sit9531x_dpll_lock_status_get(const struct dpll_device *dpll, void *dpll_priv,
 		 * counts a frozen PLL as tracking nothing for the same
 		 * reason.
 		 */
-		*status = DPLL_LOCK_STATUS_HOLDOVER;
+		*status = sit9531x_dpll_frozen_status(chan);
 	} else if (chan->locked) {
 		/*
 		 * HO_ACQ is locked *and* holdover memory acquired, so it needs
@@ -195,7 +215,8 @@ const struct dpll_device_ops sit9531x_dpll_device_ops = {
  *   the pin is the operational state.  Predicates, all evaluated under
  *   multiop_lock:
  *     M  source is present in THIS PLL's hardware priority table
- *     S  chan->selected_ref == this pin's id (the active selection)
+ *     S  chan->routed_ref == this pin's id (the reference the device
+ *        reports feeding the PLL)
  *     L  chan->locked && !chan->mode && !chan->ho_freeze
  *        (tracking a reference: outer loop running, locked, not frozen)
  *     N  the input lane's clock monitor reports loss of signal
@@ -218,12 +239,16 @@ const struct dpll_device_ops sit9531x_dpll_device_ops = {
  *                   no mode that pins one reference (see "Mode" above)
  *     other         -EINVAL
  *
- *   The ACTIVE test needs L as well as S because the selection is what the
- *   driver last wrote or the device last chose, not proof the loop uses
- *   it: a free-running, frozen or unlocked PLL follows nothing.  It needs
- *   !N because a PLL whose selection names a lane without signal has
- *   fallen back to another listed source on its own, and no register
- *   says which -- no pin is reported active then.  The INTSYNC destination
+ *   S is not the active selection the driver writes to the table: when
+ *   the selected source loses its signal the device falls back to another
+ *   listed source on its own and leaves the selection naming the dead one,
+ *   so the reference the device reports feeding the PLL is read instead,
+ *   and after such a fallback the pin the PLL moved to is the active one.
+ *   The ACTIVE test needs L as well as S because being fed to the PLL is
+ *   not proof the loop uses it: a free-running, frozen or unlocked PLL
+ *   follows nothing.  It needs !N because the device names what it feeds
+ *   the PLL, not what the PLL is locked to, and a lane without signal is
+ *   not that whatever the lock bit still says.  The INTSYNC destination
  *   has no monitor, so N and Q never hold for it.
  *
  *   M is read from the hardware priority table, not from ref->pll_mask,
@@ -241,6 +266,124 @@ const struct dpll_device_ops sit9531x_dpll_device_ops = {
  * FIXED role -- XO pin.  Always CONNECTED; it cannot be routed.
  */
 
+/*
+ * Report a selection-role pin's state on this DPLL.  @pin_id is a logical
+ * input index, SIT9531X_INTSYNC_PIN_ID for the INTSYNC destination.
+ *
+ * Membership comes from chan->prio_mask, which is the priority table read
+ * back from the chip -- not a record of what the driver asked for.  The
+ * getter runs on every poll for every input pin of every DPLL, so it takes
+ * the mask the worker refreshed rather than rescanning the table over I2C
+ * each time; table writes refresh it too, so a get right after a set does
+ * not report the old membership.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static void
+sit9531x_dpll_selection_state_get(struct sit9531x_dev *sitdev,
+				  const struct sit9531x_dpll *sitdpll,
+				  u8 pin_id, enum dpll_pin_state *state)
+{
+	const struct sit9531x_chan *chan;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	chan = sit9531x_chan_state_get(sitdev, sitdpll->id);
+
+	if (chan->prio_mask & BIT(sit9531x_input_hw_src(pin_id)))
+		*state = DPLL_PIN_STATE_SELECTABLE;
+	else
+		*state = DPLL_PIN_STATE_DISCONNECTED;
+}
+
+/*
+ * Is this the reference the PLL is tracking now?  See the S && L && !N
+ * predicate in the pin-state contract.  This is also what gates the
+ * measurements taken against the active reference.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static bool
+sit9531x_dpll_selection_active(struct sit9531x_dev *sitdev,
+			       const struct sit9531x_dpll *sitdpll, u8 pin_id)
+{
+	const struct sit9531x_chan *chan;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	chan = sit9531x_chan_state_get(sitdev, sitdpll->id);
+
+	if (chan->routed_ref != pin_id || !chan->locked || chan->mode ||
+	    chan->ho_freeze)
+		return false;
+
+	/*
+	 * Fed to the PLL is not locked to: the device names the source it
+	 * routes, and a lane that lost its signal is one the PLL is about
+	 * to be moved off, whatever the lock bit still says.
+	 */
+	if (pin_id < sitdev->info->num_inputs &&
+	    sit9531x_ref_state_get(sitdev, pin_id)->los)
+		return false;
+
+	return true;
+}
+
+/*
+ * Report a selection-role pin's operational state on this DPLL.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static void
+sit9531x_dpll_selection_operstate_get(struct sit9531x_dev *sitdev,
+				      const struct sit9531x_dpll *sitdpll,
+				      u8 pin_id,
+				      enum dpll_pin_operstate *operstate)
+{
+	const struct sit9531x_ref *ref;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (sit9531x_dpll_selection_active(sitdev, sitdpll, pin_id)) {
+		*operstate = DPLL_PIN_OPERSTATE_ACTIVE;
+		return;
+	}
+
+	if (pin_id < sitdev->info->num_inputs) {
+		ref = sit9531x_ref_state_get(sitdev, pin_id);
+		if (ref->los) {
+			*operstate = DPLL_PIN_OPERSTATE_NO_SIGNAL;
+			return;
+		}
+		if (ref->qual_fail) {
+			*operstate = DPLL_PIN_OPERSTATE_QUAL_FAILED;
+			return;
+		}
+	}
+
+	*operstate = DPLL_PIN_OPERSTATE_STANDBY;
+}
+
+static int
+sit9531x_dpll_input_pin_operstate_on_dpll_get(const struct dpll_pin *pin,
+					      void *pin_priv,
+					      const struct dpll_device *dpll,
+					      void *dpll_priv,
+					      enum dpll_pin_operstate *state,
+					      struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+
+	mutex_lock(&sitdev->multiop_lock);
+	sit9531x_dpll_selection_operstate_get(sitdev, sitdpll, dpin->id,
+					      state);
+	mutex_unlock(&sitdev->multiop_lock);
+
+	return 0;
+}
+
 static int
 sit9531x_dpll_input_pin_direction_get(const struct dpll_pin *pin,
 				      void *pin_priv,
@@ -253,8 +396,163 @@ sit9531x_dpll_input_pin_direction_get(const struct dpll_pin *pin,
 	return 0;
 }
 
+/*
+ * sit9531x_dpll_input_pin_state_on_dpll_get - get input pin DPLL state
+ *
+ * Selection role; see the pin-state contract above.
+ */
+static int
+sit9531x_dpll_input_pin_state_on_dpll_get(const struct dpll_pin *pin,
+					  void *pin_priv,
+					  const struct dpll_device *dpll,
+					  void *dpll_priv,
+					  enum dpll_pin_state *state,
+					  struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+
+	mutex_lock(&sitdev->multiop_lock);
+	sit9531x_dpll_selection_state_get(sitdev, sitdpll, dpin->id, state);
+	mutex_unlock(&sitdev->multiop_lock);
+
+	return 0;
+}
+
+/*
+ * sit9531x_dpll_input_pin_state_on_dpll_set - set input pin DPLL state
+ *
+ * Enables or disables the physical input receiver via Page 0x02
+ * force/state registers (sit9531x_input_disable/enable()) and updates
+ * this DPLL's Page 1 priority table so the state is honoured by the
+ * PLL's automatic reference selection, not just at the input buffer.
+ * Selection role; see the pin-state contract above for the states.
+ *
+ * The priority table is per PLL, so it is always updated for this DPLL.
+ * A single physical input feeds every DPLL, so the hardware receiver is
+ * only cut off once the last DPLL has released it: ref->pll_mask tracks
+ * which DPLLs currently claim the input, and the physical disable
+ * happens on the transition to an empty mask.
+ */
+static int
+sit9531x_dpll_input_pin_state_on_dpll_set(const struct dpll_pin *pin,
+					  void *pin_priv,
+					  const struct dpll_device *dpll,
+					  void *dpll_priv,
+					  enum dpll_pin_state state,
+					  struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	struct sit9531x_ref *ref = &sitdev->ref[dpin->id];
+	u8 hw_src = sit9531x_input_hw_src(dpin->id);
+	u8 pll_bit = BIT(sitdpll->id);
+	bool enabled_here = false;
+	int rc;
+
+	mutex_lock(&sitdev->multiop_lock);
+
+	switch (state) {
+	case DPLL_PIN_STATE_DISCONNECTED:
+		rc = sit9531x_input_prio_remove(sitdev, sitdpll->id, hw_src);
+		/*
+		 * The table write, the latch and the holdover release are
+		 * three steps behind one return code, so ask the table what
+		 * actually happened rather than reading the errno as "no
+		 * change".  A source that is gone from the table has been
+		 * released whatever else failed.
+		 */
+		if (rc && sit9531x_input_prio_present(sitdev, sitdpll->id,
+						      hw_src))
+			break;
+		ref->pll_mask &= ~pll_bit;
+		/*
+		 * The receiver is shared, so the last DPLL to let go turns it
+		 * off.  That has to happen even when the table rewrite
+		 * reported an error, or the input stays powered with nothing
+		 * tracking it; the first error is the one returned.
+		 */
+		if (!ref->pll_mask) {
+			int off_rc = sit9531x_input_disable(sitdev, dpin->id);
+
+			if (off_rc && !rc)
+				rc = off_rc;
+		}
+		break;
+	case DPLL_PIN_STATE_CONNECTED:
+		/*
+		 * CONNECTED asks for this input and no other, which the
+		 * device cannot be told to do: it selects by priority and the
+		 * manual-active-select path is not wired up (see "Mode").
+		 * Refuse instead of quietly behaving like SELECTABLE.
+		 */
+		NL_SET_ERR_MSG(extack,
+			       "Device selects its reference by priority; use selectable");
+		rc = -EOPNOTSUPP;
+		break;
+	case DPLL_PIN_STATE_SELECTABLE:
+		/*
+		 * Gate the receiver on whenever it is off, not only when this
+		 * DPLL holds no claim yet.  The two are tracked separately --
+		 * the claim comes from the priority table, the receiver from
+		 * the force bits -- so a PLL that already lists the input can
+		 * still find it powered down, and skipping the enable would
+		 * report success for a reference that cannot reach the loop.
+		 */
+		if (!ref->enabled) {
+			rc = sit9531x_input_enable(sitdev, dpin->id);
+			if (rc)
+				break;
+			enabled_here = true;
+		}
+		rc = sit9531x_input_prio_add(sitdev, sitdpll->id, hw_src);
+		if (rc && !sit9531x_input_prio_present(sitdev, sitdpll->id,
+						       hw_src)) {
+			/*
+			 * Undo only what this request did.  A receiver the
+			 * loaded configuration had already turned on is not
+			 * this request's to turn off.
+			 */
+			if (enabled_here)
+				sit9531x_input_disable(sitdev, dpin->id);
+			break;
+		}
+		/*
+		 * Claim the input for this DPLL only once it is both enabled
+		 * and present in the priority table.  Setting the mask before
+		 * prio_add would leak the claim if prio_add failed, keeping the
+		 * shared input receiver powered even after every DPLL released
+		 * it.
+		 */
+		ref->pll_mask |= pll_bit;
+		break;
+	default:
+		rc = -EINVAL;
+		break;
+	}
+
+	mutex_unlock(&sitdev->multiop_lock);
+
+	/*
+	 * Leave the messages the switch already set in place; only a failure
+	 * that came from the hardware path still needs one.
+	 */
+	if (rc == -ENOSPC)
+		NL_SET_ERR_MSG(extack,
+			       "Priority table is full of unique sources on this PLL");
+	else if (rc && rc != -EOPNOTSUPP && rc != -EINVAL)
+		NL_SET_ERR_MSG(extack, "Failed to set input pin state");
+
+	return rc;
+}
+
 static const struct dpll_pin_ops sit9531x_dpll_input_pin_ops = {
 	.direction_get		= sit9531x_dpll_input_pin_direction_get,
+	.state_on_dpll_get	= sit9531x_dpll_input_pin_state_on_dpll_get,
+	.state_on_dpll_set	= sit9531x_dpll_input_pin_state_on_dpll_set,
+	.operstate_on_dpll_get	= sit9531x_dpll_input_pin_operstate_on_dpll_get,
 };
 
 /*
diff --git a/drivers/dpll/sit9531x/regs.h b/drivers/dpll/sit9531x/regs.h
index 9349ec722569..fd1068982cd7 100644
--- a/drivers/dpll/sit9531x/regs.h
+++ b/drivers/dpll/sit9531x/regs.h
@@ -126,6 +126,10 @@
 #define SIT9531X_REG_GLOBAL_UPDATE		SIT9531X_REG(0x00, 0x0F)
 #define SIT9531X_SMALL_UPDATE_CMD		0x02
 
+/* PLL holdover control (PLL page offset) */
+#define SIT9531X_PLL_REG_HO_CTRL		0x6F
+#define SIT9531X_PLL_HO_FORCE_BIT		4
+
 /* One bit per input PAIR (bit 0 = CLKIN0, ..., bit 3 = CLKIN3) */
 #define SIT9531X_REG_IN_DE_FORCE		SIT9531X_REG(0x02, 0xE8)
 #define SIT9531X_REG_IN_DE_STATE		SIT9531X_REG(0x02, 0xE9)
@@ -230,6 +234,31 @@
 
 #define SIT9531X_PLL_STATUS_OUTER_DIS	BIT(5)
 
+/*
+ * Debug register -- PLL page.  Writing the key unlocks the page's debug
+ * registers for writing; writing zero locks them again.
+ */
+#define SIT9531X_PLL_REG_DEBUG		0xBD
+#define SIT9531X_PLL_DEBUG_UNLOCK		0xC3
+#define SIT9531X_PLL_DEBUG_LOCK			0x00
+
+/*
+ * Debug status bus -- PLL page.  The address register selects the block
+ * whose status the data register returns.  A read of the data register
+ * returns what the previous read latched, so the documented procedures
+ * read it three times and take the last.
+ */
+#define SIT9531X_PLL_REG_DBG_STATUS_ADDR	0xD1
+#define SIT9531X_PLL_REG_DBG_STATUS_DATA	0xD0
+#define SIT9531X_DBG_STATUS_READS		3
+
+/*
+ * Status of the reference routed to the PLL: the low nibble is the
+ * source the input subsystem feeds it, in the priority-table encoding.
+ */
+#define SIT9531X_DBG_STATUS_ROUTED_SRC	0xB0
+#define SIT9531X_DBG_ROUTED_SRC_MASK		GENMASK(3, 0)
+
 /*
  * PLL_CONFIG1F_PLL: bit 6 puts the PLL in manual active select, where it
  * no longer arbitrates by priority.  The other bits are GUI-generated
@@ -266,6 +295,18 @@
 #define SIT9531X_PLL_REG_STATUS_1		0x06
 #define SIT9531X_PLL_STATUS_1_HO_VALID	BIT(2)
 
+/*
+ * Page 0x06 clock monitor status, one nibble per input lane: P lanes in
+ * 0x02 (IN0P low, IN1P high) and 0x06 (IN2P, IN3P), N lanes in 0x92
+ * (IN0N, IN1N) and 0x96 (IN2N, IN3N).
+ */
+#define SIT9531X_CLKMON_P_STATUS_01		SIT9531X_REG(0x06, 0x02)
+#define SIT9531X_CLKMON_P_STATUS_23		SIT9531X_REG(0x06, 0x06)
+#define SIT9531X_CLKMON_N_STATUS_01		SIT9531X_REG(0x06, 0x92)
+#define SIT9531X_CLKMON_N_STATUS_23		SIT9531X_REG(0x06, 0x96)
+#define SIT9531X_CLKMON_FINE_DRIFT		BIT(0)
+#define SIT9531X_CLKMON_COARSE_DRIFT		BIT(1)
+#define SIT9531X_CLKMON_LOSS			BIT(2)
 #define SIT9531X_CLKMON_P_NOTIF_01		SIT9531X_REG(0x06, 0x03)
 #define SIT9531X_CLKMON_P_NOTIF_23		SIT9531X_REG(0x06, 0x07)
 
-- 
2.39.2 (Apple Git-143)

[PATCH net-next v12 07/12] dpll: sit9531x: add support to get and set priority on input pins

[Ali Rouhi]

From: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>

When the device has to choose a reference, it takes the first slot of
its priority table that has signal.  The driver keeps a
priority per input and PLL and builds the table from it (previous
patch), so getting a priority reads that value without touching a
register, and setting one records it and, for an input the PLL lists,
rewrites the table in the new order.  When the new order puts a
different input with signal first, the PLL moves to it; a change further
down the table leaves the PLL where it is.

Priority and state are separate attributes, and neither moves the other.
A priority can be set on a disconnected input and takes effect when it is
connected; disconnecting an input and connecting it again brings back the
priority it had.  Setting one input's priority leaves every other input's
as it was, so the named pin is the only one whose priority changes and
the core's own notification covers that; when the new order moves the
active selection, the siblings' operational state follows on the next
poll.  A priority the table write refused is not kept: the configured
value goes back to what it was, so nothing reports a priority the
device never took.  The range is 0 to 255 against a table of eleven slots:
inputs of equal priority keep the order the table already has them in,
so distinct values are what fix an order.  An input the PLL has never
listed reports the lowest slot, the priority it would be connected at.

A table rewritten behind the driver -- a profile reload, a direct I2C
tool -- is taken as the new configuration and the priorities are
re-seeded from it, so the poll now watches priority and operational state
as well as state, and notifies a pin when any of them moves.  The
notifications go out after the walk over the pins, outside multiop_lock,
since the helper takes locks the callbacks run under.

A pin's baseline for that watch -- state, operational state and priority
-- is taken when the pin is registered, under the device lock, rather
than by the first tick, so a change between the probe-time fetch and
that tick is reported instead of absorbed into the baseline.  The device
lock status is seeded the same way, so the first tick announces only
what moved since registration.

Signed-off-by: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
Assisted-by: LLM
Signed-off-by: Ali Rouhi <arouhi@sitime.com>
---
 drivers/dpll/sit9531x/core.c |  43 +++++++-
 drivers/dpll/sit9531x/core.h |   2 +
 drivers/dpll/sit9531x/dpll.c | 202 ++++++++++++++++++++++++++++++-----
 drivers/dpll/sit9531x/dpll.h |   4 +-
 drivers/dpll/sit9531x/prop.c |   4 +-
 5 files changed, 227 insertions(+), 28 deletions(-)

diff --git a/drivers/dpll/sit9531x/core.c b/drivers/dpll/sit9531x/core.c
index 999a6583853d..79520640dfc8 100644
--- a/drivers/dpll/sit9531x/core.c
+++ b/drivers/dpll/sit9531x/core.c
@@ -671,6 +671,44 @@ bool sit9531x_input_prio_present(struct sit9531x_dev *sitdev, u8 pll_idx,
 	return !!(sitdev->chan[pll_idx].prio_mask & BIT(input_idx));
 }
 
+/*
+ * sit9531x_input_prio_get - read an input's priority for a PLL
+ * @input_idx:	input source in hardware encoding (see
+ *		sit9531x_input_hw_src())
+ * @prio:	output priority (lower is preferred)
+ *
+ * Reports the priority configured for the source on this PLL, which is
+ * kept whether or not the source is currently in the table: state and
+ * priority are separate attributes, so disconnecting an input and
+ * connecting it again must not change the priority it reports.  The
+ * value is seeded from the hardware table, and re-seeded whenever the
+ * read-back shows the table was rewritten by something other than this
+ * driver.  A source that was never listed reports the lowest slot.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+int sit9531x_input_prio_get(struct sit9531x_dev *sitdev, u8 pll_idx,
+			    u8 input_idx, u8 *prio)
+{
+	const struct sit9531x_chan *chan;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (pll_idx >= SIT9531X_NUM_PLLS)
+		return -EINVAL;
+	input_idx = sit9531x_prio_src_canon(sitdev, input_idx);
+	if (input_idx >= SIT9531X_PRIO_NUM_SRC)
+		return -EINVAL;
+
+	chan = &sitdev->chan[pll_idx];
+	if (chan->cfg_known & BIT(input_idx))
+		*prio = chan->cfg_prio[input_idx];
+	else
+		*prio = SIT9531X_PRIO_MAX_SLOTS - 1;
+
+	return 0;
+}
+
 /*
  * Take the configured priorities from a table the hardware holds: each
  * listed source gets the first slot it occupies.  A source the table does
@@ -2581,9 +2619,12 @@ static int sit9531x_dpll_pins_register(struct sit9531x_dpll *sitdpll)
 		/*
 		 * Pins registered before this one are already reachable from
 		 * netlink, and the walks over this list run under
-		 * multiop_lock, so the insertion does too.
+		 * multiop_lock, so the insertion does too.  The baseline the
+		 * poll compares the pin against is taken under the same
+		 * lock, from the cache the create notification just reported.
 		 */
 		mutex_lock(&sitdpll->dev->multiop_lock);
+		sit9531x_dpll_pin_baseline(pin);
 		list_add(&pin->list, &sitdpll->pins);
 		mutex_unlock(&sitdpll->dev->multiop_lock);
 	}
diff --git a/drivers/dpll/sit9531x/core.h b/drivers/dpll/sit9531x/core.h
index cf4dd5f82d05..fa1197bfc81c 100644
--- a/drivers/dpll/sit9531x/core.h
+++ b/drivers/dpll/sit9531x/core.h
@@ -255,6 +255,8 @@ bool sit9531x_input_prio_present(struct sit9531x_dev *sitdev,
 				 u8 pll_idx, u8 input_idx);
 int sit9531x_input_prio_set(struct sit9531x_dev *sitdev, u8 pll_idx,
 			    u8 input_idx, u8 prio);
+int sit9531x_input_prio_get(struct sit9531x_dev *sitdev, u8 pll_idx,
+			    u8 input_idx, u8 *prio);
 int sit9531x_input_prio_remove(struct sit9531x_dev *sitdev, u8 pll_idx,
 			       u8 input_idx);
 int sit9531x_input_prio_add(struct sit9531x_dev *sitdev, u8 pll_idx,
diff --git a/drivers/dpll/sit9531x/dpll.c b/drivers/dpll/sit9531x/dpll.c
index 4c7cae4ce93e..0400444d91a5 100644
--- a/drivers/dpll/sit9531x/dpll.c
+++ b/drivers/dpll/sit9531x/dpll.c
@@ -34,6 +34,21 @@ sit9531x_dpll_is_xo_pin(const struct sit9531x_dpll_pin *pin)
 	       pin->id == SIT9531X_MAX_INPUTS;
 }
 
+/*
+ * The pins the poll watches: the selection-role pins -- regular references
+ * and the INTSYNC destination -- whose state, operational state and
+ * priority can move without a request: the device selects on its own, the
+ * monitors follow the signal, and a table rewritten behind the driver
+ * re-seeds the priorities.  Outputs (incl. the INTSYNC source) change only
+ * through their own set callback and the XO is permanently connected.
+ */
+static bool
+sit9531x_dpll_is_selection_pin(const struct sit9531x_dpll_pin *pin)
+{
+	return sit9531x_dpll_is_input_pin(pin) &&
+	       !sit9531x_dpll_is_xo_pin(pin);
+}
+
 /*
  * Status of a PLL whose outer loop is frozen in holdover.
  *
@@ -548,11 +563,93 @@ sit9531x_dpll_input_pin_state_on_dpll_set(const struct dpll_pin *pin,
 	return rc;
 }
 
+/*
+ * sit9531x_dpll_input_pin_prio_get - read input pin priority
+ *
+ * Reports the priority sit9531x_input_prio_get() keeps for the source on
+ * this PLL, connected or not; no register is read.
+ */
+static int
+sit9531x_dpll_input_pin_prio_get(const struct dpll_pin *pin, void *pin_priv,
+				 const struct dpll_device *dpll,
+				 void *dpll_priv, u32 *prio,
+				 struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	u8 slot;
+	int rc;
+
+	mutex_lock(&sitdev->multiop_lock);
+	rc = sit9531x_input_prio_get(sitdev, sitdpll->id,
+				     sit9531x_input_hw_src(dpin->id), &slot);
+	mutex_unlock(&sitdev->multiop_lock);
+	if (rc)
+		return rc;
+
+	/*
+	 * dpin->prio is not touched here: it is the poll's baseline for
+	 * spotting a change to notify, and a get refreshing it would hide
+	 * the change from the poll.
+	 */
+	*prio = slot;
+	return 0;
+}
+
+/*
+ * sit9531x_dpll_input_pin_prio_set - set input pin priority
+ *
+ * Records the priority and, for a pin in this PLL's table, rewrites the
+ * Page 1 table in priority order (sit9531x_input_prio_set()).  The other
+ * pins keep their priorities, so only the named pin changes and the core
+ * notifies it.  A pin that is not in the table keeps the priority for when
+ * it is connected.
+ */
+static int
+sit9531x_dpll_input_pin_prio_set(const struct dpll_pin *pin, void *pin_priv,
+				 const struct dpll_device *dpll,
+				 void *dpll_priv, u32 prio,
+				 struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	int rc;
+
+	if (dpin->dir != DPLL_PIN_DIRECTION_INPUT) {
+		NL_SET_ERR_MSG(extack, "Priority applies only to input pins");
+		return -EINVAL;
+	}
+
+	if (prio > U8_MAX) {
+		NL_SET_ERR_MSG(extack, "Priority out of range (0-255)");
+		return -EINVAL;
+	}
+
+	mutex_lock(&sitdev->multiop_lock);
+	rc = sit9531x_input_prio_set(sitdev, sitdpll->id,
+				     sit9531x_input_hw_src(dpin->id),
+				     (u8)prio);
+	if (!rc)
+		dpin->prio = prio;
+	mutex_unlock(&sitdev->multiop_lock);
+
+	if (rc) {
+		NL_SET_ERR_MSG(extack, "Failed to set input priority");
+		return rc;
+	}
+
+	return 0;
+}
+
 static const struct dpll_pin_ops sit9531x_dpll_input_pin_ops = {
 	.direction_get		= sit9531x_dpll_input_pin_direction_get,
 	.state_on_dpll_get	= sit9531x_dpll_input_pin_state_on_dpll_get,
 	.state_on_dpll_set	= sit9531x_dpll_input_pin_state_on_dpll_set,
 	.operstate_on_dpll_get	= sit9531x_dpll_input_pin_operstate_on_dpll_get,
+	.prio_get		= sit9531x_dpll_input_pin_prio_get,
+	.prio_set		= sit9531x_dpll_input_pin_prio_set,
 };
 
 /*
@@ -636,6 +733,55 @@ sit9531x_dpll_pin_ops_get(const struct sit9531x_dpll_pin *pin)
 	return &sit9531x_dpll_input_pin_ops;
 }
 
+/*
+ * The state, operational state and priority of a selection-role pin as
+ * the cache has them now: the baseline at registration, and what the poll
+ * compares it against on every tick.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static void sit9531x_dpll_pin_snapshot(struct sit9531x_dpll *sitdpll,
+				       const struct sit9531x_dpll_pin *pin,
+				       enum dpll_pin_state *state,
+				       enum dpll_pin_operstate *operstate,
+				       u8 *prio)
+{
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	u8 id = pin->id;
+
+	if (id == SIT9531X_INTSYNC_PIN_ID && sitdev->intsync_src == sitdpll->id)
+		*state = DPLL_PIN_STATE_DISCONNECTED;
+	else
+		sit9531x_dpll_selection_state_get(sitdev, sitdpll, id, state);
+	sit9531x_dpll_selection_operstate_get(sitdev, sitdpll, id, operstate);
+	if (sit9531x_input_prio_get(sitdev, sitdpll->id,
+				    sit9531x_input_hw_src(id), prio))
+		*prio = pin->prio;
+}
+
+/*
+ * sit9531x_dpll_pin_baseline - seed what the poll compares a pin against
+ *
+ * Called right after the pin is registered, under multiop_lock, so the
+ * poll's first comparison is against what the create notification
+ * carried.  A baseline taken on the first tick instead would absorb
+ * whatever moved between registration and that tick -- a lane losing its
+ * signal, a table rewritten and re-seeded -- and leave userspace with the
+ * snapshot from registration until the next change.
+ */
+void sit9531x_dpll_pin_baseline(struct sit9531x_dpll_pin *pin)
+{
+	struct sit9531x_dpll *sitdpll = pin->dpll;
+
+	lockdep_assert_held(&sitdpll->dev->multiop_lock);
+
+	if (!sit9531x_dpll_is_selection_pin(pin))
+		return;
+
+	sit9531x_dpll_pin_snapshot(sitdpll, pin, &pin->pin_state,
+				   &pin->operstate, &pin->prio);
+}
+
 /*
  * sit9531x_dpll_changes_check - check for state changes and notify
  *
@@ -671,39 +817,45 @@ void sit9531x_dpll_changes_check(struct sit9531x_dpll *sitdpll)
 		dpll_device_change_ntf(sitdpll->dpll_dev);
 	}
 
+	mutex_lock(&sitdev->multiop_lock);
 	list_for_each_entry(pin, &sitdpll->pins, list) {
-		const struct dpll_pin_ops *ops;
+		enum dpll_pin_operstate operstate;
 		enum dpll_pin_state state;
 		bool changed;
+		u8 prio;
 
-		/*
-		 * Poll input pins whose state can change autonomously: regular
-		 * references and the INTSYNC destination pin.  Outputs (incl.
-		 * the INTSYNC source) change only through their own set
-		 * callback and the XO is permanently connected, so skip those.
-		 * Each pin's state_on_dpll_get resolves to the right getter.
-		 */
-		if (!sit9531x_dpll_is_input_pin(pin) ||
-		    sit9531x_dpll_is_xo_pin(pin))
+		if (!sit9531x_dpll_is_selection_pin(pin))
 			continue;
 
-		ops = sit9531x_dpll_pin_ops_get(pin);
-		rc = ops->state_on_dpll_get(pin->dpll_pin, pin,
-					    sitdpll->dpll_dev, sitdpll,
-					    &state, NULL);
-		if (rc)
-			continue;
+		sit9531x_dpll_pin_snapshot(sitdpll, pin, &state, &operstate,
+					   &prio);
+
+		changed = state != pin->pin_state ||
+			  operstate != pin->operstate || prio != pin->prio;
+		if (changed)
+			dev_dbg(sitdev->dev,
+				"%s: state %u->%u operstate %u->%u prio %u->%u\n",
+				pin->label, pin->pin_state, state,
+				pin->operstate, operstate, pin->prio, prio);
+
+		pin->pin_state = state;
+		pin->operstate = operstate;
+		pin->prio = prio;
 
 		/*
-		 * The first pass only takes the baseline: the pin was
-		 * registered with this state, so nothing has changed yet.
+		 * The notification helper takes DPLL-subsystem locks that the
+		 * callbacks run under, so it cannot be called with
+		 * multiop_lock held; mark the pin and send after the walk.
 		 */
-		changed = pin->seen && state != pin->pin_state;
-		pin->pin_state = state;
-		pin->seen = true;
-		if (changed) {
-			dev_dbg(sitdev->dev, "%s state changed\n", pin->label);
-			dpll_pin_change_ntf(pin->dpll_pin);
-		}
+		if (changed)
+			pin->ntf_pending = true;
+	}
+	mutex_unlock(&sitdev->multiop_lock);
+
+	list_for_each_entry(pin, &sitdpll->pins, list) {
+		if (!pin->ntf_pending)
+			continue;
+		pin->ntf_pending = false;
+		dpll_pin_change_ntf(pin->dpll_pin);
 	}
 }
diff --git a/drivers/dpll/sit9531x/dpll.h b/drivers/dpll/sit9531x/dpll.h
index 9eb26505f94e..c2706ced92cd 100644
--- a/drivers/dpll/sit9531x/dpll.h
+++ b/drivers/dpll/sit9531x/dpll.h
@@ -31,7 +31,8 @@ struct sit9531x_dpll_pin {
 	u8				id;		/* hardware index */
 	u8				prio;
 	enum dpll_pin_state		pin_state;
-	bool				seen;	/* baseline taken by the poll */
+	enum dpll_pin_operstate		operstate;
+	bool				ntf_pending;
 };
 
 /* Per-PLL DPLL device state. */
@@ -63,6 +64,7 @@ void sit9531x_dpll_unregister(struct sit9531x_dpll *sitdpll);
 
 /* ---- Periodic change detection ---- */
 void sit9531x_dpll_lock_status_baseline(struct sit9531x_dpll *sitdpll);
+void sit9531x_dpll_pin_baseline(struct sit9531x_dpll_pin *pin);
 void sit9531x_dpll_changes_check(struct sit9531x_dpll *sitdpll);
 
 #endif /* _SIT9531X_DPLL_H */
diff --git a/drivers/dpll/sit9531x/prop.c b/drivers/dpll/sit9531x/prop.c
index 3635ea497e41..934db566c002 100644
--- a/drivers/dpll/sit9531x/prop.c
+++ b/drivers/dpll/sit9531x/prop.c
@@ -187,10 +187,11 @@ sit9531x_pin_props_get(struct sit9531x_dev *sitdev,
 	    index == SIT9531X_INTSYNC_PIN_ID) {
 		/*
 		 * INTSYNC destination pin: a PLL locks to the INTSYNC net as a
-		 * reference, so it can be connected.
+		 * reference, so it can be connected and re-prioritised.
 		 */
 		props->dpll_props.type = DPLL_PIN_TYPE_INT_OSCILLATOR;
 		props->dpll_props.capabilities =
+			DPLL_PIN_CAPABILITIES_PRIORITY_CAN_CHANGE |
 			DPLL_PIN_CAPABILITIES_STATE_CAN_CHANGE;
 		curr_freq = 0;
 	} else if (dir == DPLL_PIN_DIRECTION_OUTPUT &&
@@ -214,6 +215,7 @@ sit9531x_pin_props_get(struct sit9531x_dev *sitdev,
 	} else if (dir == DPLL_PIN_DIRECTION_INPUT) {
 		props->dpll_props.type = DPLL_PIN_TYPE_EXT;
 		props->dpll_props.capabilities =
+			DPLL_PIN_CAPABILITIES_PRIORITY_CAN_CHANGE |
 			DPLL_PIN_CAPABILITIES_STATE_CAN_CHANGE;
 		curr_freq = sitdev->ref[index].freq;
 	} else {
-- 
2.39.2 (Apple Git-143)

[PATCH net-next v12 08/12] dpll: sit9531x: add support to get and set frequency on pins

[Ali Rouhi]

From: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>

Both directions in one patch, since they share everything that matters.

An input's frequency is what the board presents, so it is reported from
the firmware description rather than read back: the chip has no divider on
an input whose rate it merely qualifies.  An input the firmware gives no
rate for has no frequency attribute at all rather than a zero, because
the core abandons the whole pin dump on an error from one pin.

An output's frequency is the VCO divided by that output's divider, so it
is computed from the divider read back from the chip and set by writing
a new one.  The VCO in turn comes from the feedback divider, which is
why the crystal rate is needed at probe.  That rate is trusted only
inside the band the PLL's VCO runs in: below the low band the divider is
not programmed and the PLL reports no data, and a request against a rate
outside the band is refused rather than programmed, since a divider
computed from a rate the output is not at would be reported as success.
A divider write only takes effect inside the programming state, and that
state has to be left with the output loops re-locked whatever happened
in between, so the exit runs even when a write in the middle failed and
the first error is the one returned.

Programming a divider costs about a hundred milliseconds under the device
lock: a dozen or so register transactions, then the settling time the part
requires after the loop-lock command, which is a property of the hardware
rather than a conservative guess.  The DPLL core holds its own lock across
the whole callback, so a frequency set on this device delays netlink
traffic for every DPLL in the system for that long.  Splitting the wait
out would need the ops to complete asynchronously, which the interface
does not offer; issuing the commit without waiting would let the next
request program a part that has not settled.  A rate change is a
configuration action, not something a running system does per packet, so
the cost is paid where it is visible rather than hidden behind a
completion the caller cannot wait for.

The phase flush that follows a divider write realigns every output fed by
that PLL, not only the one that changed.  The flush is a per-PLL function
in the device and there is no per-output equivalent, so an output whose
rate is set while its siblings are running will step their phase too.

The flush's own error paths restore what they changed: a failed source
select puts the original source back, a sibling is marked parked before
it is cleared so a failure cannot leave it unparked, and a failed arm
disarms rather than unparks.

Signed-off-by: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
Assisted-by: LLM
Signed-off-by: Ali Rouhi <arouhi@sitime.com>
---
 drivers/dpll/sit9531x/core.c | 805 +++++++++++++++++++++++++++++++++++
 drivers/dpll/sit9531x/core.h |   7 +
 drivers/dpll/sit9531x/dpll.c | 120 ++++++
 drivers/dpll/sit9531x/prop.c |  29 +-
 drivers/dpll/sit9531x/regs.h |  21 +
 5 files changed, 978 insertions(+), 4 deletions(-)

diff --git a/drivers/dpll/sit9531x/core.c b/drivers/dpll/sit9531x/core.c
index 79520640dfc8..ea15830b0efa 100644
--- a/drivers/dpll/sit9531x/core.c
+++ b/drivers/dpll/sit9531x/core.c
@@ -488,6 +488,140 @@ static int sit9531x_output_forced_hiz(struct sit9531x_dev *sitdev,
 					muted);
 }
 
+/* Attempts to re-lock the output loops before reporting them open. */
+#define SIT9531X_LOOP_LOCK_TRIES	3
+
+/*
+ * sit9531x_prg_abort - leave the programming state without committing
+ *
+ * Entering the state is two writes, and the second can fail with the debug
+ * block already unlocked and the part possibly already in PRG_CMD.  There
+ * is nothing to commit in that case, but the loops still have to be closed
+ * and the debug key put back, which is otherwise only done by
+ * sit9531x_prg_commit().
+ */
+static void sit9531x_prg_abort(struct sit9531x_dev *sitdev)
+{
+	u8 attempt;
+	int rc = -EIO;
+
+	for (attempt = 0; attempt < SIT9531X_LOOP_LOCK_TRIES; attempt++) {
+		rc = sit9531x_write_u8(sitdev, SIT9531X_REG_PRG_DIR_GEN,
+				       SIT9531X_LOOP_LOCK);
+		if (!rc)
+			break;
+		usleep_range(1000, 2000);
+	}
+	if (rc)
+		dev_err(sitdev->dev,
+			"output loops left unlocked after a failed entry: %d\n",
+			rc);
+
+	sit9531x_write_u8(sitdev, SIT9531X_REG_OUTSYS_DEBUG,
+			  SIT9531X_DEBUG_LOCK_VAL);
+}
+
+/*
+ * Enter the output-system programming state: unlock the debug
+ * registers on Page 3 and issue the PRG_CMD state command.  Register
+ * writes that reconfigure the output system only take effect when
+ * they are made inside this state.
+ */
+static int sit9531x_prg_enter(struct sit9531x_dev *sitdev)
+{
+	int rc;
+
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_OUTSYS_DEBUG,
+			       SIT9531X_DEBUG_UNLOCK_VAL);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_PRG_DIR_GEN,
+			       SIT9531X_PRG_CMD_STATE);
+	if (rc) {
+		/*
+		 * The debug block is unlocked at this point, and a transfer
+		 * that reported an error may still have reached the part --
+		 * which would leave the device in PRG_CMD with its output
+		 * loops open.  Callers skip the commit when the entry
+		 * fails, so close both here.
+		 */
+		sit9531x_prg_abort(sitdev);
+		return rc;
+	}
+
+	return 0;
+}
+
+/*
+ * Commit a programming sequence started by sit9531x_prg_enter():
+ * update the NVM shadow and re-lock the loops.  The sleep gives the
+ * hardware its required settling time after the loop-lock command;
+ * it is intentional despite the caller holding multiop_lock, as the
+ * whole NVM + lock sequence must be atomic.
+ */
+static int sit9531x_prg_commit(struct sit9531x_dev *sitdev)
+{
+	int rc, rc2 = 0, rc3;
+	u8 attempt;
+
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_PRG_DIR_GEN,
+			       SIT9531X_UPDATE_NVM);
+
+	/*
+	 * Issue the loop lock even if the update failed: every caller
+	 * commits whatever happened after the entry so that the chip never
+	 * stays in the PRG_CMD state with its loops open, and returning
+	 * early here would defeat that.
+	 *
+	 * Re-lock the loops.  Leaving them open is worse than any other
+	 * failure this function can report, and nothing else closes them,
+	 * so retry, as the priority commit retries the release of its
+	 * forced holdover.
+	 */
+	for (attempt = 0; attempt < SIT9531X_LOOP_LOCK_TRIES; attempt++) {
+		rc2 = sit9531x_write_u8(sitdev, SIT9531X_REG_PRG_DIR_GEN,
+					SIT9531X_LOOP_LOCK);
+		if (!rc2)
+			break;
+		usleep_range(1000, 2000);
+	}
+	if (rc2)
+		dev_err(sitdev->dev,
+			"output loops left unlocked after programming: %d\n",
+			rc2);
+
+	msleep(100);
+
+	/*
+	 * Put the output-system debug block back the way the device powers
+	 * up.  Its key register unlocks every debug register while it holds
+	 * the unlock value, and each programming sequence writes that value
+	 * itself, so nothing needs it left unlocked in between.
+	 */
+	rc3 = sit9531x_write_u8(sitdev, SIT9531X_REG_OUTSYS_DEBUG,
+				SIT9531X_DEBUG_LOCK_VAL);
+
+	if (rc)
+		return rc;
+	if (rc2)
+		return rc2;
+
+	/*
+	 * The programming is committed and the loops are locked by now;
+	 * only the debug key stayed open, and the next sequence writes it
+	 * again.  Failing here would make the caller skip what follows a
+	 * change that did take effect -- and the core drops an identical
+	 * retry, so it would never run.
+	 */
+	if (rc3)
+		dev_warn(sitdev->dev,
+			 "output debug block left unlocked after programming: %d\n",
+			 rc3);
+
+	return 0;
+}
+
 /*
  * Input priority selection
  *
@@ -1329,6 +1463,11 @@ int sit9531x_input_prio_add(struct sit9531x_dev *sitdev, u8 pll_idx,
 					 chan->prio_mask | BIT(input_idx));
 }
 
+/* Per-slot DIVO base register offsets (6 slots per page) */
+static const u8 clkout_odr_divn_base[] = {
+	0x14, 0x24, 0x34, 0x44, 0x54, 0x64
+};
+
 /* XO doubler register */
 #define SIT9531X_REG_XO2_GENERIC		SIT9531X_REG(0x00, 0x2D)
 #define SIT9531X_XO_DOUBLER_ENB_BIT		7   /* inverted: 0 = enabled */
@@ -1342,6 +1481,672 @@ int sit9531x_input_prio_add(struct sit9531x_dev *sitdev, u8 pll_idx,
 /* The output divider is a 34-bit field */
 #define SIT9531X_DIVO_MAX			GENMASK_ULL(33, 0)
 
+/*
+ * sit9531x_is_xo_doubler_enabled - check if Fref doubler is active
+ *
+ * Register 0x2D bit 7 is active-low: 0 = doubler enabled, 1 = disabled.
+ *
+ * Return: 1 if enabled, 0 if disabled, <0 on error
+ */
+static int sit9531x_is_xo_doubler_enabled(struct sit9531x_dev *sitdev)
+{
+	u8 val;
+	int rc;
+
+	rc = sit9531x_read_u8(sitdev, SIT9531X_REG_XO2_GENERIC, &val);
+	if (rc)
+		return rc;
+
+	return (~val >> SIT9531X_XO_DOUBLER_ENB_BIT) & 1u;
+}
+
+/*
+ * DIVN as a fixed-point value: int_part plus fracn/fracd, carried with
+ * SIT9531X_DIVN_SCALE steps per unit.  The scale keeps a whole DIVN
+ * well inside s64 while resolving far below the parts-per-trillion the
+ * frequency offset is reported in.
+ */
+static s64 sit9531x_divn_fixed(u32 int_part, s64 fracn, u64 fracd)
+{
+	s64 whole = (s64)int_part * SIT9531X_DIVN_SCALE;
+	u64 frac;
+
+	if (!fracd)
+		return whole;
+
+	frac = mul_u64_u64_div_u64(abs(fracn), SIT9531X_DIVN_SCALE, fracd);
+
+	return fracn < 0 ? whole - (s64)frac : whole + (s64)frac;
+}
+
+/*
+ * sit9531x_divn_static - read the configured DIVN of a PLL
+ * @sitdev:	device pointer
+ * @pll_idx:	PLL index (0-3)
+ * @divn:	result, fixed point as per sit9531x_divn_fixed()
+ *
+ * Reads PLL page regs 0x30 (integer part), 0x32-0x35 (numerator) and
+ * 0x38-0x3B (denominator).  The numerator is a two's complement 32-bit
+ * value, so DIVN can sit below the integer part, and the denominator
+ * register holds the divisor minus one.
+ *
+ * Return: 0 on success, <0 on error
+ */
+static int sit9531x_divn_static(struct sit9531x_dev *sitdev, u8 pll_idx,
+				s64 *divn)
+{
+	u32 int_part, fracn_raw = 0, fracd_raw = 0;
+	u64 fracd;
+	s64 fracn;
+	int rc, i;
+	u8 v;
+
+	rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+				  SIT9531X_PLL_REG_DIVN_INT, &v);
+	if (rc)
+		return rc;
+	int_part = v;
+
+	for (i = 3; i >= 0; i--) {
+		rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+					  SIT9531X_PLL_REG_DIVN_NUM + i, &v);
+		if (rc)
+			return rc;
+		fracn_raw = (fracn_raw << 8) | v;
+	}
+
+	for (i = 3; i >= 0; i--) {
+		rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+					  SIT9531X_PLL_REG_DIVN_DEN + i, &v);
+		if (rc)
+			return rc;
+		fracd_raw = (fracd_raw << 8) | v;
+	}
+
+	/*
+	 * NUM/DEN is the fractional part of DIVN, so |NUM| is below DEN by
+	 * construction.  A pair that says otherwise did not come from a
+	 * programmed divider, and handing it on would divide by a
+	 * denominator small enough for the quotient to leave u64 -- which
+	 * is a divide-error exception on x86, not a value a caller could
+	 * reject.
+	 */
+	fracn = (s32)fracn_raw;
+	fracd = (u64)fracd_raw + 1;
+	if ((u64)abs(fracn) >= fracd)
+		return -ENODATA;
+
+	*divn = sit9531x_divn_fixed(int_part, fracn, fracd);
+
+	return 0;
+}
+
+/* PLLB and PLLD run their VCO in the high band, PLLA and PLLC in the low. */
+static bool sit9531x_fvco_in_band(u8 pll_idx, u64 fvco)
+{
+	if (pll_idx == 1 || pll_idx == 3)
+		return fvco >= SIT9531X_FVCO_HIGHBAND_MIN &&
+		       fvco <= SIT9531X_FVCO_HIGHBAND_MAX;
+	return fvco >= SIT9531X_FVCO_LOWBAND_MIN &&
+	       fvco <= SIT9531X_FVCO_LOWBAND_MAX;
+}
+
+/*
+ * sit9531x_get_fvco - read VCO frequency from chip's DIVN registers
+ *
+ * Fvco = Fref * DIVN, where DIVN comes from sit9531x_divn_static() and
+ * Fref = xtal_freq << doubler.  DIVN is the steady-state Fvco/Fref
+ * target programmed by the NVM blob and is authoritative in both
+ * free-run and sync modes.
+ *
+ * Return: 0 with *fvco set on success, -ENODATA when DIVN is not
+ * programmed (dormant PLL), or the register access error.  A bus
+ * failure is never folded into the -ENODATA case, so callers can fail
+ * a request instead of acting on a guessed rate.
+ */
+static int sit9531x_get_fvco(struct sit9531x_dev *sitdev, u8 pll_idx,
+			     u64 *fvco)
+{
+	int doubler, rc;
+	u64 fref;
+	s64 divn;
+
+	rc = sit9531x_divn_static(sitdev, pll_idx, &divn);
+	if (rc)
+		return rc;
+	if (divn <= 0)
+		return -ENODATA;
+
+	doubler = sit9531x_is_xo_doubler_enabled(sitdev);
+	if (doubler < 0)
+		return doubler;
+
+	fref = (u64)sitdev->xtal_freq << doubler;
+
+	/*
+	 * Round to the nearest hertz: DIVN is carried in fixed point, so a
+	 * fraction such as 1/6 is already floored once, and flooring the
+	 * product again reads an exact 5 GHz VCO as 4999999999 Hz -- which
+	 * then refuses every rate the VCO divides exactly.
+	 */
+	*fvco = mul_u64_u64_div_u64(2 * fref, (u64)divn, SIT9531X_DIVN_SCALE);
+	*fvco = (*fvco + 1) / 2;
+
+	/*
+	 * No VCO of this family runs below the low band, so a product under
+	 * it is not a rate: a DIVN of a cycle or less, say, which the check
+	 * above lets through and which a profile that never programmed the
+	 * divider can leave behind.  Callers scale 34-bit register fields by
+	 * 1e12 / Fvco or more, and for a rate far enough below the band that
+	 * quotient leaves u64 -- a divide-error exception on x86, not a
+	 * value they could reject.  Report the unprogrammed divider instead.
+	 */
+	if (*fvco < SIT9531X_FVCO_LOWBAND_MIN)
+		return -ENODATA;
+
+	/*
+	 * A rate outside the band the PLL's VCO runs in usually means
+	 * Fref * DIVN is not what this PLL runs at -- a PLL fed from another
+	 * PLL rather than from the XO, for one.  The rate derived from the
+	 * registers is still the only estimate there is, so a read reports
+	 * what it derives; a set refuses to program a divider against it
+	 * (sit9531x_output_divo_calc()), since substituting the band edge
+	 * would program against a rate nothing supports and report the
+	 * result as exact.  Say so once per PLL.
+	 */
+	if (!sit9531x_fvco_in_band(pll_idx, *fvco) &&
+	    !(sitdev->fvco_band_warned & BIT(pll_idx))) {
+		sitdev->fvco_band_warned |= BIT(pll_idx);
+		dev_warn(sitdev->dev,
+			 "PLL%c: Fref * DIVN = %llu Hz is outside its VCO band\n",
+			 'A' + pll_idx, *fvco);
+	}
+
+	return 0;
+}
+
+/* Latch a change to a PLL page with a small update. */
+static int sit9531x_pll_small_update(struct sit9531x_dev *sitdev, u8 pll_idx)
+{
+	return sit9531x_write_pll_u8(sitdev, pll_idx,
+				     SIT9531X_PLL_REG_SMALL_UPDATE,
+				     SIT9531X_SMALL_UPDATE_CMD);
+}
+
+/*
+ * sit9531x_output_phase_flush - flush the output phase of a PLL
+ *
+ * Fires the chip's on-demand phase-flush (PHFL) so every output divider
+ * of @pll_idx restarts aligned to the PLL phase.  Without it a rewritten
+ * DIVO keeps counting from an arbitrary point and the output edge lands
+ * with a persistent offset against the tracked reference (only a power
+ * cycle realigned it).
+ *
+ * The sequence mirrors the documented procedure: arm the on-demand PHFL and
+ * latch it with the PLL-page small-change update, then select the
+ * in-register phase trigger on Page 0 and pulse it.  The Page 0 trigger
+ * register is touched read-modify-write so the unrelated OEb bits are
+ * preserved.
+ *
+ * A PLL the loaded configuration builds without the phase-flush feature
+ * (PLL page 0x47 bit 7 clear) has nothing to fire; it is restarted
+ * instead, which restarts its output dividers from the PLL phase.  That
+ * is what SiTime's Dely_program_output.py does for such a PLL.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static int sit9531x_output_phase_flush(struct sit9531x_dev *sitdev, u8 pll_idx)
+{
+	u8 ctrl, orig, phfl, armed_mask = 0, parked = 0, i;
+	int rc, ret;
+
+	rc = sit9531x_read_pll_u8(sitdev, pll_idx, SIT9531X_PLL_REG_CONFIG47,
+				  &phfl);
+	if (rc)
+		return rc;
+	if (!(phfl & SIT9531X_PLL_CONFIG47_PHFL_EN))
+		return sit9531x_write_pll_u8(sitdev, pll_idx,
+					     SIT9531X_PLL_REG_DIRECTIVES,
+					     SIT9531X_PLL_DIRECTIVE_RESTART);
+
+	/*
+	 * The trigger below is chip-global: every PLL whose on-demand flush
+	 * is armed answers it.  Note which ones the loaded profile arms --
+	 * this one so its setting can be put back, the others so they can
+	 * be parked for the pulse and do not realign outputs nobody asked
+	 * to move.
+	 */
+	for (i = 0; i < SIT9531X_NUM_PLLS; i++) {
+		rc = sit9531x_read_pll_u8(sitdev, i, SIT9531X_PLL_REG_PHFL_CTRL,
+					  &phfl);
+		if (rc)
+			return rc;
+		if (phfl & SIT9531X_PLL_PHFL_ON_DEMAND_EN)
+			armed_mask |= BIT(i);
+	}
+
+	for (i = 0; i < SIT9531X_NUM_PLLS; i++) {
+		if (i == pll_idx || !(armed_mask & BIT(i)))
+			continue;
+		/*
+		 * A clear whose write reported an error may still have
+		 * landed, latched or not: put it back either way.
+		 */
+		parked |= BIT(i);
+		rc = sit9531x_update_pll_u8(sitdev, i,
+					    SIT9531X_PLL_REG_PHFL_CTRL,
+					    SIT9531X_PLL_PHFL_ON_DEMAND_EN, 0);
+		if (rc)
+			goto unpark;
+		rc = sit9531x_pll_small_update(sitdev, i);
+		if (rc)
+			goto unpark;
+	}
+
+	/*
+	 * Arm the on-demand phase-flush on the PLL page.  An arm whose write
+	 * failed may have landed too, so it goes through the disarm below.
+	 */
+	rc = sit9531x_update_pll_u8(sitdev, pll_idx,
+				    SIT9531X_PLL_REG_PHFL_CTRL,
+				    SIT9531X_PLL_PHFL_ON_DEMAND_EN,
+				    SIT9531X_PLL_PHFL_ON_DEMAND_EN);
+	if (rc)
+		goto disarm;
+
+	/*
+	 * Latch it with the PLL small-change update.  Written whole, like
+	 * every other issue of this directive: the register is a command
+	 * register, and a read-modify-write skips the write entirely when
+	 * the bit still reads back set from the previous command.
+	 */
+	rc = sit9531x_pll_small_update(sitdev, pll_idx);
+	if (rc)
+		goto disarm;
+
+	/*
+	 * Select the in-register phase trigger, preserving the OEb bits.
+	 * Remember the original register value (with the trigger de-asserted)
+	 * so the trigger-source select can be restored once the pulse has
+	 * fired.
+	 */
+	rc = sit9531x_read_u8(sitdev, SIT9531X_REG_GPIO_FUNC_CTRL1, &ctrl);
+	if (rc)
+		goto disarm;
+
+	orig = ctrl & ~SIT9531X_DIVO_PHASE_TRIG;
+	ctrl = orig | SIT9531X_DIVO_PHASE_SEL_REG;
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_GPIO_FUNC_CTRL1, ctrl);
+	if (rc)
+		goto restore;
+
+	/*
+	 * Pulse the phase trigger.  No explicit delay is needed between the
+	 * set and clear writes: each I2C transaction takes far longer than
+	 * any minimum pulse width.
+	 */
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_GPIO_FUNC_CTRL1,
+			       ctrl | SIT9531X_DIVO_PHASE_TRIG);
+
+restore:
+	/*
+	 * Restore the original trigger-source select.  The pulse above has
+	 * already latched the flush, so a one-shot flush must not leave the
+	 * phase trigger permanently pinned to the in-register source.  This
+	 * runs even when the pulse write failed, and when the select write
+	 * itself reported a failure, since the transfer may have reached
+	 * the part all the same; otherwise a failed flush would keep a
+	 * hardware trigger source hijacked.  The restore error is only
+	 * surfaced when it would not mask the earlier failure.
+	 */
+	ret = sit9531x_write_u8(sitdev, SIT9531X_REG_GPIO_FUNC_CTRL1, orig);
+	if (ret && !rc)
+		rc = ret;
+
+disarm:
+	/*
+	 * Put the on-demand flush enable back as the profile had it.  One the
+	 * profile left clear must not stay armed: a later assertion of the
+	 * restored trigger source would re-flush every output divider of this
+	 * PLL.  One the profile armed -- a board realigning from a GPIO, say
+	 * -- must not be switched off by an unrelated rate change.
+	 */
+	if (!(armed_mask & BIT(pll_idx))) {
+		ret = sit9531x_update_pll_u8(sitdev, pll_idx,
+					     SIT9531X_PLL_REG_PHFL_CTRL,
+					     SIT9531X_PLL_PHFL_ON_DEMAND_EN, 0);
+		if (!ret)
+			ret = sit9531x_pll_small_update(sitdev, pll_idx);
+		if (ret && !rc)
+			rc = ret;
+	}
+
+unpark:
+	for (i = 0; i < SIT9531X_NUM_PLLS; i++) {
+		if (!(parked & BIT(i)))
+			continue;
+		ret = sit9531x_update_pll_u8(sitdev, i,
+					     SIT9531X_PLL_REG_PHFL_CTRL,
+					     SIT9531X_PLL_PHFL_ON_DEMAND_EN,
+					     SIT9531X_PLL_PHFL_ON_DEMAND_EN);
+		if (!ret)
+			ret = sit9531x_pll_small_update(sitdev, i);
+		if (ret && !rc)
+			rc = ret;
+	}
+
+	return rc;
+}
+
+/*
+ * sit9531x_output_divo_calc - work out an output's divider and its VCO
+ *
+ * Separated from the write so a caller that programs more than the
+ * divider in one sequence can compute the value before it enters the
+ * programming state.
+ */
+static int sit9531x_output_divo_calc(struct sit9531x_dev *sitdev, u8 out_idx,
+				     u8 pll_idx, u64 frequency, u64 *fvco_out,
+				     u64 *divo_out)
+{
+	const struct sit9531x_chip_info *info = sitdev->info;
+	u64 fvco, divo;
+	int rc;
+
+	if (out_idx >= info->num_outputs || pll_idx >= SIT9531X_NUM_PLLS)
+		return -EINVAL;
+
+	if (!frequency)
+		return -EINVAL;
+
+	/*
+	 * The core validates the request against the supported ranges with
+	 * the value narrowed to u32 but hands the full u64 down, so a value
+	 * like U32_MAX + 1 Hz validates as 1 Hz.  Reject anything that does
+	 * not fit the narrowed width the validation actually covered.
+	 */
+	if (frequency > U32_MAX)
+		return -EINVAL;
+
+	/*
+	 * sit9531x_get_fvco() returns the register-derived rate, so a
+	 * frequency get and a frequency set divide the same number.  A VCO
+	 * that cannot be read fails the request: programming a divider from a
+	 * guessed rate would put the output far from what was asked for
+	 * while reporting success.
+	 */
+	rc = sit9531x_get_fvco(sitdev, pll_idx, &fvco);
+	if (rc)
+		return rc == -ENODATA ? -ENODEV : rc;
+
+	/*
+	 * Fref * DIVN outside the VCO band is not what the PLL runs at, and
+	 * sit9531x_get_fvco() has said so.  A divider computed against it
+	 * would put the output at some other rate while the exactness check
+	 * below passes and the read-back, dividing the same number, confirms
+	 * the request.  Refuse the set instead.
+	 */
+	if (!sit9531x_fvco_in_band(pll_idx, fvco)) {
+		dev_dbg(sitdev->dev,
+			"out%u: PLL%c Fvco %llu Hz is outside its VCO band, rate not settable\n",
+			out_idx, 'A' + pll_idx, fvco);
+		return -EINVAL;
+	}
+
+	/*
+	 * Round to nearest rather than down: flooring picks the worse of the
+	 * two adjacent dividers whenever the remainder is above half the
+	 * request.
+	 */
+	divo = div64_u64(fvco + frequency / 2, frequency);
+	if (!divo)
+		return -EINVAL;
+
+	/* DIVO is a 34-bit field; refuse a wider divider rather than truncate it. */
+	if (divo > SIT9531X_DIVO_MAX)
+		return -EINVAL;
+
+	/*
+	 * The output divider is an integer divider of the VCO, so the only
+	 * rates the part can make are Fvco/N.  An output pin that lists no
+	 * supported frequencies advertises a continuous range, because the
+	 * divisors cannot be enumerated ahead of a known Fvco, so a request
+	 * for a rate between two of them arrives here.  Refuse it: running
+	 * the output at the nearest divider instead and reporting success
+	 * would leave the pin several percent off what was asked for with
+	 * nothing saying so.
+	 */
+	if (div64_u64(fvco, divo) != frequency) {
+		dev_dbg(sitdev->dev,
+			"out%u: %llu Hz is not Fvco/N (Fvco=%llu, nearest %llu Hz)\n",
+			out_idx, frequency, fvco, div64_u64(fvco, divo));
+		return -EINVAL;
+	}
+
+	dev_dbg(sitdev->dev,
+		"out%u: Fvco=%llu freq=%llu DIVO=%llu (effective %llu Hz)\n",
+		out_idx, fvco, frequency, divo, div64_u64(fvco, divo));
+
+	*fvco_out = fvco;
+	*divo_out = divo;
+
+	return 0;
+}
+
+/*
+ * sit9531x_output_divo_write - write the five DIVO bytes of an output
+ *
+ * The caller must already be in the programming state.  Bytes written
+ * before a failure are put back, so the output keeps the divider it had
+ * rather than a mixture of the two.
+ */
+static int sit9531x_output_divo_write(struct sit9531x_dev *sitdev, u8 out_idx,
+				      u64 divo)
+{
+	const struct sit9531x_chip_info *info = sitdev->info;
+	u8 slot, page, base_reg, divo_bytes[5], old_bytes[5], msb_old;
+	int rc, j, rb_rc;
+	u8 written = 0;
+
+	/* Map output index to physical slot */
+	slot = info->clkout_map[out_idx];
+
+	/* Determine page and per-page slot register */
+	if (slot > SIT9531X_PAGE_OUTSYS0_SLOT_MAX)
+		page = SIT9531X_PAGE_OUTSYS1;
+	else
+		page = SIT9531X_PAGE_OUTSYS0;
+	base_reg = clkout_odr_divn_base[slot % 6];
+
+	divo_bytes[0] = (divo >>  0) & 0xFF;
+	divo_bytes[1] = (divo >>  8) & 0xFF;
+	divo_bytes[2] = (divo >> 16) & 0xFF;
+	divo_bytes[3] = (divo >> 24) & 0xFF;
+	divo_bytes[4] = (divo >> 32) & 0x03;  /* only bits [1:0] */
+
+	for (j = 0; j < 5; j++) {
+		rc = sit9531x_read_u8(sitdev,
+				      SIT9531X_REG(page, base_reg - j),
+				      &old_bytes[j]);
+		if (rc)
+			return rc;
+	}
+
+	msb_old = old_bytes[4];
+	divo_bytes[4] |= msb_old & 0xFC;
+
+	for (j = 0; j < 5; j++) {
+		rc = sit9531x_write_u8(sitdev,
+				       SIT9531X_REG(page, base_reg - j),
+				       divo_bytes[j]);
+		if (rc)
+			goto rollback;
+		written++;
+	}
+
+	return 0;
+
+rollback:
+	/*
+	 * The byte whose write reported the error may still have reached
+	 * the part, so it is put back along with the ones that did.
+	 */
+	for (j = 0; j <= written && j < 5; j++) {
+		rb_rc = sit9531x_write_u8(sitdev,
+					  SIT9531X_REG(page, base_reg - j),
+					  old_bytes[j]);
+		if (rb_rc) {
+			dev_err(sitdev->dev,
+				"out%u: DIVO rollback failed (%d), the divider is part old and part new\n",
+				out_idx, rb_rc);
+			if (!rc)
+				rc = rb_rc;
+		}
+	}
+
+	return rc;
+}
+
+/*
+ * Read an output's divider back from the device.
+ *
+ * Return: 0 with *divo set, -ENODATA when the divider is not programmed,
+ * or the register access error
+ */
+static int sit9531x_output_divo_read(struct sit9531x_dev *sitdev, u8 out_idx,
+				     u64 *divo)
+{
+	u8 slot, page, base_reg, v;
+	int rc, j;
+
+	slot = sitdev->info->clkout_map[out_idx];
+	if (slot > SIT9531X_PAGE_OUTSYS0_SLOT_MAX)
+		page = SIT9531X_PAGE_OUTSYS1;
+	else
+		page = SIT9531X_PAGE_OUTSYS0;
+	base_reg = clkout_odr_divn_base[slot % 6];
+
+	*divo = 0;
+	for (j = 4; j >= 0; j--) {
+		rc = sit9531x_read_u8(sitdev,
+				      SIT9531X_REG(page, base_reg - j), &v);
+		if (rc)
+			return rc;
+		if (j == 4)
+			v &= 0x03;
+		*divo = (*divo << 8) | v;
+	}
+
+	return *divo ? 0 : -ENODATA;
+}
+
+int sit9531x_output_freq_set(struct sit9531x_dev *sitdev, u8 out_idx,
+			     u8 pll_idx, u64 frequency)
+{
+	u64 fvco, divo;
+	int rc, ret;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	rc = sit9531x_output_divo_calc(sitdev, out_idx, pll_idx, frequency,
+				       &fvco, &divo);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_prg_enter(sitdev);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_output_divo_write(sitdev, out_idx, divo);
+	/*
+	 * Step 4: NVM update + loop lock.  Always run prg_commit() so the chip
+	 * leaves the PRG_CMD state with the output loops re-locked, even when a
+	 * write above failed; keep the first error to return.  It also carries
+	 * the required post-lock settling sleep.
+	 */
+	ret = sit9531x_prg_commit(sitdev);
+	if (ret && !rc)
+		rc = ret;
+	if (rc)
+		return rc;
+
+	/*
+	 * Step 5: flush the PLL's output phase so the new DIVO starts
+	 * aligned instead of keeping the arbitrary phase the divider
+	 * happened to be at.
+	 */
+	/*
+	 * The divider is committed by this point, so the part is already
+	 * running at the new rate.  A flush that fails leaves the output
+	 * divider on its old phase, which is a realignment that did not
+	 * happen rather than a rate that did not change -- and reporting a
+	 * failure would be doubly wrong, because the core asks for the
+	 * current rate first and would drop an identical retry.
+	 */
+	rc = sit9531x_output_phase_flush(sitdev, pll_idx);
+	if (rc) {
+		dev_warn(sitdev->dev,
+			 "out%u: rate changed but the divider phase was not realigned (%d)\n",
+			 out_idx, rc);
+		rc = 0;
+	}
+
+	sitdev->out[out_idx].freq = div64_u64(fvco, divo);
+
+	return 0;
+}
+
+/*
+ * sit9531x_output_freq_get - read output clock frequency from hardware
+ * @out_idx:	output index (0-N for this chip variant)
+ * @frequency:	output frequency in Hz
+ *
+ * Reads the 34-bit DIVO divider back from the output system registers
+ * and computes the live output frequency as Fvco / DIVO.  This stays
+ * correct even when the divider was reprogrammed behind the driver's
+ * back (e.g. by a direct-I2C userspace tool), where the cached value
+ * would be stale.
+ *
+ * The cached output state is refreshed with the computed value.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ *
+ * Return: 0 on success, -ENODATA when the output divider or VCO rate
+ *	   is not resolvable, <0 on register access error.  -ENODATA and not
+ *	   -ENODEV, which the I2C layer returns for an adapter that is gone
+ *	   and which must not read as "no rate to report".
+ */
+int sit9531x_output_freq_get(struct sit9531x_dev *sitdev, u8 out_idx,
+			     u64 *frequency)
+{
+	const struct sit9531x_chip_info *info = sitdev->info;
+	u64 fvco, divo;
+	u8 pll_idx;
+	int rc;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (out_idx >= info->num_outputs)
+		return -EINVAL;
+
+	pll_idx = sitdev->out[out_idx].pll_idx;
+	if (pll_idx >= SIT9531X_NUM_PLLS || !sitdev->out[out_idx].routed)
+		return -ENODATA;
+
+	rc = sit9531x_get_fvco(sitdev, pll_idx, &fvco);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_output_divo_read(sitdev, out_idx, &divo);
+	if (rc)
+		return rc;
+
+	*frequency = div64_u64(fvco, divo);
+	sitdev->out[out_idx].freq = *frequency;
+
+	return 0;
+}
+
 /*
  * Phase adjust (PRG_RST_DELAY register-based).
  *
diff --git a/drivers/dpll/sit9531x/core.h b/drivers/dpll/sit9531x/core.h
index fa1197bfc81c..006a7fee76ab 100644
--- a/drivers/dpll/sit9531x/core.h
+++ b/drivers/dpll/sit9531x/core.h
@@ -192,6 +192,8 @@ struct sit9531x_chan {
  *			synchronization (INTSYNC), or -1 when disabled
  * @irq_ack_fails:	consecutive failures to acknowledge the
  *			notification latches from the interrupt handler
+ * @fvco_band_warned:	bit per PLL whose Fref * DIVN has been reported as
+ *			outside its VCO band; written under @multiop_lock
  */
 struct sit9531x_dev {
 	struct device			*dev;
@@ -203,6 +205,7 @@ struct sit9531x_dev {
 
 	/* Hardware state */
 	u8			irq_ack_fails;
+	u8			fvco_band_warned;
 	struct sit9531x_ref	ref[SIT9531X_MAX_INPUTS + 1]; /* +1 for xtal */
 	struct sit9531x_out	out[SIT9531X_MAX_OUTPUTS];
 	struct sit9531x_chan	chan[SIT9531X_NUM_PLLS];
@@ -265,6 +268,10 @@ int sit9531x_input_prio_add(struct sit9531x_dev *sitdev, u8 pll_idx,
 /* ---- Output enable/disable (Hi-Z control) ---- */
 
 /* ---- Output frequency ---- */
+int sit9531x_output_freq_set(struct sit9531x_dev *sitdev, u8 out_idx,
+			     u8 pll_idx, u64 frequency);
+int sit9531x_output_freq_get(struct sit9531x_dev *sitdev, u8 out_idx,
+			     u64 *frequency);
 
 /* ---- Output phase adjust (PRG_RST_DELAY register-based) ---- */
 
diff --git a/drivers/dpll/sit9531x/dpll.c b/drivers/dpll/sit9531x/dpll.c
index 0400444d91a5..aa021b374c45 100644
--- a/drivers/dpll/sit9531x/dpll.c
+++ b/drivers/dpll/sit9531x/dpll.c
@@ -411,6 +411,32 @@ sit9531x_dpll_input_pin_direction_get(const struct dpll_pin *pin,
 	return 0;
 }
 
+/*
+ * sit9531x_dpll_input_pin_frequency_get - read input pin frequency
+ *
+ * Returns the rate the board wired to the input, the first entry of its
+ * supported-frequencies-hz; an input has no frequency setter.  An input
+ * the firmware lists no rate for is registered without this callback
+ * (sit9531x_dpll_pin_ops_get()), so its attribute is absent rather than
+ * zero.
+ */
+static int
+sit9531x_dpll_input_pin_frequency_get(const struct dpll_pin *pin,
+				      void *pin_priv,
+				      const struct dpll_device *dpll,
+				      void *dpll_priv, u64 *frequency,
+				      struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	const struct sit9531x_ref *ref;
+
+	ref = sit9531x_ref_state_get(sitdpll->dev, dpin->id);
+	*frequency = ref->freq;
+
+	return 0;
+}
+
 /*
  * sit9531x_dpll_input_pin_state_on_dpll_get - get input pin DPLL state
  *
@@ -644,6 +670,23 @@ sit9531x_dpll_input_pin_prio_set(const struct dpll_pin *pin, void *pin_priv,
 }
 
 static const struct dpll_pin_ops sit9531x_dpll_input_pin_ops = {
+	.direction_get		= sit9531x_dpll_input_pin_direction_get,
+	.frequency_get		= sit9531x_dpll_input_pin_frequency_get,
+	.state_on_dpll_get	= sit9531x_dpll_input_pin_state_on_dpll_get,
+	.state_on_dpll_set	= sit9531x_dpll_input_pin_state_on_dpll_set,
+	.operstate_on_dpll_get	= sit9531x_dpll_input_pin_operstate_on_dpll_get,
+	.prio_get		= sit9531x_dpll_input_pin_prio_get,
+	.prio_set		= sit9531x_dpll_input_pin_prio_set,
+};
+
+/*
+ * The same without frequency_get, for an input whose firmware node lists
+ * no supported-frequencies-hz (or that has no node at all): there is no
+ * rate to report, and the core fails a whole pin dump on an error from
+ * any one callback, so the attribute is left out rather than reported
+ * as 0 Hz.
+ */
+static const struct dpll_pin_ops sit9531x_dpll_input_pin_norate_ops = {
 	.direction_get		= sit9531x_dpll_input_pin_direction_get,
 	.state_on_dpll_get	= sit9531x_dpll_input_pin_state_on_dpll_get,
 	.state_on_dpll_set	= sit9531x_dpll_input_pin_state_on_dpll_set,
@@ -704,6 +747,7 @@ sit9531x_dpll_xo_pin_state_on_dpll_get(const struct dpll_pin *pin,
 
 static const struct dpll_pin_ops sit9531x_dpll_xo_pin_ops = {
 	.direction_get		= sit9531x_dpll_input_pin_direction_get,
+	.frequency_get		= sit9531x_dpll_input_pin_frequency_get,
 	.state_on_dpll_get	= sit9531x_dpll_xo_pin_state_on_dpll_get,
 };
 
@@ -719,8 +763,78 @@ sit9531x_dpll_output_pin_direction_get(const struct dpll_pin *pin,
 	return 0;
 }
 
+/*
+ * sit9531x_dpll_output_pin_frequency_get - read output pin frequency
+ *
+ * Reads the DIVO divider back from the chip and computes the live
+ * frequency as Fvco / DIVO.  Falls back to the cached value only when
+ * the output is not resolvable through the divider chain (e.g. not
+ * mapped to a PLL), so transport/register errors still surface.
+ */
+static int
+sit9531x_dpll_output_pin_frequency_get(const struct dpll_pin *pin,
+				       void *pin_priv,
+				       const struct dpll_device *dpll,
+				       void *dpll_priv, u64 *frequency,
+				       struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	int rc;
+
+	mutex_lock(&sitdev->multiop_lock);
+	rc = sit9531x_output_freq_get(sitdev, dpin->id, frequency);
+	if (rc == -ENODATA)
+		*frequency = sit9531x_out_state_get(sitdev, dpin->id)->freq;
+	mutex_unlock(&sitdev->multiop_lock);
+
+	return rc == -ENODATA ? 0 : rc;
+}
+
+/*
+ * sit9531x_dpll_output_pin_frequency_set - set output pin frequency
+ *
+ * computes DIVO = Fvco / frequency and writes the
+ * 34-bit output divider to the output system registers via
+ * sit9531x_output_freq_set().
+ */
+static int
+sit9531x_dpll_output_pin_frequency_set(const struct dpll_pin *pin,
+				       void *pin_priv,
+				       const struct dpll_device *dpll,
+				       void *dpll_priv, u64 frequency,
+				       struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	u8 actual_pll;
+	int rc;
+
+	/*
+	 * Read the PLL that drives this output from its OUT_MAP state
+	 * (populated by out_state_fetch from the chip's OUT_MAP registers).
+	 * That is the index the output register programming below is keyed
+	 * by; the output is registered under the DPLL matching this PLL.
+	 */
+	actual_pll = sitdev->out[dpin->id].pll_idx;
+
+	mutex_lock(&sitdev->multiop_lock);
+	rc = sit9531x_output_freq_set(sitdev, dpin->id, actual_pll,
+				      frequency);
+	mutex_unlock(&sitdev->multiop_lock);
+
+	if (rc)
+		NL_SET_ERR_MSG(extack, "Output frequency set failed");
+
+	return rc;
+}
+
 static const struct dpll_pin_ops sit9531x_dpll_output_pin_ops = {
 	.direction_get		= sit9531x_dpll_output_pin_direction_get,
+	.frequency_get		= sit9531x_dpll_output_pin_frequency_get,
+	.frequency_set		= sit9531x_dpll_output_pin_frequency_set,
 };
 
 const struct dpll_pin_ops *
@@ -730,6 +844,12 @@ sit9531x_dpll_pin_ops_get(const struct sit9531x_dpll_pin *pin)
 		return &sit9531x_dpll_output_pin_ops;
 	if (sit9531x_dpll_is_xo_pin(pin))
 		return &sit9531x_dpll_xo_pin_ops;
+	/*
+	 * Seeded from the firmware node before the pin is registered and
+	 * never written afterwards, so register and unregister agree.
+	 */
+	if (!sit9531x_ref_state_get(pin->dpll->dev, pin->id)->freq)
+		return &sit9531x_dpll_input_pin_norate_ops;
 	return &sit9531x_dpll_input_pin_ops;
 }
 
diff --git a/drivers/dpll/sit9531x/prop.c b/drivers/dpll/sit9531x/prop.c
index 934db566c002..8270b8ee91be 100644
--- a/drivers/dpll/sit9531x/prop.c
+++ b/drivers/dpll/sit9531x/prop.c
@@ -295,15 +295,36 @@ sit9531x_pin_props_get(struct sit9531x_dev *sitdev,
 	}
 
 	/*
-	 * Seed an input's runtime ref->freq with the first DT-listed
-	 * supported frequency: for an input the board lists the rate that is
-	 * physically wired to it first.  An output's current rate is what its
-	 * divider produces, not an entry of the list it may be set to.
+	 * Seed the runtime ref->freq with the first DT-listed supported
+	 * frequency: an input's rate is a board fact the device cannot be
+	 * asked for, so firmware is the only source.  An output is left to
+	 * the read-back below, which knows what the divider is actually
+	 * doing.
 	 */
 	if (num_freqs > 0 && dir == DPLL_PIN_DIRECTION_INPUT &&
 	    index != SIT9531X_MAX_INPUTS)
 		curr_freq = freqs[0];
 
+	/*
+	 * An output's current rate is the one its divider produces, so read
+	 * it rather than assume the first entry of a list of the rates the
+	 * board supports is the one in force.  A rate taken from firmware
+	 * that the part is not running would be reported as current and,
+	 * worse, used as the output period the phase adjust quantizes
+	 * against.  An output the configuration does not route has no rate
+	 * to read, which is not an error.
+	 */
+	if (dir == DPLL_PIN_DIRECTION_OUTPUT &&
+	    index < sitdev->info->num_outputs) {
+		u64 hw_freq;
+
+		mutex_lock(&sitdev->multiop_lock);
+		rc = sit9531x_output_freq_get(sitdev, index, &hw_freq);
+		mutex_unlock(&sitdev->multiop_lock);
+		if (!rc)
+			curr_freq = hw_freq;
+	}
+
 skip_fwnode_props:
 	/* Neither INTSYNC pin carries a frequency attribute */
 	if (dir == DPLL_PIN_DIRECTION_INPUT &&
diff --git a/drivers/dpll/sit9531x/regs.h b/drivers/dpll/sit9531x/regs.h
index fd1068982cd7..eea38150b50f 100644
--- a/drivers/dpll/sit9531x/regs.h
+++ b/drivers/dpll/sit9531x/regs.h
@@ -200,6 +200,7 @@
 /* Debug register (same offset, per-page) */
 #define SIT9531X_REG_OUTSYS_DEBUG		SIT9531X_REG(0x03, 0xBD)
 #define SIT9531X_DEBUG_UNLOCK_VAL		0xC3
+#define SIT9531X_DEBUG_LOCK_VAL			0x00
 
 /*
  * On-demand phase-flush fired from a register rather than a GPIO pin.
@@ -214,6 +215,18 @@
 /* ---- PLL page registers (apply to pages 0x0A-0x0D) ---- */
 #define SIT9531X_PLL_REG_SMALL_UPDATE	0x0F
 
+/* On-demand phase-flush enable (PLL page reg 0x3D bit 7) */
+#define SIT9531X_PLL_REG_PHFL_CTRL	0x3D
+#define SIT9531X_PLL_PHFL_ON_DEMAND_EN	BIT(7)
+
+/* Whether the PLL has the phase-flush feature (PLL page reg 0x47 bit 7) */
+#define SIT9531X_PLL_REG_CONFIG47	0x47
+#define SIT9531X_PLL_CONFIG47_PHFL_EN	BIT(7)
+
+/* Directives_GENERIC_PLL: the restart bit restarts the PLL, self-clearing */
+#define SIT9531X_PLL_REG_DIRECTIVES	0x05
+#define SIT9531X_PLL_DIRECTIVE_RESTART	BIT(0)
+
 /*
  * Loop-filter coefficients on PLL_PAGE regs 0x10-0x15 (3 normal +
  * 3 fast-lock) are GUI/NVM-generated by the timing configurator and must not be
@@ -229,6 +242,14 @@
 #define SIT9531X_PLL_REG_OUT_MAP_LO		0x28
 #define SIT9531X_PLL_REG_STATUS		0x31
 
+/* DIVN registers (free-run divider readback) */
+#define SIT9531X_PLL_REG_DIVN_INT		0x30
+#define SIT9531X_PLL_REG_DIVN_NUM		0x32  /* 4 bytes (0x32-0x35) */
+#define SIT9531X_PLL_REG_DIVN_DEN		0x38  /* 4 bytes (0x38-0x3B) */
+
+/* DIVN is carried as fixed point, in steps of 1e-12 of a whole divider */
+#define SIT9531X_DIVN_SCALE		1000000000000ULL
+
 #define SIT9531X_PLL_REG_ACTIVE		0x02
 #define SIT9531X_PLL_ACTIVE_BIT		BIT(0)  /* PLL reached active state */
 
-- 
2.39.2 (Apple Git-143)

[PATCH net-next v12 09/12] dpll: sit9531x: implement output pin state on a DPLL

[Ali Rouhi]

From: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>

An output is driven by its PLL rather than selected by it, so its state
says whether it carries a signal: connected while it drives, disconnected
while it is muted.  Setting the state mutes or un-mutes it by forcing the
pad to Hi-Z, the only per-output control the device offers that leaves the
divider alone.

The force bit and the state bit are separate, and a pad follows the loaded
configuration while the force bit is clear, so both are read to decide
whether an output is muted and both are written to change it.  Which of
the four register banks applies depends on the slot and on whether the pad
is single-ended or differential.

A mute or un-mute is a per-output control, but each one that changes
something runs the device-wide programming sequence of the previous
patch, so a request for the state the output already has is answered
from the registers without entering it.  A request that fails after some
of its writes landed still announces the change, so a subscriber is not
left with the old state; the pin handle is read once, so a teardown
racing the request cannot hand the notification a cleared one.  A failed
entry into the programming state is left the way a commit leaves it:
loops re-locked and the settling time waited for.

This is also where output pins start being registered at all: until now
the registration filter took inputs only, so the output operations the
earlier patches added -- direction and frequency -- had nothing to
dispatch on.

Signed-off-by: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
Assisted-by: LLM
Signed-off-by: Ali Rouhi <arouhi@sitime.com>
---
 drivers/dpll/sit9531x/core.c | 344 +++++++++++++++++++++++++++++------
 drivers/dpll/sit9531x/core.h |   7 +
 drivers/dpll/sit9531x/dpll.c | 130 +++++++++++++
 3 files changed, 427 insertions(+), 54 deletions(-)

diff --git a/drivers/dpll/sit9531x/core.c b/drivers/dpll/sit9531x/core.c
index ea15830b0efa..19aeabd3cd4f 100644
--- a/drivers/dpll/sit9531x/core.c
+++ b/drivers/dpll/sit9531x/core.c
@@ -488,71 +488,50 @@ static int sit9531x_output_forced_hiz(struct sit9531x_dev *sitdev,
 					muted);
 }
 
-/* Attempts to re-lock the output loops before reporting them open. */
-#define SIT9531X_LOOP_LOCK_TRIES	3
-
 /*
- * sit9531x_prg_abort - leave the programming state without committing
+ * sit9531x_output_state_refresh - read an output's mute state back
  *
- * Entering the state is two writes, and the second can fail with the debug
- * block already unlocked and the part possibly already in PRG_CMD.  There
- * is nothing to commit in that case, but the loops still have to be closed
- * and the debug key put back, which is otherwise only done by
- * sit9531x_prg_commit().
+ * Used when a mute could not be confirmed at the time it was written.  The
+ * driver does not poll output state, so without this the cached value would
+ * stand until something else happened to write it.
+ *
+ * Caller must hold sitdev->multiop_lock.
  */
-static void sit9531x_prg_abort(struct sit9531x_dev *sitdev)
+int sit9531x_output_state_refresh(struct sit9531x_dev *sitdev, u8 out_idx)
 {
-	u8 attempt;
-	int rc = -EIO;
+	bool muted;
+	int rc;
 
-	for (attempt = 0; attempt < SIT9531X_LOOP_LOCK_TRIES; attempt++) {
-		rc = sit9531x_write_u8(sitdev, SIT9531X_REG_PRG_DIR_GEN,
-				       SIT9531X_LOOP_LOCK);
-		if (!rc)
-			break;
-		usleep_range(1000, 2000);
-	}
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	rc = sit9531x_output_forced_hiz(sitdev, out_idx, &muted);
 	if (rc)
-		dev_err(sitdev->dev,
-			"output loops left unlocked after a failed entry: %d\n",
-			rc);
+		return rc;
+
+	sitdev->out[out_idx].enabled = !muted;
+	sitdev->out[out_idx].state_stale = false;
 
-	sit9531x_write_u8(sitdev, SIT9531X_REG_OUTSYS_DEBUG,
-			  SIT9531X_DEBUG_LOCK_VAL);
+	return 0;
 }
 
-/*
- * Enter the output-system programming state: unlock the debug
- * registers on Page 3 and issue the PRG_CMD state command.  Register
- * writes that reconfigure the output system only take effect when
- * they are made inside this state.
- */
-static int sit9531x_prg_enter(struct sit9531x_dev *sitdev)
+static int sit9531x_hiz_set_bit(struct sit9531x_dev *sitdev,
+				unsigned int reg, u8 bit, bool set)
 {
+	u8 cur, new_val;
 	int rc;
 
-	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_OUTSYS_DEBUG,
-			       SIT9531X_DEBUG_UNLOCK_VAL);
+	rc = sit9531x_read_u8(sitdev, reg, &cur);
 	if (rc)
 		return rc;
 
-	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_PRG_DIR_GEN,
-			       SIT9531X_PRG_CMD_STATE);
-	if (rc) {
-		/*
-		 * The debug block is unlocked at this point, and a transfer
-		 * that reported an error may still have reached the part --
-		 * which would leave the device in PRG_CMD with its output
-		 * loops open.  Callers skip the commit when the entry
-		 * fails, so close both here.
-		 */
-		sit9531x_prg_abort(sitdev);
-		return rc;
-	}
+	new_val = set ? (cur | BIT(bit)) : (cur & ~BIT(bit));
 
-	return 0;
+	return sit9531x_write_u8(sitdev, reg, new_val);
 }
 
+/* Attempts to re-lock the output loops before reporting them open. */
+#define SIT9531X_LOOP_LOCK_TRIES	3
+
 /*
  * Commit a programming sequence started by sit9531x_prg_enter():
  * update the NVM shadow and re-lock the loops.  The sleep gives the
@@ -622,6 +601,251 @@ static int sit9531x_prg_commit(struct sit9531x_dev *sitdev)
 	return 0;
 }
 
+/*
+ * Enter the output-system programming state: unlock the debug
+ * registers on Page 3 and issue the PRG_CMD state command.  Register
+ * writes that reconfigure the output system only take effect when
+ * they are made inside this state.
+ */
+static int sit9531x_prg_enter(struct sit9531x_dev *sitdev)
+{
+	int rc;
+
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_OUTSYS_DEBUG,
+			       SIT9531X_DEBUG_UNLOCK_VAL);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_PRG_DIR_GEN,
+			       SIT9531X_PRG_CMD_STATE);
+	if (rc) {
+		/*
+		 * The debug block is unlocked at this point, and a transfer
+		 * that reported an error may still have reached the part --
+		 * which would leave the device in PRG_CMD with its output
+		 * loops open.  Callers skip the commit when the entry fails,
+		 * so leave the state here the way every completed sequence
+		 * does: nothing was changed, so the update commits what the
+		 * part already holds, the loops are re-locked, and the
+		 * settling time is waited out before the caller drops the
+		 * lock and the next request programs the part.  The entry
+		 * failure is the error to report.
+		 */
+		sit9531x_prg_commit(sitdev);
+		return rc;
+	}
+
+	return 0;
+}
+
+/*
+ * sit9531x_output_hiz_write - mute or unmute an output
+ *
+ * Muting takes control of the pin (MASK=1) and forces it to Hi-Z
+ * (STATE=0) on every Hi-Z pair of the slot -- differential, CMOS OutP
+ * and CMOS OutN -- because the output must go quiet whichever way it is
+ * wired; unmuting releases the override on all of them and hands the pin
+ * back to the device.  The caller must already be in the programming
+ * state.
+ */
+static int sit9531x_output_hiz_write(struct sit9531x_dev *sitdev, u8 slot,
+				     bool mute)
+{
+	struct sit9531x_hiz_pair p[SIT9531X_HIZ_PAIRS];
+	u8 mask[SIT9531X_HIZ_PAIRS], state[SIT9531X_HIZ_PAIRS];
+	int i, rc, undo_rc;
+
+	sit9531x_output_get_hiz_regs(slot, p);
+
+	if (!mute) {
+		for (i = 0; i < SIT9531X_HIZ_PAIRS; i++) {
+			rc = sit9531x_hiz_set_bit(sitdev, p[i].mask, p[i].bit,
+						  false);
+			if (rc)
+				return rc;
+		}
+		return 0;
+	}
+
+	/*
+	 * Remember every pair as it was: if the mute fails part-way, that
+	 * is what the pad goes back to -- which may already be a mute, from
+	 * an earlier request or from the loaded profile.
+	 */
+	for (i = 0; i < SIT9531X_HIZ_PAIRS; i++) {
+		rc = sit9531x_read_u8(sitdev, p[i].state, &state[i]);
+		if (rc)
+			return rc;
+		rc = sit9531x_read_u8(sitdev, p[i].mask, &mask[i]);
+		if (rc)
+			return rc;
+	}
+
+	/*
+	 * Forced value first, override enable second.  Muted is decoded as
+	 * MASK set with STATE clear, so enabling the override while STATE
+	 * still holds whatever the loaded configuration left there can pin
+	 * the pad driven for the width of an I2C transfer.
+	 */
+	for (i = 0; i < SIT9531X_HIZ_PAIRS; i++) {
+		rc = sit9531x_hiz_set_bit(sitdev, p[i].state, p[i].bit, false);
+		if (!rc)
+			rc = sit9531x_hiz_set_bit(sitdev, p[i].mask, p[i].bit,
+						  true);
+		if (rc)
+			break;
+	}
+	if (!rc)
+		return 0;
+
+	/*
+	 * Only part of the mute reached the device.  Put every pair it may
+	 * have touched back to the bits read above -- override first, then
+	 * value, the reverse of the order they went on -- so the pad ends
+	 * where the request started rather than on part of a mute, or
+	 * un-muted when it was muted before.
+	 */
+	for (; i >= 0; i--) {
+		u8 bit = BIT(p[i].bit);
+
+		undo_rc = sit9531x_hiz_set_bit(sitdev, p[i].mask, p[i].bit,
+					       mask[i] & bit);
+		if (!undo_rc)
+			undo_rc = sit9531x_hiz_set_bit(sitdev, p[i].state,
+						       p[i].bit,
+						       state[i] & bit);
+		if (undo_rc)
+			dev_err(sitdev->dev,
+				"slot%u: Hi-Z override left part applied (%d)\n",
+				slot, undo_rc);
+	}
+
+	return rc;
+}
+
+/*
+ * sit9531x_output_disable - mute an output (force Hi-Z)
+ * @index:	logical output index (0..info->num_outputs-1)
+ *
+ * Sets MASK and clears STATE on every Hi-Z pair of the slot, differential
+ * and both CMOS pads, so that the output is muted regardless of its
+ * electrical configuration.  The
+ * writes are wrapped in the PRG_CMD / NVM update / loop lock sequence
+ * so the new state is applied by the hardware.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+int sit9531x_output_disable(struct sit9531x_dev *sitdev, u8 index)
+{
+	const struct sit9531x_chip_info *info = sitdev->info;
+	bool muted;
+	u8 slot;
+	int rc, ret, state_rc;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (index >= info->num_outputs)
+		return -EINVAL;
+
+	slot = info->clkout_map[index];
+	rc = sit9531x_prg_enter(sitdev);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_output_hiz_write(sitdev, slot, true);
+
+	/*
+	 * Always leave the PRG_CMD programming state, even on a mid-sequence
+	 * write failure: prg_enter() unlocked the output loops, so returning
+	 * without prg_commit() would strand the chip in the programming state
+	 * with the loops unlocked.  Best effort -- keep the first error.
+	 */
+	ret = sit9531x_prg_commit(sitdev);
+	if (ret && !rc)
+		rc = ret;
+
+	/*
+	 * Keep the software state aligned to what hardware now drives even
+	 * when one write in the sequence failed. The commit above may have
+	 * applied a partial mask/state combination.
+	 */
+	state_rc = sit9531x_output_forced_hiz(sitdev, index, &muted);
+	if (!state_rc) {
+		sitdev->out[index].enabled = !muted;
+		sitdev->out[index].state_stale = false;
+	} else {
+		/*
+		 * The writes may well have landed; what failed is the proof.
+		 * Mark the cached state for a read-through rather than
+		 * reporting the value it had before this call.
+		 */
+		sitdev->out[index].state_stale = true;
+		if (!rc)
+			rc = state_rc;
+	}
+
+	return rc;
+}
+
+/*
+ * sit9531x_output_enable - un-mute an output (active state)
+ * @index:	logical output index (0..info->num_outputs-1)
+ *
+ * Releases MASK on every Hi-Z pair so the device drives the output
+ * again as the loaded profile configures it.  The writes are wrapped
+ * in the PRG_CMD / NVM update / loop lock sequence so the new state is
+ * applied by the hardware.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+int sit9531x_output_enable(struct sit9531x_dev *sitdev, u8 index)
+{
+	const struct sit9531x_chip_info *info = sitdev->info;
+	bool muted;
+	u8 slot;
+	int rc, ret, state_rc;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (index >= info->num_outputs)
+		return -EINVAL;
+
+	slot = info->clkout_map[index];
+	rc = sit9531x_prg_enter(sitdev);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_output_hiz_write(sitdev, slot, false);
+
+	/*
+	 * Always leave the PRG_CMD programming state, even on a mid-sequence
+	 * write failure: prg_enter() unlocked the output loops, so returning
+	 * without prg_commit() would strand the chip in the programming state
+	 * with the loops unlocked.  Best effort -- keep the first error.
+	 */
+	ret = sit9531x_prg_commit(sitdev);
+	if (ret && !rc)
+		rc = ret;
+
+	/* See sit9531x_output_disable(): commit can apply part of it. */
+	state_rc = sit9531x_output_forced_hiz(sitdev, index, &muted);
+	if (!state_rc) {
+		sitdev->out[index].enabled = !muted;
+		sitdev->out[index].state_stale = false;
+	} else {
+		/*
+		 * The writes may well have landed; what failed is the proof.
+		 * Mark the cached state for a read-through rather than
+		 * reporting the value it had before this call.
+		 */
+		sitdev->out[index].state_stale = true;
+		if (!rc)
+			rc = state_rc;
+	}
+
+	return rc;
+}
+
 /*
  * Input priority selection
  *
@@ -2512,6 +2736,8 @@ static int sit9531x_out_state_fetch(struct sit9531x_dev *sitdev, u8 index)
 	if (rc)
 		return rc;
 
+	sitdev->out[index].state_stale = false;
+
 	/*
 	 * Each PLL page holds the PLL's output-enable mask, twelve bits:
 	 * bits 0-7 in OUT_MAP_LO and bits 8-11 in OUT_MAP_HI[3:0].  PLLA and
@@ -3313,7 +3539,7 @@ static void sit9531x_dpll_pin_unregister(struct sit9531x_dpll_pin *pin)
 	 * afterwards leaves a window where the field still reads as live
 	 * and the pin behind it is already gone.
 	 */
-	pin->dpll_pin = NULL;
+	WRITE_ONCE(pin->dpll_pin, NULL);
 
 	dpll_pin_unregister(sitdpll->dpll_dev, dpll_pin, ops, pin);
 	dpll_pin_put(dpll_pin, &pin->tracker);
@@ -3363,8 +3589,8 @@ static void sit9531x_dpll_pins_unregister(struct sit9531x_dpll *sitdpll)
  * @index:	pin hardware index
  *
  * For input pins: delegate to sit9531x_input_pin_is_registrable().
- * A pin class whose state callback the tree does not have yet is not
- * registrable: the core refuses a pin without one.
+ * For output pins: the pin is registrable if this DPLL is routed to it,
+ * whether or not it is currently driving.
  *
  * Return: true if pin should be registered, false otherwise
  */
@@ -3374,13 +3600,23 @@ static bool sit9531x_dpll_pin_is_registrable(struct sit9531x_dpll *sitdpll,
 {
 	struct sit9531x_dev *sitdev = sitdpll->dev;
 
-	if (dir != DPLL_PIN_DIRECTION_INPUT)
+	if (dir == DPLL_PIN_DIRECTION_INPUT) {
+		if (index == SIT9531X_MAX_INPUTS)
+			return true;
+		if (index == SIT9531X_INTSYNC_PIN_ID)
+			return false;
+
+		return sit9531x_input_pin_is_registrable(sitdev, index);
+	}
+
+	if (index == SIT9531X_INTSYNC_OUT_PIN_ID)
 		return false;
 
-	if (index == SIT9531X_MAX_INPUTS)
-		return true;
+	if (index >= sitdev->info->num_outputs)
+		return false;
 
-	return sit9531x_input_pin_is_registrable(sitdev, index);
+	return sitdev->out[index].pll_idx == sitdpll->id &&
+	       sitdev->out[index].routed;
 }
 
 /*
diff --git a/drivers/dpll/sit9531x/core.h b/drivers/dpll/sit9531x/core.h
index 006a7fee76ab..0554b9f28503 100644
--- a/drivers/dpll/sit9531x/core.h
+++ b/drivers/dpll/sit9531x/core.h
@@ -99,6 +99,8 @@ struct sit9531x_ref {
  * @cmos:		output is wired single-ended; the Hi-Z pairs that
  *			speak for it are the two CMOS pad ones, not the
  *			differential
+ * @state_stale:	the cached mute state could not be confirmed against
+ *			hardware and has to be read back before it is reported
  * @routed:		output is mapped to @pll_idx by the initial
  *			configuration; an unrouted output has no DPLL pin
  * @pll_idx:		PLL driving this output (0-3)
@@ -107,6 +109,7 @@ struct sit9531x_out {
 	u64		freq;
 	bool		enabled;
 	bool		cmos;
+	bool		state_stale;
 	bool		routed;
 	u8		pll_idx;
 };
@@ -266,6 +269,10 @@ int sit9531x_input_prio_add(struct sit9531x_dev *sitdev, u8 pll_idx,
 			    u8 input_idx);
 
 /* ---- Output enable/disable (Hi-Z control) ---- */
+int sit9531x_output_disable(struct sit9531x_dev *sitdev, u8 index);
+int sit9531x_output_enable(struct sit9531x_dev *sitdev, u8 index);
+int sit9531x_output_state_refresh(struct sit9531x_dev *sitdev,
+				  u8 out_idx);
 
 /* ---- Output frequency ---- */
 int sit9531x_output_freq_set(struct sit9531x_dev *sitdev, u8 out_idx,
diff --git a/drivers/dpll/sit9531x/dpll.c b/drivers/dpll/sit9531x/dpll.c
index aa021b374c45..fa650cc3177d 100644
--- a/drivers/dpll/sit9531x/dpll.c
+++ b/drivers/dpll/sit9531x/dpll.c
@@ -831,10 +831,140 @@ sit9531x_dpll_output_pin_frequency_set(const struct dpll_pin *pin,
 	return rc;
 }
 
+/*
+ * sit9531x_dpll_output_pin_state_on_dpll_get - get output pin state
+ *
+ * reports CONNECTED when the output is driven and
+ * DISCONNECTED when it has been muted via sit9531x_output_disable().
+ */
+static int
+sit9531x_dpll_output_pin_state_on_dpll_get(const struct dpll_pin *pin,
+					   void *pin_priv,
+					   const struct dpll_device *dpll,
+					   void *dpll_priv,
+					   enum dpll_pin_state *state,
+					   struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	const struct sit9531x_out *out;
+	int rc;
+
+	/*
+	 * A mute whose read-back failed left the cache unconfirmed; there is
+	 * no poll of output state to correct it, so read it here rather than
+	 * report a value that may predate the request.
+	 */
+	if (sitdev->out[dpin->id].state_stale) {
+		mutex_lock(&sitdev->multiop_lock);
+		rc = sit9531x_output_state_refresh(sitdev, dpin->id);
+		mutex_unlock(&sitdev->multiop_lock);
+		if (rc) {
+			NL_SET_ERR_MSG(extack,
+				       "Output mute state could not be read back");
+			return rc;
+		}
+	}
+
+	out = sit9531x_out_state_get(sitdev, dpin->id);
+	*state = out->enabled ? DPLL_PIN_STATE_CONNECTED
+			      : DPLL_PIN_STATE_DISCONNECTED;
+	return 0;
+}
+
+/*
+ * sit9531x_dpll_output_pin_state_on_dpll_set - mute/un-mute an output
+ *
+ * Forces Hi-Z on the output through the Hi-Z force/state register pairs
+ * of its slot, the differential and the single-ended one.
+ *   CONNECTED    -> enable (release the override, the device drives it)
+ *   DISCONNECTED -> disable (force Hi-Z)
+ */
+static int
+sit9531x_dpll_output_pin_state_on_dpll_set(const struct dpll_pin *pin,
+					   void *pin_priv,
+					   const struct dpll_device *dpll,
+					   void *dpll_priv,
+					   enum dpll_pin_state state,
+					   struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	bool enable = state == DPLL_PIN_STATE_CONNECTED;
+	bool was_enabled, changed;
+	int rc;
+
+	if (!enable && state != DPLL_PIN_STATE_DISCONNECTED)
+		return -EINVAL;
+
+	mutex_lock(&sitdev->multiop_lock);
+
+	/*
+	 * The core forwards a request for the state the output is already
+	 * in.  The Hi-Z pairs say what the pad does now, so read them and
+	 * answer such a request from them rather than run the programming
+	 * sequence, which holds the output loops unlocked for the 100 ms its
+	 * commit takes and would change nothing.  A read that fails leaves
+	 * the request to the sequence and its own read-back.
+	 */
+	if (!sit9531x_output_state_refresh(sitdev, dpin->id) &&
+	    sitdev->out[dpin->id].enabled == enable) {
+		mutex_unlock(&sitdev->multiop_lock);
+		return 0;
+	}
+
+	was_enabled = sitdev->out[dpin->id].enabled;
+
+	if (enable)
+		rc = sit9531x_output_enable(sitdev, dpin->id);
+	else
+		rc = sit9531x_output_disable(sitdev, dpin->id);
+
+	/*
+	 * A read-back that failed left the cache unconfirmed, and the
+	 * writes before it most likely landed: count that as a change too,
+	 * and let the getter's read-through fill in the state when the
+	 * notification is built.
+	 */
+	changed = sitdev->out[dpin->id].enabled != was_enabled ||
+		  sitdev->out[dpin->id].state_stale;
+
+	mutex_unlock(&sitdev->multiop_lock);
+
+	if (rc) {
+		struct dpll_pin *dpll_pin;
+
+		NL_SET_ERR_MSG(extack, "Failed to set output pin state");
+		/*
+		 * The core notifies only a request that succeeded, and the
+		 * poll does not watch outputs.  A failed request whose
+		 * read-back shows the output did change, or could not show
+		 * whether it did, still has to be announced, or subscribers
+		 * keep the old state for good.  The core's lock is held here,
+		 * as the helper requires.
+		 *
+		 * Teardown clears the pin's handle without that lock before
+		 * it unregisters the pin, and this callback spends the
+		 * sequence's 100 ms under it.  Read the handle once: NULL is
+		 * a pin on its way out, with nobody left to tell, and a
+		 * handle still set stays valid until this callback returns.
+		 */
+		dpll_pin = READ_ONCE(dpin->dpll_pin);
+		if (changed && dpll_pin)
+			__dpll_pin_change_ntf(dpll_pin);
+	}
+
+	return rc;
+}
+
 static const struct dpll_pin_ops sit9531x_dpll_output_pin_ops = {
 	.direction_get		= sit9531x_dpll_output_pin_direction_get,
 	.frequency_get		= sit9531x_dpll_output_pin_frequency_get,
 	.frequency_set		= sit9531x_dpll_output_pin_frequency_set,
+	.state_on_dpll_get	= sit9531x_dpll_output_pin_state_on_dpll_get,
+	.state_on_dpll_set	= sit9531x_dpll_output_pin_state_on_dpll_set,
 };
 
 const struct dpll_pin_ops *
-- 
2.39.2 (Apple Git-143)

[PATCH net-next v12 10/12] dpll: sit9531x: add support to adjust output phase

[Ali Rouhi]

From: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>

Shift an output in time against the others driven by the same PLL.  The
device has a coarse delay counted in VCO cycles and a three-bit fine field
in fixed thirty-picosecond steps, so a requested offset is split between
the two and what the core reads back is what the registers hold rather
than what was asked for.  The divider spends two VCO cycles acting on a
programmed delay before it releases the output, so the registers hold the
request plus those two cycles and the read-back takes them off again.

The window advertised to the core is one millisecond either way: the
device holds a delay anywhere within the output period, so on a slow
output the bound is the signed 32-bit picosecond attribute rather than
the hardware, and a round figure below it costs nothing and is what
keeps the subsystem from refusing every request; the granularity is one
picosecond, because the achievable delays are whole VCO cycles plus
thirty-picosecond steps and so form no uniform lattice for the core to
check against.

Delay only ever advances, so an offset larger than one output period is
folded back into a single period -- for a periodic signal that is the
same phase.  The fold is counted in VCO cycles, since the period is
exactly the divider's count of them, and the quantizer takes whichever
of the neighbouring whole cycles with the fine steps lands nearest.  An
advance is held as the complementary delay and reads back as an advance
only where the period exceeds the advertised window; elsewhere the two
describe the same edge and the delay form is reported.  A delay the
loaded configuration left beyond the window is reported clamped and is
not carried into a later rate change.  A rate change on an output with a
programmed delay re-times it inside the rate change's own programming
window, so there is one sequence and one flush, and a flush that failed
after the delay was committed is retried by the next request.  The write
takes effect in the programming state, which is left with the loops
re-locked even when a write inside it failed.

The device has no per-output phase flush, so realigning the adjusted
output restarts the divider phase of every output that PLL drives.  On a
part where outputs are deliberately skewed against each other that is a
visible edge jump on the others, and there is no register that would let
the driver avoid it.  A PLL the loaded profile builds without the
phase-flush feature has no flush to fire; realigning its outputs
restarts the whole PLL, so a phase adjust or a rate change on such a PLL
is a loss of lock as well as an edge jump on its other outputs.

Suggested-by: Ivan Vecera <ivecera@redhat.com>
Signed-off-by: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
Assisted-by: LLM
Signed-off-by: Ali Rouhi <arouhi@sitime.com>
---
 drivers/dpll/sit9531x/core.c | 662 +++++++++++++++++++++++++++++++++--
 drivers/dpll/sit9531x/core.h |  22 ++
 drivers/dpll/sit9531x/dpll.c |  80 +++++
 drivers/dpll/sit9531x/prop.c |  22 ++
 drivers/dpll/sit9531x/regs.h |  37 ++
 5 files changed, 798 insertions(+), 25 deletions(-)

diff --git a/drivers/dpll/sit9531x/core.c b/drivers/dpll/sit9531x/core.c
index 19aeabd3cd4f..8a8872b18d2c 100644
--- a/drivers/dpll/sit9531x/core.c
+++ b/drivers/dpll/sit9531x/core.c
@@ -2264,11 +2264,422 @@ static int sit9531x_output_divo_read(struct sit9531x_dev *sitdev, u8 out_idx,
 	return *divo ? 0 : -ENODATA;
 }
 
+/*
+ * Phase adjust (PRG_RST_DELAY register-based).
+ *
+ * The chip exposes a per-output 34-bit coarse delay measured in VCO
+ * clock periods plus a 3-bit fine delay in fixed 30 ps steps.  The
+ * five bytes PROG6..PROG2 hold the field across registers:
+ *   base + 0  PROG6  [7:5] OPSTG_VCASC_BUMP (preserved via RMW)
+ *                    [4:2] PRG_RST_FINE_DELAY
+ *                    [1:0] PRG_RST_DELAY[33:32]
+ *   base + 1  PROG5  PRG_RST_DELAY[31:24]
+ *   base + 2  PROG4  PRG_RST_DELAY[23:16]
+ *   base + 3  PROG3  PRG_RST_DELAY[15:8]
+ *   base + 4  PROG2  PRG_RST_DELAY[7:0]
+ *
+ * Slots 0-5 live on Page 3, slots 6-11 on Page 4, with each slot's
+ * block at base = 0x15 + 16 * (slot % 6); the slot is the physical
+ * output position from clkout_map[], not the logical output index.
+ *
+ * The chip only supports unsigned positive delay.  Requests are folded
+ * modulo one output period: positive delays wrap naturally and a negative
+ * phase adjustment (advance) is rendered as (T_out - |phase|).
+ */
+
+/*
+ * Register of byte @i (PROG6 first) of an output's PRG_RST_DELAY block.
+ *
+ * The logical output index maps to the chip's physical output slot.  On
+ * SiT95317 the eight logical outputs land on chip slots {0, 3, 4, 5, 7,
+ * 8, 9, 11}; on SiT95316 the map is identity.  Page and base address the
+ * slot, not the logical index.
+ */
+static unsigned int sit9531x_output_prg_reg(struct sit9531x_dev *sitdev,
+					    u8 out_idx, u8 i)
+{
+	u8 slot = sitdev->info->clkout_map[out_idx];
+	u8 page = (slot > SIT9531X_PAGE_OUTSYS0_SLOT_MAX) ?
+		  SIT9531X_PAGE_OUTSYS1 : SIT9531X_PAGE_OUTSYS0;
+	u8 base = SIT9531X_OUT_PRG_DELAY_BASE +
+		  SIT9531X_OUT_PRG_SLOT_STRIDE * (slot % 6);
+
+	return SIT9531X_REG(page, base + i);
+}
+
+/* Read the PRG_RST_DELAY bytes of an output, PROG6 first. */
+static int sit9531x_output_phase_bytes_read(struct sit9531x_dev *sitdev,
+					    u8 out_idx, u8 *bytes)
+{
+	int rc;
+	u8 i;
+
+	for (i = 0; i < SIT9531X_OUT_PRG_BYTES; i++) {
+		rc = sit9531x_read_u8(sitdev,
+				      sit9531x_output_prg_reg(sitdev, out_idx, i),
+				      &bytes[i]);
+		if (rc)
+			return rc;
+	}
+
+	return 0;
+}
+
+/*
+ * Encode a quantized delay into the register bytes.  @old_bytes supplies
+ * the PROG6 bits that are not the delay's, which are preserved.
+ *
+ * The register value carries the divider's own settling time: the
+ * quantizer works in the delay the caller asked for, the register wants
+ * that plus the two VCO cycles the divider spends acting on it, and a
+ * request of zero still waits those two.  Only the register value carries
+ * them; @coarse stays the requested delay, which is what gets cached.
+ */
+static void sit9531x_output_phase_bytes_build(const u8 *old_bytes, u64 coarse,
+					      u8 fine, u8 *new_bytes)
+{
+	u64 prg_coarse = coarse + SIT9531X_OUT_PRG_DIVO_CYCLES;
+
+	/* PROG6 RMW: preserve OPSTG_VCASC_BUMP in [7:5] */
+	new_bytes[0] = old_bytes[0] & SIT9531X_OUT_PRG_OPSTG_MASK;
+	new_bytes[0] |= (fine << SIT9531X_OUT_PRG_FINE_SHIFT) &
+			SIT9531X_OUT_PRG_FINE_MASK;
+	new_bytes[0] |= (u8)((prg_coarse >> 32) &
+			     SIT9531X_OUT_PRG_COARSE_HI_MASK);
+	new_bytes[1] = (u8)((prg_coarse >> 24) & 0xFF);
+	new_bytes[2] = (u8)((prg_coarse >> 16) & 0xFF);
+	new_bytes[3] = (u8)((prg_coarse >> 8) & 0xFF);
+	new_bytes[4] = (u8)(prg_coarse & 0xFF);
+}
+
+/*
+ * Write an output's delay bytes.  The caller must already be in the
+ * programming state.  On a failure every byte is put back, the one whose
+ * write reported the error included, since it may have reached the part.
+ */
+static int sit9531x_output_phase_bytes_write(struct sit9531x_dev *sitdev,
+					     u8 out_idx, const u8 *new_bytes,
+					     const u8 *old_bytes)
+{
+	int rc, ret, rb_rc = 0;
+	u8 i;
+
+	for (i = 0; i < SIT9531X_OUT_PRG_BYTES; i++) {
+		rc = sit9531x_write_u8(sitdev,
+				       sit9531x_output_prg_reg(sitdev, out_idx, i),
+				       new_bytes[i]);
+		if (rc)
+			goto rollback;
+	}
+
+	return 0;
+
+rollback:
+	for (i = 0; i < SIT9531X_OUT_PRG_BYTES; i++) {
+		ret = sit9531x_write_u8(sitdev,
+					sit9531x_output_prg_reg(sitdev, out_idx, i),
+					old_bytes[i]);
+		if (ret && !rb_rc)
+			rb_rc = ret;
+	}
+	if (rb_rc) {
+		dev_err(sitdev->dev,
+			"out%u: phase-adjust rollback failed (%d), the delay registers are part old and part new\n",
+			out_idx, rb_rc);
+		if (!rc)
+			rc = rb_rc;
+	}
+
+	return rc;
+}
+
+/*
+ * Error of realizing @abs_ps as @cycles whole VCO cycles plus the fine
+ * steps that come nearest, which are returned through @fine.
+ */
+static u64 sit9531x_output_phase_quant_err(u64 abs_ps, u64 fvco, u64 cycles,
+					   u8 *fine)
+{
+	u64 cycles_ps, steps = 0;
+
+	cycles_ps = mul_u64_u64_div_u64(cycles, 1000000000000ULL, fvco);
+	if (abs_ps > cycles_ps)
+		steps = div64_u64(abs_ps - cycles_ps +
+				  SIT9531X_OUT_PRG_FINE_STEP_PS / 2,
+				  SIT9531X_OUT_PRG_FINE_STEP_PS);
+	*fine = min_t(u64, steps, SIT9531X_OUT_PRG_FINE_MAX);
+
+	return abs_diff(abs_ps, cycles_ps +
+			(u64)*fine * SIT9531X_OUT_PRG_FINE_STEP_PS);
+}
+
+/*
+ * Quantize a phase request: fold @phase_ps into one output period and
+ * split it into whole VCO cycles (@coarse_out, without the divider's
+ * settling cycles) and fine steps (@fine_out).  @phase_adj gets the delay
+ * the two realize, in the request's sign and bounded to the advertised
+ * range, which is what the cache holds.  Pure arithmetic against @fvco
+ * and the divider @divo the output runs on, so a caller can encode
+ * before it enters the programming state.
+ */
+static int sit9531x_output_phase_encode(u64 fvco, u64 divo, s32 phase_ps,
+					u64 *coarse_out, u8 *fine_out,
+					s32 *phase_adj)
+{
+	u64 abs_ps, cycles, frac_ps, coarse = 0, coarse_ps, t_out_ps;
+	s64 phase_norm_ps = 0;
+	u8 fine = 0;
+
+	t_out_ps = mul_u64_u64_div_u64(divo, 1000000000000ULL, fvco);
+	if (!t_out_ps)
+		return -EINVAL;
+
+	/*
+	 * Convert to unsigned absolute delay.  Both signs are folded
+	 * modulo one period: positive delays wrap naturally, negative
+	 * delays are rendered as T_out - |phase|.  abs() is safe here
+	 * because the core rejects anything outside the advertised phase
+	 * range, which is +/-1 ms.
+	 *
+	 * The period is exactly DIVO VCO cycles, whereas in picoseconds it
+	 * is a fraction more often than not: 7812.5 ps at 128 MHz from a
+	 * 5.12 GHz VCO, and a fold on the truncated 7812 drops the half
+	 * picosecond once per period folded away, so 100 us -- 12800
+	 * periods exactly -- would come out as 6400 ps rather than nothing.
+	 * Fold the whole VCO cycles of the request modulo DIVO instead, and
+	 * carry the sub-cycle part across as it is.  div64_u64_rem() rather
+	 * than the % operator: a 64-bit modulo has no compiler helper on
+	 * 32-bit targets and leaves the module with an undefined __umoddi3.
+	 */
+	abs_ps = abs(phase_ps);
+	cycles = mul_u64_u64_div_u64(abs_ps, fvco, 1000000000000ULL);
+	frac_ps = abs_ps - mul_u64_u64_div_u64(cycles, 1000000000000ULL, fvco);
+	div64_u64_rem(cycles, divo, &cycles);
+	abs_ps = mul_u64_u64_div_u64(cycles, 1000000000000ULL, fvco) + frac_ps;
+	/*
+	 * The truncations above can put a request within a picosecond of a
+	 * whole period a picosecond past it; that is the same edge as none.
+	 */
+	if (abs_ps >= t_out_ps)
+		abs_ps = 0;
+	phase_norm_ps = phase_ps < 0 ? -(s64)abs_ps : (s64)abs_ps;
+	abs_ps = (phase_ps < 0 && abs_ps) ? t_out_ps - abs_ps : abs_ps;
+
+	if (abs_ps) {
+		u64 floor_cycles, err, alt_err;
+		u8 alt_fine;
+
+		/*
+		 * coarse_cycles = abs_ps * Fvco / 1e12 ps/s.
+		 * mul_u64_u64_div_u64() avoids overflow when abs_ps approaches
+		 * one second of 1 PPS wrap-around.
+		 */
+		floor_cycles = mul_u64_u64_div_u64(abs_ps, fvco,
+						   1000000000000ULL);
+
+		/*
+		 * Fine = round((abs_ps - coarse * vco_period_ps) / 30 ps).
+		 * The fine field spans 210 ps, more than one VCO cycle in
+		 * every band, so the cycle count that floors the request is
+		 * not always the nearest encoding: one cycle more can land
+		 * closer than any fine code when the remainder sits just
+		 * under a cycle, and one cycle fewer with a larger fine code
+		 * can land closer or exact -- 210 ps at 5 GHz is seven fine
+		 * steps, not a cycle and a ten picosecond remainder.  Take
+		 * the nearest of the three, the floor on a tie.
+		 */
+		coarse = floor_cycles;
+		err = sit9531x_output_phase_quant_err(abs_ps, fvco, coarse,
+						      &fine);
+		alt_err = sit9531x_output_phase_quant_err(abs_ps, fvco,
+							  floor_cycles + 1,
+							  &alt_fine);
+		if (alt_err < err) {
+			coarse = floor_cycles + 1;
+			fine = alt_fine;
+			err = alt_err;
+		}
+		if (floor_cycles) {
+			alt_err = sit9531x_output_phase_quant_err(abs_ps, fvco,
+								  floor_cycles - 1,
+								  &alt_fine);
+			if (alt_err < err) {
+				coarse = floor_cycles - 1;
+				fine = alt_fine;
+			}
+		}
+
+		/*
+		 * A delay that quantizes to a whole output period or beyond
+		 * is the same edge as no delay at all; program none, so the
+		 * registers hold no residual past the period and the cache
+		 * below describes exactly what they realize.
+		 */
+		coarse_ps = mul_u64_u64_div_u64(coarse, 1000000000000ULL, fvco);
+		if (coarse_ps + (u64)fine * SIT9531X_OUT_PRG_FINE_STEP_PS >=
+		    t_out_ps) {
+			coarse = 0;
+			fine = 0;
+		}
+
+		if (coarse + SIT9531X_OUT_PRG_DIVO_CYCLES >=
+		    (1ULL << SIT9531X_OUT_PRG_COARSE_BITS))
+			return -ERANGE;
+	}
+
+	coarse_ps = mul_u64_u64_div_u64(coarse, 1000000000000ULL, fvco);
+	abs_ps = coarse_ps + (u64)fine * SIT9531X_OUT_PRG_FINE_STEP_PS;
+	/*
+	 * Quantization can also land a few picoseconds past the end of the
+	 * advertised range, which the getter must not report.  Bound both
+	 * signs to the range; the positive one is also what keeps the cast
+	 * to the s32 the ABI carries safe.
+	 */
+	if (phase_norm_ps < 0)
+		*phase_adj = abs_ps ?
+			     -(s32)min_t(u64, t_out_ps - abs_ps,
+					  SIT9531X_OUT_PHASE_ADJ_MAX_PS) : 0;
+	else
+		*phase_adj = (s32)min_t(u64, abs_ps,
+					 SIT9531X_OUT_PHASE_ADJ_MAX_PS);
+
+	*coarse_out = coarse;
+	*fine_out = fine;
+
+	return 0;
+}
+
+/**
+ * sit9531x_output_phase_read - read an output's programmed delay back
+ * @sitdev:	device pointer
+ * @out_idx:	logical output index
+ * @phase_ps:	result in picoseconds, in the advertised range
+ * @clamped:	set when the delay lies beyond the advertised range either
+ *		way and @phase_ps reports the end of the range in its place
+ *
+ * The delay the chip holds is part of the profile it loads before probe,
+ * and a rate or phase request that failed after its writes reached the
+ * device leaves the cache describing something else.  Decoding the five
+ * PRG_RST_DELAY bytes is the only way to say what the output is really
+ * doing.  The registers carry an unsigned delay, and an advance is held
+ * as its complement to the output period.  The two can only be told
+ * apart on an output whose period is longer than the advertised range:
+ * there a delay beyond the range whose complement is within it reads
+ * back as that advance.  On a faster output every delay is within the
+ * range, and an advance that was set reads back as the delay to the same
+ * edge, which is the same phase.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ *
+ * Return: 0 on success, -ENODATA for an output no PLL drives or whose VCO
+ * rate is unknown, <0 on register access error
+ */
+int sit9531x_output_phase_read(struct sit9531x_dev *sitdev, u8 out_idx,
+			       s32 *phase_ps, bool *clamped)
+{
+	const struct sit9531x_chip_info *info = sitdev->info;
+	u8 bytes[SIT9531X_OUT_PRG_BYTES], fine;
+	u64 coarse = 0, fvco, ps, divo;
+	int rc;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (out_idx >= info->num_outputs)
+		return -EINVAL;
+
+	*clamped = false;
+
+	/*
+	 * An output no PLL drives has no Fvco to decode its delay against;
+	 * pll_idx then holds a placeholder, not a routing.
+	 */
+	if (!sitdev->out[out_idx].routed)
+		return -ENODATA;
+
+	rc = sit9531x_get_fvco(sitdev, sitdev->out[out_idx].pll_idx, &fvco);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_output_phase_bytes_read(sitdev, out_idx, bytes);
+	if (rc)
+		return rc;
+
+	fine = (bytes[0] & SIT9531X_OUT_PRG_FINE_MASK) >>
+	       SIT9531X_OUT_PRG_FINE_SHIFT;
+	coarse = (u64)(bytes[0] & SIT9531X_OUT_PRG_COARSE_HI_MASK) << 32;
+	coarse |= (u64)bytes[1] << 24;
+	coarse |= (u64)bytes[2] << 16;
+	coarse |= (u64)bytes[3] << 8;
+	coarse |= bytes[4];
+
+	/*
+	 * The register carries the divider's settling time on top of the
+	 * delay that was asked for, so take it back off.  A profile can
+	 * leave a value below it, which describes no delay at all.
+	 */
+	coarse = (coarse > SIT9531X_OUT_PRG_DIVO_CYCLES) ?
+		 coarse - SIT9531X_OUT_PRG_DIVO_CYCLES : 0;
+
+	/*
+	 * The setter holds an advance as T_out - |advance|, so a delay
+	 * beyond the advertised range whose complement is within it is that
+	 * advance and reads back as one.  Anything else a profile left
+	 * beyond the range -- wider than an s32 on a slow output -- reports
+	 * the end of the range rather than a value the setter would refuse,
+	 * and says so: the end of the range is not the delay, and a rate
+	 * change must not re-time it into the device as though it were.
+	 *
+	 * The period comes from the divider rather than from the cached rate,
+	 * which is still unset at probe and whole hertz at best.  An output
+	 * without a programmed divider has no period to fold against; a
+	 * divider that could not be read is an error, not a missing one,
+	 * since the unfolded value would be cached as the realized delay.
+	 */
+	rc = sit9531x_output_divo_read(sitdev, out_idx, &divo);
+	if (rc && rc != -ENODATA)
+		return rc;
+
+	/*
+	 * The period is exactly DIVO VCO cycles, so fold the cycle count
+	 * rather than the picoseconds it converts to, which would drop the
+	 * fraction of a picosecond of the period once per period folded
+	 * away (see sit9531x_output_phase_encode()).  The fine steps can
+	 * still carry the sum a fraction of a cycle past the period; one
+	 * subtraction folds that without anything to accumulate.
+	 */
+	if (!rc)
+		div64_u64_rem(coarse, divo, &coarse);
+
+	ps = mul_u64_u64_div_u64(coarse, 1000000000000ULL, fvco);
+	ps += (u64)fine * SIT9531X_OUT_PRG_FINE_STEP_PS;
+
+	if (!rc) {
+		u64 t_out_ps = mul_u64_u64_div_u64(divo, 1000000000000ULL,
+						   fvco);
+
+		if (ps >= t_out_ps)
+			ps -= t_out_ps;
+		if (ps > SIT9531X_OUT_PHASE_ADJ_MAX_PS &&
+		    t_out_ps - ps <= SIT9531X_OUT_PHASE_ADJ_MAX_PS) {
+			*phase_ps = -(s32)(t_out_ps - ps);
+			return 0;
+		}
+	}
+	*clamped = ps > SIT9531X_OUT_PHASE_ADJ_MAX_PS;
+	*phase_ps = (s32)min_t(u64, ps, SIT9531X_OUT_PHASE_ADJ_MAX_PS);
+
+	return 0;
+}
+
 int sit9531x_output_freq_set(struct sit9531x_dev *sitdev, u8 out_idx,
 			     u8 pll_idx, u64 frequency)
 {
-	u64 fvco, divo;
+	u8 old_bytes[SIT9531X_OUT_PRG_BYTES], new_bytes[SIT9531X_OUT_PRG_BYTES];
+	u64 fvco, divo, coarse;
+	bool retime = false;
+	s32 phase_adj = 0;
 	int rc, ret;
+	u8 fine;
 
 	lockdep_assert_held(&sitdev->multiop_lock);
 
@@ -2277,11 +2688,44 @@ int sit9531x_output_freq_set(struct sit9531x_dev *sitdev, u8 out_idx,
 	if (rc)
 		return rc;
 
+	/*
+	 * The programmed reset delay counts VCO cycles, and a rate change
+	 * moves only the divider, so a positive delay keeps its timing; an
+	 * advance, though, is held as T_out - |advance| and has to be
+	 * re-encoded against the new period.  Re-encode the delay the output
+	 * realizes, which is what the cache holds, against the new divider,
+	 * and write it in the same programming window as the divider: the
+	 * rate change then costs one commit and one flush.  A second window
+	 * would open the output loops and wait out their settling again, and
+	 * a second flush would restart the PLL's dividers again -- or, on a
+	 * PLL the profile builds without the phase-flush feature, the PLL
+	 * itself.  For a positive delay the bytes come out the same and
+	 * nothing is written.  A re-time that cannot be worked out fails
+	 * the request before anything is written.
+	 */
+	if (sitdev->out[out_idx].phase_armed) {
+		rc = sit9531x_output_phase_encode(fvco, divo,
+						  sitdev->out[out_idx].phase_adj,
+						  &coarse, &fine, &phase_adj);
+		if (rc)
+			return rc;
+		rc = sit9531x_output_phase_bytes_read(sitdev, out_idx,
+						      old_bytes);
+		if (rc)
+			return rc;
+		sit9531x_output_phase_bytes_build(old_bytes, coarse, fine,
+						  new_bytes);
+		retime = memcmp(old_bytes, new_bytes, sizeof(new_bytes)) != 0;
+	}
+
 	rc = sit9531x_prg_enter(sitdev);
 	if (rc)
 		return rc;
 
 	rc = sit9531x_output_divo_write(sitdev, out_idx, divo);
+	if (!rc && retime)
+		rc = sit9531x_output_phase_bytes_write(sitdev, out_idx,
+						       new_bytes, old_bytes);
 	/*
 	 * Step 4: NVM update + loop lock.  Always run prg_commit() so the chip
 	 * leaves the PRG_CMD state with the output loops re-locked, even when a
@@ -2291,8 +2735,22 @@ int sit9531x_output_freq_set(struct sit9531x_dev *sitdev, u8 out_idx,
 	ret = sit9531x_prg_commit(sitdev);
 	if (ret && !rc)
 		rc = ret;
-	if (rc)
+	if (rc) {
+		/*
+		 * The divider may have changed all the same: a failed update
+		 * can have reached the part, a loop lock can fail after it
+		 * took effect, and a failed rollback leaves whatever landed.
+		 * An advance is held as T_out - |advance| against the period
+		 * that was, and the re-timed bytes may or may not be in, so
+		 * the cache no longer says what the output does.  Mark it for
+		 * a read-back: the core drops a retry of either request,
+		 * the rate because it reads the new one first and the phase
+		 * because it would match the stale cache.
+		 */
+		if (sitdev->out[out_idx].phase_armed)
+			sitdev->out[out_idx].phase_stale = true;
 		return rc;
+	}
 
 	/*
 	 * Step 5: flush the PLL's output phase so the new DIVO starts
@@ -2305,19 +2763,31 @@ int sit9531x_output_freq_set(struct sit9531x_dev *sitdev, u8 out_idx,
 	 * divider on its old phase, which is a realignment that did not
 	 * happen rather than a rate that did not change -- and reporting a
 	 * failure would be doubly wrong, because the core asks for the
-	 * current rate first and would drop an identical retry.
+	 * current rate first and would drop an identical retry.  A re-timed
+	 * delay is then committed but not applied either; mark it for a
+	 * read-back rather than cache a value the flush did not realize.
 	 */
 	rc = sit9531x_output_phase_flush(sitdev, pll_idx);
 	if (rc) {
 		dev_warn(sitdev->dev,
 			 "out%u: rate changed but the divider phase was not realigned (%d)\n",
 			 out_idx, rc);
+		if (retime)
+			sitdev->out[out_idx].phase_stale = true;
 		rc = 0;
+	} else {
+		/* Whatever flush was owed from before has now run. */
+		sitdev->out[out_idx].flush_pending = false;
+		if (retime) {
+			sitdev->out[out_idx].phase_adj = phase_adj;
+			sitdev->out[out_idx].phase_armed = phase_adj != 0;
+			sitdev->out[out_idx].phase_stale = false;
+		}
 	}
 
 	sitdev->out[out_idx].freq = div64_u64(fvco, divo);
 
-	return 0;
+	return rc;
 }
 
 /*
@@ -2371,27 +2841,140 @@ int sit9531x_output_freq_get(struct sit9531x_dev *sitdev, u8 out_idx,
 	return 0;
 }
 
-/*
- * Phase adjust (PRG_RST_DELAY register-based).
- *
- * The chip exposes a per-output 34-bit coarse delay measured in VCO
- * clock periods plus a 3-bit fine delay in fixed 30 ps steps.  The
- * five bytes PROG6..PROG2 hold the field across registers:
- *   base + 0  PROG6  [7:5] OPSTG_VCASC_BUMP (preserved via RMW)
- *                    [4:2] PRG_RST_FINE_DELAY
- *                    [1:0] PRG_RST_DELAY[33:32]
- *   base + 1  PROG5  PRG_RST_DELAY[31:24]
- *   base + 2  PROG4  PRG_RST_DELAY[23:16]
- *   base + 3  PROG3  PRG_RST_DELAY[15:8]
- *   base + 4  PROG2  PRG_RST_DELAY[7:0]
- *
- * Outputs 0-5 live on Page 3, outputs 6-11 on Page 4, with each
- * output's block at base = 0x15 + 16 * (out_idx % 6).
- *
- * The chip only supports unsigned positive delay.  A negative phase
- * adjustment (advance) is wrapped to (T_out - |phase|) modulo one
- * output period, which is identical for a periodic signal.
- */
+int sit9531x_output_phase_adjust_set(struct sit9531x_dev *sitdev,
+				     u8 out_idx, s32 phase_ps)
+{
+	u8 old_bytes[SIT9531X_OUT_PRG_BYTES], new_bytes[SIT9531X_OUT_PRG_BYTES];
+	const struct sit9531x_chip_info *info = sitdev->info;
+	u64 fvco, divo, coarse;
+	u8 pll_idx, fine;
+	s32 phase_adj;
+	int rc, ret;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (out_idx >= info->num_outputs)
+		return -EINVAL;
+
+	pll_idx = sitdev->out[out_idx].pll_idx;
+	if (pll_idx >= SIT9531X_NUM_PLLS)
+		return -EINVAL;
+
+	rc = sit9531x_get_fvco(sitdev, pll_idx, &fvco);
+	if (rc)
+		return rc == -ENODATA ? -ENODEV : rc;
+
+	/*
+	 * The output period comes from the divider the output runs on, not
+	 * from the cached rate: that is whole hertz, so a profile's output at
+	 * a fractional rate would fold an advance against the wrong period.
+	 */
+	rc = sit9531x_output_divo_read(sitdev, out_idx, &divo);
+	if (rc)
+		return rc == -ENODATA ? -ENODEV : rc;
+
+	rc = sit9531x_output_phase_encode(fvco, divo, phase_ps, &coarse, &fine,
+					  &phase_adj);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_output_phase_bytes_read(sitdev, out_idx, old_bytes);
+	if (rc)
+		return rc;
+	sit9531x_output_phase_bytes_build(old_bytes, coarse, fine, new_bytes);
+
+	/*
+	 * The pin advertises 1 ps granularity but caches the quantized
+	 * value, so a repeated off-grid request reaches here with the
+	 * registers already holding it.  Rewriting them would still restart
+	 * the divider phase of every output on the PLL; skip it unless an
+	 * earlier failure left the delay unconfirmed.  A delay whose flush
+	 * failed is committed and only owes that flush, which matching
+	 * bytes would otherwise skip as well.
+	 */
+	if (!memcmp(old_bytes, new_bytes, sizeof(new_bytes)) &&
+	    !sitdev->out[out_idx].phase_stale) {
+		if (!sitdev->out[out_idx].flush_pending)
+			goto cache;
+		goto flush;
+	}
+
+	/*
+	 * The PRG_RST_DELAY bytes live in the output system, so the writes
+	 * only take effect when made inside the PRG_CMD programming state and
+	 * committed to the NVM shadow, exactly like sit9531x_output_freq_set().
+	 */
+	rc = sit9531x_prg_enter(sitdev);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_output_phase_bytes_write(sitdev, out_idx, new_bytes,
+					       old_bytes);
+
+	/*
+	 * Always leave the PRG_CMD state via prg_commit(), even on a
+	 * mid-sequence write failure, so the output loops are re-locked rather
+	 * than stranded unlocked; keep the first error.
+	 */
+	ret = sit9531x_prg_commit(sitdev);
+	if (ret && !rc)
+		rc = ret;
+	if (rc) {
+		/*
+		 * The delay registers were written and the rollback may not
+		 * have put all of them back, so what the output realizes is
+		 * no longer what the cache says.  Mark it so the getter reads
+		 * the registers instead of reporting the value that was
+		 * cached before this call.  No flush ran either way.
+		 */
+		sitdev->out[out_idx].phase_stale = true;
+		sitdev->out[out_idx].flush_pending = true;
+		return rc;
+	}
+
+flush:
+	/*
+	 * Restart the output divider phase so the freshly programmed delay is
+	 * applied against a known edge instead of the divider's arbitrary
+	 * running phase.
+	 */
+	rc = sit9531x_output_phase_flush(sitdev, pll_idx);
+	if (rc) {
+		/*
+		 * The delay is committed but the output keeps the phase it
+		 * had, so the cache is left as it is: it still says what the
+		 * output realizes.  Record the flush that is owed instead.
+		 * Marking the cache stale would have the getter publish the
+		 * new delay off the registers, the core would then drop a
+		 * retry as a request for the value already reported, and the
+		 * realignment would never run.
+		 */
+		sitdev->out[out_idx].flush_pending = true;
+		return rc;
+	}
+	sitdev->out[out_idx].flush_pending = false;
+	sitdev->out[out_idx].phase_stale = false;
+
+cache:
+	/*
+	 * Cache what the registers realize, and only once every step has
+	 * succeeded: the core drops a repeated request with the same value,
+	 * so a cache updated by a failed call would make the retry a no-op.
+	 */
+	sitdev->out[out_idx].phase_adj = phase_adj;
+
+	/*
+	 * Arm the re-time a rate change owes only for a delay that is
+	 * actually programmed: an advance is held as T_out - |advance|,
+	 * which has to be re-encoded against the new period.  A request
+	 * that quantized to nothing stays nothing at any rate, since the
+	 * quantum is the VCO cycle and not the output period, so there is
+	 * nothing to re-time for it.
+	 */
+	sitdev->out[out_idx].phase_armed = phase_adj != 0;
+
+	return 0;
+}
 
 /*
  * sit9531x_clear_notifications - clear all notification registers
@@ -2894,12 +3477,41 @@ static int sit9531x_dev_state_fetch(struct sit9531x_dev *sitdev)
 	}
 
 	for (i = 0; i < sitdev->info->num_outputs; i++) {
+		bool clamped;
+		s32 phase_ps;
+
 		rc = sit9531x_out_state_fetch(sitdev, i);
 		if (rc) {
 			dev_err(sitdev->dev,
 				"Failed to fetch output %u state: %d\n", i, rc);
 			return rc;
 		}
+
+		/*
+		 * The delay registers are part of the profile the chip loads
+		 * before probe, so an output can already carry one.  Seeding
+		 * the cache from the device is what lets a request of 0 ps
+		 * clear it: the core drops a request equal to what the
+		 * getter reports, and a cache that started at zero would
+		 * make clearing a programmed delay impossible.  An output
+		 * the configuration does not route has no Fvco to decode
+		 * against, which is not an error here.  A delay beyond the
+		 * range is reported as its end but not armed: re-timing it
+		 * on a rate change would write that end over the profile's
+		 * delay.
+		 */
+		mutex_lock(&sitdev->multiop_lock);
+		rc = sit9531x_output_phase_read(sitdev, i, &phase_ps, &clamped);
+		mutex_unlock(&sitdev->multiop_lock);
+		if (!rc) {
+			sitdev->out[i].phase_adj = phase_ps;
+			sitdev->out[i].phase_armed = !clamped && phase_ps;
+		} else if (rc != -ENODATA) {
+			dev_err(sitdev->dev,
+				"Failed to read output %u delay: %d\n",
+				i, rc);
+			return rc;
+		}
 	}
 
 	/*
diff --git a/drivers/dpll/sit9531x/core.h b/drivers/dpll/sit9531x/core.h
index 0554b9f28503..19efff5112a3 100644
--- a/drivers/dpll/sit9531x/core.h
+++ b/drivers/dpll/sit9531x/core.h
@@ -27,6 +27,8 @@
 #define SIT9531X_MAX_INPUTS		8
 #define SIT9531X_NUM_INPUT_PAIRS	(SIT9531X_MAX_INPUTS / 2)
 #define SIT9531X_MAX_OUTPUTS		12
+/* Output phase-adjust range advertised to the core, +/-1 ms in ps */
+#define SIT9531X_OUT_PHASE_ADJ_MAX_PS	1000000000
 /*
  * INTSYNC (the inter-PLL sync net) is modeled as two pins.  The
  * destination PLL that locks to INTSYNC sees an input pin
@@ -104,6 +106,18 @@ struct sit9531x_ref {
  * @routed:		output is mapped to @pll_idx by the initial
  *			configuration; an unrouted output has no DPLL pin
  * @pll_idx:		PLL driving this output (0-3)
+ * @phase_stale:	the programmed delay may differ from @phase_adj
+ * @flush_pending:	the programmed delay is committed but the flush
+ *			that applies it failed, so the output still realizes
+ *			@phase_adj; the next request for that delay runs the
+ *			flush although the registers already hold it
+ * @phase_armed:	a non-zero delay is programmed, so a rate change
+ *			has to re-time it; a profile delay beyond the
+ *			advertised range is not, since what the cache holds
+ *			for it is the end of the range, not the delay
+ * @phase_adj:		phase adjust the delay registers actually realize,
+ *			i.e. the last request quantized to whole VCO cycles
+ *			plus 30 ps fine steps, in the request's sign
  */
 struct sit9531x_out {
 	u64		freq;
@@ -112,6 +126,10 @@ struct sit9531x_out {
 	bool		state_stale;
 	bool		routed;
 	u8		pll_idx;
+	s32		phase_adj;
+	bool		phase_armed;
+	bool		phase_stale;
+	bool		flush_pending;
 };
 
 /*
@@ -281,6 +299,10 @@ int sit9531x_output_freq_get(struct sit9531x_dev *sitdev, u8 out_idx,
 			     u64 *frequency);
 
 /* ---- Output phase adjust (PRG_RST_DELAY register-based) ---- */
+int sit9531x_output_phase_read(struct sit9531x_dev *sitdev, u8 out_idx,
+			       s32 *phase_ps, bool *clamped);
+int sit9531x_output_phase_adjust_set(struct sit9531x_dev *sitdev,
+				     u8 out_idx, s32 phase_ps);
 
 /* ---- Notification clear ---- */
 int sit9531x_clear_notifications(struct sit9531x_dev *sitdev);
diff --git a/drivers/dpll/sit9531x/dpll.c b/drivers/dpll/sit9531x/dpll.c
index fa650cc3177d..436e4b76a727 100644
--- a/drivers/dpll/sit9531x/dpll.c
+++ b/drivers/dpll/sit9531x/dpll.c
@@ -959,12 +959,92 @@ sit9531x_dpll_output_pin_state_on_dpll_set(const struct dpll_pin *pin,
 	return rc;
 }
 
+/*
+ * sit9531x_dpll_output_pin_phase_adjust_get - read output phase adjustment
+ *
+ * Returns what the delay registers hold, i.e. the value
+ * sit9531x_output_phase_adjust_set() programmed after quantization, read
+ * from the cache unless a failed request left it unconfirmed.
+ */
+static int
+sit9531x_dpll_output_pin_phase_adjust_get(const struct dpll_pin *pin,
+					  void *pin_priv,
+					  const struct dpll_device *dpll,
+					  void *dpll_priv, s32 *phase_adjust,
+					  struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	int rc;
+
+	mutex_lock(&sitdev->multiop_lock);
+	/*
+	 * A request whose writes reached the device but whose commit or
+	 * phase flush failed left the cache describing the delay before it.
+	 * There is no poll of the delay registers to correct that, so read
+	 * them here rather than report a value the output is not using.
+	 */
+	if (sitdev->out[dpin->id].phase_stale) {
+		bool clamped;
+		s32 phase_ps;
+
+		rc = sit9531x_output_phase_read(sitdev, dpin->id, &phase_ps,
+						&clamped);
+		if (rc) {
+			mutex_unlock(&sitdev->multiop_lock);
+			NL_SET_ERR_MSG(extack,
+				       "Output delay could not be read back");
+			return rc;
+		}
+		sitdev->out[dpin->id].phase_adj = phase_ps;
+		sitdev->out[dpin->id].phase_armed = !clamped && phase_ps;
+		sitdev->out[dpin->id].phase_stale = false;
+	}
+	*phase_adjust = sit9531x_out_state_get(sitdev, dpin->id)->phase_adj;
+	mutex_unlock(&sitdev->multiop_lock);
+
+	return 0;
+}
+
+/*
+ * sit9531x_dpll_output_pin_phase_adjust_set - set output phase adjustment
+ *
+ * Programs the per-output PRG_RST_DELAY registers for deterministic
+ * phase offset; see sit9531x_output_phase_adjust_set() in core.c.
+ */
+static int
+sit9531x_dpll_output_pin_phase_adjust_set(const struct dpll_pin *pin,
+					  void *pin_priv,
+					  const struct dpll_device *dpll,
+					  void *dpll_priv, s32 phase_adjust,
+					  struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	int rc;
+
+	mutex_lock(&sitdev->multiop_lock);
+	rc = sit9531x_output_phase_adjust_set(sitdev, dpin->id, phase_adjust);
+	mutex_unlock(&sitdev->multiop_lock);
+
+	if (rc) {
+		NL_SET_ERR_MSG(extack, "Phase adjust failed");
+		return rc;
+	}
+
+	return 0;
+}
+
 static const struct dpll_pin_ops sit9531x_dpll_output_pin_ops = {
 	.direction_get		= sit9531x_dpll_output_pin_direction_get,
 	.frequency_get		= sit9531x_dpll_output_pin_frequency_get,
 	.frequency_set		= sit9531x_dpll_output_pin_frequency_set,
 	.state_on_dpll_get	= sit9531x_dpll_output_pin_state_on_dpll_get,
 	.state_on_dpll_set	= sit9531x_dpll_output_pin_state_on_dpll_set,
+	.phase_adjust_get	= sit9531x_dpll_output_pin_phase_adjust_get,
+	.phase_adjust_set	= sit9531x_dpll_output_pin_phase_adjust_set,
 };
 
 const struct dpll_pin_ops *
diff --git a/drivers/dpll/sit9531x/prop.c b/drivers/dpll/sit9531x/prop.c
index 8270b8ee91be..3aaafb0efd78 100644
--- a/drivers/dpll/sit9531x/prop.c
+++ b/drivers/dpll/sit9531x/prop.c
@@ -228,6 +228,28 @@ sit9531x_pin_props_get(struct sit9531x_dev *sitdev,
 		props->dpll_props.capabilities =
 			DPLL_PIN_CAPABILITIES_STATE_CAN_CHANGE;
 		curr_freq = sitdev->out[index].freq;
+
+		/*
+		 * Allow phase-adjust over a +/-1 ms window.  The subsystem
+		 * rejects pin_set(phase-adjust, X) when X falls outside
+		 * [min, max], so leaving these at 0 silently blocks every
+		 * netlink call.  The device holds a delay anywhere within
+		 * the output period, so the bound is the s32 picosecond
+		 * attribute, not the hardware; 1 ms is a round figure below
+		 * it that costs nothing.  Only outputs get a range: input
+		 * pins have no .phase_adjust_set, and advertising one there
+		 * would promise userspace something every set would refuse.
+		 */
+		props->dpll_props.phase_range.min =
+			-SIT9531X_OUT_PHASE_ADJ_MAX_PS;
+		props->dpll_props.phase_range.max =
+			SIT9531X_OUT_PHASE_ADJ_MAX_PS;
+		/*
+		 * The fine step is 30 ps, but requests are accepted at 1 ps
+		 * resolution and rounded to the nearest achievable delay, so
+		 * advertise the request granularity, not the hardware step.
+		 */
+		props->dpll_props.phase_gran = 1;
 	}
 
 	/* Generate package label */
diff --git a/drivers/dpll/sit9531x/regs.h b/drivers/dpll/sit9531x/regs.h
index eea38150b50f..7c41111dca20 100644
--- a/drivers/dpll/sit9531x/regs.h
+++ b/drivers/dpll/sit9531x/regs.h
@@ -202,6 +202,43 @@
 #define SIT9531X_DEBUG_UNLOCK_VAL		0xC3
 #define SIT9531X_DEBUG_LOCK_VAL			0x00
 
+/*
+ * Per-output programmable phase delay: 34-bit coarse (in VCO clock
+ * cycles) plus a 3-bit fine field with fixed 30 ps steps.  Each output
+ * has a five-byte block PROG6..PROG2:
+ *
+ *   base + 0  PROG6  [7:5] OPSTG_VCASC_BUMP (preserve via RMW)
+ *                    [4:2] PRG_RST_FINE_DELAY[2:0]
+ *                    [1:0] PRG_RST_DELAY[33:32]
+ *   base + 1  PROG5  [7:0] PRG_RST_DELAY[31:24]
+ *   base + 2  PROG4  [7:0] PRG_RST_DELAY[23:16]
+ *   base + 3  PROG3  [7:0] PRG_RST_DELAY[15:8]
+ *   base + 4  PROG2  [7:0] PRG_RST_DELAY[7:0]
+ *
+ * Slots 0-5 are on Page 3, slots 6-11 on Page 4.  The block base
+ * within a page is 0x15 + 16 * (slot % 6), where slot is the physical
+ * output slot from clkout_map[], not the logical output index.
+ */
+#define SIT9531X_OUT_PRG_DELAY_BASE		0x15
+#define SIT9531X_OUT_PRG_SLOT_STRIDE		0x10
+#define SIT9531X_OUT_PRG_BYTES			5
+/* bits [7:5], preserve */
+#define SIT9531X_OUT_PRG_OPSTG_MASK		0xE0
+#define SIT9531X_OUT_PRG_FINE_SHIFT		2
+#define SIT9531X_OUT_PRG_FINE_MASK		0x1C	/* bits [4:2] */
+#define SIT9531X_OUT_PRG_COARSE_HI_MASK		0x03	/* bits [1:0] */
+/*
+ * The divider takes two VCO cycles to act on a programmed delay and
+ * release the output, so the encoded value carries them and the realized
+ * delay is the register value less that.  The reference flow adds the
+ * same two.
+ */
+#define SIT9531X_OUT_PRG_DIVO_CYCLES	2
+
+#define SIT9531X_OUT_PRG_FINE_STEP_PS		30
+#define SIT9531X_OUT_PRG_FINE_MAX		7	/* 3-bit field */
+#define SIT9531X_OUT_PRG_COARSE_BITS		34
+
 /*
  * On-demand phase-flush fired from a register rather than a GPIO pin.
  * DIVO_PHASE_SEL_REG selects the in-register trigger source and
-- 
2.39.2 (Apple Git-143)

[PATCH net-next v12 11/12] dpll: sit9531x: add support to get phase offset on the connected input pin

[Ali Rouhi]

From: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>

Report the phase difference between a PLL's reference and the PLL itself,
which is the loop's own residual error and therefore trends small on a
locked device -- that is the measurement, not an artefact of it.

The value comes from the on-chip time-to-digital converter, read through
the debug window: unlock the window, point it at the converter, then read
the trigger register, which latches a fresh sample and returns the
previous one.  It is read three times per sample for that reason; a single
read hands back the sample from the last call, so a repeated measurement
would look perfectly steady while saying nothing.  The offset keeps the
fraction of a picosecond the converter resolves.

Only the input the device feeds a PLL has a phase offset against it.
For any other pin there is nothing to measure and zero is reported,
because the core abandons an entire pin dump on an error from any one pin.
That pin reads zero too when no sample was taken: the PLL is not
tracking, drives no un-muted output, has no usable VCO rate, or the
device moved it off the pin, or the lane lost its signal, between the
check and the sample.

Signed-off-by: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
Assisted-by: LLM
Signed-off-by: Ali Rouhi <arouhi@sitime.com>
---
 drivers/dpll/sit9531x/core.c | 220 +++++++++++++++++++++++++++++++++--
 drivers/dpll/sit9531x/core.h |   5 +
 drivers/dpll/sit9531x/dpll.c | 147 +++++++++++++++++++++++
 drivers/dpll/sit9531x/regs.h |  22 ++++
 4 files changed, 385 insertions(+), 9 deletions(-)

diff --git a/drivers/dpll/sit9531x/core.c b/drivers/dpll/sit9531x/core.c
index 8a8872b18d2c..fbac70787ada 100644
--- a/drivers/dpll/sit9531x/core.c
+++ b/drivers/dpll/sit9531x/core.c
@@ -922,8 +922,9 @@ static int sit9531x_prio_prg_commit(struct sit9531x_dev *sitdev)
 	return 0;
 }
 
-/*
+/**
  * sit9531x_input_mon_fetch - read the clock monitor status of every lane
+ * @sitdev:	device pointer
  *
  * Four registers carry a nibble per lane.  Loss of signal and frequency
  * drift are what separate an input the device could lock to from one it
@@ -932,7 +933,7 @@ static int sit9531x_prio_prg_commit(struct sit9531x_dev *sitdev)
  *
  * Caller must hold sitdev->multiop_lock, or run before registration.
  */
-static int sit9531x_input_mon_fetch(struct sit9531x_dev *sitdev)
+int sit9531x_input_mon_fetch(struct sit9531x_dev *sitdev)
 {
 	static const unsigned int regs[] = {
 		SIT9531X_CLKMON_P_STATUS_01, SIT9531X_CLKMON_P_STATUS_23,
@@ -3026,6 +3027,202 @@ int sit9531x_clear_notifications(struct sit9531x_dev *sitdev)
 	return 0;
 }
 
+/**
+ * sit9531x_phase_offset_read - read phase difference via TDC
+ * @sitdev:	device pointer
+ * @pll_idx:	PLL index (0-3)
+ * @phase_offset:	phase difference in units of 1/DPLL_PHASE_OFFSET_DIVIDER
+ *		of a picosecond, as the DPLL subsystem carries it
+ *
+ * Reads the Time-to-Digital Converter (TDC) code from the PLL page
+ * registers -- a 35-bit magnitude with a separate sign bit -- then
+ * converts it using the VCO frequency: phase_diff = tdc_code / fvco.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ *
+ * Return: 0 on success, -ENODATA when the PLL has no known VCO rate
+ * (nothing is sampled then), or the register access error
+ */
+int sit9531x_phase_offset_read(struct sit9531x_dev *sitdev, u8 pll_idx,
+			       s64 *phase_offset)
+{
+	u8 v, old_write_code, old_read_code;
+	bool have_old = false;
+	int rc, ret, i;
+	s64 tdc_signed;
+	u64 fvco, mag;
+	u64 tdc_raw;
+	bool sign;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (pll_idx >= SIT9531X_NUM_PLLS)
+		return -EINVAL;
+
+	/*
+	 * Get the VCO rate first.  -ENODATA means the PLL has no rate to
+	 * convert against (a divider this board leaves unprogrammed), and
+	 * there is then no reason to open the debug window at all -- which
+	 * also keeps a bus error while it is open from ever being reported
+	 * as that benign case.
+	 */
+	rc = sit9531x_get_fvco(sitdev, pll_idx, &fvco);
+	if (rc) {
+		if (rc == -ENODATA)
+			dev_dbg(sitdev->dev,
+				"PLL%c: Fvco unknown, skip TDC\n",
+				'A' + pll_idx);
+		return rc;
+	}
+
+	/* Unlock the debug page so the TDC registers are accessible. */
+	rc = sit9531x_write_pll_u8(sitdev, pll_idx,
+				   SIT9531X_PLL_REG_DEBUG,
+				   SIT9531X_PLL_DEBUG_UNLOCK);
+	if (rc)
+		goto relock;
+
+	/*
+	 * Remember the tap selection so it can be put back.  The key
+	 * register is re-locked below, but the mux is not part of the key:
+	 * leaving it parked on the TDC with a slow sampling clock selected
+	 * is a state change the caller did not ask for, and the next reader
+	 * of a different tap would have to know to undo it.
+	 */
+	rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+				  SIT9531X_PLL_REG_DBG_WRITE_CODE,
+				  &old_write_code);
+	if (!rc)
+		rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+					  SIT9531X_PLL_REG_DBG_READ_CODE,
+					  &old_read_code);
+	if (rc)
+		goto relock;
+
+	have_old = true;
+
+	/*
+	 * Select the debug clock for taps below 200 kHz, then point the
+	 * readback at the TDC.  Only the one bit is touched: writing the
+	 * modifier register whole would clear the fields belonging to
+	 * other taps.
+	 */
+	rc = sit9531x_update_pll_u8(sitdev, pll_idx,
+				    SIT9531X_PLL_REG_DBG_WRITE_CODE,
+				    SIT9531X_DBG_LOW_FREQ_CLK_BIT,
+				    SIT9531X_DBG_LOW_FREQ_CLK_BIT);
+	if (rc)
+		goto relock;
+	rc = sit9531x_write_pll_u8(sitdev, pll_idx,
+				   SIT9531X_PLL_REG_DBG_READ_CODE,
+				   SIT9531X_DBG_READ_CODE_TDC);
+	if (rc)
+		goto relock;
+
+	/*
+	 * Latch a sample by reading the debug status data register.  A
+	 * single read returns the previous latch, so read it three times
+	 * as the documented phase-difference procedure does.
+	 */
+	for (i = 0; i < SIT9531X_DBG_STATUS_READS; i++) {
+		rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+					  SIT9531X_PLL_REG_DBG_STATUS_DATA,
+					  &v);
+		if (rc)
+			goto relock;
+	}
+
+	tdc_raw = 0;
+
+	rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+				  SIT9531X_PLL_REG_DBG_DATA_4, &v);
+	if (rc)
+		goto relock;
+	sign = !!(v & BIT(SIT9531X_TDC_SIGN_BIT));
+	tdc_raw = (u64)(v & SIT9531X_TDC_MAG_HI_MASK) << 32;
+
+	rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+				  SIT9531X_PLL_REG_DBG_DATA_3, &v);
+	if (rc)
+		goto relock;
+	tdc_raw |= (u64)v << 24;
+
+	rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+				  SIT9531X_PLL_REG_DBG_DATA_2, &v);
+	if (rc)
+		goto relock;
+	tdc_raw |= (u64)v << 16;
+
+	rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+				  SIT9531X_PLL_REG_DBG_DATA_1, &v);
+	if (rc)
+		goto relock;
+	tdc_raw |= (u64)v << 8;
+
+	rc = sit9531x_read_pll_u8(sitdev, pll_idx,
+				  SIT9531X_PLL_REG_DBG_DATA_0, &v);
+	if (rc)
+		goto relock;
+	tdc_raw |= v;
+
+	/*
+	 * Apply sign.  Per the register map the sign bit is active-high
+	 * for a positive offset: bit set -> +code, bit clear -> -code.
+	 */
+	tdc_signed = sign ? (s64)tdc_raw : -(s64)tdc_raw;
+
+	/*
+	 * phase_diff (seconds) = tdc_code / fvco
+	 * phase_diff (ps) = tdc_code * 1e12 / fvco
+	 *
+	 * Scaled by the subsystem's divider before the division rather than
+	 * after it: one TDC code is 1e12 / fvco ps, a fraction of a
+	 * picosecond more often than not (203.45 ps at 4.9152 GHz), and
+	 * truncating to whole picoseconds first would leave the three
+	 * fractional digits the attribute carries always zero.  The
+	 * quotient fits u64 for any rate sit9531x_get_fvco() returns: it
+	 * refuses one below the VCO band.
+	 *
+	 * mul_u64_u64_div_u64() keeps the exact Hz denominator; dividing
+	 * by whole MHz instead would lose up to ~40 ppm of scale on a
+	 * fractional-DIVN Fvco.
+	 */
+	mag = mul_u64_u64_div_u64(tdc_signed < 0 ? -tdc_signed : tdc_signed,
+				  1000000000000ULL * DPLL_PHASE_OFFSET_DIVIDER,
+				  fvco);
+	*phase_offset = tdc_signed < 0 ? -(s64)mag : (s64)mag;
+
+	rc = 0;
+
+relock:
+	if (have_old) {
+		ret = sit9531x_write_pll_u8(sitdev, pll_idx,
+					    SIT9531X_PLL_REG_DBG_READ_CODE,
+					    old_read_code);
+		if (ret && !rc)
+			rc = ret;
+		ret = sit9531x_write_pll_u8(sitdev, pll_idx,
+					    SIT9531X_PLL_REG_DBG_WRITE_CODE,
+					    old_write_code);
+		if (ret && !rc)
+			rc = ret;
+	}
+
+	/*
+	 * Close the debug window again.  The key register opens every debug
+	 * register on this PLL while it holds the unlock value, and this read
+	 * runs on every pin-get of a connected input, so leaving it open
+	 * would mean normal monitoring permanently unlocks the block.
+	 */
+	ret = sit9531x_write_pll_u8(sitdev, pll_idx,
+				    SIT9531X_PLL_REG_DEBUG,
+				    SIT9531X_PLL_DEBUG_LOCK);
+	if (ret && !rc)
+		rc = ret;
+
+	return rc;
+}
+
 /*
  * sit9531x_ref_state_fetch - read input reference status from hardware
  * @index:	logical input index
@@ -3124,8 +3321,13 @@ static int sit9531x_pll_is_active(struct sit9531x_dev *sitdev, u8 pll_idx,
 	return 0;
 }
 
-/*
- * Read the reference the device feeds a PLL.
+/**
+ * sit9531x_chan_routed_ref_read - read the reference the device feeds a PLL
+ * @sitdev:	device pointer
+ * @pll_idx:	PLL index (0-3)
+ * @ref:	result: logical input index, SIT9531X_INTSYNC_PIN_ID for the
+ *		inter-PLL sync net, or SIT9531X_REF_INVALID when the code
+ *		names no registered input
  *
  * The active selection names the source the PLL was told to follow.  The
  * input subsystem feeds the PLL that source while it has signal and falls
@@ -3140,12 +3342,12 @@ static int sit9531x_pll_is_active(struct sit9531x_dev *sitdev, u8 pll_idx,
  * free-run the PLL is fed nothing and the bus is not consulted, so the
  * caller checks the mode first.
  *
- * @ref is the logical input index, SIT9531X_INTSYNC_PIN_ID for the
- * inter-PLL sync net, or SIT9531X_REF_INVALID when the code names no
- * registered input.  Caller must hold sitdev->multiop_lock.
+ * Caller must hold sitdev->multiop_lock.
+ *
+ * Return: 0 on success, <0 on error
  */
-static int sit9531x_chan_routed_ref_read(struct sit9531x_dev *sitdev,
-					 u8 pll_idx, u8 *ref)
+int sit9531x_chan_routed_ref_read(struct sit9531x_dev *sitdev, u8 pll_idx,
+				  u8 *ref)
 {
 	int rc, lock_rc;
 	u8 v, i;
diff --git a/drivers/dpll/sit9531x/core.h b/drivers/dpll/sit9531x/core.h
index 19efff5112a3..1ed20354f94d 100644
--- a/drivers/dpll/sit9531x/core.h
+++ b/drivers/dpll/sit9531x/core.h
@@ -310,6 +310,11 @@ int sit9531x_clear_notifications(struct sit9531x_dev *sitdev);
 /* ---- INTSYNC (inter-PLL synchronization) ---- */
 
 /* ---- Phase offset (TDC readback) ---- */
+int sit9531x_chan_routed_ref_read(struct sit9531x_dev *sitdev, u8 pll_idx,
+				  u8 *ref);
+int sit9531x_input_mon_fetch(struct sit9531x_dev *sitdev);
+int sit9531x_phase_offset_read(struct sit9531x_dev *sitdev, u8 pll_idx,
+			       s64 *phase_offset);
 
 /* ---- State helpers ---- */
 
diff --git a/drivers/dpll/sit9531x/dpll.c b/drivers/dpll/sit9531x/dpll.c
index 436e4b76a727..aab5a4f0f946 100644
--- a/drivers/dpll/sit9531x/dpll.c
+++ b/drivers/dpll/sit9531x/dpll.c
@@ -669,6 +669,151 @@ sit9531x_dpll_input_pin_prio_set(const struct dpll_pin *pin, void *pin_priv,
 	return 0;
 }
 
+/*
+ * sit9531x_dpll_input_pin_phase_offset_get - phase offset of a reference
+ *
+ * What this reports, and what it deliberately does not:
+ *
+ * The ABI defines the attribute as the phase difference between the signal
+ * on a pin and its parent DPLL device, so this is the loop's own residual
+ * error, sampled with the loop closed.  On a locked DPLL it therefore
+ * trends small -- that is the measurement, not an artefact of it.  The
+ * documentation describes the reported value as one that may be averaged
+ * over prior measurements, which suits a closed-loop residual and not a
+ * one-shot open-loop capture; the core publishes whatever this callback
+ * returns, so the averaging, if any, would be this driver's to do.
+ *
+ * The chip can also measure the reference against the local oscillator
+ * with the outer loop's correction frozen, which is a different quantity
+ * and the one the documented phase-difference procedure produces.  That
+ * needs the digital loop filter held (and, on the 1PPS PLL, the automatic
+ * phase- and frequency-lock helpers held off), which leaves the PLL
+ * undisciplined until it is released.  A netlink read must not do that,
+ * so that measurement is not offered here at all; it belongs to a caller
+ * that can own the freeze and restore it.
+ *
+ * Precondition, which this callback cannot create: the TDC compares
+ * against a signal the PLL drives, so a PLL driving no output with its
+ * zero-delay buffer off has nothing to measure.  SiTime clock
+ * engineering confirms this is a property of the hardware, not of
+ * SiTime's TDC measurement procedure, which satisfies it by mapping a
+ * spare output and restarting the PLL -- side effects that do not belong
+ * in a getter, so a reading taken in that state is simply not meaningful.
+ *
+ * Non-selected pins and a PLL with no programmed divider report zero
+ * rather than an error: the DPLL core propagates any error from this
+ * callback and fails the whole pin dump with it.  The core has no per-pin
+ * "no data" for phase offset, as it has -ENODATA for the fractional
+ * frequency offset, so it is a value or no callback at all.
+ */
+static int
+sit9531x_dpll_input_pin_phase_offset_get(const struct dpll_pin *pin,
+					 void *pin_priv,
+					 const struct dpll_device *dpll,
+					 void *dpll_priv, s64 *phase_offset,
+					 struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	bool drives = false;
+	s64 offset;
+	u8 routed, i;
+	int rc;
+
+	mutex_lock(&sitdev->multiop_lock);
+
+	/*
+	 * The on-chip TDC is a per-PLL resource that always measures the
+	 * phase difference between the VCO and the PLL's currently
+	 * selected reference; it cannot be pointed at an arbitrary input,
+	 * so an input that is not the active reference reports 0 rather
+	 * than the active reference's value.
+	 *
+	 * The sample needs both: the PLL tracking this pin as the poll last
+	 * saw it (locked, outer loop running, not frozen), and the device
+	 * still feeding it this pin, read now -- the device moves on its
+	 * own, and a cache up to a poll period old could attribute a live
+	 * measurement to the pin the PLL used to be fed.  The device is read
+	 * again after the sample for the same reason: it can switch during
+	 * the dozen transfers the sample takes.
+	 *
+	 * The TDC also compares against a signal the PLL drives, so a PLL
+	 * with no routed, driving output has nothing to measure and reports
+	 * 0 like any other pin without a reading.  Output state is never
+	 * polled, so a mute or unmute whose read-back failed is read
+	 * through here first, as the output's own getter does, rather than
+	 * taken from a cache that was left describing the state before it.
+	 */
+	for (i = 0; i < sitdev->info->num_outputs; i++) {
+		if (!sitdev->out[i].routed ||
+		    sitdev->out[i].pll_idx != sitdpll->id)
+			continue;
+		if (sitdev->out[i].state_stale) {
+			rc = sit9531x_output_state_refresh(sitdev, i);
+			if (rc) {
+				mutex_unlock(&sitdev->multiop_lock);
+				NL_SET_ERR_MSG(extack,
+					       "Output mute state could not be read back");
+				return rc;
+			}
+		}
+		if (sitdev->out[i].enabled)
+			drives = true;
+	}
+
+	/*
+	 * The lane's signal is read live as well: a loss since the last poll
+	 * makes the device fall back on its own, and a sample taken then
+	 * would be credited to a pin the PLL is no longer on.
+	 */
+	rc = sit9531x_input_mon_fetch(sitdev);
+	if (rc) {
+		mutex_unlock(&sitdev->multiop_lock);
+		NL_SET_ERR_MSG(extack,
+			       "Failed to read the input clock monitors");
+		return rc;
+	}
+
+	if (!drives ||
+	    !sit9531x_dpll_selection_active(sitdev, sitdpll, dpin->id)) {
+		mutex_unlock(&sitdev->multiop_lock);
+		*phase_offset = 0;
+		return 0;
+	}
+
+	rc = sit9531x_chan_routed_ref_read(sitdev, sitdpll->id, &routed);
+	if (!rc && routed == dpin->id) {
+		rc = sit9531x_phase_offset_read(sitdev, sitdpll->id, &offset);
+		if (!rc)
+			rc = sit9531x_chan_routed_ref_read(sitdev, sitdpll->id,
+							   &routed);
+		if (!rc && routed != dpin->id)
+			rc = -ENODATA;
+	} else if (!rc) {
+		rc = -ENODATA;
+	}
+	mutex_unlock(&sitdev->multiop_lock);
+
+	/*
+	 * -ENODATA means no reading: the PLL has no known VCO rate, or the
+	 * device moved the PLL off this pin around the sample.  Report 0 so a
+	 * full pin-get dump does not fail over it.  Every other errno,
+	 * -ENODEV from a vanished adapter included, is a failure.
+	 */
+	if (rc == -ENODATA) {
+		*phase_offset = 0;
+		return 0;
+	}
+	if (rc) {
+		NL_SET_ERR_MSG(extack, "TDC phase readback failed");
+		return rc;
+	}
+
+	*phase_offset = offset;
+	return 0;
+}
+
 static const struct dpll_pin_ops sit9531x_dpll_input_pin_ops = {
 	.direction_get		= sit9531x_dpll_input_pin_direction_get,
 	.frequency_get		= sit9531x_dpll_input_pin_frequency_get,
@@ -677,6 +822,7 @@ static const struct dpll_pin_ops sit9531x_dpll_input_pin_ops = {
 	.operstate_on_dpll_get	= sit9531x_dpll_input_pin_operstate_on_dpll_get,
 	.prio_get		= sit9531x_dpll_input_pin_prio_get,
 	.prio_set		= sit9531x_dpll_input_pin_prio_set,
+	.phase_offset_get	= sit9531x_dpll_input_pin_phase_offset_get,
 };
 
 /*
@@ -693,6 +839,7 @@ static const struct dpll_pin_ops sit9531x_dpll_input_pin_norate_ops = {
 	.operstate_on_dpll_get	= sit9531x_dpll_input_pin_operstate_on_dpll_get,
 	.prio_get		= sit9531x_dpll_input_pin_prio_get,
 	.prio_set		= sit9531x_dpll_input_pin_prio_set,
+	.phase_offset_get	= sit9531x_dpll_input_pin_phase_offset_get,
 };
 
 /*
diff --git a/drivers/dpll/sit9531x/regs.h b/drivers/dpll/sit9531x/regs.h
index 7c41111dca20..1891679698e2 100644
--- a/drivers/dpll/sit9531x/regs.h
+++ b/drivers/dpll/sit9531x/regs.h
@@ -284,6 +284,28 @@
 #define SIT9531X_PLL_REG_DIVN_NUM		0x32  /* 4 bytes (0x32-0x35) */
 #define SIT9531X_PLL_REG_DIVN_DEN		0x38  /* 4 bytes (0x38-0x3B) */
 
+/*
+ * Signal pathway debug readback -- PLL page.  Dig_Sys_ReadCode selects
+ * which point of the pathway is tapped, Dig_Sys_WriteCode carries the
+ * modifiers for that read, Dig_Sys_read7..read0 hold the sampled bytes
+ * and a read of the debug status data register latches a sample.  The
+ * TDC phase measurement is one tap among several, reached through read
+ * code 69.
+ */
+#define SIT9531X_PLL_REG_DBG_READ_CODE	0xB3
+#define SIT9531X_PLL_REG_DBG_WRITE_CODE	0xB4
+#define SIT9531X_DBG_LOW_FREQ_CLK_BIT	BIT(7)
+#define SIT9531X_PLL_REG_DBG_DATA_0		0xB5  /* [7:0] */
+#define SIT9531X_PLL_REG_DBG_DATA_1		0xB6  /* [15:8] */
+#define SIT9531X_PLL_REG_DBG_DATA_2		0xB7  /* [23:16] */
+#define SIT9531X_PLL_REG_DBG_DATA_3		0xB8  /* [31:24] */
+#define SIT9531X_PLL_REG_DBG_DATA_4		0xB9  /* [34:32] + sign */
+
+/* Read code of the TDC phase tap, and the sign bit of its sample */
+#define SIT9531X_DBG_READ_CODE_TDC		69
+#define SIT9531X_TDC_SIGN_BIT		3
+#define SIT9531X_TDC_MAG_HI_MASK	GENMASK(2, 0)
+
 /* DIVN is carried as fixed point, in steps of 1e-12 of a whole divider */
 #define SIT9531X_DIVN_SCALE		1000000000000ULL
 
-- 
2.39.2 (Apple Git-143)

[PATCH net-next v12 12/12] dpll: sit9531x: model the inter-PLL sync net as a pair of pins

[Ali Rouhi]

From: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>

The device has an internal net by which one PLL can drive the others: the
source PLL puts its output on it, and any other PLL can select it as a
reference instead of an external input.  The two ends are nothing alike --
one is driven, the other is selected -- so they are two pins rather than
one: an output pin on the source and an input pin on each destination.

That keeps each pin honest about what its state means.  The source pin
reports whether this PLL is the one driving the net, and setting it takes
the net over or gives it up; a destination pin reports whether its PLL has
selected the net, and behaves like any other selectable input.  A single
pin would have had to answer both questions at once and could only have
been right about one of them.

A destination pin whose net no PLL drives reports no signal, as an
external input that lost its clock does.  The driver takes the net as
driven when it enabled the source itself or found that configuration
already in place.  The net has no signal monitor, and a loaded profile
can drive it with a configuration of its own, so a PLL the device feeds
from the net and holds locked also counts as the net carrying a signal.
A source that failed to take the net over, or whose configuration the
scan found only partly in place, is recorded as a partial owner, so a
retry re-runs the enable instead of being refused as busy; giving the
net up restores the global enable only while the net is still
configured, and the restore is latched as every other write to that
register is.  A failed request that moved the owner is announced.
Ownership and the output mutes are read back from the part on resume.

Signed-off-by: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
Assisted-by: LLM
Signed-off-by: Ali Rouhi <arouhi@sitime.com>
---
 drivers/dpll/sit9531x/core.c | 414 ++++++++++++++++++++++++++++++++++-
 drivers/dpll/sit9531x/core.h |   7 +
 drivers/dpll/sit9531x/dpll.c | 409 +++++++++++++++++++++++++++++++++-
 drivers/dpll/sit9531x/regs.h |   3 +
 4 files changed, 823 insertions(+), 10 deletions(-)

diff --git a/drivers/dpll/sit9531x/core.c b/drivers/dpll/sit9531x/core.c
index fbac70787ada..c2d6fbd0363f 100644
--- a/drivers/dpll/sit9531x/core.c
+++ b/drivers/dpll/sit9531x/core.c
@@ -3027,6 +3027,381 @@ int sit9531x_clear_notifications(struct sit9531x_dev *sitdev)
 	return 0;
 }
 
+/*
+ * Close the debug window on a PLL's EXT page.  The key register opens
+ * every debug register on that page while it holds the unlock value.
+ */
+static int sit9531x_intsync_debug_lock(struct sit9531x_dev *sitdev, u8 ext_page)
+{
+	return sit9531x_write_u8(sitdev,
+				 SIT9531X_REG(ext_page, SIT9531X_PLL_REG_DEBUG),
+				 SIT9531X_PLL_DEBUG_LOCK);
+}
+
+/*
+ * INTSYNC configuration register values.
+ * These are written to the source PLL's EXT page to enable/disable
+ * inter-PLL synchronization (lock frequency PLL to phase PLL).
+ */
+struct sit9531x_intsync_reg {
+	u8 offset;
+	u8 en_val;
+	u8 dis_val;
+};
+
+static const struct sit9531x_intsync_reg intsync_config[] = {
+	{ 0x2D, 0x02, 0x00 },
+	{ 0x50, 0x08, 0x00 },
+	{ 0x51, 0x04, 0x00 },
+	{ 0x54, 0x02, 0x00 },
+	{ 0x55, 0x28, 0x20 },
+	{ 0x5C, 0x0F, 0x00 },
+	{ 0x5D, 0xFF, 0x00 },
+	{ 0x6C, 0xDD, 0x00 },
+};
+
+int sit9531x_intsync_src_detect(struct sit9531x_dev *sitdev)
+{
+	s8 src = -1, partial = -1;
+	u8 global;
+	u8 pll, ext_page;
+	int rc, ret, n_en, n_dis;
+	unsigned int i;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	rc = sit9531x_read_u8(sitdev, SIT9531X_REG_INTSYNC_GLOBAL, &global);
+	if (rc)
+		return rc;
+
+	if (!(global & BIT(SIT9531X_INTSYNC_EN_BIT))) {
+		sitdev->intsync_src = -1;
+		sitdev->intsync_partial = false;
+		return 0;
+	}
+
+	for (pll = 0; pll < SIT9531X_NUM_PLLS; pll++) {
+		ext_page = SIT9531X_PLL_EXT_PAGE(pll);
+
+		/*
+		 * These are debug registers, which the enable and disable
+		 * sequences only touch with the EXT page's debug window
+		 * open; read them the same way.
+		 */
+		rc = sit9531x_write_u8(sitdev,
+				       SIT9531X_REG(ext_page,
+						    SIT9531X_PLL_REG_DEBUG),
+				       SIT9531X_PLL_DEBUG_UNLOCK);
+		if (rc)
+			return rc;
+
+		n_en = 0;
+		n_dis = 0;
+		for (i = 0; i < ARRAY_SIZE(intsync_config); i++) {
+			u16 reg;
+			u8 val;
+
+			reg = SIT9531X_REG(ext_page, intsync_config[i].offset);
+
+			rc = sit9531x_read_u8(sitdev, reg, &val);
+			if (rc)
+				break;
+			if (val == intsync_config[i].en_val)
+				n_en++;
+			else if (val == intsync_config[i].dis_val)
+				n_dis++;
+		}
+
+		ret = sit9531x_intsync_debug_lock(sitdev, ext_page);
+		if (!rc)
+			rc = ret;
+		if (rc)
+			return rc;
+
+		if (n_en == ARRAY_SIZE(intsync_config)) {
+			/*
+			 * Only one PLL can drive the net.  If a second
+			 * one matches, the registers are not describing
+			 * a state this driver put the device in, so say
+			 * so rather than pick silently.
+			 */
+			if (src < 0)
+				src = pll;
+			else
+				dev_warn(sitdev->dev,
+					 "PLL%c also matches the INTSYNC source pattern; keeping PLL%c\n",
+					 'A' + pll, 'A' + src);
+		} else if (n_en && n_dis &&
+			   n_en + n_dis == ARRAY_SIZE(intsync_config) &&
+			   partial < 0) {
+			/*
+			 * Every register holds one of the two patterns and both
+			 * occur: the residue of an enable or a disable that
+			 * stopped part way, and nothing a profile writes.
+			 */
+			partial = pll;
+		}
+	}
+
+	/*
+	 * An enable or a disable that stopped part way leaves a PLL holding
+	 * a mix of the two patterns.  Treat it as the owner, so that another
+	 * PLL cannot be enabled on top of the leftover configuration, but
+	 * record that it is partial: a repeated connect on that PLL must run
+	 * the enable again rather than take the PLL for configured, and a
+	 * repeated disconnect runs the disable again.
+	 */
+	sitdev->intsync_partial = src < 0 && partial >= 0;
+	if (sitdev->intsync_partial) {
+		dev_warn(sitdev->dev,
+			 "PLL%c holds a partial INTSYNC source configuration\n",
+			 'A' + partial);
+		src = partial;
+	}
+
+	sitdev->intsync_src = src;
+
+	return 0;
+}
+
+static int __sit9531x_intsync_disable(struct sit9531x_dev *sitdev,
+				      u8 src_pll_idx, bool restore);
+
+/*
+ * sit9531x_intsync_enable - enable inter-PLL synchronization
+ * @src_pll_idx: source (frequency) PLL index (0-3)
+ *
+ * Enables INTSYNC global bit, unlocks the source PLL's EXT page
+ * debug registers, writes configuration, and triggers a small
+ * update on the source PLL.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+int sit9531x_intsync_enable(struct sit9531x_dev *sitdev, u8 src_pll_idx)
+{
+	u8 ext_page, val;
+	int rc, lock_rc;
+	unsigned int i;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (src_pll_idx >= SIT9531X_NUM_PLLS)
+		return -EINVAL;
+
+	ext_page = SIT9531X_PLL_EXT_PAGE(src_pll_idx);
+
+	rc = sit9531x_read_u8(sitdev, SIT9531X_REG_INTSYNC_GLOBAL, &val);
+	if (rc)
+		return rc;
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_INTSYNC_GLOBAL,
+			       val | BIT(SIT9531X_INTSYNC_EN_BIT));
+	if (rc)
+		return rc;
+
+	/* Small update on Page 0 */
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_GLOBAL_UPDATE,
+			       SIT9531X_SMALL_UPDATE_CMD);
+	usleep_range(1000, 2000);
+	if (rc)
+		goto relock_err;
+
+	/* Unlock debug on EXT page */
+	rc = sit9531x_write_u8(sitdev,
+			       SIT9531X_REG(ext_page,
+					    SIT9531X_PLL_REG_DEBUG),
+			       SIT9531X_PLL_DEBUG_UNLOCK);
+	if (rc)
+		goto relock_err;
+
+	for (i = 0; i < ARRAY_SIZE(intsync_config); i++) {
+		rc = sit9531x_write_u8(sitdev,
+				       SIT9531X_REG(ext_page,
+						    intsync_config[i].offset),
+				       intsync_config[i].en_val);
+		if (rc)
+			goto relock_err;
+	}
+
+	/* Small update on source PLL */
+	rc = sit9531x_pll_small_update(sitdev, src_pll_idx);
+	if (rc)
+		goto relock_err;
+
+	rc = 0;
+	goto relock;
+
+relock_err:
+	sit9531x_intsync_debug_lock(sitdev, ext_page);
+	goto err_disable;
+
+relock:
+	/*
+	 * Close the EXT page debug window the sequence opened.  Nothing
+	 * else writes the key back, so leaving it open would keep the block
+	 * unlocked for as long as the device runs.  The net is driven by
+	 * now, though, so a failure here must not read as a failed enable:
+	 * the caller would then not record the owner of a net that is
+	 * driven.
+	 */
+	lock_rc = sit9531x_intsync_debug_lock(sitdev, ext_page);
+	if (lock_rc)
+		dev_warn(sitdev->dev,
+			 "PLL%c: INTSYNC enabled but the debug window was left open: %d\n",
+			 'A' + src_pll_idx, lock_rc);
+
+	return rc;
+
+err_disable:
+	/*
+	 * The global enable is already set at this point.  The caller only
+	 * records the source PLL when this function succeeds, so nothing
+	 * else will ever clear the bit: undo it here rather than leave the
+	 * net asserted with a half-written EXT page.  The disable must not
+	 * put the bit back when it fails part way, as it does for a
+	 * disconnect: here the bit is what the rollback set out to clear,
+	 * and restoring it would leave the net asserted with no PLL
+	 * matching the source pattern, which no owner on record would ever
+	 * clear.
+	 */
+	{
+		int rollback_rc;
+
+		rollback_rc = __sit9531x_intsync_disable(sitdev, src_pll_idx,
+							 false);
+		if (rollback_rc)
+			dev_warn(sitdev->dev,
+				 "INTSYNC rollback failed after enable error: %d (original %d)\n",
+				 rollback_rc, rc);
+	}
+
+	return rc;
+}
+
+/*
+ * The disable sequence.  @restore says whether a failure before the EXT
+ * page holds the disable pattern puts the global enable back, which a
+ * disconnect wants (see restore_global below) and the rollback of a
+ * failed enable does not.
+ */
+static int __sit9531x_intsync_disable(struct sit9531x_dev *sitdev,
+				      u8 src_pll_idx, bool restore)
+{
+	u8 ext_page, val;
+	int rc, lock_rc;
+	unsigned int i;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (src_pll_idx >= SIT9531X_NUM_PLLS)
+		return -EINVAL;
+
+	ext_page = SIT9531X_PLL_EXT_PAGE(src_pll_idx);
+
+	rc = sit9531x_read_u8(sitdev, SIT9531X_REG_INTSYNC_GLOBAL, &val);
+	if (rc)
+		return rc;
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_INTSYNC_GLOBAL,
+			       val & ~BIT(SIT9531X_INTSYNC_EN_BIT));
+	if (rc)
+		goto restore_global;
+
+	/* Small update on Page 0 */
+	rc = sit9531x_write_u8(sitdev, SIT9531X_REG_GLOBAL_UPDATE,
+			       SIT9531X_SMALL_UPDATE_CMD);
+	usleep_range(1000, 2000);
+	if (rc)
+		goto restore_global;
+
+	/* Unlock debug on EXT page */
+	rc = sit9531x_write_u8(sitdev,
+			       SIT9531X_REG(ext_page,
+					    SIT9531X_PLL_REG_DEBUG),
+			       SIT9531X_PLL_DEBUG_UNLOCK);
+	if (rc)
+		goto restore_global;
+
+	for (i = 0; i < ARRAY_SIZE(intsync_config); i++) {
+		rc = sit9531x_write_u8(sitdev,
+				       SIT9531X_REG(ext_page,
+						    intsync_config[i].offset),
+				       intsync_config[i].dis_val);
+		if (rc)
+			goto restore_global;
+	}
+
+	/*
+	 * Small update on source PLL.  The global enable is latched off and
+	 * every register holds the disable value by now, so the net is not
+	 * driven whether or not this latch went through.  Putting the bit
+	 * back for a failure here would describe the net as driven with no
+	 * PLL matching the source pattern: the detector would record no
+	 * owner, and nothing would ever clear the bit.
+	 */
+	rc = sit9531x_pll_small_update(sitdev, src_pll_idx);
+
+	goto relock;
+
+restore_global:
+	/*
+	 * The global enable was cleared first, so a failure here leaves the
+	 * EXT page still holding the enable pattern with nothing pointing
+	 * at it: the source detector keys on the global bit, would report
+	 * the net as unowned, and a retry of the disable would then
+	 * short-circuit.  Put the bit back so the state stays one the
+	 * driver can describe and the request can be repeated.
+	 */
+	if (restore &&
+	    !sit9531x_read_u8(sitdev, SIT9531X_REG_INTSYNC_GLOBAL, &val) &&
+	    !sit9531x_write_u8(sitdev, SIT9531X_REG_INTSYNC_GLOBAL,
+			       val | BIT(SIT9531X_INTSYNC_EN_BIT))) {
+		/*
+		 * Every write of the global enable, here and in SiTime's
+		 * sequences, is followed by the page-0 small update that
+		 * applies it.  Without it the bit would sit pending until
+		 * an unrelated commit through the same update register
+		 * applied it, re-asserting the net over a half-written
+		 * EXT page with nobody having asked.
+		 */
+		sit9531x_write_u8(sitdev, SIT9531X_REG_GLOBAL_UPDATE,
+				  SIT9531X_SMALL_UPDATE_CMD);
+		usleep_range(1000, 2000);
+	}
+
+relock:
+	/*
+	 * Close the EXT page debug window the sequence opened.  After a
+	 * disable that took effect, a failure here is a warning, for the
+	 * same reason as in sit9531x_intsync_enable().
+	 */
+	lock_rc = sit9531x_intsync_debug_lock(sitdev, ext_page);
+	if (lock_rc) {
+		if (rc)
+			dev_warn(sitdev->dev,
+				 "PLL%c: debug window left open: %d\n",
+				 'A' + src_pll_idx, lock_rc);
+		else
+			dev_warn(sitdev->dev,
+				 "PLL%c: INTSYNC disabled but the debug window was left open: %d\n",
+				 'A' + src_pll_idx, lock_rc);
+	}
+
+	return rc;
+}
+
+/*
+ * sit9531x_intsync_disable - disable inter-PLL synchronization
+ * @src_pll_idx: source (frequency) PLL index (0-3)
+ *
+ * Clears INTSYNC global bit, writes disable values to the source
+ * PLL's EXT page, and triggers a small update.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+int sit9531x_intsync_disable(struct sit9531x_dev *sitdev, u8 src_pll_idx)
+{
+	return __sit9531x_intsync_disable(sitdev, src_pll_idx, true);
+}
+
 /**
  * sit9531x_phase_offset_read - read phase difference via TDC
  * @sitdev:	device pointer
@@ -3678,6 +4053,15 @@ static int sit9531x_dev_state_fetch(struct sit9531x_dev *sitdev)
 		return rc;
 	}
 
+	mutex_lock(&sitdev->multiop_lock);
+	rc = sit9531x_intsync_src_detect(sitdev);
+	mutex_unlock(&sitdev->multiop_lock);
+	if (rc) {
+		dev_err(sitdev->dev,
+			"Failed to detect INTSYNC source: %d\n", rc);
+		return rc;
+	}
+
 	for (i = 0; i < sitdev->info->num_outputs; i++) {
 		bool clamped;
 		s32 phase_ps;
@@ -4418,13 +4802,13 @@ static bool sit9531x_dpll_pin_is_registrable(struct sit9531x_dpll *sitdpll,
 		if (index == SIT9531X_MAX_INPUTS)
 			return true;
 		if (index == SIT9531X_INTSYNC_PIN_ID)
-			return false;
+			return true;
 
 		return sit9531x_input_pin_is_registrable(sitdev, index);
 	}
 
 	if (index == SIT9531X_INTSYNC_OUT_PIN_ID)
-		return false;
+		return true;
 
 	if (index >= sitdev->info->num_outputs)
 		return false;
@@ -4860,8 +5244,34 @@ static int sit9531x_suspend(struct device *dev)
 static int sit9531x_resume(struct device *dev)
 {
 	struct sit9531x_dev *sitdev = dev_get_drvdata(dev);
+	int rc;
+	u8 i;
 
 	sit9531x_page_cache_drop(sitdev);
+
+	/*
+	 * A part that lost power across suspend comes back with its
+	 * profile's INTSYNC routing and output mutes, not with what the
+	 * caches say, and the poll watches neither.  Read them back here;
+	 * a cache that cannot be read is left for the getter's read-through.
+	 * Nothing races this: the poll is parked and the IRQ disabled.
+	 */
+	mutex_lock(&sitdev->multiop_lock);
+	rc = sit9531x_intsync_src_detect(sitdev);
+	if (rc)
+		dev_warn(sitdev->dev,
+			 "INTSYNC source not re-detected on resume: %d\n", rc);
+	for (i = 0; i < sitdev->info->num_outputs; i++) {
+		rc = sit9531x_output_state_refresh(sitdev, i);
+		if (rc) {
+			dev_warn(sitdev->dev,
+				 "Output %u mute state not read on resume: %d\n",
+				 i, rc);
+			sitdev->out[i].state_stale = true;
+		}
+	}
+	mutex_unlock(&sitdev->multiop_lock);
+
 	if (sitdev->irq > 0)
 		enable_irq(sitdev->irq);
 	kthread_queue_delayed_work(sitdev->kworker, &sitdev->work, 0);
diff --git a/drivers/dpll/sit9531x/core.h b/drivers/dpll/sit9531x/core.h
index 1ed20354f94d..a5b343033a41 100644
--- a/drivers/dpll/sit9531x/core.h
+++ b/drivers/dpll/sit9531x/core.h
@@ -211,6 +211,9 @@ struct sit9531x_chan {
  *			I2C client), 0 if no IRQ is wired
  * @intsync_src:	PLL index currently sourcing inter-PLL
  *			synchronization (INTSYNC), or -1 when disabled
+ * @intsync_partial:	@intsync_src holds only part of the source
+ *			configuration, left by an enable or a disable
+ *			that stopped part way
  * @irq_ack_fails:	consecutive failures to acknowledge the
  *			notification latches from the interrupt handler
  * @fvco_band_warned:	bit per PLL whose Fref * DIVN has been reported as
@@ -248,6 +251,7 @@ struct sit9531x_dev {
 
 	/* Inter-PLL synchronization state */
 	s8			intsync_src;
+	bool			intsync_partial;
 
 };
 
@@ -308,6 +312,9 @@ int sit9531x_output_phase_adjust_set(struct sit9531x_dev *sitdev,
 int sit9531x_clear_notifications(struct sit9531x_dev *sitdev);
 
 /* ---- INTSYNC (inter-PLL synchronization) ---- */
+int sit9531x_intsync_enable(struct sit9531x_dev *sitdev, u8 src_pll_idx);
+int sit9531x_intsync_disable(struct sit9531x_dev *sitdev, u8 src_pll_idx);
+int sit9531x_intsync_src_detect(struct sit9531x_dev *sitdev);
 
 /* ---- Phase offset (TDC readback) ---- */
 int sit9531x_chan_routed_ref_read(struct sit9531x_dev *sitdev, u8 pll_idx,
diff --git a/drivers/dpll/sit9531x/dpll.c b/drivers/dpll/sit9531x/dpll.c
index aab5a4f0f946..4c86ee9e7980 100644
--- a/drivers/dpll/sit9531x/dpll.c
+++ b/drivers/dpll/sit9531x/dpll.c
@@ -27,6 +27,20 @@ static bool sit9531x_dpll_is_input_pin(const struct sit9531x_dpll_pin *pin)
 	return pin->dir == DPLL_PIN_DIRECTION_INPUT;
 }
 
+static bool
+sit9531x_dpll_is_intsync_pin(const struct sit9531x_dpll_pin *pin)
+{
+	return sit9531x_dpll_is_input_pin(pin) &&
+	       pin->id == SIT9531X_INTSYNC_PIN_ID;
+}
+
+static bool
+sit9531x_dpll_is_intsync_src_pin(const struct sit9531x_dpll_pin *pin)
+{
+	return !sit9531x_dpll_is_input_pin(pin) &&
+	       pin->id == SIT9531X_INTSYNC_OUT_PIN_ID;
+}
+
 static bool
 sit9531x_dpll_is_xo_pin(const struct sit9531x_dpll_pin *pin)
 {
@@ -311,6 +325,59 @@ sit9531x_dpll_selection_state_get(struct sit9531x_dev *sitdev,
 		*state = DPLL_PIN_STATE_DISCONNECTED;
 }
 
+/*
+ * Does the device feed a locked PLL from the INTSYNC net?
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static bool sit9531x_dpll_intsync_tracked(struct sit9531x_dev *sitdev)
+{
+	const struct sit9531x_chan *chan;
+	u8 pll;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	for (pll = 0; pll < SIT9531X_NUM_PLLS; pll++) {
+		chan = sit9531x_chan_state_get(sitdev, pll);
+		if (chan->routed_ref == SIT9531X_INTSYNC_PIN_ID &&
+		    chan->locked && !chan->ho_freeze)
+			return true;
+	}
+
+	return false;
+}
+
+/*
+ * Does a selection-role pin carry a signal?  A physical input has the
+ * device's LOS monitor; the INTSYNC net has no monitor, and what stands in
+ * for one is the driver's record of a PLL driving it.  A partial source
+ * configuration does not count: the source pin reports it as no
+ * connection, and the net is not confirmed driven.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static bool
+sit9531x_dpll_selection_no_signal(struct sit9531x_dev *sitdev, u8 pin_id)
+{
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (pin_id == SIT9531X_INTSYNC_PIN_ID) {
+		/*
+		 * The driver knows the net is driven when it enabled the
+		 * source itself or found the configuration it would have
+		 * written.  A profile can drive the net with a configuration
+		 * of its own; then a PLL the device feeds from the net and
+		 * holds locked is the evidence that the net carries a signal.
+		 */
+		if (sitdev->intsync_src >= 0 && !sitdev->intsync_partial)
+			return false;
+		return !sit9531x_dpll_intsync_tracked(sitdev);
+	}
+
+	return pin_id < sitdev->info->num_inputs &&
+	       sit9531x_ref_state_get(sitdev, pin_id)->los;
+}
+
 /*
  * Is this the reference the PLL is tracking now?  See the S && L && !N
  * predicate in the pin-state contract.  This is also what gates the
@@ -334,11 +401,10 @@ sit9531x_dpll_selection_active(struct sit9531x_dev *sitdev,
 
 	/*
 	 * Fed to the PLL is not locked to: the device names the source it
-	 * routes, and a lane that lost its signal is one the PLL is about
+	 * routes, and a source that lost its signal is one the PLL is about
 	 * to be moved off, whatever the lock bit still says.
 	 */
-	if (pin_id < sitdev->info->num_inputs &&
-	    sit9531x_ref_state_get(sitdev, pin_id)->los)
+	if (sit9531x_dpll_selection_no_signal(sitdev, pin_id))
 		return false;
 
 	return true;
@@ -364,12 +430,17 @@ sit9531x_dpll_selection_operstate_get(struct sit9531x_dev *sitdev,
 		return;
 	}
 
+	/*
+	 * Standby is a qualified source the PLL is not using.  A net nobody
+	 * drives is no more that than a lane in LOS is.
+	 */
+	if (sit9531x_dpll_selection_no_signal(sitdev, pin_id)) {
+		*operstate = DPLL_PIN_OPERSTATE_NO_SIGNAL;
+		return;
+	}
+
 	if (pin_id < sitdev->info->num_inputs) {
 		ref = sit9531x_ref_state_get(sitdev, pin_id);
-		if (ref->los) {
-			*operstate = DPLL_PIN_OPERSTATE_NO_SIGNAL;
-			return;
-		}
 		if (ref->qual_fail) {
 			*operstate = DPLL_PIN_OPERSTATE_QUAL_FAILED;
 			return;
@@ -869,8 +940,325 @@ sit9531x_dpll_output_pin_direction_get(const struct dpll_pin *pin,
 				       enum dpll_pin_direction *direction,
 				       struct netlink_ext_ack *extack);
 
+/*
+ * Does this PLL drive the INTSYNC net with a complete configuration?
+ * What the source pin reports as CONNECTED.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+static bool
+sit9531x_dpll_intsync_src_connected(const struct sit9531x_dev *sitdev,
+				    const struct sit9531x_dpll *sitdpll)
+{
+	return sitdev->intsync_src == sitdpll->id && !sitdev->intsync_partial;
+}
+
+static int
+sit9531x_dpll_intsync_src_state_on_dpll_get(const struct dpll_pin *pin,
+					    void *pin_priv,
+					    const struct dpll_device *dpll,
+					    void *dpll_priv,
+					    enum dpll_pin_state *state,
+					    struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+
+	mutex_lock(&sitdev->multiop_lock);
+	if (sit9531x_dpll_intsync_src_connected(sitdev, sitdpll))
+		*state = DPLL_PIN_STATE_CONNECTED;
+	else
+		*state = DPLL_PIN_STATE_DISCONNECTED;
+	mutex_unlock(&sitdev->multiop_lock);
+
+	return 0;
+}
+
+/*
+ * sit9531x_dpll_intsync_src_state_on_dpll_set - drive INTSYNC from a PLL
+ *
+ *   CONNECTED    -> this PLL drives the INTSYNC net
+ *   DISCONNECTED -> stop driving INTSYNC if this PLL drives it
+ *
+ * SELECTABLE is rejected: driving the net is an explicit output routing,
+ * not an automatic-selection candidate, matching the regular output pin.
+ */
+static int
+sit9531x_dpll_intsync_src_state_on_dpll_set(const struct dpll_pin *pin,
+					    void *pin_priv,
+					    const struct dpll_device *dpll,
+					    void *dpll_priv,
+					    enum dpll_pin_state state,
+					    struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	int rc = 0, detect_rc = 0;
+	bool changed = false;
+	bool was_connected, moved;
+	u8 hw_src;
+
+	mutex_lock(&sitdev->multiop_lock);
+
+	was_connected = sit9531x_dpll_intsync_src_connected(sitdev, sitdpll);
+
+	switch (state) {
+	case DPLL_PIN_STATE_CONNECTED:
+		/*
+		 * A partial configuration on this PLL is not a connection:
+		 * run the enable again so a retry after a failed one repairs
+		 * the device instead of reporting success over it.
+		 */
+		if (was_connected)
+			break;
+		if (sitdev->intsync_src >= 0 &&
+		    sitdev->intsync_src != sitdpll->id) {
+			NL_SET_ERR_MSG(extack,
+				       "INTSYNC is already sourced by another PLL");
+			rc = -EBUSY;
+			break;
+		}
+		/*
+		 * A PLL that already lists INTSYNC among its references must
+		 * not also drive it: the destination side refuses the mirror
+		 * of this, and without the check here the net could be routed
+		 * back into the PLL feeding it.
+		 */
+		hw_src = sit9531x_input_hw_src(SIT9531X_INTSYNC_PIN_ID);
+		if (sit9531x_input_prio_present(sitdev, sitdpll->id, hw_src)) {
+			NL_SET_ERR_MSG(extack,
+				       "PLL selects INTSYNC as a reference; it cannot drive it");
+			rc = -EBUSY;
+			break;
+		}
+		rc = sit9531x_intsync_enable(sitdev, sitdpll->id);
+		changed = true;
+		break;
+	case DPLL_PIN_STATE_DISCONNECTED:
+		if (sitdev->intsync_src != sitdpll->id)
+			break;
+		rc = sit9531x_intsync_disable(sitdev, sitdpll->id);
+		changed = true;
+		break;
+	default:
+		rc = -EINVAL;
+		break;
+	}
+
+	/*
+	 * Record what was done before confirming it, and only when this PLL
+	 * actually changed: the core forwards a request for the state the
+	 * pin is already in, and a DISCONNECTED on a PLL that never drove the
+	 * net must not erase the owner.  The refresh below leaves the cache
+	 * untouched when a read fails, and a cache that wrongly says nobody
+	 * drives the net would let a second PLL be configured to drive it.
+	 */
+	if (changed && !rc) {
+		sitdev->intsync_src = state == DPLL_PIN_STATE_CONNECTED ?
+				      sitdpll->id : -1;
+		sitdev->intsync_partial = false;
+	}
+
+	/*
+	 * Re-scan hardware after a transition so the cache follows a
+	 * partially failed enable or disable as closely as possible.
+	 */
+	if (changed)
+		detect_rc = sit9531x_intsync_src_detect(sitdev);
+	/*
+	 * A failed enable that the scan still finds on this PLL is partial
+	 * even when every register reads the enable pattern: the small
+	 * update that commits it may be the step that failed.  Mark it, so
+	 * a retried connect runs the enable again.
+	 *
+	 * When the scan itself failed, nothing says how far the enable and
+	 * its rollback got, and the net may be driven.  Record this PLL as
+	 * the partial owner rather than leave the cache saying nobody drives
+	 * the net, which would let a second PLL be configured on top of it.
+	 * A disconnect on this PLL runs the disable and a scan that settle
+	 * the record.
+	 */
+	if (changed && rc && state == DPLL_PIN_STATE_CONNECTED &&
+	    (detect_rc || sitdev->intsync_src == sitdpll->id)) {
+		sitdev->intsync_src = sitdpll->id;
+		sitdev->intsync_partial = true;
+	}
+	/*
+	 * The refresh only re-reads what the device now shows.  Failing
+	 * the request because that read hit a bus error would tell
+	 * userspace the enable did not happen when it did.
+	 */
+	if (detect_rc)
+		dev_warn(sitdev->dev,
+			 "INTSYNC source cache not refreshed: %d\n",
+			 detect_rc);
+
+	/*
+	 * What the pin reports may have moved although the request failed:
+	 * a disable that stopped at its last step leaves nothing driving
+	 * the net, a failed enable leaves a partial owner.  The core
+	 * notifies only a request that succeeded and the poll does not
+	 * watch this pin, so announce it here, as the output setter does.
+	 */
+	moved = sit9531x_dpll_intsync_src_connected(sitdev, sitdpll) !=
+		was_connected;
+
+	mutex_unlock(&sitdev->multiop_lock);
+
+	if (rc) {
+		struct dpll_pin *dpll_pin;
+
+		if (rc != -EBUSY && rc != -EINVAL && rc != -EOPNOTSUPP)
+			NL_SET_ERR_MSG(extack,
+				       "Failed to set INTSYNC source state");
+		/*
+		 * The core's lock is held here, as the helper requires.
+		 * Teardown clears the handle before it unregisters the pin;
+		 * see the output state setter.
+		 */
+		dpll_pin = READ_ONCE(dpin->dpll_pin);
+		if (moved && dpll_pin)
+			__dpll_pin_change_ntf(dpll_pin);
+	}
+
+	return rc;
+}
+
+static const struct dpll_pin_ops sit9531x_dpll_intsync_src_pin_ops = {
+	.direction_get		= sit9531x_dpll_output_pin_direction_get,
+	.state_on_dpll_get	= sit9531x_dpll_intsync_src_state_on_dpll_get,
+	.state_on_dpll_set	= sit9531x_dpll_intsync_src_state_on_dpll_set,
+};
+
 /* ---- INTSYNC destination (input) pin ---- */
 
+/*
+ * sit9531x_dpll_intsync_dst_state_on_dpll_get - INTSYNC reference state
+ *
+ * Selection role, so the contract above decides this exactly as it does
+ * for a physical input: the priority table is the eligibility record, and
+ * whether a source PLL happens to be driving the net right now is no more
+ * a state than a momentary LOS is on an external reference.  The one
+ * addition is that the PLL driving INTSYNC is never its own destination.
+ */
+static int
+sit9531x_dpll_intsync_dst_state_on_dpll_get(const struct dpll_pin *pin,
+					    void *pin_priv,
+					    const struct dpll_device *dpll,
+					    void *dpll_priv,
+					    enum dpll_pin_state *state,
+					    struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+
+	mutex_lock(&sitdev->multiop_lock);
+	if (sitdev->intsync_src == sitdpll->id)
+		*state = DPLL_PIN_STATE_DISCONNECTED;
+	else
+		sit9531x_dpll_selection_state_get(sitdev, sitdpll,
+						  SIT9531X_INTSYNC_PIN_ID,
+						  state);
+	mutex_unlock(&sitdev->multiop_lock);
+
+	return 0;
+}
+
+/*
+ * sit9531x_dpll_intsync_dst_state_on_dpll_set - lock a PLL to INTSYNC
+ *
+ * Selection role, so this accepts and refuses what a physical input does,
+ * CONNECTED included: the device pins no reference on request whichever
+ * source is asked for.  INTSYNC is an internal net with no physical
+ * receiver, so only the per-PLL priority table is touched; the source pin
+ * controls generation.
+ */
+static int
+sit9531x_dpll_intsync_dst_state_on_dpll_set(const struct dpll_pin *pin,
+					    void *pin_priv,
+					    const struct dpll_device *dpll,
+					    void *dpll_priv,
+					    enum dpll_pin_state state,
+					    struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	u8 hw_src = sit9531x_input_hw_src(SIT9531X_INTSYNC_PIN_ID);
+	int rc;
+
+	mutex_lock(&sitdev->multiop_lock);
+
+	switch (state) {
+	case DPLL_PIN_STATE_DISCONNECTED:
+		rc = sit9531x_input_prio_remove(sitdev, sitdpll->id, hw_src);
+		break;
+	case DPLL_PIN_STATE_CONNECTED:
+		NL_SET_ERR_MSG(extack,
+			       "Device selects its reference by priority; use selectable");
+		rc = -EOPNOTSUPP;
+		break;
+	case DPLL_PIN_STATE_SELECTABLE:
+		if (sitdev->intsync_src == sitdpll->id) {
+			NL_SET_ERR_MSG(extack,
+				       "PLL cannot lock to the INTSYNC it drives");
+			rc = -EINVAL;
+			break;
+		}
+		rc = sit9531x_input_prio_add(sitdev, sitdpll->id, hw_src);
+		break;
+	default:
+		rc = -EINVAL;
+		break;
+	}
+
+	mutex_unlock(&sitdev->multiop_lock);
+
+	if (rc == -ENOSPC)
+		NL_SET_ERR_MSG(extack,
+			       "Priority table is full of unique sources on this PLL");
+	else if (rc && rc != -EINVAL && rc != -EOPNOTSUPP)
+		NL_SET_ERR_MSG(extack, "Failed to set INTSYNC input state");
+
+	return rc;
+}
+
+static int
+sit9531x_dpll_intsync_dst_operstate_on_dpll_get(const struct dpll_pin *pin,
+						void *pin_priv,
+						const struct dpll_device *dpll,
+						void *dpll_priv,
+						enum dpll_pin_operstate *state,
+						struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+
+	mutex_lock(&sitdev->multiop_lock);
+	sit9531x_dpll_selection_operstate_get(sitdev, sitdpll,
+					      SIT9531X_INTSYNC_PIN_ID,
+					      state);
+	mutex_unlock(&sitdev->multiop_lock);
+
+	return 0;
+}
+
+/*
+ * Do not add .frequency_get / the generic input state getter here: the
+ * destination pin id is SIT9531X_INTSYNC_PIN_ID, one past the end of the
+ * ref[] array (INTSYNC is an internal net with no ref[] entry).  The ops
+ * below only ever key on chan[] and the priority table, never ref[id].
+ */
+static const struct dpll_pin_ops sit9531x_dpll_intsync_dst_pin_ops = {
+	.direction_get		= sit9531x_dpll_input_pin_direction_get,
+	.state_on_dpll_get	= sit9531x_dpll_intsync_dst_state_on_dpll_get,
+	.state_on_dpll_set	= sit9531x_dpll_intsync_dst_state_on_dpll_set,
+	.operstate_on_dpll_get	=
+		sit9531x_dpll_intsync_dst_operstate_on_dpll_get,
+	.prio_get		= sit9531x_dpll_input_pin_prio_get,
+	.prio_set		= sit9531x_dpll_input_pin_prio_set,
+};
+
 /*
  * XO (crystal oscillator) pin ops
  *
@@ -1197,8 +1585,13 @@ static const struct dpll_pin_ops sit9531x_dpll_output_pin_ops = {
 const struct dpll_pin_ops *
 sit9531x_dpll_pin_ops_get(const struct sit9531x_dpll_pin *pin)
 {
-	if (!sit9531x_dpll_is_input_pin(pin))
+	if (!sit9531x_dpll_is_input_pin(pin)) {
+		if (sit9531x_dpll_is_intsync_src_pin(pin))
+			return &sit9531x_dpll_intsync_src_pin_ops;
 		return &sit9531x_dpll_output_pin_ops;
+	}
+	if (sit9531x_dpll_is_intsync_pin(pin))
+		return &sit9531x_dpll_intsync_dst_pin_ops;
 	if (sit9531x_dpll_is_xo_pin(pin))
 		return &sit9531x_dpll_xo_pin_ops;
 	/*
diff --git a/drivers/dpll/sit9531x/regs.h b/drivers/dpll/sit9531x/regs.h
index 1891679698e2..601dafbb2179 100644
--- a/drivers/dpll/sit9531x/regs.h
+++ b/drivers/dpll/sit9531x/regs.h
@@ -312,6 +312,9 @@
 #define SIT9531X_PLL_REG_ACTIVE		0x02
 #define SIT9531X_PLL_ACTIVE_BIT		BIT(0)  /* PLL reached active state */
 
+/* PLL EXT page INTSYNC configuration registers */
+#define SIT9531X_PLL_EXT_PAGE(_idx)	(SIT9531X_PAGE_PLLA_EXT + (_idx))
+
 #define SIT9531X_PLL_STATUS_OUTER_DIS	BIT(5)
 
 /*
-- 
2.39.2 (Apple Git-143)