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

From: Ali Rouhi

Date: Thu Nov 19 2026 - 16:22:13 EST


On Mon, 16 Nov 2026 18:18:25 -0800, Jakub Kicinski wrote:

> > + if (rc == -ENODATA)
> > + dev_dbg(sitdev->dev,
> > + "PLL%c: Fvco unknown, skip TDC\n",
> > + 'A' + pll_idx);
> > + return rc;
> > + }
>
> [Severity: Medium]
> Can this scale the TDC code by an Fvco that the driver itself treats as
> wrong?
>
> For an out-of-band value, sit9531x_get_fvco() warns once per PLL and still
> returns 0:
>
> drivers/dpll/sit9531x/core.c:sit9531x_get_fvco() {
> ...
> /*
> * Outside the PLL's VCO band, Fref * DIVN is usually not the rate the
> * PLL runs at, as for a PLL fed from another PLL.
> */
> if (!sit9531x_fvco_in_band(pll_idx, *fvco) &&
> !(sitdev->fvco_band_warned & BIT(pll_idx))) {
> ...
> }
>
> return 0;
> }
>
> sit9531x_output_phase_adjust_set() and the output frequency setter reject
> an out-of-band Fvco through sit9531x_fvco_in_band(). This path has no such
> check.
>
> When a PLL's Fref * DIVN is out of band, would a phase offset scaled by the
> wrong Fvco be reported as a valid DPLL_A_PIN_PHASE_OFFSET? After the first
> warning there would be no indication at all. The kernel-doc above also
> promises "-ENODATA if Fvco is unknown".

Same answer as for the frequency and delay getters: the offset is scaled
by the Fvco the driver computes and the log names the PLL once; the
driver cannot tell a suspect Fvco from a VCO run outside the nominal
band. Deriving the reference of a PLL fed from another PLL is the
follow-up. The kernel-doc line is kept as it is, since -ENODATA is
returned for an unknown Fvco.

> > + rc = sit9531x_read_pll_u8(sitdev, pll_idx,
> > + SIT9531X_PLL_REG_DBG_STATUS_DATA,
> > + &v);
> > + if (rc)
> > + goto relock;
> > + }
>
> [Severity: Low]
> Should SIT9531X_PLL_REG_DBG_STATUS_ADDR be programmed before these reads?
>
> According to regs.h, the address register "selects the block the data
> register reports". Nothing writes it here, so the latch reads use the last
> address written. The only writer is sit9531x_chan_routed_ref_read(), which
> leaves SIT9531X_DBG_STATUS_ROUTED_SRC in place.
>
> In today's only caller, the first routed-ref read always runs just before
> this, so the state is predictable. Neither the kernel-doc nor regs.h
> mentions that dependency, though.
>
> If the Dig_Sys_read latch only advances for a specific status address,
> could DBG_DATA_0..4 hold a stale or unrelated sample here?

The documented procedure for the TDC reads the status data register
three times and does not write the status address; the sample comes from
the debug data registers of the tap the read code selects. The comment
at the reads now says the address is left unwritten.

> > + /* Per the register map the sign bit set means a positive offset. */
> > + tdc_signed = sign ? (s64)tdc_raw : -(s64)tdc_raw;
>
> [Severity: Medium]
> Does "positive" in the register map match the DPLL uAPI sign convention?
>
> Documentation/driver-api/dpll.rst defines DPLL_A_PIN_PHASE_OFFSET as:
>
> The negative value means that phase of signal on pin is earlier in time
> than dpll's signal. Positive value means that phase of signal on pin is
> later in time than signal of a dpll.
>
> Neither this comment nor SIT9531X_TDC_SIGN_BIT in regs.h says which signal
> the register map treats as leading. If positive there means the reference
> leads the feedback, every reported offset would have the opposite sign.
>
> Could the comment say which convention the hardware uses?

The sign bit is set when the reference edge comes first, and the uAPI
reports a pin earlier than the DPLL as negative, so v15 had the sign
inverted. The next revision negates it and states the convention in the
kernel-doc.

> > - * first and must hold sitdev->multiop_lock.
> > +/**
> > + * sit9531x_chan_routed_ref_read - read the reference the device feeds a PLL
> > + * @sitdev: device pointer
> > + * @pll_idx: PLL index (0-3)
> > + * @ref: logical input index, SIT9531X_INTSYNC_PIN_ID, or SIT9531X_REF_INVALID
>
> [Severity: Low]
> Should SIT9531X_MAX_INPUTS also be listed for @ref?
>
> sit9531x_hw_src_input() maps SIT9531X_PRIO_SRC_OCXO to SIT9531X_MAX_INPUTS,
> the XO slot. That value is not below info->num_inputs. A future caller of
> the newly exported helper could use it to index state sized by num_inputs.

Yes, added.

> > + sit9531x_dpll_unregister(sitdpll);
> > +
> > + sit9531x_dev_pending_retry(sitdev);
> > +
> > + return rc;
> > +}
>
> [Severity: Low]
> This isn't a bug, but the probe failure path changes here and the commit
> message doesn't mention it.
>
> Before this patch, err_unregister only unregistered the DPLLs. It now runs
> the former body of sit9531x_dev_stop(): priority table write-backs, forced
> holdover release, phase flush undo, output re-timing, sit9531x_prg_commit()
> and divider flushes.
>
> Would this fit better as a separate fix, or in the patch that added the
> pending-write machinery?
>
> Some other parts don't seem to belong here either:
>
> - The reworded comment above sit9531x_reselect() is unrelated to phase
> offset.
> - tap_pending was added in "dpll: sit9531x: add support to adjust output
> phase" with no user. Its companions tap_write_code, tap_read_code and
> key_pending only arrive in this patch.

Agreed on the three points: the commit message now says that the probe
failure path runs the same retries as removal, the comment rewording is
in the patch that adds the comment, and tap_pending is declared here
with its companions.

> >
> > +/*
> > + * Report the loop's residual phase error, sampled with the loop closed. The TDC
> > + * compares against a signal the PLL drives, so a PLL driving no output returns
> > + * -ENODATA.
> > + */
>
> [Severity: Medium]
> Is "sampled with the loop closed" actually enforced?
>
> The callback never checks sitdev->loops_open. sit9531x_prg_commit() sets
> it when the SIT9531X_LOOP_LOCK write fails on every try:
>
> sitdev->loops_open = !!rc2;
>
> The poll worker treats that as a known state: it retries the commit and
> skips flush pulses. Here, though, the decision to sample comes from
> sit9531x_dpll_selection_active(), which uses lock state cached at the last
> poll.
>
> Suppose prg_commit() fails during an output frequency, mute or delay change.
> Until the next poll, could the cache still report tracking, so the TDC is
> sampled with the loops open and reported as a residual phase error?

Agreed. The callback now returns -ENODATA while a failed programming
sequence has left the output loops open.

> > + if (rc) {
> > + mutex_unlock(&sitdev->multiop_lock);
> > + NL_SET_ERR_MSG(extack,
> > + "Failed to read the input clock monitors");
> > + return rc;
> > + }
>
> [Severity: Medium]
> Can a transient I2C error here end the whole system-wide pin dump?
>
> For the routed, tracking pin, this callback does live I2C on every pin GET,
> every pin DUMP and every pin change notification. That covers an optional
> output state refresh, two monitor fetches, two routed-ref reads and the
> full TDC sequence in sit9531x_phase_offset_read(). In total that is dozens
> of transfers under multiop_lock.
>
> The earlier patch "dpll: sit9531x: register DPLL devices and pins" caches
> status "so a netlink call does not become a burst of I2C transfers". This
> commit message doesn't mention moving away from that.
>
> Every I2C failure becomes a hard error. That includes failures in
> sit9531x_output_state_refresh() and sit9531x_input_mon_fetch(), which only
> decide whether the optional attribute is present.
>
> In sit9531x_phase_offset_read(), a failed tap restore or relock is already
> queued for retry, yet it still replaces a valid sample:
>
> ret = sit9531x_tap_restore(sitdev, pll_idx);
> if (ret)
> chan->tap_pending = true;
> if (ret && !rc)
> rc = ret;
>
> The core only tolerates -ENODATA:
>
> drivers/dpll/dpll_netlink.c:dpll_msg_add_phase_offset() {
> ...
> if (ret) {
> if (ret == -ENODATA)
> return 0;
> return ret;
> }
> ...
> }
>
> and dpll_nl_pin_get_dumpit() only carries on after -ENODEV:
>
> ret = dpll_cmd_pin_get_one(skb, pin, cb->extack);
> if (ret) {
> genlmsg_cancel(skb, hdr);
> if (ret == -ENODEV) {
> ret = 0;
> continue;
> }
> break;
> }
>
> Wouldn't a single I2C error on this device drop the pins of every other
> DPLL driver listed after it in the dump? It would also make
> dpll_pin_event_send() drop the notification. The driver's own comment
> already notes that "the core fails a whole pin dump if any callback
> returns an error".
>
> Should these cases return -ENODATA instead, at least once a valid sample
> has been taken?

Agreed. A sample that could not be taken is now an absent attribute: the
callback logs the error rate-limited and returns -ENODATA, so one bus
error no longer ends a dump or drops a notification. The offset stays
sampled on request, since a sample costs several dozen transfers per PLL
and the poll would pay that every period; the commit message will say
so.

> > + 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);
>
> [Severity: Medium]
> Can these routed-ref reads leave the PLL debug window unlocked without
> key_pending recording it?
>
> sit9531x_phase_offset_read() ends with:
>
> chan->key_pending = !!ret;
>
> so after a successful relock, key_pending is false. The second
> sit9531x_chan_routed_ref_read() then unlocks SIT9531X_PLL_REG_DEBUG again.
> If its final lock write fails all SIT9531X_CLOSE_TRIES, it only returns
> the error:
>
> relock:
> lock_rc = sit9531x_write_pll_close(sitdev, pll_idx,
> SIT9531X_PLL_REG_DEBUG,
> SIT9531X_PLL_DEBUG_LOCK);
>
> return rc ? rc : lock_rc;
>
> The first routed-ref read behaves the same way.
>
> In that case sit9531x_tap_back_retry() returns early:
>
> if (!chan->tap_pending && !chan->key_pending)
> return;
>
> So neither the poll worker nor sit9531x_tap_pending_retry() (on stop or
> probe failure) relocks the window. The only other closer is
> sit9531x_chan_state_fetch(), and it calls the routed-ref read only while
> the PLL is tracking.
>
> If the PLL then moves to holdover, free-run or OUTER_DIS, does the debug
> window stay open, even after the driver is removed?

Fixed in the next revision: the routed-reference read records a closing
write that failed, and the poll and the removal path retry it.

> > static const struct dpll_pin_ops sit9531x_dpll_input_pin_norate_manual_ops = {
> > .direction_get = sit9531x_dpll_input_pin_direction_get,
> > .state_on_dpll_get = sit9531x_dpll_input_pin_state_on_dpll_get,
> > .operstate_on_dpll_get = sit9531x_dpll_input_pin_operstate_on_dpll_get,
> > + .phase_offset_get = sit9531x_dpll_input_pin_phase_offset_get,
> > };
>
> [Severity: Low]
> What about the XO pin? The commit message says:
>
> Only the input the part feeds the PLL has an offset.
>
> but sit9531x_dpll_xo_pin_ops has no phase_offset_get:
>
> 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,
> };
>
> SIT9531X_PRIO_SRC_OCXO is a priority table source, and
> sit9531x_hw_src_input() maps it to SIT9531X_MAX_INPUTS, the XO pin id. So
> sit9531x_chan_routed_ref_read() can report the XO as routed, and a PLL
> tracking the OCXO never reports an offset.
>
> Is the XO meant to be excluded? If so, could the commit message say so and
> explain why the TDC doesn't apply to it?

Excluded on purpose, and the commit message now says so: the XO pin is
the frequency base of every PLL, not an input the loop is steered to.