[PATCH v3 net-next 0/3] dpll: add SiTime SiT9531x DPLL clock driver

[Ali Rouhi <arouhi@sitime.com>]

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

The series contains 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/

Changes since v2:

  - Scale the reported netlink phase offset by DPLL_PHASE_OFFSET_DIVIDER.
    DPLL_A_PIN_PHASE_OFFSET carries 1/DPLL_PHASE_OFFSET_DIVIDER of a
    picosecond; the driver passed the raw TDC picosecond value straight
    through, so pin-get reported every reading a thousand times too small
    (a measured -9151 ps appeared as -9.151 ps).
  - Fix the kernel-doc of the state structs and getters (parameter names
    and missing descriptions) so the series is clean under kernel-doc.
  - Sync the cached PLL mode from the mode_set callback so a later
    mode_get returns the value just set instead of a stale cache.
  - Report a forced Hi-Z output as DPLL_PIN_STATE_DISCONNECTED so
    state-get reflects what the pin actually drives.
  - Manage the input pll_mask correctly: seed it from the hardware at
    probe and set it only after prio_add succeeds, so disabling an input
    shared by several DPLLs never cuts a reference still in use and a
    failed claim does not leak.
  - Commit the priority table even when a slot write returns an error,
    so a partial failure cannot strand the chip in the PRG_CMD
    programming state.
  - Read input priority from the chip's Page-1 priority table instead of
    a software default; pin-get previously reported priority 0 for every
    input.
  - Remove a DISCONNECTED input from the PLL priority table, not just the
    receiver enable bits, so automatic mode can no longer keep selecting
    it; reconnect re-adds it at the lowest priority.
  - Refcount an input shared by several DPLLs; the physical receiver is
    disabled only when the last DPLL releases it.
  - Split INTSYNC into a source (output) pin and a destination (input)
    pin so neither role overloads the other; the destination pin carries
    priority ops and is polled for autonomous state changes.
  - Expose the on-chip XO as a read-only DPLL_PIN_TYPE_INT_OSCILLATOR
    pin, and read its status from the XO clock monitor rather than an
    unrelated input-lane monitor.
  - Constrain output-pll-map per variant in the binding (SiT95317 limited
    to 8, SiT95316 requires all 12 when present) and default unspecified
    trailing entries to unmapped (0xff).
  - Acknowledge the notification latches inside the threaded IRQ handler
    so the IRQF_ONESHOT unmask cannot trigger an interrupt storm.
  - Deassert the reset GPIO with a boot delay before the first I2C access
    so a board powered up in reset does not NACK the first read.
  - Commit the phase-adjust write through the PRG_CMD/PHFL programming
    sequence so the programmed delay lands against a defined edge.
  - Program the pulse generator on an esync set; the embedded-sync marker
    was advertised but never emitted.
  - Restore the phase trigger source select after an output phase flush,
    including on the pulse-write failure path, so a hardware sync input
    is not left permanently hijacked.
  - Wrap the PULSE_CTRL register write in the PRG_CMD programming state so
    the pulse configuration latches standalone.
  - Leave the PRG_CMD programming state on any output-system write
    failure so the chip is not left with the output loops unlocked.
  - Fix the implicit fractional denominator in the DCO helpers (default
    2^32, 64-bit intermediates); reject out-of-range ppb.
  - Restore the other PLLs' DCO mask after dco_adjust so their autonomous
    tracking is not silently broken.
  - Init monitoring work before DPLL allocation so the error path does
    not cancel an uninitialized work.
  - Propagate the holdover-release error and clear pin->dpll_pin on the
    pin_get failure path so the free helper does not warn on an ERR_PTR.

Notes for reviewers (points raised in review that are intentional):

  - sit9531x_dco_adjust() and sit9531x_pll_sysref_mode_set() have no
    caller in this patch.  They are infrastructure for follow-up work
    (the DCO path pairs with a loop-bandwidth netlink attribute; SYSREF
    mode needs a new netlink op).  Kept because the helpers are
    non-trivial and removing them would require re-review when re-added.
  - dco_calc_outer(): the DIVN2 integer part is read from a 35-bit
    register; for low-frequency outer references the divn2_num product
    can exceed u64 when fracd_eff defaults to 2^32. The arithmetic is
    split so no intermediate overflows: divn2_num formation uses
    mul_u64_u64_div_u64() where needed, and the downstream ppb products
    already use 128-bit helpers.
  - The reset GPIO is intentionally never pulsed. The chip configuration
    is loaded from efuse or an NVM blob before probe, so a runtime reset
    would discard it; the line is only held deasserted to guarantee the
    chip is out of reset for I2C.
  - Automatic vs manual mode: on this chip automatic means the PLL tracks
    a reference (sync) and manual means free-run. There is no separate
    mode to turn off automatic input selection while still syncing (as
    zl3073x has); the closest analogue, sync with a manually pinned input
    (MANUAL_ACTIVE_SEL_PLL + man_in_sel), is documented in the code but
    not wired to a netlink op yet.

Tested on a SiT95316EBX board (I2C, 96 MHz XO): input enable/disable and
priority, input disconnect and reconnect, INTSYNC lock, output frequency
set (scope-verified), phase-adjust, esync pulse, and phase-offset
readback. checkpatch --strict is clean across the series.

Ali Rouhi (3):
  dt-bindings: vendor-prefixes: add SiTime Corporation
  dt-bindings: dpll: add SiTime SiT9531x clock generator
  dpll: add SiTime SiT9531x DPLL clock driver

 .../bindings/dpll/sitime,sit9531x.yaml        |  201 +
 .../devicetree/bindings/vendor-prefixes.yaml  |    2 +
 MAINTAINERS                                   |    7 +
 drivers/dpll/Kconfig                          |    1 +
 drivers/dpll/Makefile                         |    1 +
 drivers/dpll/sit9531x/Kconfig                 |   17 +
 drivers/dpll/sit9531x/Makefile                |    4 +
 drivers/dpll/sit9531x/core.c                  | 3609 +++++++++++++++++
 drivers/dpll/sit9531x/core.h                  |  388 ++
 drivers/dpll/sit9531x/dpll.c                  | 1580 ++++++++
 drivers/dpll/sit9531x/dpll.h                  |   87 +
 drivers/dpll/sit9531x/prop.c                  |  415 ++
 drivers/dpll/sit9531x/prop.h                  |   39 +
 drivers/dpll/sit9531x/regs.h                  |  419 ++
 14 files changed, 6770 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/dpll/sitime,sit9531x.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

--
2.43.0

This email message and any attachments are for the sole use of the intended recipient and contain proprietary and/or confidential information that may be privileged or otherwise protected from disclosure. Any unauthorized review, use, disclosure, copying or distribution of the information included in this message and any attachment is prohibited and may be unlawful. If you are not an intended recipient, please contact the sender by reply email and permanently delete and destroy the original message and any attachments, and any printouts or copies of the message and attachments to the original message. Thank you.