Documentation/driver-api/dpll.rst

4 The Linux kernel dpll subsystem
7 DPLL  chapter
14 DPLL - Digital Phase Locked Loop is an integrated circuit which in
17 DPLL's input and output may be configurable.
22 The main purpose of dpll subsystem is to provide general interface
32 Single dpll device object means single Digital PLL circuit and bunch of
38 Changing the configuration of dpll device is done with `do` request of
52 The number of pins per dpll vary, but usually multiple pins shall be
53 provided for a single dpll device.
68 In general, selected pin (the one which signal is driving the dpll
70 one pin shall be in ``DPLL_PIN_STATE_CONNECTED`` state for any dpll
74 on hardware capabilities and active dpll device work mode
77 for the states the user can request for a dpll device.
82 - ``DPLL_PIN_STATE_CONNECTED`` - the pin is used to drive dpll device
83 - ``DPLL_PIN_STATE_DISCONNECTED`` - the pin is not used to drive dpll
96 algorithm locks a dpll device with one of the inputs.
101 A single pin object can be attached to multiple dpll devices.
104 1) Set on a pin - the configuration affects all dpll devices pin is
106 2) Set on a pin-dpll tuple - the configuration affects only selected
107    dpll device (i.e., ``DPLL_A_PIN_PRIO``, ``DPLL_A_PIN_STATE``,
115 being directly registered to a dpll device.
155 means only pins directly connected to the dpll can be used for automatic
160 pick a highest priority valid signal and use it to control the DPLL
166                                related to parent dpll device
167     ``DPLL_A_PIN_PARENT_ID``   parent dpll device id
168     ``DPLL_A_PIN_PRIO``        requested pin prio on parent dpll
180 on a pin and its parent dpll device. If pin-dpll phase offset measurement
182 attribute for each parent dpll device.
197                                   adjustment on parent dpll device
199                                   configuration on given parent dpll
201     ``DPLL_A_PIN_PARENT_ID``      parent dpll device id
203                                   between a pin and parent dpll device
208 phase of signal on pin is earlier in time than dpll's signal. Positive
210 a dpll.
221 dpll devices (and pins), as well as set configuration of device or pins.
222 As dpll devices must be abstracted and reflect real hardware,
223 there is no way to add new dpll device via netlink from user space and
232 Constants identifying command types for dpll device uses a
234 The dpll device related attributes use a ``DPLL_A_`` prefix and
243     ``DPLL_A_TYPE``                    attr type of dpll device
249     ``DPLL_A_ID``                      attr unique dpll device ID
256     ``DPLL_A_LOCK_STATUS``             attr dpll device lock status
258     ``DPLL_A_TYPE``                    attr type of dpll device
262   ``DPLL_CMD_DEVICE_SET``              command to set dpll device config
263     ``DPLL_A_ID``                      attr internal dpll device index
315       ``DPLL_A_PIN_PARENT_ID``         attr parent dpll device id
317                                        dpll device
319                                        dpll device
321                                        parent dpll device
323                                        between a pin and parent dpll
338     ``DPLL_A_PIN_PARENT_DEVICE``       nested attr for each parent dpll
340       ``DPLL_A_PIN_PARENT_ID``         attr parent dpll device id
343                                        the dpll device
345                                        the dpll device
364 ``DPLL_CMD_DEVICE_SET`` - to target a dpll device, the user provides
365 ``DPLL_A_ID``, which is unique identifier of dpll device in the system,
371 If ``DPLL_A_PIN_FREQUENCY`` is configured, this affects all the dpll
390 .. kernel-doc:: include/uapi/linux/dpll.h
395 dpll device can provide notifications regarding status changes of the
403   ``DPLL_CMD_DEVICE_CREATE_NTF`` dpll device was created
404   ``DPLL_CMD_DEVICE_DELETE_NTF`` dpll device was deleted
405   ``DPLL_CMD_DEVICE_CHANGE_NTF`` dpll device has changed
406   ``DPLL_CMD_PIN_CREATE_NTF``    dpll pin was created
407   ``DPLL_CMD_PIN_DELETE_NTF``    dpll pin was deleted
408   ``DPLL_CMD_PIN_CHANGE_NTF``    dpll pin has changed
431 dpll_device_get(), as well as register dpll device with their own
439 A pin can be registered with parent dpll device or parent pin, depending
443 - dpll_pin_register() - register pin with a dpll device,
446 Notifications of adding or removing dpll devices are created within
450 Notifications about status changes either of dpll device or a pin are
453 - after successful change was requested on dpll subsystem, the subsystem
458 The device driver using dpll interface is not required to implement all
461 Required dpll device level callback operations:
468 - ``.state_on_dpll_get`` (pins registered with dpll device),
499         bp->dpll = dpll_device_get(clkid, 0, THIS_MODULE);
500         if (IS_ERR(bp->dpll)) {
501                 err = PTR_ERR(bp->dpll);
506         err = dpll_device_register(bp->dpll, DPLL_TYPE_PPS, &dpll_ops, bp);
513                         err = PTR_ERR(bp->dpll);
517                 err = dpll_pin_register(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops,
531                 dpll_pin_unregister(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops, &bp->sma[i]);
534         dpll_device_put(bp->dpll);
540 For SyncE enablement it is required to allow control over dpll device
542 dpll device in response to current state of a dpll device and its
544 In such scenario, dpll device input signal shall be also configurable
545 to drive dpll with signal recovered from the PHY netdevice.