DPLL¶

PLL - Phase Locked Loop is an electronic circuit which syntonizes clocksignal of a device with an external clock signal. Effectively enablingdevice to run on the same clock signal beat as provided on a PLL input.

DPLL - Digital Phase Locked Loop is an integrated circuit which inaddition to plain PLL behavior incorporates a digital phase detectorand may have digital divider in the loop. As a result, the frequency onDPLL’s input and output may be configurable.

Subsystem¶

The main purpose of dpll subsystem is to provide general interfaceto configure devices that use any kind of Digital PLL and could usedifferent sources of input signal to synchronize to, as well asdifferent types of outputs.The main interface is NETLINK_GENERIC based protocol with an eventmonitoring multicast group defined.

Device object¶

Single dpll device object means single Digital PLL circuit and bunch ofconnected pins.It reports the supported modes of operation and current status to theuser in response to thedo request of netlink commandDPLL_CMD_DEVICE_GET and list of dplls registered in the subsystemwithdump netlink request of the same command.Changing the configuration of dpll device is done withdo request ofnetlinkDPLL_CMD_DEVICE_SET command.A device handle isDPLL_A_ID, it shall be provided to get or setconfiguration of particular device in the system. It can be obtainedwith aDPLL_CMD_DEVICE_GETdump request oraDPLL_CMD_DEVICE_ID_GETdo request, where the one must provideattributes that result in single device match.

Pin object¶

A pin is amorphic object which represents either input or output, itcould be internal component of the device, as well as externallyconnected.The number of pins per dpll vary, but usually multiple pins shall beprovided for a single dpll device.Pin’s properties, capabilities and status is provided to the user inresponse todo request of netlinkDPLL_CMD_PIN_GET command.It is also possible to list all the pins that were registered in thesystem withdump request ofDPLL_CMD_PIN_GET command.Configuration of a pin can be changed bydo request of netlinkDPLL_CMD_PIN_SET command.Pin handle is aDPLL_A_PIN_ID, it shall be provided to get or setconfiguration of particular pin in the system. It can be obtained withDPLL_CMD_PIN_GETdump request orDPLL_CMD_PIN_ID_GETdorequest, where user provides attributes that result in single pin match.

Pin selection¶

In general, selected pin (the one which signal is driving the dplldevice) can be obtained fromDPLL_A_PIN_STATE attribute, and onlyone pin shall be inDPLL_PIN_STATE_CONNECTED state for any dplldevice.

Pin selection can be done either manually or automatically, dependingon hardware capabilities and active dpll device work mode(DPLL_A_MODE attribute). The consequence is that there aredifferences for each mode in terms of available pin states, as well asfor the states the user can request for a dpll device.

In manual mode (DPLL_MODE_MANUAL) the user can request or receiveone of following pin states:

• DPLL_PIN_STATE_CONNECTED - the pin is used to drive dpll device

• DPLL_PIN_STATE_DISCONNECTED - the pin is not used to drive dplldevice

In automatic mode (DPLL_MODE_AUTOMATIC) the user can request orreceive one of following pin states:

• DPLL_PIN_STATE_SELECTABLE - the pin shall be considered as validinput for automatic selection algorithm

• DPLL_PIN_STATE_DISCONNECTED - the pin shall be not considered asa valid input for automatic selection algorithm

In automatic mode (DPLL_MODE_AUTOMATIC) the user can only receivepin stateDPLL_PIN_STATE_CONNECTED once automatic selectionalgorithm locks a dpll device with one of the inputs.

Shared pins¶

A single pin object can be attached to multiple dpll devices.Then there are two groups of configuration knobs:

1. Set on a pin - the configuration affects all dpll devices pin isregistered to (i.e.,DPLL_A_PIN_FREQUENCY),

2. Set on a pin-dpll tuple - the configuration affects only selecteddpll device (i.e.,DPLL_A_PIN_PRIO,DPLL_A_PIN_STATE,DPLL_A_PIN_DIRECTION).

MUX-type pins¶

A pin can be MUX-type, it aggregates child pins and serves as a pinmultiplexer. One or more pins are registered with MUX-type instead ofbeing directly registered to a dpll device.Pins registered with a MUX-type pin provide user with additional nestedattributeDPLL_A_PIN_PARENT_PIN for each parent they were registeredwith.If a pin was registered with multiple parent pins, they behave like amultiple output multiplexer. In this case output of aDPLL_CMD_PIN_GET would contain multiple pin-parent nestedattributes with current state related to each parent, like:

'pin': [{{  'clock-id': 282574471561216,  'module-name': 'ice',  'capabilities': 4,  'id': 13,  'parent-pin': [  {'parent-id': 2, 'state': 'connected'},  {'parent-id': 3, 'state': 'disconnected'}  ],  'type': 'synce-eth-port'  }}]

Only one child pin can provide its signal to the parent MUX-type pin ata time, the selection is done by requesting change of a child pin stateon desired parent, with the use ofDPLL_A_PIN_PARENT nestedattribute. Example of netlinkset state on parent pin message format:

DPLL_A_PIN_ID	child pin id
DPLL_A_PIN_PARENT_PIN	nested attribute for requesting configurationrelated to parent pin
DPLL_A_PIN_PARENT_ID	parent pin id
DPLL_A_PIN_STATE	requested pin state on parent

Pin priority¶

Some devices might offer a capability of automatic pin selection mode(enumvalueDPLL_MODE_AUTOMATIC ofDPLL_A_MODE attribute).Usually, automatic selection is performed on the hardware level, whichmeans only pins directly connected to the dpll can be used for automaticinput pin selection.In automatic selection mode, the user cannot manually select a inputpin for the device, instead the user shall provide all directlyconnected pins with a priorityDPLL_A_PIN_PRIO, the device wouldpick a highest priority valid signal and use it to control the DPLLdevice. Example of netlinkset priority on parent pin message format:

DPLL_A_PIN_ID	configured pin id
DPLL_A_PIN_PARENT_DEVICE	nested attribute for requesting configurationrelated to parent dpll device
DPLL_A_PIN_PARENT_ID	parent dpll device id
DPLL_A_PIN_PRIO	requested pin prio on parent dpll

Child pin of MUX-type pin is not capable of automatic input pin selection,in order to configure active input of a MUX-type pin, the user needs torequest desired pin state of the child pin on the parent pin,as described in theMUX-typepins chapter.

Phase offset measurement and adjustment¶

Device may provide ability to measure a phase difference between signalson a pin and its parent dpll device. If pin-dpll phase offset measurementis supported, it shall be provided withDPLL_A_PIN_PHASE_OFFSETattribute for each parent dpll device. The reported phase offset may becomputed as the average of prior values and the current measurement, usingthe following formula:

wherecurr_avg is the current reported phase offset,prev_avg is thepreviously reported value,new_val is the current measurement, andN isthe averaging factor. Configured averaging factor value is provided withDPLL_A_PHASE_OFFSET_AVG_FACTOR attribute of a device and value change canbe requested with the same attribute withDPLL_CMD_DEVICE_SET command.

DPLL_A_PHASE_OFFSET_AVG_FACTOR

attr configured value of phase offsetaveraging factor

Device may also provide ability to adjust a signal phase on a pin.If pin phase adjustment is supported, minimal and maximal values andgranularity that pin handle shall be provided to the user onDPLL_CMD_PIN_GET respond withDPLL_A_PIN_PHASE_ADJUST_MIN,DPLL_A_PIN_PHASE_ADJUST_MAX andDPLL_A_PIN_PHASE_ADJUST_GRANattributes. Configured phase adjust value is provided withDPLL_A_PIN_PHASE_ADJUST attribute of a pin, and value change can berequested with the same attribute withDPLL_CMD_PIN_SET command.

DPLL_A_PIN_ID	configured pin id
DPLL_A_PIN_PHASE_ADJUST_GRAN	attr granularity of phase adjustment value
DPLL_A_PIN_PHASE_ADJUST_MIN	attr minimum value of phase adjustment
DPLL_A_PIN_PHASE_ADJUST_MAX	attr maximum value of phase adjustment
DPLL_A_PIN_PHASE_ADJUST	attr configured value of phaseadjustment on parent dpll device
DPLL_A_PIN_PARENT_DEVICE	nested attribute for requestingconfiguration on given parent dplldevice
DPLL_A_PIN_PARENT_ID	parent dpll device id
DPLL_A_PIN_PHASE_OFFSET	attr measured phase differencebetween a pin and parent dpll device

All phase related values are provided in pico seconds, which representstime difference between signals phase. The negative value means thatphase of signal on pin is earlier in time than dpll’s signal. Positivevalue means that phase of signal on pin is later in time than signal ofa dpll.

Phase adjust (also min and max) values are integers, but measured phaseoffset values are fractional with 3-digit decimal places and shell bedivided withDPLL_PIN_PHASE_OFFSET_DIVIDER to get integer part andmodulo divided to get fractional part.

Phase offset monitor¶

Phase offset measurement is typically performed against the current activesource. However, some DPLL (Digital Phase-Locked Loop) devices may offerthe capability to monitor phase offsets across all available inputs.The attribute and current feature state shall be included in the responsemessage of theDPLL_CMD_DEVICE_GET command for supported DPLL devices.In such cases, users can also control the feature using theDPLL_CMD_DEVICE_SET command by setting theenumdpll_feature_statevalues for the attribute.Once enabled the phase offset measurements for the input shall be returnedin theDPLL_A_PIN_PHASE_OFFSET attribute.

DPLL_A_PHASE_OFFSET_MONITOR

attr state of a feature

Embedded SYNC¶

Device may provide ability to use Embedded SYNC feature. It allowsto embed additional SYNC signal into the base frequency of a pin - a onespecial pulse of base frequency signal every time SYNC signal pulsehappens. The user can configure the frequency of Embedded SYNC.The Embedded SYNC capability is always related to a given base frequencyand HW capabilities. The user is provided a range of Embedded SYNCfrequencies supported, depending on current base frequency configured forthe pin.

DPLL_A_PIN_ESYNC_FREQUENCY	current Embedded SYNC frequency
DPLL_A_PIN_ESYNC_FREQUENCY_SUPPORTED	nest available Embedded SYNCfrequency ranges
DPLL_A_PIN_FREQUENCY_MIN	attr minimum value of frequency
DPLL_A_PIN_FREQUENCY_MAX	attr maximum value of frequency
DPLL_A_PIN_ESYNC_PULSE	pulse type of Embedded SYNC

Reference SYNC¶

The device may support the Reference SYNC feature, which allows the combinationof two inputs into a input pair. In this configuration, clock signalsfrom both inputs are used to synchronize the DPLL device. The higher frequencysignal is utilized for the loop bandwidth of the DPLL, while the lower frequencysignal is used to syntonize the output signal of the DPLL device. This featureenables the provision of a high-quality loop bandwidth signal from an externalsource.

A capable input provides a list of inputs that can be bound with to createReference SYNC. To control this feature, the user must request a desiredstate for a target pin: useDPLL_PIN_STATE_CONNECTED to enable orDPLL_PIN_STATE_DISCONNECTED to disable the feature. An input pin can bebound to only one other pin at any given time.

DPLL_A_PIN_REFERENCE_SYNC	nested attribute for providing info orrequesting configuration of the ReferenceSYNC feature
DPLL_A_PIN_ID	target pin id for Reference SYNC feature
DPLL_A_PIN_STATE	state of Reference SYNC connection

Configuration commands group¶

Configuration commands are used to get information about registereddpll devices (and pins), as well as set configuration of device or pins.As dpll devices must be abstracted and reflect real hardware,there is no way to add new dpll device via netlink from user space andeach device should be registered by its driver.

All netlink commands requireGENL_ADMIN_PERM. This is to preventany spamming/DoS from unauthorized userspace applications.

List of netlink commands with possible attributes¶

Constants identifying command types for dpll device uses aDPLL_CMD_ prefix and suffix according to command purpose.The dpll device related attributes use aDPLL_A_ prefix andsuffix according to attribute purpose.

DPLL_CMD_DEVICE_ID_GET	command to get device ID
DPLL_A_MODULE_NAME	attr module name of registerer
DPLL_A_CLOCK_ID	attr Unique Clock Identifier(EUI-64), as defined by theIEEE 1588 standard
DPLL_A_TYPE	attr type of dpll device

DPLL_CMD_DEVICE_GET	command to get device info ordump list of available devices
DPLL_A_ID	attr unique dpll device ID
DPLL_A_MODULE_NAME	attr module name of registerer
DPLL_A_CLOCK_ID	attr Unique Clock Identifier(EUI-64), as defined by theIEEE 1588 standard
DPLL_A_MODE	attr selection mode
DPLL_A_MODE_SUPPORTED	attr available selection modes
DPLL_A_LOCK_STATUS	attr dpll device lock status
DPLL_A_TEMP	attr device temperature info
DPLL_A_TYPE	attr type of dpll device

DPLL_CMD_DEVICE_SET	command to set dpll device config
DPLL_A_ID	attr internal dpll device index
DPLL_A_MODE	attr selection mode to configure

Constants identifying command types for pins uses aDPLL_CMD_PIN_ prefix and suffix according to command purpose.The pin related attributes use aDPLL_A_PIN_ prefix and suffixaccording to attribute purpose.

DPLL_CMD_PIN_ID_GET	command to get pin ID
DPLL_A_PIN_MODULE_NAME	attr module name of registerer
DPLL_A_PIN_CLOCK_ID	attr Unique Clock Identifier(EUI-64), as defined by theIEEE 1588 standard
DPLL_A_PIN_BOARD_LABEL	attr pin board label providedby registerer
DPLL_A_PIN_PANEL_LABEL	attr pin panel label providedby registerer
DPLL_A_PIN_PACKAGE_LABEL	attr pin package label providedby registerer
DPLL_A_PIN_TYPE	attr type of a pin

DPLL_CMD_PIN_GET	command to get pin info or dumplist of available pins
DPLL_A_PIN_ID	attr unique a pin ID
DPLL_A_PIN_MODULE_NAME	attr module name of registerer
DPLL_A_PIN_CLOCK_ID	attr Unique Clock Identifier(EUI-64), as defined by theIEEE 1588 standard
DPLL_A_PIN_BOARD_LABEL	attr pin board label providedby registerer
DPLL_A_PIN_PANEL_LABEL	attr pin panel label providedby registerer
DPLL_A_PIN_PACKAGE_LABEL	attr pin package label providedby registerer
DPLL_A_PIN_TYPE	attr type of a pin
DPLL_A_PIN_FREQUENCY	attr current frequency of a pin
DPLL_A_PIN_FREQUENCY_SUPPORTED	nested attr provides supportedfrequencies
DPLL_A_PIN_ANY_FREQUENCY_MIN	attr minimum value of frequency
DPLL_A_PIN_ANY_FREQUENCY_MAX	attr maximum value of frequency
DPLL_A_PIN_PHASE_ADJUST_GRAN	attr granularity of phaseadjustment value
DPLL_A_PIN_PHASE_ADJUST_MIN	attr minimum value of phaseadjustment
DPLL_A_PIN_PHASE_ADJUST_MAX	attr maximum value of phaseadjustment
DPLL_A_PIN_PHASE_ADJUST	attr configured value of phaseadjustment on parent device
DPLL_A_PIN_PARENT_DEVICE	nested attr for each parent devicethe pin is connected with
DPLL_A_PIN_PARENT_ID	attr parent dpll device id
DPLL_A_PIN_PRIO	attr priority of pin on thedpll device
DPLL_A_PIN_STATE	attr state of pin on the parentdpll device
DPLL_A_PIN_DIRECTION	attr direction of a pin on theparent dpll device
DPLL_A_PIN_PHASE_OFFSET	attr measured phase differencebetween a pin and parent dpll
DPLL_A_PIN_PARENT_PIN	nested attr for each parent pinthe pin is connected with
DPLL_A_PIN_PARENT_ID	attr parent pin id
DPLL_A_PIN_STATE	attr state of pin on the parentpin
DPLL_A_PIN_CAPABILITIES	attr bitmask of pin capabilities

DPLL_CMD_PIN_SET	command to set pins configuration
DPLL_A_PIN_ID	attr unique a pin ID
DPLL_A_PIN_FREQUENCY	attr requested frequency of a pin
DPLL_A_PIN_PHASE_ADJUST	attr requested value of phaseadjustment on parent device
DPLL_A_PIN_PARENT_DEVICE	nested attr for each parent dplldevice configuration request
DPLL_A_PIN_PARENT_ID	attr parent dpll device id
DPLL_A_PIN_DIRECTION	attr requested direction of a pin
DPLL_A_PIN_PRIO	attr requested priority of pin onthe dpll device
DPLL_A_PIN_STATE	attr requested state of pin onthe dpll device
DPLL_A_PIN_PARENT_PIN	nested attr for each parent pinconfiguration request
DPLL_A_PIN_PARENT_ID	attr parent pin id
DPLL_A_PIN_STATE	attr requested state of pin onparent pin

Netlink dump requests¶

TheDPLL_CMD_DEVICE_GET andDPLL_CMD_PIN_GET commands arecapable of dump type netlink requests, in which case the response is inthe same format as for theirdo request, but every device or pinregistered in the system is returned.

SET commands format¶

DPLL_CMD_DEVICE_SET - to target a dpll device, the user providesDPLL_A_ID, which is unique identifier of dpll device in the system,as well as parameter being configured (DPLL_A_MODE).

DPLL_CMD_PIN_SET - to target a pin user must provide aDPLL_A_PIN_ID, which is unique identifier of a pin in the system.Also configured pin parameters must be added.IfDPLL_A_PIN_FREQUENCY is configured, this affects all the dplldevices that are connected with the pin, that is why frequency attributeshall not be enclosed inDPLL_A_PIN_PARENT_DEVICE.Other attributes:DPLL_A_PIN_PRIO,DPLL_A_PIN_STATE orDPLL_A_PIN_DIRECTION must be enclosed inDPLL_A_PIN_PARENT_DEVICE as their configuration relates to only oneof parent dplls, targeted byDPLL_A_PIN_PARENT_ID attribute which isalso required inside that nest.For MUX-type pins theDPLL_A_PIN_STATE attribute is configured insimilar way, by enclosing required state inDPLL_A_PIN_PARENT_PINnested attribute and targeted parent pin id inDPLL_A_PIN_PARENT_ID.

In general, it is possible to configure multiple parameters at once, butinternally each parameter change will be invoked separately, where orderof configuration is not guaranteed by any means.

Configuration pre-defined enums¶

enumdpll_mode¶

working modes a dpll can support, differentiates if and how dpll selects one of its inputs to syntonize with it, valid values for DPLL_A_MODE attribute

enumdpll_lock_status¶

provides information of dpll device lock status, valid values for DPLL_A_LOCK_STATUS attribute

enumdpll_lock_status_error¶

if previous status change was done due to a failure, this provides information of dpll device lock status error. Valid values for DPLL_A_LOCK_STATUS_ERROR attribute

enumdpll_type¶

type of dpll, valid values for DPLL_A_TYPE attribute

enumdpll_pin_type¶

defines possible types of a pin, valid values for DPLL_A_PIN_TYPE attribute

enumdpll_pin_direction¶

defines possible direction of a pin, valid values for DPLL_A_PIN_DIRECTION attribute

enumdpll_pin_state¶

defines possible states of a pin, valid values for DPLL_A_PIN_STATE attribute

enumdpll_pin_capabilities¶

defines possible capabilities of a pin, valid flags on DPLL_A_PIN_CAPABILITIES attribute

enumdpll_feature_state¶

Allow control (enable/disable) and status checking over features.

Notifications¶

dpll device can provide notifications regarding status changes of thedevice, i.e. lock status changes, input/output changes or other alarms.There is one multicast group that is used to notify user-space apps vianetlink socket:DPLL_MCGRP_MONITOR

Notifications messages:

DPLL_CMD_DEVICE_CREATE_NTF	dpll device was created
DPLL_CMD_DEVICE_DELETE_NTF	dpll device was deleted
DPLL_CMD_DEVICE_CHANGE_NTF	dpll device has changed
DPLL_CMD_PIN_CREATE_NTF	dpll pin was created
DPLL_CMD_PIN_DELETE_NTF	dpll pin was deleted
DPLL_CMD_PIN_CHANGE_NTF	dpll pin has changed

Events format is the same as for the corresponding get command.Format ofDPLL_CMD_DEVICE_ events is the same as response ofDPLL_CMD_DEVICE_GET.Format ofDPLL_CMD_PIN_ events is same as response ofDPLL_CMD_PIN_GET.

Device driver implementation¶

Device is allocated bydpll_device_get() call. Second call with thesame arguments will not create new object but provides pointer topreviously created device for given arguments, it also increasesrefcount of that object.Device is deallocated bydpll_device_put() call, which firstdecreases the refcount, once refcount is cleared the object isdestroyed.

Device should implement set of operations and register device viadpll_device_register() at which point it becomes available to theusers. Multiple driver instances can obtain reference to it withdpll_device_get(), as well as register dpll device with their ownops and priv.

The pins are allocated separately withdpll_pin_get(), it workssimilarly todpll_device_get(). Function first creates object and thenfor each call with the same arguments only the object refcountincreases. Alsodpll_pin_put() works similarly todpll_device_put().

A pin can be registered with parent dpll device or parent pin, dependingon hardware needs. Each registration requires registerer to provide setof pin callbacks, and private data pointer for calling them:

• dpll_pin_register() - register pin with a dpll device,

• dpll_pin_on_pin_register() - register pin with another MUX type pin.

Notifications of adding or removing dpll devices are created withinsubsystem itself.Notifications about registering/deregistering pins are also invoked bythe subsystem.Notifications about status changes either of dpll device or a pin areinvoked in two ways:

• after successful change was requested on dpll subsystem, the subsystemcalls corresponding notification,

• requested by device driver withdpll_device_change_ntf() ordpll_pin_change_ntf() when driver informs about the status change.

The device driver using dpll interface is not required to implement allthe callback operation. Nevertheless, there are few required to beimplemented.Required dpll device level callback operations:

• .mode_get,

• .lock_status_get.

Required pin level callback operations:

• .state_on_dpll_get (pins registered with dpll device),

• .state_on_pin_get (pins registered with parent pin),

• .direction_get.

Every other operation handler is checked for existence and-EOPNOTSUPP is returned in case of absence of specific handler.

The simplest implementation is in the OCP TimeCard driver. The opsstructures are defined like this:

staticconststructdpll_device_opsdpll_ops={.lock_status_get=ptp_ocp_dpll_lock_status_get,.mode_get=ptp_ocp_dpll_mode_get,.mode_supported=ptp_ocp_dpll_mode_supported,};staticconststructdpll_pin_opsdpll_pins_ops={.frequency_get=ptp_ocp_dpll_frequency_get,.frequency_set=ptp_ocp_dpll_frequency_set,.direction_get=ptp_ocp_dpll_direction_get,.direction_set=ptp_ocp_dpll_direction_set,.state_on_dpll_get=ptp_ocp_dpll_state_get,};

The registration part is then looks like this part:

clkid=pci_get_dsn(pdev);bp->dpll=dpll_device_get(clkid,0,THIS_MODULE);if(IS_ERR(bp->dpll)){err=PTR_ERR(bp->dpll);dev_err(&pdev->dev,"dpll_device_alloc failed\n");gotoout;}err=dpll_device_register(bp->dpll,DPLL_TYPE_PPS,&dpll_ops,bp);if(err)gotoout;for(i=0;i<OCP_SMA_NUM;i++){bp->sma[i].dpll_pin=dpll_pin_get(clkid,i,THIS_MODULE,&bp->sma[i].dpll_prop);if(IS_ERR(bp->sma[i].dpll_pin)){err=PTR_ERR(bp->dpll);gotoout_dpll;}err=dpll_pin_register(bp->dpll,bp->sma[i].dpll_pin,&dpll_pins_ops,&bp->sma[i]);if(err){dpll_pin_put(bp->sma[i].dpll_pin);gotoout_dpll;}}

In the error path we have to rewind every allocation in the reverse order:

while(i){--i;dpll_pin_unregister(bp->dpll,bp->sma[i].dpll_pin,&dpll_pins_ops,&bp->sma[i]);dpll_pin_put(bp->sma[i].dpll_pin);}dpll_device_put(bp->dpll);

More complex example can be found in Intel’s ICE driver or nVidia’s mlx5 driver.

SyncE enablement¶

For SyncE enablement it is required to allow control over dpll devicefor a software application which monitors and configures the inputs ofdpll device in response to current state of a dpll device and itsinputs.In such scenario, dpll device input signal shall be also configurableto drive dpll with signal recovered from the PHY netdevice.This is done by exposing a pin to the netdevice - attaching pin to thenetdevice itself withdpll_netdev_pin_set(structnet_device*dev,structdpll_pin*dpll_pin).Exposed pin id handleDPLL_A_PIN_ID is then identifiable by the useras it is attached to rtnetlink respond to getRTM_NEWLINK command innested attributeIFLA_DPLL_PIN.