Lines Matching +full:device +full:- +full:unique
1 .. SPDX-License-Identifier: GPL-2.0
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.
14 DPLL - Digital Phase Locked Loop is an integrated circuit which in
29 Device object
32 Single dpll device object means single Digital PLL circuit and bunch of
38 Changing the configuration of dpll device is done with `do` request of
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
44 attributes that result in single device match.
50 could be internal component of the device, as well as externally
53 provided for a single dpll device.
69 device) can be obtained from ``DPLL_A_PIN_STATE`` attribute, and only
71 device.
74 on hardware capabilities and active dpll device work mode
77 for the states the user can request for a dpll device.
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
89 - ``DPLL_PIN_STATE_SELECTABLE`` - the pin shall be considered as valid
91 - ``DPLL_PIN_STATE_DISCONNECTED`` - the pin shall be not considered as
96 algorithm locks a dpll device with one of the inputs.
104 1) Set on a pin - the configuration affects all dpll devices pin is
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``,
110 MUX-type pins
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
121 ``DPLL_CMD_PIN_GET`` would contain multiple pin-parent nested
125 'clock-id': 282574471561216,
126 'module-name': 'ice',
129 'parent-pin': [
130 {'parent-id': 2, 'state': 'connected'},
131 {'parent-id': 3, 'state': 'disconnected'}
133 'type': 'synce-eth-port'
136 Only one child pin can provide its signal to the parent MUX-type pin at
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
161 device. Example of netlink `set priority on parent pin` message format:
166 related to parent dpll device
167 ``DPLL_A_PIN_PARENT_ID`` parent dpll device id
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
174 as described in the ``MUX-type pins`` chapter.
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
182 attribute for each parent dpll device.
184 Device may also provide ability to adjust a signal phase on a pin.
197 adjustment on parent dpll device
200 device
201 ``DPLL_A_PIN_PARENT_ID`` parent dpll device id
203 between a pin and parent dpll device
213 offset values are fractional with 3-digit decimal places and shell be
221 dpll devices (and pins), as well as set configuration of device or pins.
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.
232 Constants identifying command types for dpll device uses a
234 The dpll device related attributes use a ``DPLL_A_`` prefix and
238 ``DPLL_CMD_DEVICE_ID_GET`` command to get device ID
240 ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier
241 (EUI-64), as defined by the
243 ``DPLL_A_TYPE`` attr type of dpll device
247 ``DPLL_CMD_DEVICE_GET`` command to get device info or
249 ``DPLL_A_ID`` attr unique dpll device ID
251 ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier
252 (EUI-64), as defined by the
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
262 ``DPLL_CMD_DEVICE_SET`` command to set dpll device config
263 ``DPLL_A_ID`` attr internal dpll device index
275 ``DPLL_A_PIN_CLOCK_ID`` attr Unique Clock Identifier
276 (EUI-64), as defined by the
290 ``DPLL_A_PIN_ID`` attr unique a pin ID
292 ``DPLL_A_PIN_CLOCK_ID`` attr Unique Clock Identifier
293 (EUI-64), as defined by the
312 adjustment on parent device
313 ``DPLL_A_PIN_PARENT_DEVICE`` nested attr for each parent device
315 ``DPLL_A_PIN_PARENT_ID`` attr parent dpll device id
317 dpll device
319 dpll device
321 parent dpll device
334 ``DPLL_A_PIN_ID`` attr unique a pin ID
337 adjustment on parent device
339 device configuration request
340 ``DPLL_A_PIN_PARENT_ID`` attr parent dpll device id
343 the dpll device
345 the dpll device
358 the same format as for their ``do`` request, but every device or pin
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,
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.
379 For MUX-type pins the ``DPLL_A_PIN_STATE`` attribute is configured in
387 Configuration pre-defined enums
390 .. kernel-doc:: include/uapi/linux/dpll.h
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
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
417 Device driver implementation
420 Device is allocated by dpll_device_get() call. Second call with the
422 previously created device for given arguments, it also increases
424 Device is deallocated by dpll_device_put() call, which first
428 Device should implement set of operations and register device via
431 dpll_device_get(), as well as register dpll device with their own
439 A pin can be registered with parent dpll device or parent pin, depending
443 - dpll_pin_register() - register pin with a dpll device,
444 - dpll_pin_on_pin_register() - register pin with another MUX type pin.
450 Notifications about status changes either of dpll device or a pin are
453 - after successful change was requested on dpll subsystem, the subsystem
455 - requested by device driver with dpll_device_change_ntf() or
458 The device driver using dpll interface is not required to implement all
461 Required dpll device level callback operations:
463 - ``.mode_get``,
464 - ``.lock_status_get``.
468 - ``.state_on_dpll_get`` (pins registered with dpll device),
469 - ``.state_on_pin_get`` (pins registered with parent pin),
470 - ``.direction_get``.
473 ``-EOPNOTSUPP`` is returned in case of absence of specific handler.
478 .. code-block:: c
496 .. code-block:: c
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");
506 err = dpll_device_register(bp->dpll, DPLL_TYPE_PPS, &dpll_ops, bp);
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);
517 err = dpll_pin_register(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops,
518 &bp->sma[i]);
520 dpll_pin_put(bp->sma[i].dpll_pin);
527 .. code-block:: c
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);
534 dpll_device_put(bp->dpll);
540 For SyncE enablement it is required to allow control over dpll device
542 dpll device in response to current state of a dpll device and its
544 In such scenario, dpll device input signal shall be also configurable
546 This is done by exposing a pin to the netdevice - attaching pin to the