Question/proposal for DPLL NCO (DCO) mode

Question/proposal for DPLL NCO (DCO) mode

[Ivan Vecera]

Hi all,

I am currently working on adding PTP clock support (PHC) to the ZL3073x
driver, and I would like to discuss an architectural addition to the
DPLL subsystem enum dpll_mode before sending the formal patch series.

To support IEEE 1588 PTP, the hardware DPLL must be decoupled from
tracking physical reference pins. Instead, its output frequency needs to
be continuously steered by a software PTP stack (e.g., linuxptp) using
the .adjfine() callback. In the industry, this specific hardware state
is widely known as NCO (Numerically Controlled Oscillator) or DCO
(Digitally Controlled Oscillator) mode.

Currently, the DPLL subsystem defines two modes in enum dpll_mode:

MANUAL: The user explicitly selects a physical input pin to track.

AUTOMATIC: The hardware automatically selects the best physical input 
pin based on priorities.

Neither of these accurately represents the NCO/DCO state, where physical
pins are ignored, and the loop is fully software-steered.

Without a dedicated mode, drivers are forced into "automagic"
workarounds. A driver might implicitly switch the hardware to NCO mode
in the background as soon as .adjfine() is called, while misreporting
its mode as MANUAL to the DPLL subsystem.

I strongly believe this hidden "automagic" behavior is a bad design. The
user-space should have full visibility and explicit control over what
the DPLL state machine is actually doing.

The Proposal:
I would like to propose adding a new mode: DPLL_MODE_NCO (or
DPLL_MODE_DCO, I am open to suggestions regarding the terminology).

The expected workflow would be explicit:
If a user wants to actively steer the DPLL frequency via software (for
PTP or other Time-over-Packet applications), they must explicitly set
the DPLL device to this mode via Netlink first. Only then will the
hardware accept frequency adjustments via .adjfine().

I would appreciate any feedback from the DPLL subsystem maintainers and
the community on this approach.

Thanks,
Ivan

Re: Question/proposal for DPLL NCO (DCO) mode

[Jiri Pirko]

Mon, Apr 20, 2026 at 01:42:29PM +0200, ivecera@redhat.com wrote:
>Hi all,
>
>I am currently working on adding PTP clock support (PHC) to the ZL3073x
>driver, and I would like to discuss an architectural addition to the
>DPLL subsystem enum dpll_mode before sending the formal patch series.
>
>To support IEEE 1588 PTP, the hardware DPLL must be decoupled from
>tracking physical reference pins. Instead, its output frequency needs to
>be continuously steered by a software PTP stack (e.g., linuxptp) using
>the .adjfine() callback. In the industry, this specific hardware state
>is widely known as NCO (Numerically Controlled Oscillator) or DCO
>(Digitally Controlled Oscillator) mode.
>
>Currently, the DPLL subsystem defines two modes in enum dpll_mode:
>
>MANUAL: The user explicitly selects a physical input pin to track.
>
>AUTOMATIC: The hardware automatically selects the best physical input pin
>based on priorities.
>
>Neither of these accurately represents the NCO/DCO state, where physical
>pins are ignored, and the loop is fully software-steered.

The manual/automatic mode is defining strategy/behaviour about how the
input pins are selected.

<header_quote>
 * enum dpll_mode - working modes a dpll can support, differentiates if and how
 *   dpll selects one of its inputs to syntonize with it
</header_quote>

You don't want to change the strategy. You just
don't want that/don't care. Why it make sense to add a mode then?

I was thinking exposing this over STATUS. We have:
UNLOCKED (free running)
LOCKED
LOCKED_HO_ACQ
HOLDOVER

So something maybe like SW_STEERED? But:

The problem is you need to do selection. Perhaps we can have a
"magic pin" to select for this :S ? We have pin of type
DPLL_PIN_TYPE_INT_OSCILLATOR already. Perhaps we can have
DPLL_PIN_TYPE_INT_NCO/NDO? It's a source.

Makes sense?


>
>Without a dedicated mode, drivers are forced into "automagic"
>workarounds. A driver might implicitly switch the hardware to NCO mode
>in the background as soon as .adjfine() is called, while misreporting
>its mode as MANUAL to the DPLL subsystem.
>
>I strongly believe this hidden "automagic" behavior is a bad design. The
>user-space should have full visibility and explicit control over what
>the DPLL state machine is actually doing.
>
>The Proposal:
>I would like to propose adding a new mode: DPLL_MODE_NCO (or
>DPLL_MODE_DCO, I am open to suggestions regarding the terminology).
>
>The expected workflow would be explicit:
>If a user wants to actively steer the DPLL frequency via software (for
>PTP or other Time-over-Packet applications), they must explicitly set
>the DPLL device to this mode via Netlink first. Only then will the
>hardware accept frequency adjustments via .adjfine().
>
>I would appreciate any feedback from the DPLL subsystem maintainers and
>the community on this approach.
>
>Thanks,
>Ivan
>

Re: Question/proposal for DPLL NCO (DCO) mode

[Ivan Vecera]

On 4/20/26 3:43 PM, Jiri Pirko wrote:
> Mon, Apr 20, 2026 at 01:42:29PM +0200, ivecera@redhat.com wrote:
>> Hi all,
>>
>> I am currently working on adding PTP clock support (PHC) to the ZL3073x
>> driver, and I would like to discuss an architectural addition to the
>> DPLL subsystem enum dpll_mode before sending the formal patch series.
>>
>> To support IEEE 1588 PTP, the hardware DPLL must be decoupled from
>> tracking physical reference pins. Instead, its output frequency needs to
>> be continuously steered by a software PTP stack (e.g., linuxptp) using
>> the .adjfine() callback. In the industry, this specific hardware state
>> is widely known as NCO (Numerically Controlled Oscillator) or DCO
>> (Digitally Controlled Oscillator) mode.
>>
>> Currently, the DPLL subsystem defines two modes in enum dpll_mode:
>>
>> MANUAL: The user explicitly selects a physical input pin to track.
>>
>> AUTOMATIC: The hardware automatically selects the best physical input pin
>> based on priorities.
>>
>> Neither of these accurately represents the NCO/DCO state, where physical
>> pins are ignored, and the loop is fully software-steered.
> 
> The manual/automatic mode is defining strategy/behaviour about how the
> input pins are selected.
> 
> <header_quote>
>   * enum dpll_mode - working modes a dpll can support, differentiates if and how
>   *   dpll selects one of its inputs to syntonize with it
> </header_quote>
> 
> You don't want to change the strategy. You just
> don't want that/don't care. Why it make sense to add a mode then?

It depends on the perspective. NCO is a selection strategy where the
DPLL does not lock onto an input reference (select nothing); instead,
its frequency is software-driven.

Btw. we’ve included DPLL_MODE_DETACHED in the documentation, which could
describe this use case.

But...

> I was thinking exposing this over STATUS. We have:
> UNLOCKED (free running)
> LOCKED
> LOCKED_HO_ACQ
> HOLDOVER
> 
> So something maybe like SW_STEERED? But:
> 
> The problem is you need to do selection. Perhaps we can have a
> "magic pin" to select for this :S ? We have pin of type
> DPLL_PIN_TYPE_INT_OSCILLATOR already. Perhaps we can have
> DPLL_PIN_TYPE_INT_NCO/NDO? It's a source.
> 
> Makes sense?

Yes, this makes sense from a selection standpoint, and I have to say I
like the idea. It also has an additional benefit: if we have an NCO pin
type, that pin's frequency can be used to configure the delta frequency
offset of the DPLL device itself.

I’ll proceed this way. Thanks for the advice!

Ivan