Documentation/driver-api/dpll.rst

1 .. SPDX-License-Identifier: GPL-2.0
10 PLL - Phase Locked Loop is an electronic circuit which syntonizes clock
14 DPLL - Digital Phase Locked Loop is an integrated circuit which in
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
89 - ``DPLL_PIN_STATE_SELECTABLE`` - the pin shall be considered as valid
91 - ``DPLL_PIN_STATE_DISCONNECTED`` - the pin shall be not considered as
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
110 MUX-type pins
113 A pin can be MUX-type, it aggregates child pins and serves as a pin
114 multiplexer. One or more pins are registered with MUX-type instead of
116 Pins registered with a MUX-type pin provide user with additional nested
121 ``DPLL_CMD_PIN_GET`` would contain multiple pin-parent nested
125           'clock-id': 282574471561216,
126           'module-name': 'ice',
129           'parent-pin': [
130           {'parent-id': 2, 'state': 'connected'},
131           {'parent-id': 3, 'state': 'disconnected'}
133           'type': 'synce-eth-port'
136 Only one child pin can provide its signal to the parent MUX-type pin at
171 Child pin of MUX-type pin is not capable of automatic input pin selection,
172 in order to configure active input of a MUX-type pin, the user needs to
174 as described in the ``MUX-type pins`` chapter.
180 on a pin and its parent dpll device. If pin-dpll phase offset measurement
213 offset values are fractional with 3-digit decimal places and shell be
241                                        (EUI-64), as defined by the
252                                        (EUI-64), as defined by the
276                                        (EUI-64), as defined by the
293                                        (EUI-64), as defined by the
364 ``DPLL_CMD_DEVICE_SET`` - to target a dpll device, the user provides
368 ``DPLL_CMD_PIN_SET`` - to target a pin user must provide a
379 For MUX-type pins the ``DPLL_A_PIN_STATE`` attribute is configured in
387 Configuration pre-defined enums
390 .. kernel-doc:: include/uapi/linux/dpll.h
397 There is one multicast group that is used to notify user-space apps via
443 - dpll_pin_register() - register pin with a dpll device,
444 - dpll_pin_on_pin_register() - register pin with another MUX type pin.
453 - after successful change was requested on dpll subsystem, the subsystem
455 - requested by device driver with dpll_device_change_ntf() or
463 - ``.mode_get``,
464 - ``.lock_status_get``.
468 - ``.state_on_dpll_get`` (pins registered with dpll device),
469 - ``.state_on_pin_get`` (pins registered with parent pin),
470 - ``.direction_get``.
473 ``-EOPNOTSUPP`` is returned in case of absence of specific handler.
478 .. code-block:: c
496 .. code-block:: c
499         bp->dpll = dpll_device_get(clkid, 0, THIS_MODULE);
500         if (IS_ERR(bp->dpll)) {
501                 err = PTR_ERR(bp->dpll);
502                 dev_err(&pdev->dev, "dpll_device_alloc failed\n");
506         err = dpll_device_register(bp->dpll, DPLL_TYPE_PPS, &dpll_ops, bp);
511                 bp->sma[i].dpll_pin = dpll_pin_get(clkid, i, THIS_MODULE, &bp->sma[i].dpll_prop);
512                 if (IS_ERR(bp->sma[i].dpll_pin)) {
513                         err = PTR_ERR(bp->dpll);
517                 err = dpll_pin_register(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops,
518                                         &bp->sma[i]);
520                         dpll_pin_put(bp->sma[i].dpll_pin);
527 .. code-block:: c
530                 --i;
531                 dpll_pin_unregister(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops, &bp->sma[i]);
532                 dpll_pin_put(bp->sma[i].dpll_pin);
534         dpll_device_put(bp->dpll);
546 This is done by exposing a pin to the netdevice - attaching pin to the