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
206 All phase related values are provided in pico seconds, which represents
213 offset values are fractional with 3-digit decimal places and shell be
221 to embed additional SYNC signal into the base frequency of a pin - a one
262                                        (EUI-64), as defined by the
273                                        (EUI-64), as defined by the
297                                        (EUI-64), as defined by the
314                                        (EUI-64), as defined by the
385 ``DPLL_CMD_DEVICE_SET`` - to target a dpll device, the user provides
389 ``DPLL_CMD_PIN_SET`` - to target a pin user must provide a
400 For MUX-type pins the ``DPLL_A_PIN_STATE`` attribute is configured in
408 Configuration pre-defined enums
411 .. kernel-doc:: include/uapi/linux/dpll.h
418 There is one multicast group that is used to notify user-space apps via
464 - dpll_pin_register() - register pin with a dpll device,
465 - dpll_pin_on_pin_register() - register pin with another MUX type pin.
474 - after successful change was requested on dpll subsystem, the subsystem
476 - requested by device driver with dpll_device_change_ntf() or
484 - ``.mode_get``,
485 - ``.lock_status_get``.
489 - ``.state_on_dpll_get`` (pins registered with dpll device),
490 - ``.state_on_pin_get`` (pins registered with parent pin),
491 - ``.direction_get``.
494 ``-EOPNOTSUPP`` is returned in case of absence of specific handler.
499 .. code-block:: c
517 .. code-block:: c
520         bp->dpll = dpll_device_get(clkid, 0, THIS_MODULE);
521         if (IS_ERR(bp->dpll)) {
522                 err = PTR_ERR(bp->dpll);
523                 dev_err(&pdev->dev, "dpll_device_alloc failed\n");
527         err = dpll_device_register(bp->dpll, DPLL_TYPE_PPS, &dpll_ops, bp);
532                 bp->sma[i].dpll_pin = dpll_pin_get(clkid, i, THIS_MODULE, &bp->sma[i].dpll_prop);
533                 if (IS_ERR(bp->sma[i].dpll_pin)) {
534                         err = PTR_ERR(bp->dpll);
538                 err = dpll_pin_register(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops,
539                                         &bp->sma[i]);
541                         dpll_pin_put(bp->sma[i].dpll_pin);
548 .. code-block:: c
551                 --i;
552                 dpll_pin_unregister(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops, &bp->sma[i]);
553                 dpll_pin_put(bp->sma[i].dpll_pin);
555         dpll_device_put(bp->dpll);
567 This is done by exposing a pin to the netdevice - attaching pin to the