The Linux kernel dpll subsystem

Linux kernel dpll subsystem과 DPLL 정의

SPDX license identifier는 `GPL-2.0`입니다.

PLL(Phase Locked Loop)은 device clock signal을 외부 clock signal에 syntonize해 PLL input과 같은 clock beat로 device를 동작시키는 electronic circuit입니다.

DPLL(Digital Phase Locked Loop)은 일반 PLL 동작에 digital phase detector를 포함하고 loop 안에 digital divider를 둘 수 있는 integrated circuit입니다. 따라서 DPLL input과 output frequency를 구성할 수 있습니다.

Subsystem과 device object

dpll subsystem의 주 목적은 여러 input synchronization source와 여러 output type을 사용할 수 있는 Digital PLL device를 구성하는 general interface를 제공하는 것입니다. 주 interface는 event monitoring multicast group을 정의한 `NETLINK_GENERIC` protocol입니다.

dpll device object 하나는 Digital PLL circuit 하나와 연결된 pin 집합을 뜻합니다. `DPLL_CMD_DEVICE_GET` netlink command의 `do` request에는 지원 operation mode와 현재 status를 반환하고, 같은 command의 `dump` request에는 subsystem에 등록된 DPLL 목록을 반환합니다. `DPLL_CMD_DEVICE_SET`의 `do` request로 configuration을 변경합니다.

device handle은 `DPLL_A_ID`이며 특정 device의 configuration을 get/set할 때 제공해야 합니다. `DPLL_CMD_DEVICE_GET` dump 또는 하나의 device만 match하도록 attribute를 제공한 `DPLL_CMD_DEVICE_ID_GET` do request로 얻습니다.

Pin object

pin은 input 또는 output을 나타내는 amorphic object이며 device 내부 component일 수도, 외부 연결일 수도 있습니다. dpll마다 pin 수는 다르지만 보통 device 하나에 여러 pin이 제공됩니다.

`DPLL_CMD_PIN_GET`의 do request는 pin property, capability와 status를 반환하고 dump request는 system에 등록된 모든 pin을 나열합니다. `DPLL_CMD_PIN_SET` do request로 configuration을 바꿉니다.

pin handle은 `DPLL_A_PIN_ID`이며 특정 pin을 get/set할 때 필요합니다. `DPLL_CMD_PIN_GET` dump 또는 하나의 pin만 match하도록 attribute를 제공한 `DPLL_CMD_PIN_ID_GET` do request로 얻습니다.

Pin selection

일반적으로 DPLL을 drive하는 selected pin은 `DPLL_A_PIN_STATE`에서 확인하며, dpll device마다 `DPLL_PIN_STATE_CONNECTED` 상태의 pin은 하나만 있어야 합니다.

pin selection은 hardware capability와 `DPLL_A_MODE`의 active work mode에 따라 manual 또는 automatic으로 수행합니다. mode마다 사용할 수 있는 pin state와 user가 요청할 수 있는 state가 다릅니다.

• `DPLL_MODE_MANUAL`: `DPLL_PIN_STATE_CONNECTED`는 pin이 device를 drive함을, `DPLL_PIN_STATE_DISCONNECTED`는 사용하지 않음을 뜻합니다.
• `DPLL_MODE_AUTOMATIC`: user가 `DPLL_PIN_STATE_SELECTABLE`로 automatic selection 후보에 포함하거나 `DPLL_PIN_STATE_DISCONNECTED`로 제외할 수 있습니다. selection algorithm이 input 하나에 lock한 뒤에만 user가 `DPLL_PIN_STATE_CONNECTED`를 receive할 수 있습니다.

Shared pin configuration scope

pin object 하나를 여러 dpll device에 attach할 수 있으며 configuration knob는 두 scope로 나뉩니다.

• pin 자체에 설정: `DPLL_A_PIN_FREQUENCY`처럼 pin이 등록된 모든 dpll device에 영향을 줍니다.
• pin-dpll tuple에 설정: `DPLL_A_PIN_PRIO`, `DPLL_A_PIN_STATE`, `DPLL_A_PIN_DIRECTION`처럼 선택한 dpll device에만 영향을 줍니다.

MUX-type pin

MUX-type pin은 child pin을 aggregate하는 pin multiplexer입니다. child는 dpll device에 직접 등록하는 대신 하나 이상의 MUX parent에 등록됩니다. 각 parent마다 `DPLL_A_PIN_PARENT_PIN` nested attribute를 제공합니다.

pin 하나가 여러 parent pin에 등록되면 multiple-output multiplexer처럼 동작하며 `DPLL_CMD_PIN_GET` 출력에 parent별 current state가 여러 nested attribute로 나타납니다.

attributes with current state related to each parent, like::

        'pin': [{{
          'clock-id': 282574471561216,
          'module-name': 'ice',
          'capabilities': 4,
          'id': 13,
          'parent-pin': [
          {'parent-id': 2, 'state': 'connected'},
          {'parent-id': 3, 'state': 'disconnected'}
          ],
          'type': 'synce-eth-port'
          }}]

한 번에 child pin 하나만 parent MUX에 signal을 제공할 수 있습니다. 원하는 parent에서 child state를 변경하도록 `DPLL_A_PIN_PARENT` nested attribute를 사용해 선택합니다.

Automatic mode pin priority

`DPLL_MODE_AUTOMATIC` capability가 있는 device는 보통 hardware에서 automatic selection을 수행하므로 dpll에 직접 연결된 pin만 automatic input 후보가 될 수 있습니다.

user는 input pin을 직접 선택하지 않고 직접 연결된 모든 pin에 `DPLL_A_PIN_PRIO`를 제공합니다. device는 유효 signal 가운데 priority가 가장 높은 것을 선택해 DPLL을 control합니다.

MUX-type의 child pin은 automatic input selection 대상이 아닙니다. active MUX input은 앞 절처럼 parent pin에서 원하는 child state를 요청해 구성합니다.

Phase offset 측정과 조정

device는 pin signal과 parent dpll 사이 phase difference를 측정할 수 있습니다. 지원된다면 parent별 `DPLL_A_PIN_PHASE_OFFSET`을 제공합니다. 보고 offset은 이전 평균과 현재 측정값으로 다음 식을 사용해 계산할 수 있습니다.

.. math::
   curr\_avg = prev\_avg * \frac{2^N-1}{2^N} + new\_val * \frac{1}{2^N}

`curr_avg`는 현재 보고값, `prev_avg`는 이전 보고값, `new_val`은 현재 측정값, `N`은 averaging factor입니다. device의 `DPLL_A_PHASE_OFFSET_AVG_FACTOR`가 factor를 제공하며 `DPLL_CMD_DEVICE_SET`에서 같은 attribute로 변경을 요청합니다.

pin phase adjustment를 지원하면 `DPLL_CMD_PIN_GET` 응답에 `DPLL_A_PIN_PHASE_ADJUST_MIN`, `DPLL_A_PIN_PHASE_ADJUST_MAX`, `DPLL_A_PIN_PHASE_ADJUST_GRAN`을 제공합니다. 현재 값은 `DPLL_A_PIN_PHASE_ADJUST`이고 `DPLL_CMD_PIN_SET`에서 같은 attribute로 변경합니다.

모든 phase 값은 signal phase의 시간 차이를 나타내는 picosecond 단위입니다. 음수는 pin signal이 dpll signal보다 빠르고 양수는 늦음을 뜻합니다. phase adjust와 min/max는 integer이지만 measured offset은 소수점 3자리의 fractional value입니다. `DPLL_PIN_PHASE_OFFSET_DIVIDER`로 나눈 몫이 integer part, 나머지가 fractional part입니다.

Phase offset monitor

phase offset은 보통 현재 active source를 기준으로 측정하지만 일부 DPLL은 모든 input을 monitor할 수 있습니다. 지원 device는 `DPLL_CMD_DEVICE_GET` 응답에 `DPLL_A_PHASE_OFFSET_MONITOR`와 current feature state를 포함합니다.

user는 `DPLL_CMD_DEVICE_SET`에서 이 attribute에 `enum dpll_feature_state` 값을 설정해 제어합니다. enable하면 input의 측정값을 `DPLL_A_PIN_PHASE_OFFSET`으로 반환합니다.

Embedded SYNC

Embedded SYNC는 pin의 base frequency에 추가 SYNC signal을 넣습니다. SYNC pulse가 발생할 때마다 base-frequency signal의 special pulse 하나를 삽입하며 user가 Embedded SYNC frequency를 구성할 수 있습니다.

capability는 현재 base frequency와 hardware capability에 종속됩니다. pin에 구성된 base frequency에 따라 지원 Embedded SYNC frequency range를 제공합니다.

Reference SYNC

Reference SYNC는 input 두 개를 pair로 묶고 두 clock signal을 모두 사용해 DPLL을 synchronize합니다. 높은 frequency signal은 DPLL loop bandwidth에, 낮은 frequency signal은 output syntonization에 사용해 외부 source에서 고품질 loop bandwidth signal을 제공합니다.

지원 input은 결합 가능한 input 목록을 제공합니다. target pin state를 `DPLL_PIN_STATE_CONNECTED`로 요청하면 enable, `DISCONNECTED`로 요청하면 disable합니다. input pin 하나는 한 시점에 다른 pin 하나와만 결합할 수 있습니다.

Configuration command group와 permission

configuration command는 등록된 dpll device와 pin 정보를 얻고 configuration을 설정합니다. object는 실제 hardware를 반영해야 하므로 userspace가 netlink로 새 dpll device를 추가할 수 없고 각 driver가 등록해야 합니다.

모든 netlink command에는 `GENL_ADMIN_PERM`이 필요합니다. unauthorized userspace application의 spam/DoS를 방지하기 위한 것입니다.

Netlink command와 attribute 목록

device command는 `DPLL_CMD_`, device attribute는 `DPLL_A_`, pin command는 `DPLL_CMD_PIN_`, pin attribute는 `DPLL_A_PIN_` prefix를 사용하고 목적에 맞는 suffix를 붙입니다.

Netlink dump와 SET format

`DPLL_CMD_DEVICE_GET`과 `DPLL_CMD_PIN_GET`은 dump request를 지원합니다. response format은 do request와 같지만 system에 등록된 모든 device 또는 pin을 반환합니다.

• `DPLL_CMD_DEVICE_SET`: system에서 unique한 `DPLL_A_ID`와 구성할 `DPLL_A_MODE`를 제공합니다.
• `DPLL_CMD_PIN_SET`: unique `DPLL_A_PIN_ID`와 변경할 pin parameter를 제공합니다. `DPLL_A_PIN_FREQUENCY`는 연결된 모든 dpll에 영향을 주므로 `DPLL_A_PIN_PARENT_DEVICE` 안에 넣지 않습니다.
• `DPLL_A_PIN_PRIO`, `STATE`, `DIRECTION`은 parent 하나에만 관련되므로 `DPLL_A_PIN_PARENT_DEVICE` 안에 넣고 같은 nest에 target `DPLL_A_PIN_PARENT_ID`도 제공합니다.
• MUX child state는 `DPLL_A_PIN_PARENT_PIN` 안에 state와 target parent pin ID를 넣습니다.

여러 parameter를 한 번에 구성할 수 있지만 내부에서는 각 변경 handler를 따로 호출하며 실행 순서는 보장되지 않습니다.

Pre-defined enum과 notification

configuration pre-defined enum은 `include/uapi/linux/dpll.h`의 kernel-doc에서 가져옵니다.

dpll device는 lock status, input/output 변화와 alarm 같은 status change를 `DPLL_MCGRP_MONITOR` multicast group으로 userspace netlink socket에 알립니다.

event format은 대응 GET command와 같습니다. `DPLL_CMD_DEVICE_` event는 `DPLL_CMD_DEVICE_GET`, `DPLL_CMD_PIN_` event는 `DPLL_CMD_PIN_GET` response format을 사용합니다.

Device driver object lifecycle와 callback

`dpll_device_get()`은 device를 할당합니다. 같은 argument로 다시 호출하면 새 object 대신 기존 pointer를 반환하고 refcount를 증가시킵니다. `dpll_device_put()`은 refcount를 줄이고 0이 되면 object를 destroy합니다.

operation set을 구현하고 `dpll_device_register()`로 등록하면 userspace에 공개됩니다. 여러 driver instance가 `dpll_device_get()`으로 같은 object reference를 얻고 자체 ops와 priv로 등록할 수 있습니다.

pin은 `dpll_pin_get()`으로 별도 할당하고 같은 argument의 후속 호출은 refcount만 늘립니다. `dpll_pin_put()`은 device put과 같은 방식입니다. hardware에 따라 `dpll_pin_register()`로 dpll device에, `dpll_pin_on_pin_register()`로 다른 MUX-type pin에 등록하며 각 registration은 callback set과 private data pointer가 필요합니다.

device·pin 추가/제거 notification은 subsystem이 생성합니다. status change는 subsystem request가 성공한 뒤 자동 호출하거나 driver가 `dpll_device_change_ntf()` 또는 `dpll_pin_change_ntf()`를 호출하는 두 방식입니다.

모든 callback을 구현할 필요는 없지만 다음 callback은 필수입니다.

• device level: `.mode_get`, `.lock_status_get`.
• pin level: dpll device에 등록된 pin의 `.state_on_dpll_get`, parent pin에 등록된 pin의 `.state_on_pin_get`, `.direction_get`.

나머지 handler는 존재 여부를 검사하고 없으면 `-EOPNOTSUPP`를 반환합니다.

OCP TimeCard 구현과 error unwind

가장 단순한 구현은 OCP TimeCard driver이며 ops 구조체는 다음과 같습니다.

.. code-block:: c

        static const struct dpll_device_ops dpll_ops = {
                .lock_status_get = ptp_ocp_dpll_lock_status_get,
                .mode_get = ptp_ocp_dpll_mode_get,
                .mode_supported = ptp_ocp_dpll_mode_supported,
        };

        static const struct dpll_pin_ops dpll_pins_ops = {
                .frequency_get = ptp_ocp_dpll_frequency_get,
                .frequency_set = ptp_ocp_dpll_frequency_set,
                .direction_get = ptp_ocp_dpll_direction_get,
                .direction_set = ptp_ocp_dpll_direction_set,
                .state_on_dpll_get = ptp_ocp_dpll_state_get,
        };

device와 pin registration 예시는 다음과 같습니다.

.. code-block:: c

        clkid = pci_get_dsn(pdev);
        bp->dpll = dpll_device_get(clkid, 0, THIS_MODULE);
        if (IS_ERR(bp->dpll)) {
                err = PTR_ERR(bp->dpll);
                dev_err(&pdev->dev, "dpll_device_alloc failed\n");
                goto out;
        }

        err = dpll_device_register(bp->dpll, DPLL_TYPE_PPS, &dpll_ops, bp);
        if (err)
                goto out;

        for (i = 0; i < OCP_SMA_NUM; i++) {
                bp->sma[i].dpll_pin = dpll_pin_get(clkid, i, THIS_MODULE, &bp->sma[i].dpll_prop);
                if (IS_ERR(bp->sma[i].dpll_pin)) {
                        err = PTR_ERR(bp->dpll);
                        goto out_dpll;
                }

                err = dpll_pin_register(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops,
                                        &bp->sma[i]);
                if (err) {
                        dpll_pin_put(bp->sma[i].dpll_pin);
                        goto out_dpll;
                }
        }

error path에서는 모든 allocation을 역순으로 되돌려야 합니다.

.. code-block:: c

        while (i) {
                --i;
                dpll_pin_unregister(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops, &bp->sma[i]);
                dpll_pin_put(bp->sma[i].dpll_pin);
        }
        dpll_device_put(bp->dpll);

더 복잡한 예시는 Intel ICE driver와 NVIDIA mlx5 driver에서 찾을 수 있습니다.

SyncE enablement

SyncE를 enable하려면 dpll device와 input current state를 monitor하고 그에 맞춰 input을 구성하는 software application이 dpll device를 control할 수 있어야 합니다.

dpll input signal은 PHY netdevice에서 복구한 signal로 dpll을 drive하도록 구성할 수 있어야 합니다. `dpll_netdev_pin_set(struct net_device *dev, struct dpll_pin *dpll_pin)`으로 pin을 netdevice 자체에 attach해 노출합니다.

노출된 `DPLL_A_PIN_ID` handle은 `RTM_NEWLINK` get response의 nested `IFLA_DPLL_PIN`에 붙으므로 user가 식별할 수 있습니다.