Documentation/driver-api/dpll.rst

4 The Linux kernel dpll subsystem
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
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.
242 dpll devices (and pins), as well as set configuration of device or pins.
243 As dpll devices must be abstracted and reflect real hardware,
244 there is no way to add new dpll device via netlink from user space and
253 Constants identifying command types for dpll device uses a
255 The dpll device related attributes use a ``DPLL_A_`` prefix and
264     ``DPLL_A_TYPE``                    attr type of dpll device
270     ``DPLL_A_ID``                      attr unique dpll device ID
277     ``DPLL_A_LOCK_STATUS``             attr dpll device lock status
279     ``DPLL_A_TYPE``                    attr type of dpll device
283   ``DPLL_CMD_DEVICE_SET``              command to set dpll device config
284     ``DPLL_A_ID``                      attr internal dpll device index
336       ``DPLL_A_PIN_PARENT_ID``         attr parent dpll device id
338                                        dpll device
340                                        dpll device
342                                        parent dpll device
344                                        between a pin and parent dpll
359     ``DPLL_A_PIN_PARENT_DEVICE``       nested attr for each parent dpll
361       ``DPLL_A_PIN_PARENT_ID``         attr parent dpll device id
364                                        the dpll device
366                                        the dpll device
385 ``DPLL_CMD_DEVICE_SET`` - to target a dpll device, the user provides
386 ``DPLL_A_ID``, which is unique identifier of dpll device in the system,
392 If ``DPLL_A_PIN_FREQUENCY`` is configured, this affects all the dpll
411 .. kernel-doc:: include/uapi/linux/dpll.h
416 dpll device can provide notifications regarding status changes of the
424   ``DPLL_CMD_DEVICE_CREATE_NTF`` dpll device was created
425   ``DPLL_CMD_DEVICE_DELETE_NTF`` dpll device was deleted
426   ``DPLL_CMD_DEVICE_CHANGE_NTF`` dpll device has changed
427   ``DPLL_CMD_PIN_CREATE_NTF``    dpll pin was created
428   ``DPLL_CMD_PIN_DELETE_NTF``    dpll pin was deleted
429   ``DPLL_CMD_PIN_CHANGE_NTF``    dpll pin has changed
452 dpll_device_get(), as well as register dpll device with their own
460 A pin can be registered with parent dpll device or parent pin, depending
464 - dpll_pin_register() - register pin with a dpll device,
467 Notifications of adding or removing dpll devices are created within
471 Notifications about status changes either of dpll device or a pin are
474 - after successful change was requested on dpll subsystem, the subsystem
479 The device driver using dpll interface is not required to implement all
482 Required dpll device level callback operations:
489 - ``.state_on_dpll_get`` (pins registered with dpll device),
520         bp->dpll = dpll_device_get(clkid, 0, THIS_MODULE);
521         if (IS_ERR(bp->dpll)) {
522                 err = PTR_ERR(bp->dpll);
527         err = dpll_device_register(bp->dpll, DPLL_TYPE_PPS, &dpll_ops, bp);
534                         err = PTR_ERR(bp->dpll);
538                 err = dpll_pin_register(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops,
552                 dpll_pin_unregister(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops, &bp->sma[i]);
555         dpll_device_put(bp->dpll);
561 For SyncE enablement it is required to allow control over dpll device
563 dpll device in response to current state of a dpll device and its
565 In such scenario, dpll device input signal shall be also configurable
566 to drive dpll with signal recovered from the PHY netdevice.