Documentation/driver-api/dpll.rst

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