From: Ali Rouhi <arouhi@sitime.com>
To: Jakub Kicinski <kuba@kernel.org>
Cc: "jiri@resnulli.us" <jiri@resnulli.us>,
"vadim.fedorenko@linux.dev" <vadim.fedorenko@linux.dev>,
"arkadiusz.kubalewski@intel.com" <arkadiusz.kubalewski@intel.com>,
"ivecera@redhat.com" <ivecera@redhat.com>,
"pabeni@redhat.com" <pabeni@redhat.com>,
"robh@kernel.org" <robh@kernel.org>,
"krzk+dt@kernel.org" <krzk+dt@kernel.org>,
"conor+dt@kernel.org" <conor+dt@kernel.org>,
"cjubran@nvidia.com" <cjubran@nvidia.com>,
"Oleg.Zadorozhnyi@devoxsoftware.com"
<Oleg.Zadorozhnyi@devoxsoftware.com>,
"prabhakar.mahadev-lad.rj@bp.renesas.com"
<prabhakar.mahadev-lad.rj@bp.renesas.com>,
"devicetree@vger.kernel.org" <devicetree@vger.kernel.org>,
"netdev@vger.kernel.org" <netdev@vger.kernel.org>,
"linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>
Subject: Re: [PATCH net-next v15 11/13] dpll: sit9531x: add support to adjust output phase
Date: Thu, 19 Nov 2026 21:20:20 +0000 [thread overview]
Message-ID: <20261119212014.13180-8-arouhi@sitime.com> (raw)
In-Reply-To: <20261117021822.2220376-1-kuba@kernel.org>
On Mon, 16 Nov 2026 18:18:22 -0800, Jakub Kicinski wrote:
> > The range advertised to the core is +/-1 ms at 1 ps granularity. The
> > driver writes only positive delays, so an advance is held as the
> > complementary delay within the output period. The delay is applied by
> > the PLL's phase flush, which restarts the divider phase of every output
> > the PLL drives, and a rate change re-times a programmed delay in the
> > same programming window.
>
> [Severity: Low]
> Does "restarts the divider phase of every output the PLL drives" cover
> every case? When the profile has PHFL off (CONFIG47 bit 7 clear),
> sit9531x_output_phase_flush() does a full PLL restart instead:
>
> if (!(phfl & SIT9531X_PLL_CONFIG47_PHFL_EN)) {
> rc = sit9531x_write_pll_u8(sitdev, pll_idx,
> SIT9531X_PLL_REG_DIRECTIVES,
> SIT9531X_PLL_DIRECTIVE_RESTART);
> fired = !rc;
> goto out;
> }
>
> On those profiles, any phase-adjust request that changes the delay bytes
> restarts the whole PLL. So does every poll or removal retry of a pending
> flush.
>
> The code comment documents this fallback. Could the commit message
> mention it too?
Yes, the commit message will say it: on a configuration with the flush
off the dividers are realigned by restarting the PLL, as the reference
sequence does, and that is also what a retried flush does.
> [Severity: Medium]
> The commit message covers the delay split, the advertised range and the
> advance folding. Should it also describe the deferred retry logic this
> patch adds?
>
> The previous patch ("dpll: sit9531x: implement output pin state on a
> DPLL") already declared flush_pending, flush_ctrl_pending, flush_ctrl,
> flush_arm_pending, flush_armed, retime_pending and retime_ps in core.h,
> but nothing in core.c used them.
>
> This patch adds sit9531x_phase_flush_undo(),
> sit9531x_phase_flush_undo_retry(), sit9531x_flush_retry() and
> sit9531x_retime_retry(). It calls them from
> sit9531x_dev_chan_states_update() and sit9531x_dev_stop().
>
> This also changes the existing rate-change path. Before this patch, a
> failed flush in sit9531x_output_freq_set() was logged and ignored. Now a
> failed flush sets chan->flush_pending, and so does a failed commit after
> the divider write landed. The poll or the unbind path then fires the
> flush later, which is a full PLL restart when PHFL is off.
>
> sit9531x_retime_retry() also calls sit9531x_output_phase_adjust_set()
> from the poll and at removal. That enters PRG_CMD, opening the output
> loops and waiting 100 ms in sit9531x_prg_commit(), and then flushes. None
> of this needs a user request.
Agreed on both. The message now describes the retries, and the pending
fields move to the patch that first uses them. A delay alone now takes
the small update, so its retry no longer opens the output loops.
> > rc = sit9531x_write_u8(sitdev, SIT9531X_REG_GPIO_FUNC_CTRL1,
> > ctrl | SIT9531X_DIVO_PHASE_TRIG);
> > -
> > -restore:
> > - ret = sit9531x_write_u8(sitdev, SIT9531X_REG_GPIO_FUNC_CTRL1, orig);
> > + fired = !rc;
>
> [Severity: Medium]
> Should fired also depend on the TRIG-low write? regs.h describes the
> flush as the whole pulse ("pulsing DIVO_PHASE_TRIG high then low
> flushes"). The low write only happens later, in
> sit9531x_phase_flush_undo():
>
> if (ctrl_back) {
> rc = sit9531x_write_close(sitdev, SIT9531X_REG_GPIO_FUNC_CTRL1,
> ctrl);
> sitdev->flush_ctrl_pending = !!rc;
>
> If that write fails, the undo still re-arms PHFL_ON_DEMAND_EN on the
> parked PLLs and disarms the target PLL, while TRIG may still be high.
> chan->flush_pending is already cleared because fired is true.
>
> When sit9531x_phase_flush_undo_retry() later gets the low write through,
> can the pulse complete with the wrong PLLs armed? The parked PLLs would
> get their dividers restarted and the target would not, yet the driver
> would record the target as realigned. This depends on whether the
> hardware acts on the falling edge or on the full pulse.
Correct for a failed write of the trigger low. The fix keeps the
enables, and the flush recorded as pending, until the trigger is low; it
is postponed with the other error-path changes.
> > + rc = sit9531x_get_fvco(sitdev, sitdev->out[out_idx].pll_idx, &fvco);
> > + if (rc)
> > + return rc;
>
> [Severity: Medium]
> Should this path check sit9531x_fvco_in_band() as the setter does?
> sit9531x_get_fvco() warns once about an out-of-band rate but still
> returns success. sit9531x_output_phase_adjust_set() refuses that case:
>
> /* Fref * DIVN outside the VCO band is not the rate the PLL runs at. */
> if (!sit9531x_fvco_in_band(pll_idx, fvco)) {
>
> Here the same Fvco is used to compute ps and t_out_ps, to choose between
> advance and delay, and to set beyond.
>
> The result is cached in out->phase_adj and phase_armed at probe, in the
> getter and in the ntf path. At the end of the series it is also cached on
> resume.
>
> For a PLL fed from another PLL, wouldn't the reported delay differ from
> the real edge? phase_armed would then also drive the re-time decision in
> sit9531x_output_freq_set().
Same answer as for the frequency getter in the frequency patch: the read
paths report the value computed from Fref * DIVN and the log names the
PLL once, the write paths refuse, and deriving the reference of a PLL
fed from another PLL is the follow-up that removes the case.
> > + if (ps > SIT9531X_OUT_PHASE_ADJ_MAX_PS &&
> > + t_out_ps - ps <= SIT9531X_OUT_PHASE_ADJ_MAX_PS) {
> > + *phase_ps = -(s64)(t_out_ps - ps);
> > + return 0;
> > + }
> > + }
>
> [Severity: Medium]
> Do the encoder and this decoder agree on the sign of an advance?
> sit9531x_output_phase_encode() stores an advance of -X as the delay
> T_out - X and reports the request's sign:
>
> if (phase_norm_ps < 0)
> *phase_adj = abs_ps ? -(s32)(t_out_ps - abs_ps) : 0;
>
> This read path returns a negative value only when the positive decode is
> above SIT9531X_OUT_PHASE_ADJ_MAX_PS. That never happens for an output of
> 1 kHz or faster.
>
> Take a 10 MHz output from a 5 GHz VCO (T_out = 100000 ps) and a request
> of -1000 ps. Encode writes 495 + 2 cycles (99000 ps) and caches -1000.
> This function then decodes 99000 and returns +99000 with beyond false.
>
> Any path that sets phase_stale replaces the cached -1000 with +99000 on
> the next re-read: the getter, the ntf path, or the start of
> sit9531x_output_freq_set(). The failure branches of freq_set and
> phase_adjust_set set phase_stale. So does the resume re-read added later
> in the series in "dpll: sit9531x: model the inter-PLL sync line as a pair
> of pins". DPLL_A_PIN_PHASE_ADJUST would then jump from -1000 to 99000
> with no hardware change.
>
> After that, sit9531x_output_freq_set() re-times from
> held = out->phase_adj. A change to 25 MHz (T = 40000 ps) then programs
> 19000 ps instead of the intended 39000 ps.
>
> Doesn't that contradict the core.h kerneldoc for phase_adj ("with the
> requested sign")? The code is the same at the end of the series.
Agreed, that was a real disagreement. Both paths now report the stored
delay in the form nearer to zero: a delay up to half the output period,
an advance beyond it. A request of -1000 ps reads back as -1000 ps from
the cache and from the registers, and a rate change re-times the same
value.
> > + /*
> > + * Skip the write if the quantized bytes are unchanged; a rewrite
> > + * restarts the divider phase of every output on the PLL.
> > + */
> > + same = !memcmp(old_bytes, new_bytes, sizeof(new_bytes)) &&
> > + !out->phase_stale;
>
> [Severity: Medium]
> Can a request that quantizes to zero still fail this raw-byte compare?
> sit9531x_output_phase_bytes_decode() treats register values 0, 1 and 2
> all as no delay:
>
> *coarse = (prg_coarse > SIT9531X_OUT_PRG_DIVO_CYCLES) ?
> prg_coarse - SIT9531X_OUT_PRG_DIVO_CYCLES : 0;
>
> But sit9531x_output_phase_bytes_build() always writes coarse 0 as
> register value 2:
>
> u64 prg_coarse = coarse + SIT9531X_OUT_PRG_DIVO_CYCLES;
>
> Suppose the profile leaves the block at 0. A request of +1 ps, which
> phase_gran = 1 allows, encodes to coarse 0, fine 0 and phase_adj 0, but
> the bytes still differ. This function then enters PRG_CMD, writes the
> bytes, waits in sit9531x_prg_commit() and flushes every divider on the
> PLL, for a delay that stays at 0.
>
> If the hardware does treat 0 and 2 differently, wouldn't outputs left at
> the profile's zero and outputs set to zero by the driver end up two VCO
> cycles apart, with both reported as 0 ps?
Correct, and intended. The output divider needs two clock edges to
settle, so the delay field carries a two-cycle offset and a value below
two does not give the requested delay. The first request rewrites the
configuration's 0 to 2, and later requests compare equal. Until then an
output the configuration leaves at 0 is reported as 0 ps.
> > + }
> > +
> > + /*
> > + * Restart the divider phase so the delay applies against a known edge.
> > + */
> > + rc = sit9531x_output_phase_flush(sitdev, pll_idx);
>
> [Severity: Medium]
> Should this flush be skipped while sitdev->loops_open is set? The poll
> and the removal path both avoid flushing into open loops:
>
> /*
> * A flush pulse sent into open loops may be lost when they
> * re-lock.
> */
> if (!sitdev->loops_open)
> sit9531x_flush_retry(sitdev, i);
>
> Consider this sequence:
>
> 1. sit9531x_output_freq_set() writes DIVO on PLL X.
> 2. sit9531x_prg_commit() fails LOOP_LOCK, which leaves loops_open = true
> and chan->flush_pending = true.
> 3. Before the next poll, a phase request arrives for any output of PLL X
> that quantizes to the bytes already programmed. With phase_gran = 1, a
> value 1 ps away from the cached one gets past the core's equality
> check.
>
> Then same == true, so the code skips PRG enter and commit and reaches
> sit9531x_output_phase_flush() with the loops still open.
>
> The flush sets fired, so flush_pending is cleared at the out label. Once
> the loops re-lock, the poll has nothing left to retry.
>
> Could this leave the dividers unaligned, with no warning, while the
> request returns 0?
Fixed in the next revision: the request re-locks the loops before it
flushes, and when the re-lock fails the flush stays pending for the
poll.
> > + dev_warn(sitdev->dev,
> > + "PLL%c: output dividers left unaligned\n",
> > + 'A' + i);
> > + }
> > mutex_unlock(&sitdev->multiop_lock);
> > }
>
> [Severity: Low]
> The undo retry and its warnings run before these retime and flush
> retries. Both retries reach sit9531x_output_phase_flush(), which:
>
> - parks the other armed PLLs
> - may arm pll_idx
> - selects the register trigger in GPIO_FUNC_CTRL1
>
> If its closing sit9531x_phase_flush_undo() fails here, it only records
> flush_arm_pending or flush_ctrl_pending. sit9531x_flush_retry() drops the
> return value:
>
> sit9531x_output_phase_flush(sitdev, pll_idx);
>
> Nothing after this point retries the undo or warns.
>
> Could the device be left at unbind with on-demand flush armed or parked
> against its profile, or with the register trigger selected, and none of
> the warnings from the earlier block printed?
>
> This is the same at the end of the series, where the code is in
> sit9531x_dev_pending_retry().
Fixed in the next revision: the removal path runs the undo retry and its
warnings after the re-time and flush retries.
> > + if (rc) {
> > + mutex_unlock(&sitdev->multiop_lock);
> > + NL_SET_ERR_MSG(extack,
> > + "Output delay could not be read back");
> > + return rc;
> > + }
>
> [Severity: Low]
> Should the extack message be set when rc is -ENODATA? That is what
> sit9531x_output_phase_read() returns when Fvco is unknown, and the dpll
> core treats it as an absent attribute. dpll_pin_phase_adj_set() goes on
> to call ops->phase_adjust_set():
>
> if (ret && ret != -ENODATA) {
>
> A successful set would then still carry "Output delay could not be read
> back" in the ACK. A pin-get would leave the attribute out but still set
> the message.
>
> The driver's phase_offset_get returns -ENODATA without a message.
Right, the message is no longer set when the readback returns -ENODATA.
> > + sitdev->out[dpin->id].phase_adj = phase_ps;
> > + sitdev->out[dpin->id].phase_armed = !beyond && phase_ps;
> > + sitdev->out[dpin->id].phase_stale = false;
> > + }
>
> [Severity: Medium]
> Is it intended to clear phase_stale here while out->retime_pending is
> still set? Say sit9531x_output_freq_set() fails after the new DIVO landed
> but before the re-timed bytes were written. It then does:
>
> } else if (retime && landed) {
> out->retime_ps = held;
> out->retime_pending = true;
> out->phase_stale = true;
>
> freq_set itself skips the re-read in that state:
>
> if (out->phase_stale && !out->retime_pending) {
>
> The getter reports the hardware readback V and clears phase_stale, but
> retime_pending stays set.
>
> If userspace then sends PIN_SET with phase-adjust = V,
> dpll_pin_phase_adj_set() sees an unchanged value and returns 0 without
> calling phase_adjust_set:
>
> if (!ret && phase_adj == old_phase_adj)
> return 0;
>
> phase_adjust_set is the only path that clears retime_pending.
>
> On the next poll, sit9531x_retime_retry() calls
> sit9531x_output_phase_adjust_set(sitdev, out_idx, out->retime_ps).
> Wouldn't that reprogram the delay to a value other than V, and restart
> the PLL's dividers, after userspace was told V is applied?
Fixed in the next revision: while a re-time is pending the getter
reports the cached delay, which is the value the retry programs, and
does not read the bytes of the old rate.
> > + * A profile delay on a slow output can exceed the s32 attribute; leave
> > + * it out.
> > + */
> > + if (phase_adj > S32_MAX)
> > + return -ENODATA;
> > + *phase_adjust = phase_adj;
>
> [Severity: Medium]
> Can this report values above the advertised phase_range.max?
> sit9531x_output_phase_read() sets beyond when ps is above
> SIT9531X_OUT_PHASE_ADJ_MAX_PS (1e9 ps) but still returns ps. Three paths
> cache it in out->phase_adj: sit9531x_dev_state_fetch(), the stale path
> above and the ntf path. This check only hides values above S32_MAX.
>
> Consider a profile delay above 1 ms on an output slower than 1 kHz, such
> as 1PPS. It would be reported as a PHASE_ADJUST between 1e9 and S32_MAX,
> while PHASE_ADJUST_MAX is 1e9. Writing that value back would be rejected
> by dpll_pin_phase_adj_set() as out of range.
Intended. The range bounds what can be requested; a delay loaded with
the configuration before the driver bound is state, and it is reported
as it is so that userspace can see it, and left out only when the s32
attribute cannot hold it. A request of 0 clears it.
> > + SIT9531X_OUT_PHASE_ADJ_MAX_PS;
> > + /*
> > + * The 30 ps fine step is not advertised; requests are rounded
> > + * to the nearest achievable delay.
> > + */
> > + props->dpll_props.phase_gran = 1;
>
> [Severity: Low]
> With phase_range at +/-1e9 ps and phase_gran = 1 on every output, every
> value passes the core's checks in dpll_pin_phase_adj_set().
> sit9531x_output_phase_encode() then folds the request modulo the output
> period and rounds it to VCO cycles plus 30 ps steps. The call returns
> success and a change notification follows.
>
> On a 10 MHz output, +150 ns is accepted and reads back as +50 ns.
>
> Is it intended that userspace has no way to learn the real step or the
> per-output period limit? zl3073x, for comparison, advertises its real
> granularity.
Intended. The grid is not a single step: one VCO cycle, which depends on
the PLL's rate, plus up to seven 30 ps steps, folded into an output
period that changes with the rate, and the pin properties are fixed at
registration. The driver programs the nearest point and reports the
realized value in a get and in the change notification. The commit
message will say this.
> > }
>
> [Severity: Low]
> This isn't a bug, but after this patch the comment further down in
> sit9531x_pin_props_get() is no longer accurate:
>
> /*
> * Read the divider into the cached output rate used by phase adjust;
> * -ENODATA is an unprogrammed divider or unknown VCO rate.
> */
>
> sit9531x_output_phase_adjust_set() and sit9531x_output_phase_read() both
> read DIVO directly and never use out->freq ("the cached rate is whole
> hertz"). Should the comment be updated?
Yes, corrected: phase adjust takes the period from the divider.
next prev parent reply other threads:[~2026-11-19 21:20 UTC|newest]
Thread overview: 36+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-10 20:26 [PATCH net-next v15 00/13] dpll: add SiTime SiT9531x DPLL clock driver Ali Rouhi
2026-11-10 20:26 ` [PATCH net-next v15 01/13] dpll: omit pin phase attributes the driver has no value for Ali Rouhi
2026-11-11 15:35 ` Ivan Vecera
2026-11-10 20:26 ` [PATCH net-next v15 02/13] dt-bindings: vendor-prefixes: add SiTime Corporation Ali Rouhi
2026-11-10 20:26 ` [PATCH net-next v15 03/13] dt-bindings: dpll: add SiTime SiT95316 clock generator Ali Rouhi
2026-11-17 2:18 ` Jakub Kicinski
2026-11-19 21:20 ` Ali Rouhi
2026-11-10 20:26 ` [PATCH net-next v15 04/13] dpll: add basic SiTime SiT9531x support Ali Rouhi
2026-11-17 2:18 ` Jakub Kicinski
2026-11-19 21:20 ` Ali Rouhi
2026-11-10 20:26 ` [PATCH net-next v15 05/13] dpll: sit9531x: read DPLL types and pin properties from system firmware Ali Rouhi
2026-11-17 2:18 ` Jakub Kicinski
2026-11-19 21:20 ` Ali Rouhi
2026-11-10 20:26 ` [PATCH net-next v15 06/13] dpll: sit9531x: register DPLL devices and pins Ali Rouhi
2026-11-17 2:18 ` Jakub Kicinski
2026-11-19 21:20 ` Ali Rouhi
2026-11-10 20:26 ` [PATCH net-next v15 07/13] dpll: sit9531x: implement input pin state on a DPLL Ali Rouhi
2026-11-10 20:26 ` [PATCH net-next v15 08/13] dpll: sit9531x: add support to get and set priority on input pins Ali Rouhi
2026-11-17 2:18 ` Jakub Kicinski
2026-11-19 21:20 ` Ali Rouhi
2026-11-10 20:26 ` [PATCH net-next v15 09/13] dpll: sit9531x: add support to get and set frequency on pins Ali Rouhi
2026-11-17 2:18 ` Jakub Kicinski
2026-11-19 21:20 ` Ali Rouhi
2026-11-10 20:26 ` [PATCH net-next v15 10/13] dpll: sit9531x: implement output pin state on a DPLL Ali Rouhi
2026-11-17 2:18 ` Jakub Kicinski
2026-11-19 21:20 ` Ali Rouhi
2026-11-10 20:26 ` [PATCH net-next v15 12/13] dpll: sit9531x: add support to get phase offset on the connected input pin Ali Rouhi
2026-11-17 2:18 ` Jakub Kicinski
2026-11-19 21:20 ` Ali Rouhi
2026-11-10 20:26 ` [PATCH net-next v15 11/13] dpll: sit9531x: add support to adjust output phase Ali Rouhi
2026-11-17 2:18 ` Jakub Kicinski
2026-11-19 21:20 ` Ali Rouhi [this message]
2026-11-10 20:26 ` [PATCH net-next v15 13/13] dpll: sit9531x: model the inter-PLL sync line as a pair of pins Ali Rouhi
2026-11-17 2:18 ` Jakub Kicinski
2026-11-19 21:20 ` Ali Rouhi
2026-11-17 9:27 ` [PATCH net-next v15 00/13] dpll: add SiTime SiT9531x DPLL clock driver Paolo Abeni
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261119212014.13180-8-arouhi@sitime.com \
--to=arouhi@sitime.com \
--cc=Oleg.Zadorozhnyi@devoxsoftware.com \
--cc=arkadiusz.kubalewski@intel.com \
--cc=cjubran@nvidia.com \
--cc=conor+dt@kernel.org \
--cc=devicetree@vger.kernel.org \
--cc=ivecera@redhat.com \
--cc=jiri@resnulli.us \
--cc=krzk+dt@kernel.org \
--cc=kuba@kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=netdev@vger.kernel.org \
--cc=pabeni@redhat.com \
--cc=prabhakar.mahadev-lad.rj@bp.renesas.com \
--cc=robh@kernel.org \
--cc=vadim.fedorenko@linux.dev \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox