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
220 Device may provide ability to use Embedded SYNC feature. It allows
221 to embed additional SYNC signal into the base frequency of a pin - a one
242 dpll devices (and pins), as well as set configuration of device or pins.
244 there is no way to add new dpll device via netlink from user space and
245 each device should be registered by its driver.
253 Constants identifying command types for dpll device uses a
255 The dpll device related attributes use a ``DPLL_A_`` prefix and
259 ``DPLL_CMD_DEVICE_ID_GET`` command to get device ID
261 ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier
262 (EUI-64), as defined by the
264 ``DPLL_A_TYPE`` attr type of dpll device
268 ``DPLL_CMD_DEVICE_GET`` command to get device info or
270 ``DPLL_A_ID`` attr unique dpll device ID
272 ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier
273 (EUI-64), as defined by the
277 ``DPLL_A_LOCK_STATUS`` attr dpll device lock status
278 ``DPLL_A_TEMP`` attr device temperature info
279 ``DPLL_A_TYPE`` attr type of dpll device
283 ``DPLL_CMD_DEVICE_SET`` command to set dpll device config
284 ``DPLL_A_ID`` attr internal dpll device index
296 ``DPLL_A_PIN_CLOCK_ID`` attr Unique Clock Identifier
297 (EUI-64), as defined by the
311 ``DPLL_A_PIN_ID`` attr unique a pin ID
313 ``DPLL_A_PIN_CLOCK_ID`` attr Unique Clock Identifier
314 (EUI-64), as defined by the
333 adjustment on parent device
334 ``DPLL_A_PIN_PARENT_DEVICE`` nested attr for each parent device
336 ``DPLL_A_PIN_PARENT_ID`` attr parent dpll device id
338 dpll device
340 dpll device
342 parent dpll device
355 ``DPLL_A_PIN_ID`` attr unique a pin ID
358 adjustment on parent device
360 device configuration request
361 ``DPLL_A_PIN_PARENT_ID`` attr parent dpll device id
364 the dpll device
366 the dpll device
379 the same format as for their ``do`` request, but every device or pin
385 ``DPLL_CMD_DEVICE_SET`` - to target a dpll device, the user provides
386 ``DPLL_A_ID``, which is unique identifier of dpll device in the system,
389 ``DPLL_CMD_PIN_SET`` - to target a pin user must provide a
390 ``DPLL_A_PIN_ID``, which is unique identifier of a pin in the system.
400 For MUX-type pins the ``DPLL_A_PIN_STATE`` attribute is configured in
408 Configuration pre-defined enums
411 .. kernel-doc:: include/uapi/linux/dpll.h
416 dpll device can provide notifications regarding status changes of the
417 device, i.e. lock status changes, input/output changes or other alarms.
418 There is one multicast group that is used to notify user-space apps via
424 ``DPLL_CMD_DEVICE_CREATE_NTF`` dpll device was created
425 ``DPLL_CMD_DEVICE_DELETE_NTF`` dpll device was deleted
426 ``DPLL_CMD_DEVICE_CHANGE_NTF`` dpll device has changed
438 Device driver implementation
441 Device is allocated by dpll_device_get() call. Second call with the
443 previously created device for given arguments, it also increases
445 Device is deallocated by dpll_device_put() call, which first
449 Device should implement set of operations and register device via
452 dpll_device_get(), as well as register dpll device with their own
460 A pin can be registered with parent dpll device or parent pin, depending
464 - dpll_pin_register() - register pin with a dpll device,
465 - dpll_pin_on_pin_register() - register pin with another MUX type pin.
471 Notifications about status changes either of dpll device or a pin are
474 - after successful change was requested on dpll subsystem, the subsystem
476 - requested by device driver with dpll_device_change_ntf() or
479 The device driver using dpll interface is not required to implement all
482 Required dpll device level callback operations:
484 - ``.mode_get``,
485 - ``.lock_status_get``.
489 - ``.state_on_dpll_get`` (pins registered with dpll device),
490 - ``.state_on_pin_get`` (pins registered with parent pin),
491 - ``.direction_get``.
494 ``-EOPNOTSUPP`` is returned in case of absence of specific handler.
499 .. code-block:: c
517 .. code-block:: c
520 bp->dpll = dpll_device_get(clkid, 0, THIS_MODULE);
521 if (IS_ERR(bp->dpll)) {
522 err = PTR_ERR(bp->dpll);
523 dev_err(&pdev->dev, "dpll_device_alloc failed\n");
527 err = dpll_device_register(bp->dpll, DPLL_TYPE_PPS, &dpll_ops, bp);
532 bp->sma[i].dpll_pin = dpll_pin_get(clkid, i, THIS_MODULE, &bp->sma[i].dpll_prop);
533 if (IS_ERR(bp->sma[i].dpll_pin)) {
534 err = PTR_ERR(bp->dpll);
538 err = dpll_pin_register(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops,
539 &bp->sma[i]);
541 dpll_pin_put(bp->sma[i].dpll_pin);
548 .. code-block:: c
551 --i;
552 dpll_pin_unregister(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops, &bp->sma[i]);
553 dpll_pin_put(bp->sma[i].dpll_pin);
555 dpll_device_put(bp->dpll);
561 For SyncE enablement it is required to allow control over dpll device
563 dpll device in response to current state of a dpll device and its
565 In such scenario, dpll device input signal shall be also configurable
567 This is done by exposing a pin to the netdevice - attaching pin to the