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
44 attributes that result in single device match.
63 request, where user provides attributes that result in single pin match.
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
122 attributes with current state related to each parent, like::
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
138 on desired parent, with the use of ``DPLL_A_PIN_PARENT`` nested
143   ``DPLL_A_PIN_PARENT_PIN``  nested attribute for requesting configuration
165   ``DPLL_A_PIN_PARENT_DEVICE`` nested attribute for requesting configuration
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
188 attributes. Configured phase adjust value is provided with
198   ``DPLL_A_PIN_PARENT_DEVICE``    nested attribute for requesting
213 offset values are fractional with 3-digit decimal places and shell be
229 List of netlink commands with possible attributes
234 The dpll device related attributes use a ``DPLL_A_`` prefix and
241                                        (EUI-64), as defined by the
252                                        (EUI-64), as defined by the
269 The pin related attributes use a ``DPLL_A_PIN_`` prefix and suffix
276                                        (EUI-64), as defined by the
293                                        (EUI-64), as defined by the
303     ``DPLL_A_PIN_FREQUENCY_SUPPORTED`` nested attr provides supported
313     ``DPLL_A_PIN_PARENT_DEVICE``       nested attr for each parent device
324     ``DPLL_A_PIN_PARENT_PIN``          nested attr for each parent pin
338     ``DPLL_A_PIN_PARENT_DEVICE``       nested attr for each parent dpll
346     ``DPLL_A_PIN_PARENT_PIN``          nested attr for each parent pin
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
374 Other attributes: ``DPLL_A_PIN_PRIO``, ``DPLL_A_PIN_STATE`` or
379 For MUX-type pins the ``DPLL_A_PIN_STATE`` attribute is configured in
381 nested attribute and targeted parent pin id in ``DPLL_A_PIN_PARENT_ID``.
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
551 nested attribute ``IFLA_DPLL_PIN``.