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. 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 pin 186handle shall be provide to the user on ``DPLL_CMD_PIN_GET`` respond 187with ``DPLL_A_PIN_PHASE_ADJUST_MIN`` and ``DPLL_A_PIN_PHASE_ADJUST_MAX`` 188attributes. Configured phase adjust value is provided with 189``DPLL_A_PIN_PHASE_ADJUST`` attribute of a pin, and value change can be 190requested with the same attribute with ``DPLL_CMD_PIN_SET`` command. 191 192 =============================== ====================================== 193 ``DPLL_A_PIN_ID`` configured pin id 194 ``DPLL_A_PIN_PHASE_ADJUST_MIN`` attr minimum value of phase adjustment 195 ``DPLL_A_PIN_PHASE_ADJUST_MAX`` attr maximum value of phase adjustment 196 ``DPLL_A_PIN_PHASE_ADJUST`` attr configured value of phase 197 adjustment on parent dpll device 198 ``DPLL_A_PIN_PARENT_DEVICE`` nested attribute for requesting 199 configuration on given parent dpll 200 device 201 ``DPLL_A_PIN_PARENT_ID`` parent dpll device id 202 ``DPLL_A_PIN_PHASE_OFFSET`` attr measured phase difference 203 between a pin and parent dpll device 204 =============================== ====================================== 205 206All phase related values are provided in pico seconds, which represents 207time difference between signals phase. The negative value means that 208phase of signal on pin is earlier in time than dpll's signal. Positive 209value means that phase of signal on pin is later in time than signal of 210a dpll. 211 212Phase adjust (also min and max) values are integers, but measured phase 213offset values are fractional with 3-digit decimal places and shell be 214divided with ``DPLL_PIN_PHASE_OFFSET_DIVIDER`` to get integer part and 215modulo divided to get fractional part. 216 217Phase offset monitor 218==================== 219 220Phase offset measurement is typically performed against the current active 221source. However, some DPLL (Digital Phase-Locked Loop) devices may offer 222the capability to monitor phase offsets across all available inputs. 223The attribute and current feature state shall be included in the response 224message of the ``DPLL_CMD_DEVICE_GET`` command for supported DPLL devices. 225In such cases, users can also control the feature using the 226``DPLL_CMD_DEVICE_SET`` command by setting the ``enum dpll_feature_state`` 227values for the attribute. 228Once enabled the phase offset measurements for the input shall be returned 229in the ``DPLL_A_PIN_PHASE_OFFSET`` attribute. 230 231 =============================== ======================== 232 ``DPLL_A_PHASE_OFFSET_MONITOR`` attr state of a feature 233 =============================== ======================== 234 235Embedded SYNC 236============= 237 238Device may provide ability to use Embedded SYNC feature. It allows 239to embed additional SYNC signal into the base frequency of a pin - a one 240special pulse of base frequency signal every time SYNC signal pulse 241happens. The user can configure the frequency of Embedded SYNC. 242The Embedded SYNC capability is always related to a given base frequency 243and HW capabilities. The user is provided a range of Embedded SYNC 244frequencies supported, depending on current base frequency configured for 245the pin. 246 247 ========================================= ================================= 248 ``DPLL_A_PIN_ESYNC_FREQUENCY`` current Embedded SYNC frequency 249 ``DPLL_A_PIN_ESYNC_FREQUENCY_SUPPORTED`` nest available Embedded SYNC 250 frequency ranges 251 ``DPLL_A_PIN_FREQUENCY_MIN`` attr minimum value of frequency 252 ``DPLL_A_PIN_FREQUENCY_MAX`` attr maximum value of frequency 253 ``DPLL_A_PIN_ESYNC_PULSE`` pulse type of Embedded SYNC 254 ========================================= ================================= 255 256Configuration commands group 257============================ 258 259Configuration commands are used to get information about registered 260dpll devices (and pins), as well as set configuration of device or pins. 261As dpll devices must be abstracted and reflect real hardware, 262there is no way to add new dpll device via netlink from user space and 263each device should be registered by its driver. 264 265All netlink commands require ``GENL_ADMIN_PERM``. This is to prevent 266any spamming/DoS from unauthorized userspace applications. 267 268List of netlink commands with possible attributes 269================================================= 270 271Constants identifying command types for dpll device uses a 272``DPLL_CMD_`` prefix and suffix according to command purpose. 273The dpll device related attributes use a ``DPLL_A_`` prefix and 274suffix according to attribute purpose. 275 276 ==================================== ================================= 277 ``DPLL_CMD_DEVICE_ID_GET`` command to get device ID 278 ``DPLL_A_MODULE_NAME`` attr module name of registerer 279 ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier 280 (EUI-64), as defined by the 281 IEEE 1588 standard 282 ``DPLL_A_TYPE`` attr type of dpll device 283 ==================================== ================================= 284 285 ==================================== ================================= 286 ``DPLL_CMD_DEVICE_GET`` command to get device info or 287 dump list of available devices 288 ``DPLL_A_ID`` attr unique dpll device ID 289 ``DPLL_A_MODULE_NAME`` attr module name of registerer 290 ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier 291 (EUI-64), as defined by the 292 IEEE 1588 standard 293 ``DPLL_A_MODE`` attr selection mode 294 ``DPLL_A_MODE_SUPPORTED`` attr available selection modes 295 ``DPLL_A_LOCK_STATUS`` attr dpll device lock status 296 ``DPLL_A_TEMP`` attr device temperature info 297 ``DPLL_A_TYPE`` attr type of dpll device 298 ==================================== ================================= 299 300 ==================================== ================================= 301 ``DPLL_CMD_DEVICE_SET`` command to set dpll device config 302 ``DPLL_A_ID`` attr internal dpll device index 303 ``DPLL_A_MODE`` attr selection mode to configure 304 ==================================== ================================= 305 306Constants identifying command types for pins uses a 307``DPLL_CMD_PIN_`` prefix and suffix according to command purpose. 308The pin related attributes use a ``DPLL_A_PIN_`` prefix and suffix 309according to attribute purpose. 310 311 ==================================== ================================= 312 ``DPLL_CMD_PIN_ID_GET`` command to get pin ID 313 ``DPLL_A_PIN_MODULE_NAME`` attr module name of registerer 314 ``DPLL_A_PIN_CLOCK_ID`` attr Unique Clock Identifier 315 (EUI-64), as defined by the 316 IEEE 1588 standard 317 ``DPLL_A_PIN_BOARD_LABEL`` attr pin board label provided 318 by registerer 319 ``DPLL_A_PIN_PANEL_LABEL`` attr pin panel label provided 320 by registerer 321 ``DPLL_A_PIN_PACKAGE_LABEL`` attr pin package label provided 322 by registerer 323 ``DPLL_A_PIN_TYPE`` attr type of a pin 324 ==================================== ================================= 325 326 ==================================== ================================== 327 ``DPLL_CMD_PIN_GET`` command to get pin info or dump 328 list of available pins 329 ``DPLL_A_PIN_ID`` attr unique a pin ID 330 ``DPLL_A_PIN_MODULE_NAME`` attr module name of registerer 331 ``DPLL_A_PIN_CLOCK_ID`` attr Unique Clock Identifier 332 (EUI-64), as defined by the 333 IEEE 1588 standard 334 ``DPLL_A_PIN_BOARD_LABEL`` attr pin board label provided 335 by registerer 336 ``DPLL_A_PIN_PANEL_LABEL`` attr pin panel label provided 337 by registerer 338 ``DPLL_A_PIN_PACKAGE_LABEL`` attr pin package label provided 339 by registerer 340 ``DPLL_A_PIN_TYPE`` attr type of a pin 341 ``DPLL_A_PIN_FREQUENCY`` attr current frequency of a pin 342 ``DPLL_A_PIN_FREQUENCY_SUPPORTED`` nested attr provides supported 343 frequencies 344 ``DPLL_A_PIN_ANY_FREQUENCY_MIN`` attr minimum value of frequency 345 ``DPLL_A_PIN_ANY_FREQUENCY_MAX`` attr maximum value of frequency 346 ``DPLL_A_PIN_PHASE_ADJUST_MIN`` attr minimum value of phase 347 adjustment 348 ``DPLL_A_PIN_PHASE_ADJUST_MAX`` attr maximum value of phase 349 adjustment 350 ``DPLL_A_PIN_PHASE_ADJUST`` attr configured value of phase 351 adjustment on parent device 352 ``DPLL_A_PIN_PARENT_DEVICE`` nested attr for each parent device 353 the pin is connected with 354 ``DPLL_A_PIN_PARENT_ID`` attr parent dpll device id 355 ``DPLL_A_PIN_PRIO`` attr priority of pin on the 356 dpll device 357 ``DPLL_A_PIN_STATE`` attr state of pin on the parent 358 dpll device 359 ``DPLL_A_PIN_DIRECTION`` attr direction of a pin on the 360 parent dpll device 361 ``DPLL_A_PIN_PHASE_OFFSET`` attr measured phase difference 362 between a pin and parent dpll 363 ``DPLL_A_PIN_PARENT_PIN`` nested attr for each parent pin 364 the pin is connected with 365 ``DPLL_A_PIN_PARENT_ID`` attr parent pin id 366 ``DPLL_A_PIN_STATE`` attr state of pin on the parent 367 pin 368 ``DPLL_A_PIN_CAPABILITIES`` attr bitmask of pin capabilities 369 ==================================== ================================== 370 371 ==================================== ================================= 372 ``DPLL_CMD_PIN_SET`` command to set pins configuration 373 ``DPLL_A_PIN_ID`` attr unique a pin ID 374 ``DPLL_A_PIN_FREQUENCY`` attr requested frequency of a pin 375 ``DPLL_A_PIN_PHASE_ADJUST`` attr requested value of phase 376 adjustment on parent device 377 ``DPLL_A_PIN_PARENT_DEVICE`` nested attr for each parent dpll 378 device configuration request 379 ``DPLL_A_PIN_PARENT_ID`` attr parent dpll device id 380 ``DPLL_A_PIN_DIRECTION`` attr requested direction of a pin 381 ``DPLL_A_PIN_PRIO`` attr requested priority of pin on 382 the dpll device 383 ``DPLL_A_PIN_STATE`` attr requested state of pin on 384 the dpll device 385 ``DPLL_A_PIN_PARENT_PIN`` nested attr for each parent pin 386 configuration request 387 ``DPLL_A_PIN_PARENT_ID`` attr parent pin id 388 ``DPLL_A_PIN_STATE`` attr requested state of pin on 389 parent pin 390 ==================================== ================================= 391 392Netlink dump requests 393===================== 394 395The ``DPLL_CMD_DEVICE_GET`` and ``DPLL_CMD_PIN_GET`` commands are 396capable of dump type netlink requests, in which case the response is in 397the same format as for their ``do`` request, but every device or pin 398registered in the system is returned. 399 400SET commands format 401=================== 402 403``DPLL_CMD_DEVICE_SET`` - to target a dpll device, the user provides 404``DPLL_A_ID``, which is unique identifier of dpll device in the system, 405as well as parameter being configured (``DPLL_A_MODE``). 406 407``DPLL_CMD_PIN_SET`` - to target a pin user must provide a 408``DPLL_A_PIN_ID``, which is unique identifier of a pin in the system. 409Also configured pin parameters must be added. 410If ``DPLL_A_PIN_FREQUENCY`` is configured, this affects all the dpll 411devices that are connected with the pin, that is why frequency attribute 412shall not be enclosed in ``DPLL_A_PIN_PARENT_DEVICE``. 413Other attributes: ``DPLL_A_PIN_PRIO``, ``DPLL_A_PIN_STATE`` or 414``DPLL_A_PIN_DIRECTION`` must be enclosed in 415``DPLL_A_PIN_PARENT_DEVICE`` as their configuration relates to only one 416of parent dplls, targeted by ``DPLL_A_PIN_PARENT_ID`` attribute which is 417also required inside that nest. 418For MUX-type pins the ``DPLL_A_PIN_STATE`` attribute is configured in 419similar way, by enclosing required state in ``DPLL_A_PIN_PARENT_PIN`` 420nested attribute and targeted parent pin id in ``DPLL_A_PIN_PARENT_ID``. 421 422In general, it is possible to configure multiple parameters at once, but 423internally each parameter change will be invoked separately, where order 424of configuration is not guaranteed by any means. 425 426Configuration pre-defined enums 427=============================== 428 429.. kernel-doc:: include/uapi/linux/dpll.h 430 431Notifications 432============= 433 434dpll device can provide notifications regarding status changes of the 435device, i.e. lock status changes, input/output changes or other alarms. 436There is one multicast group that is used to notify user-space apps via 437netlink socket: ``DPLL_MCGRP_MONITOR`` 438 439Notifications messages: 440 441 ============================== ===================================== 442 ``DPLL_CMD_DEVICE_CREATE_NTF`` dpll device was created 443 ``DPLL_CMD_DEVICE_DELETE_NTF`` dpll device was deleted 444 ``DPLL_CMD_DEVICE_CHANGE_NTF`` dpll device has changed 445 ``DPLL_CMD_PIN_CREATE_NTF`` dpll pin was created 446 ``DPLL_CMD_PIN_DELETE_NTF`` dpll pin was deleted 447 ``DPLL_CMD_PIN_CHANGE_NTF`` dpll pin has changed 448 ============================== ===================================== 449 450Events format is the same as for the corresponding get command. 451Format of ``DPLL_CMD_DEVICE_`` events is the same as response of 452``DPLL_CMD_DEVICE_GET``. 453Format of ``DPLL_CMD_PIN_`` events is same as response of 454``DPLL_CMD_PIN_GET``. 455 456Device driver implementation 457============================ 458 459Device is allocated by dpll_device_get() call. Second call with the 460same arguments will not create new object but provides pointer to 461previously created device for given arguments, it also increases 462refcount of that object. 463Device is deallocated by dpll_device_put() call, which first 464decreases the refcount, once refcount is cleared the object is 465destroyed. 466 467Device should implement set of operations and register device via 468dpll_device_register() at which point it becomes available to the 469users. Multiple driver instances can obtain reference to it with 470dpll_device_get(), as well as register dpll device with their own 471ops and priv. 472 473The pins are allocated separately with dpll_pin_get(), it works 474similarly to dpll_device_get(). Function first creates object and then 475for each call with the same arguments only the object refcount 476increases. Also dpll_pin_put() works similarly to dpll_device_put(). 477 478A pin can be registered with parent dpll device or parent pin, depending 479on hardware needs. Each registration requires registerer to provide set 480of pin callbacks, and private data pointer for calling them: 481 482- dpll_pin_register() - register pin with a dpll device, 483- dpll_pin_on_pin_register() - register pin with another MUX type pin. 484 485Notifications of adding or removing dpll devices are created within 486subsystem itself. 487Notifications about registering/deregistering pins are also invoked by 488the subsystem. 489Notifications about status changes either of dpll device or a pin are 490invoked in two ways: 491 492- after successful change was requested on dpll subsystem, the subsystem 493 calls corresponding notification, 494- requested by device driver with dpll_device_change_ntf() or 495 dpll_pin_change_ntf() when driver informs about the status change. 496 497The device driver using dpll interface is not required to implement all 498the callback operation. Nevertheless, there are few required to be 499implemented. 500Required dpll device level callback operations: 501 502- ``.mode_get``, 503- ``.lock_status_get``. 504 505Required pin level callback operations: 506 507- ``.state_on_dpll_get`` (pins registered with dpll device), 508- ``.state_on_pin_get`` (pins registered with parent pin), 509- ``.direction_get``. 510 511Every other operation handler is checked for existence and 512``-EOPNOTSUPP`` is returned in case of absence of specific handler. 513 514The simplest implementation is in the OCP TimeCard driver. The ops 515structures are defined like this: 516 517.. code-block:: c 518 519 static const struct dpll_device_ops dpll_ops = { 520 .lock_status_get = ptp_ocp_dpll_lock_status_get, 521 .mode_get = ptp_ocp_dpll_mode_get, 522 .mode_supported = ptp_ocp_dpll_mode_supported, 523 }; 524 525 static const struct dpll_pin_ops dpll_pins_ops = { 526 .frequency_get = ptp_ocp_dpll_frequency_get, 527 .frequency_set = ptp_ocp_dpll_frequency_set, 528 .direction_get = ptp_ocp_dpll_direction_get, 529 .direction_set = ptp_ocp_dpll_direction_set, 530 .state_on_dpll_get = ptp_ocp_dpll_state_get, 531 }; 532 533The registration part is then looks like this part: 534 535.. code-block:: c 536 537 clkid = pci_get_dsn(pdev); 538 bp->dpll = dpll_device_get(clkid, 0, THIS_MODULE); 539 if (IS_ERR(bp->dpll)) { 540 err = PTR_ERR(bp->dpll); 541 dev_err(&pdev->dev, "dpll_device_alloc failed\n"); 542 goto out; 543 } 544 545 err = dpll_device_register(bp->dpll, DPLL_TYPE_PPS, &dpll_ops, bp); 546 if (err) 547 goto out; 548 549 for (i = 0; i < OCP_SMA_NUM; i++) { 550 bp->sma[i].dpll_pin = dpll_pin_get(clkid, i, THIS_MODULE, &bp->sma[i].dpll_prop); 551 if (IS_ERR(bp->sma[i].dpll_pin)) { 552 err = PTR_ERR(bp->dpll); 553 goto out_dpll; 554 } 555 556 err = dpll_pin_register(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops, 557 &bp->sma[i]); 558 if (err) { 559 dpll_pin_put(bp->sma[i].dpll_pin); 560 goto out_dpll; 561 } 562 } 563 564In the error path we have to rewind every allocation in the reverse order: 565 566.. code-block:: c 567 568 while (i) { 569 --i; 570 dpll_pin_unregister(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops, &bp->sma[i]); 571 dpll_pin_put(bp->sma[i].dpll_pin); 572 } 573 dpll_device_put(bp->dpll); 574 575More complex example can be found in Intel's ICE driver or nVidia's mlx5 driver. 576 577SyncE enablement 578================ 579For SyncE enablement it is required to allow control over dpll device 580for a software application which monitors and configures the inputs of 581dpll device in response to current state of a dpll device and its 582inputs. 583In such scenario, dpll device input signal shall be also configurable 584to drive dpll with signal recovered from the PHY netdevice. 585This is done by exposing a pin to the netdevice - attaching pin to the 586netdevice itself with 587``dpll_netdev_pin_set(struct net_device *dev, struct dpll_pin *dpll_pin)``. 588Exposed pin id handle ``DPLL_A_PIN_ID`` is then identifiable by the user 589as it is attached to rtnetlink respond to get ``RTM_NEWLINK`` command in 590nested attribute ``IFLA_DPLL_PIN``. 591