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