573 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3===============================4The Linux kernel dpll subsystem5===============================6 7DPLL8====9 10PLL - Phase Locked Loop is an electronic circuit which syntonizes clock11signal of a device with an external clock signal. Effectively enabling12device to run on the same clock signal beat as provided on a PLL input.13 14DPLL - Digital Phase Locked Loop is an integrated circuit which in15addition to plain PLL behavior incorporates a digital phase detector16and may have digital divider in the loop. As a result, the frequency on17DPLL's input and output may be configurable.18 19Subsystem20=========21 22The main purpose of dpll subsystem is to provide general interface23to configure devices that use any kind of Digital PLL and could use24different sources of input signal to synchronize to, as well as25different types of outputs.26The main interface is NETLINK_GENERIC based protocol with an event27monitoring multicast group defined.28 29Device object30=============31 32Single dpll device object means single Digital PLL circuit and bunch of33connected pins.34It reports the supported modes of operation and current status to the35user in response to the `do` request of netlink command36``DPLL_CMD_DEVICE_GET`` and list of dplls registered in the subsystem37with `dump` netlink request of the same command.38Changing the configuration of dpll device is done with `do` request of39netlink ``DPLL_CMD_DEVICE_SET`` command.40A device handle is ``DPLL_A_ID``, it shall be provided to get or set41configuration of particular device in the system. It can be obtained42with a ``DPLL_CMD_DEVICE_GET`` `dump` request or43a ``DPLL_CMD_DEVICE_ID_GET`` `do` request, where the one must provide44attributes that result in single device match.45 46Pin object47==========48 49A pin is amorphic object which represents either input or output, it50could be internal component of the device, as well as externally51connected.52The number of pins per dpll vary, but usually multiple pins shall be53provided for a single dpll device.54Pin's properties, capabilities and status is provided to the user in55response to `do` request of netlink ``DPLL_CMD_PIN_GET`` command.56It is also possible to list all the pins that were registered in the57system with `dump` request of ``DPLL_CMD_PIN_GET`` command.58Configuration of a pin can be changed by `do` request of netlink59``DPLL_CMD_PIN_SET`` command.60Pin handle is a ``DPLL_A_PIN_ID``, it shall be provided to get or set61configuration of particular pin in the system. It can be obtained with62``DPLL_CMD_PIN_GET`` `dump` request or ``DPLL_CMD_PIN_ID_GET`` `do`63request, where user provides attributes that result in single pin match.64 65Pin selection66=============67 68In general, selected pin (the one which signal is driving the dpll69device) can be obtained from ``DPLL_A_PIN_STATE`` attribute, and only70one pin shall be in ``DPLL_PIN_STATE_CONNECTED`` state for any dpll71device.72 73Pin selection can be done either manually or automatically, depending74on hardware capabilities and active dpll device work mode75(``DPLL_A_MODE`` attribute). The consequence is that there are76differences for each mode in terms of available pin states, as well as77for the states the user can request for a dpll device.78 79In manual mode (``DPLL_MODE_MANUAL``) the user can request or receive80one of following pin states:81 82- ``DPLL_PIN_STATE_CONNECTED`` - the pin is used to drive dpll device83- ``DPLL_PIN_STATE_DISCONNECTED`` - the pin is not used to drive dpll84 device85 86In automatic mode (``DPLL_MODE_AUTOMATIC``) the user can request or87receive one of following pin states:88 89- ``DPLL_PIN_STATE_SELECTABLE`` - the pin shall be considered as valid90 input for automatic selection algorithm91- ``DPLL_PIN_STATE_DISCONNECTED`` - the pin shall be not considered as92 a valid input for automatic selection algorithm93 94In automatic mode (``DPLL_MODE_AUTOMATIC``) the user can only receive95pin state ``DPLL_PIN_STATE_CONNECTED`` once automatic selection96algorithm locks a dpll device with one of the inputs.97 98Shared pins99===========100 101A single pin object can be attached to multiple dpll devices.102Then there are two groups of configuration knobs:103 1041) Set on a pin - the configuration affects all dpll devices pin is105 registered to (i.e., ``DPLL_A_PIN_FREQUENCY``),1062) Set on a pin-dpll tuple - the configuration affects only selected107 dpll device (i.e., ``DPLL_A_PIN_PRIO``, ``DPLL_A_PIN_STATE``,108 ``DPLL_A_PIN_DIRECTION``).109 110MUX-type pins111=============112 113A pin can be MUX-type, it aggregates child pins and serves as a pin114multiplexer. One or more pins are registered with MUX-type instead of115being directly registered to a dpll device.116Pins registered with a MUX-type pin provide user with additional nested117attribute ``DPLL_A_PIN_PARENT_PIN`` for each parent they were registered118with.119If a pin was registered with multiple parent pins, they behave like a120multiple output multiplexer. In this case output of a121``DPLL_CMD_PIN_GET`` would contain multiple pin-parent nested122attributes with current state related to each parent, like::123 124 'pin': [{{125 'clock-id': 282574471561216,126 'module-name': 'ice',127 'capabilities': 4,128 'id': 13,129 'parent-pin': [130 {'parent-id': 2, 'state': 'connected'},131 {'parent-id': 3, 'state': 'disconnected'}132 ],133 'type': 'synce-eth-port'134 }}]135 136Only one child pin can provide its signal to the parent MUX-type pin at137a time, the selection is done by requesting change of a child pin state138on desired parent, with the use of ``DPLL_A_PIN_PARENT`` nested139attribute. Example of netlink `set state on parent pin` message format:140 141 ========================== =============================================142 ``DPLL_A_PIN_ID`` child pin id143 ``DPLL_A_PIN_PARENT_PIN`` nested attribute for requesting configuration144 related to parent pin145 ``DPLL_A_PIN_PARENT_ID`` parent pin id146 ``DPLL_A_PIN_STATE`` requested pin state on parent147 ========================== =============================================148 149Pin priority150============151 152Some devices might offer a capability of automatic pin selection mode153(enum value ``DPLL_MODE_AUTOMATIC`` of ``DPLL_A_MODE`` attribute).154Usually, automatic selection is performed on the hardware level, which155means only pins directly connected to the dpll can be used for automatic156input pin selection.157In automatic selection mode, the user cannot manually select a input158pin for the device, instead the user shall provide all directly159connected pins with a priority ``DPLL_A_PIN_PRIO``, the device would160pick a highest priority valid signal and use it to control the DPLL161device. Example of netlink `set priority on parent pin` message format:162 163 ============================ =============================================164 ``DPLL_A_PIN_ID`` configured pin id165 ``DPLL_A_PIN_PARENT_DEVICE`` nested attribute for requesting configuration166 related to parent dpll device167 ``DPLL_A_PIN_PARENT_ID`` parent dpll device id168 ``DPLL_A_PIN_PRIO`` requested pin prio on parent dpll169 ============================ =============================================170 171Child pin of MUX-type pin is not capable of automatic input pin selection,172in order to configure active input of a MUX-type pin, the user needs to173request desired pin state of the child pin on the parent pin,174as described in the ``MUX-type pins`` chapter.175 176Phase offset measurement and adjustment177========================================178 179Device may provide ability to measure a phase difference between signals180on a pin and its parent dpll device. If pin-dpll phase offset measurement181is supported, it shall be provided with ``DPLL_A_PIN_PHASE_OFFSET``182attribute for each parent dpll device.183 184Device may also provide ability to adjust a signal phase on a pin.185If pin phase adjustment is supported, minimal and maximal values that pin186handle shall be provide to the user on ``DPLL_CMD_PIN_GET`` respond187with ``DPLL_A_PIN_PHASE_ADJUST_MIN`` and ``DPLL_A_PIN_PHASE_ADJUST_MAX``188attributes. Configured phase adjust value is provided with189``DPLL_A_PIN_PHASE_ADJUST`` attribute of a pin, and value change can be190requested with the same attribute with ``DPLL_CMD_PIN_SET`` command.191 192 =============================== ======================================193 ``DPLL_A_PIN_ID`` configured pin id194 ``DPLL_A_PIN_PHASE_ADJUST_MIN`` attr minimum value of phase adjustment195 ``DPLL_A_PIN_PHASE_ADJUST_MAX`` attr maximum value of phase adjustment196 ``DPLL_A_PIN_PHASE_ADJUST`` attr configured value of phase197 adjustment on parent dpll device198 ``DPLL_A_PIN_PARENT_DEVICE`` nested attribute for requesting199 configuration on given parent dpll200 device201 ``DPLL_A_PIN_PARENT_ID`` parent dpll device id202 ``DPLL_A_PIN_PHASE_OFFSET`` attr measured phase difference203 between a pin and parent dpll device204 =============================== ======================================205 206All phase related values are provided in pico seconds, which represents207time difference between signals phase. The negative value means that208phase of signal on pin is earlier in time than dpll's signal. Positive209value means that phase of signal on pin is later in time than signal of210a dpll.211 212Phase adjust (also min and max) values are integers, but measured phase213offset values are fractional with 3-digit decimal places and shell be214divided with ``DPLL_PIN_PHASE_OFFSET_DIVIDER`` to get integer part and215modulo divided to get fractional part.216 217Embedded SYNC218=============219 220Device may provide ability to use Embedded SYNC feature. It allows221to embed additional SYNC signal into the base frequency of a pin - a one222special pulse of base frequency signal every time SYNC signal pulse223happens. The user can configure the frequency of Embedded SYNC.224The Embedded SYNC capability is always related to a given base frequency225and HW capabilities. The user is provided a range of Embedded SYNC226frequencies supported, depending on current base frequency configured for227the pin.228 229 ========================================= =================================230 ``DPLL_A_PIN_ESYNC_FREQUENCY`` current Embedded SYNC frequency231 ``DPLL_A_PIN_ESYNC_FREQUENCY_SUPPORTED`` nest available Embedded SYNC232 frequency ranges233 ``DPLL_A_PIN_FREQUENCY_MIN`` attr minimum value of frequency234 ``DPLL_A_PIN_FREQUENCY_MAX`` attr maximum value of frequency235 ``DPLL_A_PIN_ESYNC_PULSE`` pulse type of Embedded SYNC236 ========================================= =================================237 238Configuration commands group239============================240 241Configuration commands are used to get information about registered242dpll devices (and pins), as well as set configuration of device or pins.243As dpll devices must be abstracted and reflect real hardware,244there is no way to add new dpll device via netlink from user space and245each device should be registered by its driver.246 247All netlink commands require ``GENL_ADMIN_PERM``. This is to prevent248any spamming/DoS from unauthorized userspace applications.249 250List of netlink commands with possible attributes251=================================================252 253Constants identifying command types for dpll device uses a254``DPLL_CMD_`` prefix and suffix according to command purpose.255The dpll device related attributes use a ``DPLL_A_`` prefix and256suffix according to attribute purpose.257 258 ==================================== =================================259 ``DPLL_CMD_DEVICE_ID_GET`` command to get device ID260 ``DPLL_A_MODULE_NAME`` attr module name of registerer261 ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier262 (EUI-64), as defined by the263 IEEE 1588 standard264 ``DPLL_A_TYPE`` attr type of dpll device265 ==================================== =================================266 267 ==================================== =================================268 ``DPLL_CMD_DEVICE_GET`` command to get device info or269 dump list of available devices270 ``DPLL_A_ID`` attr unique dpll device ID271 ``DPLL_A_MODULE_NAME`` attr module name of registerer272 ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier273 (EUI-64), as defined by the274 IEEE 1588 standard275 ``DPLL_A_MODE`` attr selection mode276 ``DPLL_A_MODE_SUPPORTED`` attr available selection modes277 ``DPLL_A_LOCK_STATUS`` attr dpll device lock status278 ``DPLL_A_TEMP`` attr device temperature info279 ``DPLL_A_TYPE`` attr type of dpll device280 ==================================== =================================281 282 ==================================== =================================283 ``DPLL_CMD_DEVICE_SET`` command to set dpll device config284 ``DPLL_A_ID`` attr internal dpll device index285 ``DPLL_A_MODE`` attr selection mode to configure286 ==================================== =================================287 288Constants identifying command types for pins uses a289``DPLL_CMD_PIN_`` prefix and suffix according to command purpose.290The pin related attributes use a ``DPLL_A_PIN_`` prefix and suffix291according to attribute purpose.292 293 ==================================== =================================294 ``DPLL_CMD_PIN_ID_GET`` command to get pin ID295 ``DPLL_A_PIN_MODULE_NAME`` attr module name of registerer296 ``DPLL_A_PIN_CLOCK_ID`` attr Unique Clock Identifier297 (EUI-64), as defined by the298 IEEE 1588 standard299 ``DPLL_A_PIN_BOARD_LABEL`` attr pin board label provided300 by registerer301 ``DPLL_A_PIN_PANEL_LABEL`` attr pin panel label provided302 by registerer303 ``DPLL_A_PIN_PACKAGE_LABEL`` attr pin package label provided304 by registerer305 ``DPLL_A_PIN_TYPE`` attr type of a pin306 ==================================== =================================307 308 ==================================== ==================================309 ``DPLL_CMD_PIN_GET`` command to get pin info or dump310 list of available pins311 ``DPLL_A_PIN_ID`` attr unique a pin ID312 ``DPLL_A_PIN_MODULE_NAME`` attr module name of registerer313 ``DPLL_A_PIN_CLOCK_ID`` attr Unique Clock Identifier314 (EUI-64), as defined by the315 IEEE 1588 standard316 ``DPLL_A_PIN_BOARD_LABEL`` attr pin board label provided317 by registerer318 ``DPLL_A_PIN_PANEL_LABEL`` attr pin panel label provided319 by registerer320 ``DPLL_A_PIN_PACKAGE_LABEL`` attr pin package label provided321 by registerer322 ``DPLL_A_PIN_TYPE`` attr type of a pin323 ``DPLL_A_PIN_FREQUENCY`` attr current frequency of a pin324 ``DPLL_A_PIN_FREQUENCY_SUPPORTED`` nested attr provides supported325 frequencies326 ``DPLL_A_PIN_ANY_FREQUENCY_MIN`` attr minimum value of frequency327 ``DPLL_A_PIN_ANY_FREQUENCY_MAX`` attr maximum value of frequency328 ``DPLL_A_PIN_PHASE_ADJUST_MIN`` attr minimum value of phase329 adjustment330 ``DPLL_A_PIN_PHASE_ADJUST_MAX`` attr maximum value of phase331 adjustment332 ``DPLL_A_PIN_PHASE_ADJUST`` attr configured value of phase333 adjustment on parent device334 ``DPLL_A_PIN_PARENT_DEVICE`` nested attr for each parent device335 the pin is connected with336 ``DPLL_A_PIN_PARENT_ID`` attr parent dpll device id337 ``DPLL_A_PIN_PRIO`` attr priority of pin on the338 dpll device339 ``DPLL_A_PIN_STATE`` attr state of pin on the parent340 dpll device341 ``DPLL_A_PIN_DIRECTION`` attr direction of a pin on the342 parent dpll device343 ``DPLL_A_PIN_PHASE_OFFSET`` attr measured phase difference344 between a pin and parent dpll345 ``DPLL_A_PIN_PARENT_PIN`` nested attr for each parent pin346 the pin is connected with347 ``DPLL_A_PIN_PARENT_ID`` attr parent pin id348 ``DPLL_A_PIN_STATE`` attr state of pin on the parent349 pin350 ``DPLL_A_PIN_CAPABILITIES`` attr bitmask of pin capabilities351 ==================================== ==================================352 353 ==================================== =================================354 ``DPLL_CMD_PIN_SET`` command to set pins configuration355 ``DPLL_A_PIN_ID`` attr unique a pin ID356 ``DPLL_A_PIN_FREQUENCY`` attr requested frequency of a pin357 ``DPLL_A_PIN_PHASE_ADJUST`` attr requested value of phase358 adjustment on parent device359 ``DPLL_A_PIN_PARENT_DEVICE`` nested attr for each parent dpll360 device configuration request361 ``DPLL_A_PIN_PARENT_ID`` attr parent dpll device id362 ``DPLL_A_PIN_DIRECTION`` attr requested direction of a pin363 ``DPLL_A_PIN_PRIO`` attr requested priority of pin on364 the dpll device365 ``DPLL_A_PIN_STATE`` attr requested state of pin on366 the dpll device367 ``DPLL_A_PIN_PARENT_PIN`` nested attr for each parent pin368 configuration request369 ``DPLL_A_PIN_PARENT_ID`` attr parent pin id370 ``DPLL_A_PIN_STATE`` attr requested state of pin on371 parent pin372 ==================================== =================================373 374Netlink dump requests375=====================376 377The ``DPLL_CMD_DEVICE_GET`` and ``DPLL_CMD_PIN_GET`` commands are378capable of dump type netlink requests, in which case the response is in379the same format as for their ``do`` request, but every device or pin380registered in the system is returned.381 382SET commands format383===================384 385``DPLL_CMD_DEVICE_SET`` - to target a dpll device, the user provides386``DPLL_A_ID``, which is unique identifier of dpll device in the system,387as well as parameter being configured (``DPLL_A_MODE``).388 389``DPLL_CMD_PIN_SET`` - to target a pin user must provide a390``DPLL_A_PIN_ID``, which is unique identifier of a pin in the system.391Also configured pin parameters must be added.392If ``DPLL_A_PIN_FREQUENCY`` is configured, this affects all the dpll393devices that are connected with the pin, that is why frequency attribute394shall not be enclosed in ``DPLL_A_PIN_PARENT_DEVICE``.395Other attributes: ``DPLL_A_PIN_PRIO``, ``DPLL_A_PIN_STATE`` or396``DPLL_A_PIN_DIRECTION`` must be enclosed in397``DPLL_A_PIN_PARENT_DEVICE`` as their configuration relates to only one398of parent dplls, targeted by ``DPLL_A_PIN_PARENT_ID`` attribute which is399also required inside that nest.400For MUX-type pins the ``DPLL_A_PIN_STATE`` attribute is configured in401similar way, by enclosing required state in ``DPLL_A_PIN_PARENT_PIN``402nested attribute and targeted parent pin id in ``DPLL_A_PIN_PARENT_ID``.403 404In general, it is possible to configure multiple parameters at once, but405internally each parameter change will be invoked separately, where order406of configuration is not guaranteed by any means.407 408Configuration pre-defined enums409===============================410 411.. kernel-doc:: include/uapi/linux/dpll.h412 413Notifications414=============415 416dpll device can provide notifications regarding status changes of the417device, i.e. lock status changes, input/output changes or other alarms.418There is one multicast group that is used to notify user-space apps via419netlink socket: ``DPLL_MCGRP_MONITOR``420 421Notifications messages:422 423 ============================== =====================================424 ``DPLL_CMD_DEVICE_CREATE_NTF`` dpll device was created425 ``DPLL_CMD_DEVICE_DELETE_NTF`` dpll device was deleted426 ``DPLL_CMD_DEVICE_CHANGE_NTF`` dpll device has changed427 ``DPLL_CMD_PIN_CREATE_NTF`` dpll pin was created428 ``DPLL_CMD_PIN_DELETE_NTF`` dpll pin was deleted429 ``DPLL_CMD_PIN_CHANGE_NTF`` dpll pin has changed430 ============================== =====================================431 432Events format is the same as for the corresponding get command.433Format of ``DPLL_CMD_DEVICE_`` events is the same as response of434``DPLL_CMD_DEVICE_GET``.435Format of ``DPLL_CMD_PIN_`` events is same as response of436``DPLL_CMD_PIN_GET``.437 438Device driver implementation439============================440 441Device is allocated by dpll_device_get() call. Second call with the442same arguments will not create new object but provides pointer to443previously created device for given arguments, it also increases444refcount of that object.445Device is deallocated by dpll_device_put() call, which first446decreases the refcount, once refcount is cleared the object is447destroyed.448 449Device should implement set of operations and register device via450dpll_device_register() at which point it becomes available to the451users. Multiple driver instances can obtain reference to it with452dpll_device_get(), as well as register dpll device with their own453ops and priv.454 455The pins are allocated separately with dpll_pin_get(), it works456similarly to dpll_device_get(). Function first creates object and then457for each call with the same arguments only the object refcount458increases. Also dpll_pin_put() works similarly to dpll_device_put().459 460A pin can be registered with parent dpll device or parent pin, depending461on hardware needs. Each registration requires registerer to provide set462of pin callbacks, and private data pointer for calling them:463 464- dpll_pin_register() - register pin with a dpll device,465- dpll_pin_on_pin_register() - register pin with another MUX type pin.466 467Notifications of adding or removing dpll devices are created within468subsystem itself.469Notifications about registering/deregistering pins are also invoked by470the subsystem.471Notifications about status changes either of dpll device or a pin are472invoked in two ways:473 474- after successful change was requested on dpll subsystem, the subsystem475 calls corresponding notification,476- requested by device driver with dpll_device_change_ntf() or477 dpll_pin_change_ntf() when driver informs about the status change.478 479The device driver using dpll interface is not required to implement all480the callback operation. Nevertheless, there are few required to be481implemented.482Required dpll device level callback operations:483 484- ``.mode_get``,485- ``.lock_status_get``.486 487Required pin level callback operations:488 489- ``.state_on_dpll_get`` (pins registered with dpll device),490- ``.state_on_pin_get`` (pins registered with parent pin),491- ``.direction_get``.492 493Every other operation handler is checked for existence and494``-EOPNOTSUPP`` is returned in case of absence of specific handler.495 496The simplest implementation is in the OCP TimeCard driver. The ops497structures are defined like this:498 499.. code-block:: c500 501 static const struct dpll_device_ops dpll_ops = {502 .lock_status_get = ptp_ocp_dpll_lock_status_get,503 .mode_get = ptp_ocp_dpll_mode_get,504 .mode_supported = ptp_ocp_dpll_mode_supported,505 };506 507 static const struct dpll_pin_ops dpll_pins_ops = {508 .frequency_get = ptp_ocp_dpll_frequency_get,509 .frequency_set = ptp_ocp_dpll_frequency_set,510 .direction_get = ptp_ocp_dpll_direction_get,511 .direction_set = ptp_ocp_dpll_direction_set,512 .state_on_dpll_get = ptp_ocp_dpll_state_get,513 };514 515The registration part is then looks like this part:516 517.. code-block:: c518 519 clkid = pci_get_dsn(pdev);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");524 goto out;525 }526 527 err = dpll_device_register(bp->dpll, DPLL_TYPE_PPS, &dpll_ops, bp);528 if (err)529 goto out;530 531 for (i = 0; i < OCP_SMA_NUM; i++) {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);535 goto out_dpll;536 }537 538 err = dpll_pin_register(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops,539 &bp->sma[i]);540 if (err) {541 dpll_pin_put(bp->sma[i].dpll_pin);542 goto out_dpll;543 }544 }545 546In the error path we have to rewind every allocation in the reverse order:547 548.. code-block:: c549 550 while (i) {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);554 }555 dpll_device_put(bp->dpll);556 557More complex example can be found in Intel's ICE driver or nVidia's mlx5 driver.558 559SyncE enablement560================561For SyncE enablement it is required to allow control over dpll device562for a software application which monitors and configures the inputs of563dpll device in response to current state of a dpll device and its564inputs.565In such scenario, dpll device input signal shall be also configurable566to drive dpll with signal recovered from the PHY netdevice.567This is done by exposing a pin to the netdevice - attaching pin to the568netdevice itself with569``dpll_netdev_pin_set(struct net_device *dev, struct dpll_pin *dpll_pin)``.570Exposed pin id handle ``DPLL_A_PIN_ID`` is then identifiable by the user571as it is attached to rtnetlink respond to get ``RTM_NEWLINK`` command in572nested attribute ``IFLA_DPLL_PIN``.573