1.. SPDX-License-Identifier: GPL-2.0 2 3=============================== 4The Linux kernel dpll subsystem 5=============================== 6 7DPLL 8==== 9 10PLL - Phase Locked Loop is an electronic circuit which syntonizes clock 11signal of a device with an external clock signal. Effectively enabling 12device 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 in 15addition to plain PLL behavior incorporates a digital phase detector 16and may have digital divider in the loop. As a result, the frequency on 17DPLL's input and output may be configurable. 18 19Subsystem 20========= 21 22The main purpose of dpll subsystem is to provide general interface 23to configure devices that use any kind of Digital PLL and could use 24different sources of input signal to synchronize to, as well as 25different types of outputs. 26The main interface is NETLINK_GENERIC based protocol with an event 27monitoring multicast group defined. 28 29Device object 30============= 31 32Single dpll device object means single Digital PLL circuit and bunch of 33connected pins. 34It reports the supported modes of operation and current status to the 35user in response to the `do` request of netlink command 36``DPLL_CMD_DEVICE_GET`` and list of dplls registered in the subsystem 37with `dump` netlink request of the same command. 38Changing the configuration of dpll device is done with `do` request of 39netlink ``DPLL_CMD_DEVICE_SET`` command. 40A device handle is ``DPLL_A_ID``, it shall be provided to get or set 41configuration of particular device in the system. It can be obtained 42with a ``DPLL_CMD_DEVICE_GET`` `dump` request or 43a ``DPLL_CMD_DEVICE_ID_GET`` `do` request, where the one must provide 44attributes that result in single device match. 45 46Pin object 47========== 48 49A pin is amorphic object which represents either input or output, it 50could be internal component of the device, as well as externally 51connected. 52The number of pins per dpll vary, but usually multiple pins shall be 53provided for a single dpll device. 54Pin's properties, capabilities and status is provided to the user in 55response to `do` request of netlink ``DPLL_CMD_PIN_GET`` command. 56It is also possible to list all the pins that were registered in the 57system with `dump` request of ``DPLL_CMD_PIN_GET`` command. 58Configuration of a pin can be changed by `do` request of netlink 59``DPLL_CMD_PIN_SET`` command. 60Pin handle is a ``DPLL_A_PIN_ID``, it shall be provided to get or set 61configuration of particular pin in the system. It can be obtained with 62``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 selection 66============= 67 68In general, selected pin (the one which signal is driving the dpll 69device) can be obtained from ``DPLL_A_PIN_STATE`` attribute, and only 70one pin shall be in ``DPLL_PIN_STATE_CONNECTED`` state for any dpll 71device. 72 73Pin selection can be done either manually or automatically, depending 74on hardware capabilities and active dpll device work mode 75(``DPLL_A_MODE`` attribute). The consequence is that there are 76differences for each mode in terms of available pin states, as well as 77for the states the user can request for a dpll device. 78 79In manual mode (``DPLL_MODE_MANUAL``) the user can request or receive 80one of following pin states: 81 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 84 device 85 86In automatic mode (``DPLL_MODE_AUTOMATIC``) the user can request or 87receive one of following pin states: 88 89- ``DPLL_PIN_STATE_SELECTABLE`` - the pin shall be considered as valid 90 input for automatic selection algorithm 91- ``DPLL_PIN_STATE_DISCONNECTED`` - the pin shall be not considered as 92 a valid input for automatic selection algorithm 93 94In automatic mode (``DPLL_MODE_AUTOMATIC``) the user can only receive 95pin state ``DPLL_PIN_STATE_CONNECTED`` once automatic selection 96algorithm locks a dpll device with one of the inputs. 97 98Shared pins 99=========== 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 is 105 registered to (i.e., ``DPLL_A_PIN_FREQUENCY``), 1062) Set on a pin-dpll tuple - the configuration affects only selected 107 dpll device (i.e., ``DPLL_A_PIN_PRIO``, ``DPLL_A_PIN_STATE``, 108 ``DPLL_A_PIN_DIRECTION``). 109 110MUX-type pins 111============= 112 113A pin can be MUX-type, it aggregates child pins and serves as a pin 114multiplexer. One or more pins are registered with MUX-type instead of 115being directly registered to a dpll device. 116Pins registered with a MUX-type pin provide user with additional nested 117attribute ``DPLL_A_PIN_PARENT_PIN`` for each parent they were registered 118with. 119If a pin was registered with multiple parent pins, they behave like a 120multiple output multiplexer. In this case output of a 121``DPLL_CMD_PIN_GET`` would contain multiple pin-parent nested 122attributes 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 at 137a time, the selection is done by requesting change of a child pin state 138on desired parent, with the use of ``DPLL_A_PIN_PARENT`` nested 139attribute. Example of netlink `set state on parent pin` message format: 140 141 ========================== ============================================= 142 ``DPLL_A_PIN_ID`` child pin id 143 ``DPLL_A_PIN_PARENT_PIN`` nested attribute for requesting configuration 144 related to parent pin 145 ``DPLL_A_PIN_PARENT_ID`` parent pin id 146 ``DPLL_A_PIN_STATE`` requested pin state on parent 147 ========================== ============================================= 148 149Pin priority 150============ 151 152Some devices might offer a capability of automatic pin selection mode 153(enum value ``DPLL_MODE_AUTOMATIC`` of ``DPLL_A_MODE`` attribute). 154Usually, automatic selection is performed on the hardware level, which 155means only pins directly connected to the dpll can be used for automatic 156input pin selection. 157In automatic selection mode, the user cannot manually select a input 158pin for the device, instead the user shall provide all directly 159connected pins with a priority ``DPLL_A_PIN_PRIO``, the device would 160pick a highest priority valid signal and use it to control the DPLL 161device. Example of netlink `set priority on parent pin` message format: 162 163 ============================ ============================================= 164 ``DPLL_A_PIN_ID`` configured pin id 165 ``DPLL_A_PIN_PARENT_DEVICE`` nested attribute for requesting configuration 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 169 ============================ ============================================= 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 to 173request desired pin state of the child pin on the parent pin, 174as described in the ``MUX-type pins`` chapter. 175 176Phase offset measurement and adjustment 177======================================== 178 179Device may provide ability to measure a phase difference between signals 180on a pin and its parent dpll device. If pin-dpll phase offset measurement 181is supported, it shall be provided with ``DPLL_A_PIN_PHASE_OFFSET`` 182attribute for each parent dpll device. The reported phase offset may be 183computed as the average of prior values and the current measurement, using 184the following formula: 185 186.. math:: 187 curr\_avg = prev\_avg * \frac{2^N-1}{2^N} + new\_val * \frac{1}{2^N} 188 189where `curr_avg` is the current reported phase offset, `prev_avg` is the 190previously reported value, `new_val` is the current measurement, and `N` is 191the averaging factor. Configured averaging factor value is provided with 192``DPLL_A_PHASE_OFFSET_AVG_FACTOR`` attribute of a device and value change can 193be requested with the same attribute with ``DPLL_CMD_DEVICE_SET`` command. 194 195 ================================== ====================================== 196 ``DPLL_A_PHASE_OFFSET_AVG_FACTOR`` attr configured value of phase offset 197 averaging factor 198 ================================== ====================================== 199 200Device may also provide ability to adjust a signal phase on a pin. 201If pin phase adjustment is supported, minimal and maximal values and 202granularity that pin handle shall be provided to the user on 203``DPLL_CMD_PIN_GET`` respond with ``DPLL_A_PIN_PHASE_ADJUST_MIN``, 204``DPLL_A_PIN_PHASE_ADJUST_MAX`` and ``DPLL_A_PIN_PHASE_ADJUST_GRAN`` 205attributes. Configured phase adjust value is provided with 206``DPLL_A_PIN_PHASE_ADJUST`` attribute of a pin, and value change can be 207requested with the same attribute with ``DPLL_CMD_PIN_SET`` command. 208 209 ================================ ========================================== 210 ``DPLL_A_PIN_ID`` configured pin id 211 ``DPLL_A_PIN_PHASE_ADJUST_GRAN`` attr granularity of phase adjustment value 212 ``DPLL_A_PIN_PHASE_ADJUST_MIN`` attr minimum value of phase adjustment 213 ``DPLL_A_PIN_PHASE_ADJUST_MAX`` attr maximum value of phase adjustment 214 ``DPLL_A_PIN_PHASE_ADJUST`` attr configured value of phase 215 adjustment on parent dpll device 216 ``DPLL_A_PIN_PARENT_DEVICE`` nested attribute for requesting 217 configuration on given parent dpll 218 device 219 ``DPLL_A_PIN_PARENT_ID`` parent dpll device id 220 ``DPLL_A_PIN_PHASE_OFFSET`` attr measured phase difference 221 between a pin and parent dpll device 222 ================================ ========================================== 223 224All phase related values are provided in pico seconds, which represents 225time difference between signals phase. The negative value means that 226phase of signal on pin is earlier in time than dpll's signal. Positive 227value means that phase of signal on pin is later in time than signal of 228a dpll. 229 230Phase adjust (also min and max) values are integers, but measured phase 231offset values are fractional with 3-digit decimal places and shell be 232divided with ``DPLL_PIN_PHASE_OFFSET_DIVIDER`` to get integer part and 233modulo divided to get fractional part. 234 235Phase offset monitor 236==================== 237 238Phase offset measurement is typically performed against the current active 239source. However, some DPLL (Digital Phase-Locked Loop) devices may offer 240the capability to monitor phase offsets across all available inputs. 241The attribute and current feature state shall be included in the response 242message of the ``DPLL_CMD_DEVICE_GET`` command for supported DPLL devices. 243In such cases, users can also control the feature using the 244``DPLL_CMD_DEVICE_SET`` command by setting the ``enum dpll_feature_state`` 245values for the attribute. 246Once enabled the phase offset measurements for the input shall be returned 247in the ``DPLL_A_PIN_PHASE_OFFSET`` attribute. 248 249 =============================== ======================== 250 ``DPLL_A_PHASE_OFFSET_MONITOR`` attr state of a feature 251 =============================== ======================== 252 253Frequency monitor 254================= 255 256Some DPLL devices may offer the capability to measure the actual 257frequency of all available input pins. The attribute and current feature state 258shall be included in the response message of the ``DPLL_CMD_DEVICE_GET`` 259command for supported DPLL devices. In such cases, users can also control 260the feature using the ``DPLL_CMD_DEVICE_SET`` command by setting the 261``enum dpll_feature_state`` values for the attribute. 262Once enabled the measured input frequency for each input pin shall be 263returned in the ``DPLL_A_PIN_MEASURED_FREQUENCY`` attribute. The value 264is in millihertz (mHz), using ``DPLL_PIN_MEASURED_FREQUENCY_DIVIDER`` 265as the divider. 266 267 =============================== ======================== 268 ``DPLL_A_FREQUENCY_MONITOR`` attr state of a feature 269 =============================== ======================== 270 271Embedded SYNC 272============= 273 274Device may provide ability to use Embedded SYNC feature. It allows 275to embed additional SYNC signal into the base frequency of a pin - a one 276special pulse of base frequency signal every time SYNC signal pulse 277happens. The user can configure the frequency of Embedded SYNC. 278The Embedded SYNC capability is always related to a given base frequency 279and HW capabilities. The user is provided a range of Embedded SYNC 280frequencies supported, depending on current base frequency configured for 281the pin. 282 283 ========================================= ================================= 284 ``DPLL_A_PIN_ESYNC_FREQUENCY`` current Embedded SYNC frequency 285 ``DPLL_A_PIN_ESYNC_FREQUENCY_SUPPORTED`` nest available Embedded SYNC 286 frequency ranges 287 ``DPLL_A_PIN_FREQUENCY_MIN`` attr minimum value of frequency 288 ``DPLL_A_PIN_FREQUENCY_MAX`` attr maximum value of frequency 289 ``DPLL_A_PIN_ESYNC_PULSE`` pulse type of Embedded SYNC 290 ========================================= ================================= 291 292Reference SYNC 293============== 294 295The device may support the Reference SYNC feature, which allows the combination 296of two inputs into a input pair. In this configuration, clock signals 297from both inputs are used to synchronize the DPLL device. The higher frequency 298signal is utilized for the loop bandwidth of the DPLL, while the lower frequency 299signal is used to syntonize the output signal of the DPLL device. This feature 300enables the provision of a high-quality loop bandwidth signal from an external 301source. 302 303A capable input provides a list of inputs that can be bound with to create 304Reference SYNC. To control this feature, the user must request a desired 305state for a target pin: use ``DPLL_PIN_STATE_CONNECTED`` to enable or 306``DPLL_PIN_STATE_DISCONNECTED`` to disable the feature. An input pin can be 307bound to only one other pin at any given time. 308 309 ============================== ========================================== 310 ``DPLL_A_PIN_REFERENCE_SYNC`` nested attribute for providing info or 311 requesting configuration of the Reference 312 SYNC feature 313 ``DPLL_A_PIN_ID`` target pin id for Reference SYNC feature 314 ``DPLL_A_PIN_STATE`` state of Reference SYNC connection 315 ============================== ========================================== 316 317Configuration commands group 318============================ 319 320Configuration commands are used to get information about registered 321dpll devices (and pins), as well as set configuration of device or pins. 322As dpll devices must be abstracted and reflect real hardware, 323there is no way to add new dpll device via netlink from user space and 324each device should be registered by its driver. 325 326All netlink commands require ``GENL_ADMIN_PERM``. This is to prevent 327any spamming/DoS from unauthorized userspace applications. 328 329List of netlink commands with possible attributes 330================================================= 331 332Constants identifying command types for dpll device uses a 333``DPLL_CMD_`` prefix and suffix according to command purpose. 334The dpll device related attributes use a ``DPLL_A_`` prefix and 335suffix according to attribute purpose. 336 337 ==================================== ================================= 338 ``DPLL_CMD_DEVICE_ID_GET`` command to get device ID 339 ``DPLL_A_MODULE_NAME`` attr module name of registerer 340 ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier 341 (EUI-64), as defined by the 342 IEEE 1588 standard 343 ``DPLL_A_TYPE`` attr type of dpll device 344 ==================================== ================================= 345 346 ==================================== ================================= 347 ``DPLL_CMD_DEVICE_GET`` command to get device info or 348 dump list of available devices 349 ``DPLL_A_ID`` attr unique dpll device ID 350 ``DPLL_A_MODULE_NAME`` attr module name of registerer 351 ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier 352 (EUI-64), as defined by the 353 IEEE 1588 standard 354 ``DPLL_A_MODE`` attr selection mode 355 ``DPLL_A_MODE_SUPPORTED`` attr available selection modes 356 ``DPLL_A_LOCK_STATUS`` attr dpll device lock status 357 ``DPLL_A_TEMP`` attr device temperature info 358 ``DPLL_A_TYPE`` attr type of dpll device 359 ==================================== ================================= 360 361 ==================================== ================================= 362 ``DPLL_CMD_DEVICE_SET`` command to set dpll device config 363 ``DPLL_A_ID`` attr internal dpll device index 364 ``DPLL_A_MODE`` attr selection mode to configure 365 ==================================== ================================= 366 367Constants identifying command types for pins uses a 368``DPLL_CMD_PIN_`` prefix and suffix according to command purpose. 369The pin related attributes use a ``DPLL_A_PIN_`` prefix and suffix 370according to attribute purpose. 371 372 ==================================== ================================= 373 ``DPLL_CMD_PIN_ID_GET`` command to get pin ID 374 ``DPLL_A_PIN_MODULE_NAME`` attr module name of registerer 375 ``DPLL_A_PIN_CLOCK_ID`` attr Unique Clock Identifier 376 (EUI-64), as defined by the 377 IEEE 1588 standard 378 ``DPLL_A_PIN_BOARD_LABEL`` attr pin board label provided 379 by registerer 380 ``DPLL_A_PIN_PANEL_LABEL`` attr pin panel label provided 381 by registerer 382 ``DPLL_A_PIN_PACKAGE_LABEL`` attr pin package label provided 383 by registerer 384 ``DPLL_A_PIN_TYPE`` attr type of a pin 385 ==================================== ================================= 386 387 ==================================== ================================== 388 ``DPLL_CMD_PIN_GET`` command to get pin info or dump 389 list of available pins 390 ``DPLL_A_PIN_ID`` attr unique a pin ID 391 ``DPLL_A_PIN_MODULE_NAME`` attr module name of registerer 392 ``DPLL_A_PIN_CLOCK_ID`` attr Unique Clock Identifier 393 (EUI-64), as defined by the 394 IEEE 1588 standard 395 ``DPLL_A_PIN_BOARD_LABEL`` attr pin board label provided 396 by registerer 397 ``DPLL_A_PIN_PANEL_LABEL`` attr pin panel label provided 398 by registerer 399 ``DPLL_A_PIN_PACKAGE_LABEL`` attr pin package label provided 400 by registerer 401 ``DPLL_A_PIN_TYPE`` attr type of a pin 402 ``DPLL_A_PIN_FREQUENCY`` attr current frequency of a pin 403 ``DPLL_A_PIN_FREQUENCY_SUPPORTED`` nested attr provides supported 404 frequencies 405 ``DPLL_A_PIN_ANY_FREQUENCY_MIN`` attr minimum value of frequency 406 ``DPLL_A_PIN_ANY_FREQUENCY_MAX`` attr maximum value of frequency 407 ``DPLL_A_PIN_PHASE_ADJUST_GRAN`` attr granularity of phase 408 adjustment value 409 ``DPLL_A_PIN_PHASE_ADJUST_MIN`` attr minimum value of phase 410 adjustment 411 ``DPLL_A_PIN_PHASE_ADJUST_MAX`` attr maximum value of phase 412 adjustment 413 ``DPLL_A_PIN_PHASE_ADJUST`` attr configured value of phase 414 adjustment on parent device 415 ``DPLL_A_PIN_PARENT_DEVICE`` nested attr for each parent device 416 the pin is connected with 417 ``DPLL_A_PIN_PARENT_ID`` attr parent dpll device id 418 ``DPLL_A_PIN_PRIO`` attr priority of pin on the 419 dpll device 420 ``DPLL_A_PIN_STATE`` attr state of pin on the parent 421 dpll device 422 ``DPLL_A_PIN_DIRECTION`` attr direction of a pin on the 423 parent dpll device 424 ``DPLL_A_PIN_PHASE_OFFSET`` attr measured phase difference 425 between a pin and parent dpll 426 ``DPLL_A_PIN_PARENT_PIN`` nested attr for each parent pin 427 the pin is connected with 428 ``DPLL_A_PIN_PARENT_ID`` attr parent pin id 429 ``DPLL_A_PIN_STATE`` attr state of pin on the parent 430 pin 431 ``DPLL_A_PIN_CAPABILITIES`` attr bitmask of pin capabilities 432 ``DPLL_A_PIN_MEASURED_FREQUENCY`` attr measured frequency of 433 an input pin in mHz 434 ==================================== ================================== 435 436 ==================================== ================================= 437 ``DPLL_CMD_PIN_SET`` command to set pins configuration 438 ``DPLL_A_PIN_ID`` attr unique a pin ID 439 ``DPLL_A_PIN_FREQUENCY`` attr requested frequency of a pin 440 ``DPLL_A_PIN_PHASE_ADJUST`` attr requested value of phase 441 adjustment on parent device 442 ``DPLL_A_PIN_PARENT_DEVICE`` nested attr for each parent dpll 443 device configuration request 444 ``DPLL_A_PIN_PARENT_ID`` attr parent dpll device id 445 ``DPLL_A_PIN_DIRECTION`` attr requested direction of a pin 446 ``DPLL_A_PIN_PRIO`` attr requested priority of pin on 447 the dpll device 448 ``DPLL_A_PIN_STATE`` attr requested state of pin on 449 the dpll device 450 ``DPLL_A_PIN_PARENT_PIN`` nested attr for each parent pin 451 configuration request 452 ``DPLL_A_PIN_PARENT_ID`` attr parent pin id 453 ``DPLL_A_PIN_STATE`` attr requested state of pin on 454 parent pin 455 ==================================== ================================= 456 457Netlink dump requests 458===================== 459 460The ``DPLL_CMD_DEVICE_GET`` and ``DPLL_CMD_PIN_GET`` commands are 461capable of dump type netlink requests, in which case the response is in 462the same format as for their ``do`` request, but every device or pin 463registered in the system is returned. 464 465SET commands format 466=================== 467 468``DPLL_CMD_DEVICE_SET`` - to target a dpll device, the user provides 469``DPLL_A_ID``, which is unique identifier of dpll device in the system, 470as well as parameter being configured (``DPLL_A_MODE``). 471 472``DPLL_CMD_PIN_SET`` - to target a pin user must provide a 473``DPLL_A_PIN_ID``, which is unique identifier of a pin in the system. 474Also configured pin parameters must be added. 475If ``DPLL_A_PIN_FREQUENCY`` is configured, this affects all the dpll 476devices that are connected with the pin, that is why frequency attribute 477shall not be enclosed in ``DPLL_A_PIN_PARENT_DEVICE``. 478Other attributes: ``DPLL_A_PIN_PRIO``, ``DPLL_A_PIN_STATE`` or 479``DPLL_A_PIN_DIRECTION`` must be enclosed in 480``DPLL_A_PIN_PARENT_DEVICE`` as their configuration relates to only one 481of parent dplls, targeted by ``DPLL_A_PIN_PARENT_ID`` attribute which is 482also required inside that nest. 483For MUX-type pins the ``DPLL_A_PIN_STATE`` attribute is configured in 484similar way, by enclosing required state in ``DPLL_A_PIN_PARENT_PIN`` 485nested attribute and targeted parent pin id in ``DPLL_A_PIN_PARENT_ID``. 486 487In general, it is possible to configure multiple parameters at once, but 488internally each parameter change will be invoked separately, where order 489of configuration is not guaranteed by any means. 490 491Configuration pre-defined enums 492=============================== 493 494.. kernel-doc:: include/uapi/linux/dpll.h 495 496Notifications 497============= 498 499dpll device can provide notifications regarding status changes of the 500device, i.e. lock status changes, input/output changes or other alarms. 501There is one multicast group that is used to notify user-space apps via 502netlink socket: ``DPLL_MCGRP_MONITOR`` 503 504Notifications messages: 505 506 ============================== ===================================== 507 ``DPLL_CMD_DEVICE_CREATE_NTF`` dpll device was created 508 ``DPLL_CMD_DEVICE_DELETE_NTF`` dpll device was deleted 509 ``DPLL_CMD_DEVICE_CHANGE_NTF`` dpll device has changed 510 ``DPLL_CMD_PIN_CREATE_NTF`` dpll pin was created 511 ``DPLL_CMD_PIN_DELETE_NTF`` dpll pin was deleted 512 ``DPLL_CMD_PIN_CHANGE_NTF`` dpll pin has changed 513 ============================== ===================================== 514 515Events format is the same as for the corresponding get command. 516Format of ``DPLL_CMD_DEVICE_`` events is the same as response of 517``DPLL_CMD_DEVICE_GET``. 518Format of ``DPLL_CMD_PIN_`` events is same as response of 519``DPLL_CMD_PIN_GET``. 520 521Device driver implementation 522============================ 523 524Device is allocated by dpll_device_get() call. Second call with the 525same arguments will not create new object but provides pointer to 526previously created device for given arguments, it also increases 527refcount of that object. 528Device is deallocated by dpll_device_put() call, which first 529decreases the refcount, once refcount is cleared the object is 530destroyed. 531 532Device should implement set of operations and register device via 533dpll_device_register() at which point it becomes available to the 534users. Multiple driver instances can obtain reference to it with 535dpll_device_get(), as well as register dpll device with their own 536ops and priv. 537 538The pins are allocated separately with dpll_pin_get(), it works 539similarly to dpll_device_get(). Function first creates object and then 540for each call with the same arguments only the object refcount 541increases. Also dpll_pin_put() works similarly to dpll_device_put(). 542 543A pin can be registered with parent dpll device or parent pin, depending 544on hardware needs. Each registration requires registerer to provide set 545of pin callbacks, and private data pointer for calling them: 546 547- dpll_pin_register() - register pin with a dpll device, 548- dpll_pin_on_pin_register() - register pin with another MUX type pin. 549 550Notifications of adding or removing dpll devices are created within 551subsystem itself. 552Notifications about registering/deregistering pins are also invoked by 553the subsystem. 554Notifications about status changes either of dpll device or a pin are 555invoked in two ways: 556 557- after successful change was requested on dpll subsystem, the subsystem 558 calls corresponding notification, 559- requested by device driver with dpll_device_change_ntf() or 560 dpll_pin_change_ntf() when driver informs about the status change. 561 562The device driver using dpll interface is not required to implement all 563the callback operation. Nevertheless, there are few required to be 564implemented. 565Required dpll device level callback operations: 566 567- ``.mode_get``, 568- ``.lock_status_get``. 569 570Required pin level callback operations: 571 572- ``.state_on_dpll_get`` (pins registered with dpll device), 573- ``.state_on_pin_get`` (pins registered with parent pin), 574- ``.direction_get``. 575 576Every other operation handler is checked for existence and 577``-EOPNOTSUPP`` is returned in case of absence of specific handler. 578 579The simplest implementation is in the OCP TimeCard driver. The ops 580structures are defined like this: 581 582.. code-block:: c 583 584 static const struct dpll_device_ops dpll_ops = { 585 .lock_status_get = ptp_ocp_dpll_lock_status_get, 586 .mode_get = ptp_ocp_dpll_mode_get, 587 .mode_supported = ptp_ocp_dpll_mode_supported, 588 }; 589 590 static const struct dpll_pin_ops dpll_pins_ops = { 591 .frequency_get = ptp_ocp_dpll_frequency_get, 592 .frequency_set = ptp_ocp_dpll_frequency_set, 593 .direction_get = ptp_ocp_dpll_direction_get, 594 .direction_set = ptp_ocp_dpll_direction_set, 595 .state_on_dpll_get = ptp_ocp_dpll_state_get, 596 }; 597 598The registration part is then looks like this part: 599 600.. code-block:: c 601 602 clkid = pci_get_dsn(pdev); 603 bp->dpll = dpll_device_get(clkid, 0, THIS_MODULE); 604 if (IS_ERR(bp->dpll)) { 605 err = PTR_ERR(bp->dpll); 606 dev_err(&pdev->dev, "dpll_device_alloc failed\n"); 607 goto out; 608 } 609 610 err = dpll_device_register(bp->dpll, DPLL_TYPE_PPS, &dpll_ops, bp); 611 if (err) 612 goto out; 613 614 for (i = 0; i < OCP_SMA_NUM; i++) { 615 bp->sma[i].dpll_pin = dpll_pin_get(clkid, i, THIS_MODULE, &bp->sma[i].dpll_prop); 616 if (IS_ERR(bp->sma[i].dpll_pin)) { 617 err = PTR_ERR(bp->dpll); 618 goto out_dpll; 619 } 620 621 err = dpll_pin_register(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops, 622 &bp->sma[i]); 623 if (err) { 624 dpll_pin_put(bp->sma[i].dpll_pin); 625 goto out_dpll; 626 } 627 } 628 629In the error path we have to rewind every allocation in the reverse order: 630 631.. code-block:: c 632 633 while (i) { 634 --i; 635 dpll_pin_unregister(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops, &bp->sma[i]); 636 dpll_pin_put(bp->sma[i].dpll_pin); 637 } 638 dpll_device_put(bp->dpll); 639 640More complex example can be found in Intel's ICE driver or nVidia's mlx5 driver. 641 642SyncE enablement 643================ 644For SyncE enablement it is required to allow control over dpll device 645for a software application which monitors and configures the inputs of 646dpll device in response to current state of a dpll device and its 647inputs. 648In such scenario, dpll device input signal shall be also configurable 649to drive dpll with signal recovered from the PHY netdevice. 650This is done by exposing a pin to the netdevice - attaching pin to the 651netdevice itself with 652``dpll_netdev_pin_set(struct net_device *dev, struct dpll_pin *dpll_pin)``. 653Exposed pin id handle ``DPLL_A_PIN_ID`` is then identifiable by the user 654as it is attached to rtnetlink respond to get ``RTM_NEWLINK`` command in 655nested attribute ``IFLA_DPLL_PIN``. 656