Common Clock 프레임워크 (CCF)

리눅스 Common Clock Framework를 "SoC 안의 클록 트리를 추상화하는 API" 수준이 아니라, provider 등록부터 consumer 사용, rate/parent negotiation, prepare/enable 락 규칙, bootloader handoff, assigned-clocks 초기화, runtime PM·reset·regulator 시퀀스, debugfs와 tracepoint 기반 디버깅(Debugging)까지 이어지는 전체 모델로 정리합니다. clk_core, clk_hw, clk_ops, composite clock, clk_summary, clk_ignore_unused, notifier, bulk API, exclusivity API 같은 실전 포인트를 자세히 다룹니다.

CCF가 필요한 이유와 책임 경계

과거에는 많은 SoC 드라이버가 MMIO 레지스터(Register)를 직접 만져 gate 비트와 divider 값을 바꾸는 식으로 클록을 다뤘습니다. 하지만 SoC가 복잡해지면서 하나의 PLL이 CPU, GPU, UART, 디스플레이, 멀티미디어 블록을 동시에 먹이고, parent selection과 rate 변경이 전력 정책과 연결되며, 부팅 초기에 firmware가 설정해 둔 값과 커널이 나중에 설정한 값이 섞이기 시작했습니다. 이 복잡성을 각 드라이버가 제멋대로 처리하면 공유 자원 충돌과 유지보수 지옥이 생깁니다. CCF는 이 문제를 공통 트리 모델과 공통 API로 정리합니다.

또한 CCF는 이름이 비슷한 다른 "clock" 계층과 책임이 다릅니다. 특히 clocksource/timekeeper, cpufreq, regulator, reset과 자주 혼동됩니다.

핵심 객체 모델: struct clk, clk_core, clk_hw, clk_ops

CCF는 consumer와 provider를 일부러 다른 타입으로 분리합니다. 소비자 드라이버는 opaque handle인 struct clk만 보고, 제공자 드라이버는 struct clk_hw를 자신만의 하드웨어 구조체(Struct)에 embed한 뒤 clk_ops로 콜백(Callback)을 구현합니다. 프레임워크 내부에서는 struct clk_core가 topology와 accounting을 들고 있습니다.

공식 커널 문서는 struct clk_core가 topology를, clk_hw와 clk_ops가 하드웨어 특화 부분을 담당한다고 설명합니다. 즉 provider는 "레지스터를 어떻게 만질지"만 알면 되고, enable count나 notifier list 같은 공통 bookkeeping은 프레임워크가 맡습니다.

/* 간소화한 개념도: 실제 헤더의 일부만 발췌 */
struct clk_core {
    const char *name;
    const struct clk_ops *ops;
    struct clk_hw *hw;
    struct clk_core *parent;
    struct clk_core **parents;
    u8 num_parents;
    /* enable_count, notifier, flags, rate 관련 bookkeeping ... */
};

struct clk_ops {
    int  (*prepare)(struct clk_hw *hw);
    void (*unprepare)(struct clk_hw *hw);
    int  (*enable)(struct clk_hw *hw);
    void (*disable)(struct clk_hw *hw);
    unsigned long (*recalc_rate)(struct clk_hw *hw,
                                       unsigned long parent_rate);
    long (*round_rate)(struct clk_hw *hw,
                       unsigned long rate,
                       unsigned long *parent_rate);
    int (*determine_rate)(struct clk_hw *hw,
                          struct clk_rate_request *req);
    int (*set_parent)(struct clk_hw *hw, u8 index);
    u8  (*get_parent)(struct clk_hw *hw);
    int (*set_rate)(struct clk_hw *hw,
                    unsigned long rate,
                    unsigned long parent_rate);
    int (*set_rate_and_parent)(struct clk_hw *hw,
                               unsigned long rate,
                               unsigned long parent_rate,
                               u8 index);
    unsigned long (*recalc_accuracy)(struct clk_hw *hw,
                                           unsigned long parent_accuracy);
    int (*get_phase)(struct clk_hw *hw);
    int (*set_phase)(struct clk_hw *hw, int degrees);
    void (*debug_init)(struct clk_hw *hw, struct dentry *dentry);
};

이 분리는 매우 중요합니다. provider는 gate 비트, divider 필드, PLL lock polling 같은 하드웨어 세부사항만 관리하고, consumer는 "이 클록이 몇 MHz여야 하는가"라는 의도만 표현합니다. 그래서 같은 consumer 코드가 다른 SoC에서도 비교적 동일하게 유지될 수 있습니다.

struct clk_hw 필드별 해설

struct clk_hw는 provider 드라이버가 자신의 하드웨어 구조체에 embed하는 핵심 고리입니다. provider는 clk_hw를 container_of()로 감싸서 자신의 private 구조체를 복원하고, 프레임워크는 clk_hw를 통해 clk_core와 clk_ops에 접근합니다.

/* include/linux/clk-provider.h — 간소화 발췌 */
struct clk_hw {
    struct clk_core         *core;    /* 프레임워크 내부 topology 노드 */
    struct clk              *clk;     /* __clk_get_hw() 역참조용 (deprecated 경향) */
    const struct clk_init_data *init; /* 등록 시에만 유효, 등록 후 NULL */
};

/* provider 드라이버의 전형적인 embed + container_of 패턴 */
struct my_pll {
    void __iomem        *base;
    struct clk_hw        hw;     /* embed */
    spinlock_t           lock;
};

#define to_my_pll(_hw) container_of(_hw, struct my_pll, hw)

static unsigned long my_pll_recalc_rate(struct clk_hw *hw,
                                          unsigned long parent_rate)
{
    struct my_pll *pll = to_my_pll(hw);
    u32 mult = readl(pll->base + 0x04) & 0x7F;
    return parent_rate * mult;
}

struct clk_ops 필드별 해설

struct clk_ops는 provider가 구현하는 콜백 테이블입니다. 모든 콜백이 필수는 아니며, clock 유형에 따라 필요한 것만 채우면 됩니다. 아래는 주요 콜백의 역할과 호출 문맥을 정리한 것입니다.

struct clk_core 주요 필드 분석

struct clk_core는 프레임워크 내부 전용 구조체로, clock 트리의 각 노드를 표현합니다. 이 구조체는 drivers/clk/clk.c에 정의되어 있으며 외부 헤더에 공개되지 않습니다. provider와 consumer 드라이버는 직접 접근할 수 없고, 반드시 CCF API를 통해 간접적으로 다룹니다.

/* drivers/clk/clk.c — 핵심 필드만 발췌, 실제 구조체는 훨씬 큽니다 */
struct clk_core {
    const char              *name;         /* clock 이름 (debugfs, 로그) */
    const struct clk_ops    *ops;          /* provider 콜백 테이블 */
    struct clk_hw           *hw;           /* provider측 하드웨어 핸들 */
    struct module           *owner;        /* 모듈 참조 카운트 */
    struct device           *dev;          /* 연결된 디바이스 (있으면) */

    struct clk_core         *parent;       /* 현재 선택된 부모 */
    struct clk_parent_map   *parents;      /* 가능한 부모 배열 */
    u8                      num_parents;   /* 부모 후보 수 */

    unsigned long           rate;          /* 캐시된 현재 rate */
    unsigned long           req_rate;      /* consumer가 요청한 rate */
    unsigned long           new_rate;      /* set_rate 진행 중 새 rate */
    struct clk_core         *new_parent;   /* set_rate 중 선택된 새 부모 */
    struct clk_core         *new_child;    /* reparent 대상 자식 */

    unsigned long           flags;         /* CLK_SET_RATE_PARENT 등 */
    unsigned int            enable_count;  /* enable 참조 카운트 */
    unsigned int            prepare_count; /* prepare 참조 카운트 */
    unsigned int            protect_count; /* rate protection 카운트 */
    bool                    orphan;        /* 부모를 못 찾은 상태 */

    struct hlist_head       children;      /* 자식 clock 목록 */
    struct hlist_node       child_node;    /* 부모의 children에 연결 */
    struct hlist_head       clks;          /* consumer handle 목록 */
    struct clk_notifier     *notifier;     /* rate change notifier */
    struct dentry           *dentry;       /* debugfs 디렉토리 */
};

provider가 만드는 클록 토폴로지(Topology)

CCF의 provider는 대개 clock-controller 드라이버입니다. 이 드라이버는 SoC 내부의 발진기, PLL, mux, divider, gate, composite clock을 트리 형태로 등록합니다. 소비자 드라이버는 트리 전체를 몰라도 leaf 이름이나 phandle만 알면 됩니다.

하나의 UART가 48MHz를 필요로 한다고 해서, 항상 leaf gate만 켜면 끝나는 것은 아닙니다. parent mux를 바꿔야 할 수도 있고, divider를 조정해야 할 수도 있으며, 경우에 따라 상위 PLL rate가 바뀌어 다른 형제 노드도 영향을 받을 수 있습니다.

#include <linux/clk-provider.h>

struct my_gate {
    struct clk_hw hw;
    void __iomem *reg;
    u8 bit_idx;
    spinlock_t *lock;
};

#define to_my_gate(_hw) container_of(_hw, struct my_gate, hw)

static int my_gate_enable(struct clk_hw *hw)
{
    struct my_gate *g = to_my_gate(hw);
    unsigned long flags;
    u32 val;

    spin_lock_irqsave(g->lock, flags);
    val = readl(g->reg);
    val |= BIT(g->bit_idx);
    writel(val, g->reg);
    spin_unlock_irqrestore(g->lock, flags);
    return 0;
}

static const struct clk_ops my_gate_ops = {
    .enable = my_gate_enable,
    .disable = my_gate_disable,
    .is_enabled = my_gate_is_enabled,
};

공식 커널 문서도 provider 구현은 clk_hw를 자신의 하드웨어 구조체에 embed하고, container_of()로 다시 되돌아가 MMIO 레지스터를 만지는 패턴을 기본으로 설명합니다. 중요한 점은 enable count, notifier count, topology bookkeeping을 provider가 직접 관리하지 않는다는 것입니다.

PLL 구현 패턴: lock 대기, VCO 범위, fractional divider

SoC 클록 트리에서 가장 복잡한 provider는 PLL(Phase-Locked Loop)입니다. PLL은 기준 클록을 입력받아 정수 또는 분수 배수로 주파수를 합성하며, 내부에 VCO(Voltage Controlled Oscillator)와 post-divider를 포함합니다. 커널 드라이버가 PLL을 구현할 때는 몇 가지 하드웨어 제약을 반드시 고려해야 합니다.

struct my_pll {
    struct clk_hw hw;
    void __iomem *base;
    u32 lock_offset;
    u32 lock_bit;
    unsigned long vco_min;
    unsigned long vco_max;
};

#define to_my_pll(_hw) container_of(_hw, struct my_pll, hw)

static int my_pll_set_rate(struct clk_hw *hw,
                            unsigned long rate,
                            unsigned long parent_rate)
{
    struct my_pll *pll = to_my_pll(hw);
    u32 fbdiv, refdiv, postdiv;
    u32 val;
    int ret;

    /* fbdiv, refdiv, postdiv 계산 (VCO 범위 준수) */
    my_pll_calc_params(rate, parent_rate,
                       pll->vco_min, pll->vco_max,
                       &fbdiv, &refdiv, &postdiv);

    /* PLL 파라미터를 레지스터에 기록 */
    val = readl(pll->base + PLL_CON0);
    val &= ~(FBDIV_MASK | REFDIV_MASK);
    val |= (FIELD_PREP(FBDIV_MASK, fbdiv) |
            FIELD_PREP(REFDIV_MASK, refdiv));
    writel(val, pll->base + PLL_CON0);

    /* lock 대기: PLL이 새 주파수에 안정화될 때까지 polling */
    ret = readl_poll_timeout(pll->base + pll->lock_offset, val,
                            val & BIT(pll->lock_bit),
                            1, 1000);
    if (ret)
        pr_warn("PLL %s: lock timeout\n",
                clk_hw_get_name(hw));

    return ret;
}

CCF는 fractional divider를 위한 전용 helper도 제공합니다. clk_fractional_divider는 정수부와 분수부를 분리하여 더 정밀한 주파수 합성을 지원하며, 주로 오디오 코덱이나 디스플레이 pixel clock처럼 정밀도가 중요한 경로에 사용됩니다.

/* fractional divider helper 사용 예 */
hw = clk_hw_register_fractional_divider(dev, "pixel_clk",
        "pll_video", 0,
        base + FRAC_DIV_REG,
        16,     /* mwidth: 정수부 비트 수 */
        16,     /* nwidth: 분수부 비트 수 */
        0,      /* CLK_FRAC_DIVIDER_ZERO_BASED 등 */
        &lock);

composite clock helper와 실전 SoC 매핑(Mapping)

실제 SoC에서 하나의 peripheral clock 경로는 보통 mux, divider, gate가 같은 레지스터 블록에 묶여 있습니다. 이런 구조를 개별 clk_hw로 따로따로 등록하면 관리가 복잡해지고, rate 변경과 gate 토글이 분리되어 중간 상태가 위험할 수 있습니다. CCF의 composite clock helper는 이를 하나의 논리적 clock으로 묶어 줍니다.

#include <linux/clk-provider.h>

/* composite clock 등록: mux + divider + gate를 하나로 묶는다 */
static struct clk_hw *my_register_composite(struct device *dev,
                                             void __iomem *base,
                                             spinlock_t *lock)
{
    const char *parent_names[] = { "pll_periph", "pll_audio", "osc24m" };
    struct clk_mux *mux;
    struct clk_divider *div;
    struct clk_gate *gate;

    mux = devm_kzalloc(dev, sizeof(*mux), GFP_KERNEL);
    div = devm_kzalloc(dev, sizeof(*div), GFP_KERNEL);
    gate = devm_kzalloc(dev, sizeof(*gate), GFP_KERNEL);

    mux->reg = base + 0x100;
    mux->shift = 24;
    mux->mask = 0x3;
    mux->lock = lock;

    div->reg = base + 0x100;
    div->shift = 8;
    div->width = 4;
    div->lock = lock;

    gate->reg = base + 0x100;
    gate->bit_idx = 0;
    gate->lock = lock;

    return clk_hw_register_composite(dev, "uart0_clk",
            parent_names, ARRAY_SIZE(parent_names),
            &mux->hw, &clk_mux_ops,
            &div->hw, &clk_divider_ops,
            &gate->hw, &clk_gate_ops,
            CLK_SET_RATE_PARENT);
}

rate negotiation: recalc, round, determine, set_parent

CCF에서 가장 까다로운 부분은 "얼마나 빠르게 돌릴 것인가"보다 "그 속도를 어떤 부모와 어떤 divider 조합으로 만들 것인가"입니다. 실제 하드웨어는 임의의 모든 주파수를 만들 수 없기 때문에, 요청 rate는 rounding되거나 parent가 바뀌거나, 심지어 상위 PLL까지 손을 대야 할 수 있습니다.

static int my_div_determine_rate(struct clk_hw *hw,
                                  struct clk_rate_request *req)
{
    unsigned long best_parent = req->best_parent_rate;
    unsigned long best_rate = 0;

    /* 실제 구현은 가능한 parent/div 조합을 훑으며 오차가 가장 적은 후보를 고른다 */
    /* req->best_parent_hw / req->best_parent_rate / req->rate 채움 */

    req->best_parent_rate = best_parent;
    req->rate = best_rate;
    return 0;
}

공식 커널 문서는 rate-changing clock은 round_rate 또는 determine_rate 중 하나가 필요하다고 설명합니다. 단순 divider처럼 부모가 하나인 경우엔 round_rate만으로 충분할 수 있지만, 부모 선택까지 포함하는 복잡한 트리라면 determine_rate가 더 적합합니다.

clk_set_rate() 함수 구현 분석

clk_set_rate()는 단순히 레지스터 값 하나를 바꾸는 것이 아닙니다. 프레임워크 내부에서는 2단계 프로토콜로 동작합니다: 먼저 트리를 순회하며 각 노드에서 달성 가능한 rate를 계산하고(clk_calc_new_rates), 그 다음 실제 하드웨어에 반영합니다(clk_change_rate). 중간에 notifier로 consumer에게 사전 통보도 합니다.

/* drivers/clk/clk.c — clk_set_rate 핵심 흐름 (간소화) */
int clk_set_rate(struct clk *clk, unsigned long rate)
{
    int ret;

    clk_prepare_lock();  /* prepare mutex 획득 */

    /* protection 카운트 확인: 다른 consumer가 rate를 보호 중이면 거부 */
    if (clk->exclusive_count)
        clk_core_rate_unprotect(clk->core);

    /* 1단계: 트리 순회하며 각 노드의 new_rate 계산 */
    top = clk_calc_new_rates(clk->core, rate);

    /* notifier: PRE_RATE_CHANGE 발송 */
    ret = clk_pm_runtime_get(clk->core);
    if (ret)
        goto err;

    ret = clk_notify_pre_rate_change(top);
    if (ret) {
        clk_notify_abort_rate_change(top);
        goto err;
    }

    /* 2단계: top-down으로 실제 rate 변경 (set_rate, reparent) */
    clk_change_rate(top);

    /* notifier: POST_RATE_CHANGE 완료 */
err:
    if (clk->exclusive_count)
        clk_core_rate_protect(clk->core);
    clk_prepare_unlock();
    return ret;
}

flags와 제약 조건

CCF의 실제 동작은 콜백만이 아니라 등록 시 지정하는 flags에도 크게 좌우됩니다. 아래는 provider 드라이버에서 자주 보는 flags의 의미입니다.

flags를 잘못 주면 디버깅이 아주 어려워집니다. 예를 들어 필수 bus clock에 CLK_IS_CRITICAL 또는 동등한 보호가 빠지면, late init 단계의 unused clock disable이 예상치 못하게 시스템을 굳혀 버릴 수 있습니다. 반대로 아무거나 critical로 마크하면 진짜로 누수가 있는 clock enable imbalance를 놓칠 수 있습니다.

prepare lock, enable lock, 그리고 문맥 제약

공식 커널 문서가 특히 강조하는 부분이 락입니다. CCF는 전역적으로 두 개의 락 그룹을 사용합니다. enable lock은 spinlock이고 .enable, .disable에 걸립니다. prepare lock은 mutex이고 그 외 다른 연산들에 걸립니다. 이 구조 때문에 enable/disable은 sleep하면 안 되고, prepare류와 rate/parent 변경 연산은 sleep 가능 컨텍스트에서 수행됩니다.

공식 문서는 또한 CCF가 재진입 가능(reentrant)하다고 설명합니다. 즉 하나의 .set_rate 구현이 내부에서 다른 clock API를 다시 호출할 수 있습니다. 이런 중첩 호출은 provider 구현자가 의도적으로 설계하는 경우가 많지만, 락 순서와 recursion 경로를 잘못 잡으면 deadlock이나 예상치 못한 parent churn으로 이어질 수 있습니다.

clk_prepare_enable() 호출 체인 분석

consumer가 가장 자주 호출하는 clk_prepare_enable()은 사실 clk_prepare()와 clk_enable()을 순서대로 호출하는 편의 함수입니다. 각각이 내부에서 부모를 재귀적으로 먼저 처리하고, 참조 카운트가 0→1이 되는 순간에만 실제 하드웨어 콜백을 호출합니다.

/* drivers/clk/clk.c — 간소화한 호출 체인 */

/* 1단계: prepare (mutex 보호) */
int clk_prepare(struct clk *clk)
{
    clk_prepare_lock();                 /* prepare mutex 획득 */
    ret = clk_core_prepare(clk->core);
    clk_prepare_unlock();
    return ret;
}

static int clk_core_prepare(struct clk_core *core)
{
    if (core->prepare_count == 0) {
        /* 부모를 먼저 재귀적으로 prepare */
        ret = clk_core_prepare(core->parent);
        if (ret)
            return ret;
        /* provider의 .prepare 콜백 호출 */
        if (core->ops->prepare)
            ret = core->ops->prepare(core->hw);
    }
    core->prepare_count++;
    return 0;
}

/* 2단계: enable (spinlock 보호) */
int clk_enable(struct clk *clk)
{
    unsigned long flags;
    clk_enable_lock(&flags);           /* enable spinlock 획득 */
    ret = clk_core_enable(clk->core);
    clk_enable_unlock(flags);
    return ret;
}

static int clk_core_enable(struct clk_core *core)
{
    if (core->enable_count == 0) {
        /* 부모를 먼저 재귀적으로 enable */
        ret = clk_core_enable(core->parent);
        if (ret)
            return ret;
        /* provider의 .enable 콜백 호출 (gate bit set 등) */
        if (core->ops->enable)
            ret = core->ops->enable(core->hw);
    }
    core->enable_count++;
    return 0;
}

provider 등록 패턴

clock-controller 드라이버는 probe 시에 자신의 하드웨어 클록들을 등록하고, DT provider로 노출합니다. 단일 clock 하나를 내놓을 수도 있지만, SoC CCU/CRU 드라이버는 보통 수십에서 수백 개의 clk_hw를 배열로 관리합니다.

#include <linux/clk-provider.h>

struct my_ccu {
    void __iomem *base;
    spinlock_t lock;
    struct clk_hw_onecell_data *onecell;
};

static int my_ccu_probe(struct platform_device *pdev)
{
    struct my_ccu *ccu;

    ccu = devm_kzalloc(&pdev->dev, sizeof(*ccu), GFP_KERNEL);
    if (!ccu)
        return -ENOMEM;

    spin_lock_init(&ccu->lock);
    ccu->base = devm_platform_ioremap_resource(pdev, 0);
    if (IS_ERR(ccu->base))
        return PTR_ERR(ccu->base);

    ccu->onecell = devm_kzalloc(&pdev->dev,
                                    struct_size(ccu->onecell, hws, 128),
                                    GFP_KERNEL);
    if (!ccu->onecell)
        return -ENOMEM;

    ccu->onecell->num = 128;
    ccu->onecell->hws[5] =
        clk_hw_register_gate(&pdev->dev, "uart0_gate", "uart0_div",
                             0, ccu->base + 0x120, 4, 0, &ccu->lock);
    /* divider/mux/pll/composite도 같은 식으로 채움 */

    return devm_of_clk_add_hw_provider(&pdev->dev, of_clk_hw_onecell_get,
                                       ccu->onecell);
}

단일 onecell provider는 인덱스 기반 phandle을 받는 DT와 잘 맞습니다. 더 복잡한 controller는 composite helper나 커스텀 provider 함수를 사용할 수 있습니다. 핵심은 provider probe가 끝난 뒤에야 consumer의 devm_clk_get()가 성공한다는 점입니다.

clock 등록 내부 경로: clk_register() / devm_clk_hw_register()

provider가 clk_hw_register()(또는 그 devm_ 래퍼)를 호출하면, 프레임워크 내부에서 clk_core를 할당하고 clk_init_data의 정보를 복사하며, 트리에 노드를 삽입합니다. 이 과정을 이해하면 orphan clock 문제나 등록 순서 의존성을 디버깅하기가 쉬워집니다.

/* drivers/clk/clk.c — clk_core_register() 핵심 경로 (간소화) */
static int __clk_core_init(struct clk_core *core)
{
    struct clk_core *parent;

    /* 1. init_data에서 정보 복사 */
    core->name   = kstrdup_const(hw->init->name, GFP_KERNEL);
    core->ops    = hw->init->ops;
    core->flags  = hw->init->flags;
    core->num_parents = hw->init->num_parents;

    /* 2. parent map 구축 (이름/인덱스/fw_name/hw 포인터) */
    clk_core_populate_parent_map(core, hw->init);

    /* 3. ops->init 호출 (있으면) — 하드웨어 초기 상태 확인 */
    if (core->ops->init)
        core->ops->init(core->hw);

    /* 4. 부모 찾기 — 아직 없으면 orphan 목록에 추가 */
    parent = __clk_init_parent(core);
    clk_core_set_parent_nolock(core, parent);

    if (!parent)
        hlist_add_head(&core->child_node, &clk_orphan_list);
    else
        hlist_add_head(&core->child_node, &parent->children);

    /* 5. rate 초기 계산 */
    clk_core_update_orphan_status(core, !parent);
    core->rate = clk_recalc(core, parent ? parent->rate : 0);

    /* 6. 이 clock의 등록으로 orphan이 해결될 수 있는지 확인 */
    clk_core_reparent_orphans_nolock();

    /* 7. init 포인터 무효화 — 등록 후 접근 금지 */
    hw->init = NULL;

    return 0;
}

/* devm 래퍼: 드라이버 unbind 시 자동 unregister */
int devm_clk_hw_register(struct device *dev, struct clk_hw *hw)
{
    struct clk_hw **hwp;
    int ret;

    hwp = devres_alloc(devm_clk_hw_release, sizeof(*hwp), GFP_KERNEL);
    if (!hwp)
        return -ENOMEM;

    ret = clk_hw_register(dev, hw);
    if (!ret) {
        *hwp = hw;
        devres_add(dev, hwp);
    } else {
        devres_free(hwp);
    }
    return ret;
}

static void devm_clk_hw_release(struct device *dev, void *res)
{
    clk_hw_unregister(*(struct clk_hw **)res);
}

consumer API와 드라이버 사용 패턴

일반 디바이스 드라이버는 CCF를 opaque 리소스처럼 사용합니다. 가장 기본 흐름은 devm_clk_get()으로 클록을 얻고, 필요 시 clk_prepare_enable(), clk_set_rate(), clk_disable_unprepare()를 균형 있게 호출하는 것입니다.

static int mydev_probe(struct platform_device *pdev)
{
    struct mydev *priv;
    int ret;

    priv = devm_kzalloc(&pdev->dev, sizeof(*priv), GFP_KERNEL);
    if (!priv)
        return -ENOMEM;

    priv->core_clk = devm_clk_get(&pdev->dev, "core");
    if (IS_ERR(priv->core_clk))
        return dev_err_probe(&pdev->dev, PTR_ERR(priv->core_clk),
                             "failed to get core clock\n");

    ret = clk_set_rate(priv->core_clk, 50000000);
    if (ret)
        return dev_err_probe(&pdev->dev, ret, "failed to set rate\n");

    ret = clk_prepare_enable(priv->core_clk);
    if (ret)
        return dev_err_probe(&pdev->dev, ret, "failed to enable clock\n");

    ret = mydev_hw_init(priv);
    if (ret) {
        clk_disable_unprepare(priv->core_clk);
        return ret;
    }

    return 0;
}

실전에서는 클록이 하나가 아닌 경우가 많으므로 bulk API도 중요합니다.

static struct clk_bulk_data my_clks[] = {
    { .id = "apb" },
    { .id = "core" },
    { .id = "bus" },
};

ret = devm_clk_bulk_get(dev, ARRAY_SIZE(my_clks), my_clks);
if (ret)
    return ret;

ret = clk_bulk_prepare_enable(ARRAY_SIZE(my_clks), my_clks);
if (ret)
    return ret;

Device Tree 바인딩, clocks, assigned-clocks

Device Tree에서 consumer는 보통 clocks와 clock-names로 provider를 참조합니다. phandle entries는 순서가 명확해야 하고, clock이 둘 이상이면 이름도 함께 주는 것이 일반적입니다. 공식 DT binding 지침은 phandle 배열은 명시적으로 ordered해야 하며, 이름을 줄 때는 suffix를 붙이지 말라고 권고합니다.

ccu: clock-controller@ff760000 {
    compatible = "vendor,soc-ccu";
    reg = <0x0 0xff760000 0x0 0x1000>;
    #clock-cells = <1>;
};

uart0: serial@10000000 {
    compatible = "vendor,my-uart";
    reg = <0x0 0x10000000 0x0 0x100>;
    clocks = <&ccu 5>, <&ccu 6>;
    clock-names = "baud", "apb";
};

spi1: spi@10010000 {
    compatible = "vendor,my-spi";
    reg = <0x0 0x10010000 0x0 0x1000>;
    clocks = <&ccu 17>, <&ccu 18>;
    clock-names = "core", "bus";
};

부팅 초기에 default parent와 rate를 미리 잡아야 할 때는 assigned-clocks, assigned-clock-parents, assigned-clock-rates를 씁니다.

&ccu {
    assigned-clocks = <&ccu 5>, <&ccu 17>;
    assigned-clock-parents = <&pll_uart>, <&pll_periph>;
    assigned-clock-rates = <48000000>, <100000000>;
};

bootloader handoff, orphan, unused clock disable

CCF 문서를 이론적으로만 읽으면 놓치기 쉬운 부분이 부팅 초기 상태입니다. 많은 플랫폼에서 bootloader나 firmware는 이미 console, DRAM, interconnect, UART, storage용 클록을 켜 둡니다. 커널은 provider가 등록되면 그 상태를 해석하고, late init 단계에서 unused clock을 끄기도 합니다. 이 과정에서 "driver는 아무 enable도 안 했는데 장치는 되더라" 같은 착시가 생깁니다.

공식 CCF 문서는 개발 중 bootloader 의존성을 임시로 회피하려면 clk_ignore_unused bootarg를 쓸 수 있다고 설명합니다. 다만 이 옵션은 진짜 버그를 감추기 쉬우므로 원인 분석이 끝나면 제거하는 편이 좋습니다.

# unused clock disable 추적
tp_printk trace_event=clk:clk_disable

# 개발 중 임시 우회
clk_ignore_unused

runtime PM, reset, regulator와의 시퀀스

대부분의 장치에서 clock enable은 독립 동작이 아닙니다. 실제 하드웨어는 전압 레일이 먼저 살아야 하고, 어떤 장치는 reset line을 deassert하기 전에 parent clock이 안정되어 있어야 하며, runtime suspend 때는 register retention 여부에 따라 reset을 유지할지 말지 판단해야 합니다.

물론 하드웨어에 따라 순서는 달라질 수 있습니다. 중요한 것은 "모든 장치가 같은 순서를 쓴다"가 아니라, driver가 그 장치의 데이터시트 요구를 CCF API와 reset/regulator/runtime PM API 조합으로 정확히 표현해야 한다는 점입니다.

static int mydev_runtime_resume(struct device *dev)
{
    struct mydev *priv = dev_get_drvdata(dev);
    int ret;

    ret = regulator_bulk_enable(priv->num_supplies, priv->supplies);
    if (ret)
        return ret;

    ret = clk_bulk_prepare_enable(priv->num_clks, priv->clks);
    if (ret)
        goto err_disable_regs;

    ret = reset_control_deassert(priv->rst);
    if (ret)
        goto err_disable_clks;

    return 0;

err_disable_clks:
    clk_bulk_disable_unprepare(priv->num_clks, priv->clks);
err_disable_regs:
    regulator_bulk_disable(priv->num_supplies, priv->supplies);
    return ret;
}

DVFS 계열 driver에서는 regulator와 CCF가 더 촘촘하게 엮입니다. 주파수 상승 시 보통 전압을 먼저 올리고 그 다음 clk_set_rate()를 호출해야 하고, 주파수 하강 시에는 반대로 rate를 먼저 내린 뒤 전압을 낮추는 순서가 필요합니다. 이런 작업은 Regulator 프레임워크와 OPP 계층이 조율하는 경우가 많습니다.

고급 API: notifier, bulk, phase, exclusivity

기본 API만으로도 많은 driver가 충분히 동작하지만, CCF에는 복잡한 장치용 고급 기능도 있습니다.

static int my_clk_notifier(struct notifier_block *nb,
                           unsigned long event, void *data)
{
    struct clk_notifier_data *cnd = data;

    switch (event) {
    case PRE_RATE_CHANGE:
        /* FIFO watermark, divider shadow register 등 사전 조정 */
        break;
    case POST_RATE_CHANGE:
        /* 새 실제 rate 기준으로 timing 재설정 */
        break;
    }

    return NOTIFY_OK;
}

clock protection, duty cycle, accuracy API

CCF는 기본적인 rate/enable 외에도 clock 신호의 세밀한 속성을 제어하는 API를 제공합니다. 이러한 API는 모든 드라이버에 필요한 것은 아니지만, 특수한 하드웨어 요구사항이 있을 때 정확한 동작을 보장합니다.

/* duty cycle 제어: DDR PHY 등에서 50% duty가 필수인 경우 */
struct clk_duty duty;
int ret;

ret = clk_set_duty_cycle(priv->ddr_clk, 50, 100);  /* num=50, den=100 → 50% */
if (ret)
    dev_warn(dev, "duty cycle 설정 실패: %d\n", ret);

/* rate protection: 디스플레이 pixel clock을 보호 */
ret = clk_set_rate_protect(priv->pixel_clk, 148500000);
if (ret)
    return ret;

/* 사용 완료 후 보호 해제 */
clk_rate_exclusive_put(priv->pixel_clk);

clock notifier 상세 rate change 전파 메커니즘

CCF의 notifier 체계는 단순 이벤트 알림이 아닙니다. rate change는 3단계(PRE → ABORT 또는 POST)로 진행되며, PRE 단계에서 consumer가 거부할 수 있습니다. 이 구조는 shared parent를 여러 consumer가 사용할 때, 한 consumer의 rate 변경이 다른 consumer에 미치는 영향을 사전에 검증하는 메커니즘입니다.

static int uart_clk_notifier_cb(struct notifier_block *nb,
                                 unsigned long event, void *data)
{
    struct clk_notifier_data *cnd = data;
    struct my_uart *uart = container_of(nb, struct my_uart, clk_nb);

    switch (event) {
    case PRE_RATE_CHANGE:
        /* 새 rate로 baud rate divisor를 만들 수 있는지 확인 */
        if (!my_uart_can_adjust_baud(uart, cnd->new_rate))
            return NOTIFY_STOP;  /* 거부: 이 rate에서 baud 생성 불가 */
        /* TX FIFO drain 등 사전 준비 */
        my_uart_suspend_tx(uart);
        break;
    case POST_RATE_CHANGE:
        /* 새 rate 기반으로 baud divisor 재설정 */
        my_uart_update_baud(uart, cnd->new_rate);
        my_uart_resume_tx(uart);
        break;
    case ABORT_RATE_CHANGE:
        /* PRE에서 다른 consumer가 거부한 경우, 원래 상태 복원 */
        my_uart_resume_tx(uart);
        break;
    }

    return NOTIFY_OK;
}

/* probe에서 notifier 등록 */
uart->clk_nb.notifier_call = uart_clk_notifier_cb;
ret = clk_notifier_register(uart->baud_clk, &uart->clk_nb);

devm 패턴과 자원 해제 전략

현대 커널 드라이버에서는 devm_ 접두사를 붙인 managed API를 사용하는 것이 표준입니다. CCF에서도 devm_clk_get(), devm_clk_bulk_get(), devm_clk_get_optional(), devm_of_clk_add_hw_provider() 등이 제공됩니다. devm API는 드라이버 unbind 시 자동으로 자원을 해제하여, error path에서 수동 clk_put()을 빠뜨리는 실수를 방지합니다.

/* 권장 패턴: devm_clk_get_enabled()로 get+prepare+enable 한번에 */
static int simple_dev_probe(struct platform_device *pdev)
{
    struct clk *clk;

    /* get + prepare + enable을 한 줄로: unbind 시 자동 해제 */
    clk = devm_clk_get_enabled(&pdev->dev, "core");
    if (IS_ERR(clk))
        return dev_err_probe(&pdev->dev, PTR_ERR(clk),
                             "core clock\n");

    /* 선택적 clock: 없어도 에러가 아님 */
    clk = devm_clk_get_optional_enabled(&pdev->dev, "debug");
    if (IS_ERR(clk))
        return PTR_ERR(clk);
    /* clk이 NULL이면 이 하드웨어에는 debug clock이 없는 것 */

    return 0;
}

주요 SoC vendor CCU 드라이버 구조 비교

CCF의 공통 API는 동일하지만, 각 SoC vendor는 자사 하드웨어에 맞는 clock controller driver 구조를 발전시켜 왔습니다. 이 차이를 이해하면 새로운 SoC의 CCU 드라이버를 읽을 때 진입 장벽이 낮아집니다.

debugfs, tracepoint, 관측 포인트

CCF 디버깅의 시작점은 거의 항상 clk_summary입니다. 여기에 이름, 실제 rate, prepare/enable count, parent 관계가 나오므로, driver가 기대하는 트리와 실제 트리를 맞춰 볼 수 있습니다. 여기에 tracepoint와 dmesg, DT dump를 조합하면 대부분의 문제를 좁힐 수 있습니다.

# debugfs mount
mount -t debugfs none /sys/kernel/debug

# 전체 클록 트리 요약
cat /sys/kernel/debug/clk/clk_summary

# 특정 leaf 확인
grep -E 'uart|spi|gpu|disp' /sys/kernel/debug/clk/clk_summary

# DT의 clock-names 확인
grep -R "clock-names" /sys/firmware/devicetree/base 2>/dev/null

# tracepoint로 disable 추적
echo 1 > /sys/kernel/tracing/events/clk/enable/enable
echo 1 > /sys/kernel/tracing/events/clk/disable/enable
echo 1 > /sys/kernel/tracing/events/clk/set_rate/enable
cat /sys/kernel/tracing/trace_pipe

다음과 같은 체크리스트를 기억해 두면 좋습니다.

• rate가 다르다 — provider가 rounding했는지, parent가 예상과 다른지, assigned-clocks가 덮어썼는지 봅니다.
• 부팅 직후만 된다 — bootloader가 켜 둔 클록에 기대고 있는지, clk_ignore_unused 없이는 재현되는지 봅니다.
• suspend 후 죽는다 — runtime PM/resume에서 rate와 parent를 복원하는지, reset과 순서가 맞는지 봅니다.
• 특정 형제 장치까지 같이 깨진다 — shared PLL나 shared divider를 건드렸는지 봅니다.
• provider 내부 race — enable bit와 divider bit가 같은 register에 있는데 provider 전용 락이 없는지 봅니다.

흔한 실패 패턴

끝까지 따라가는 상태 전이 예제

아래는 UART driver가 probe되는 동안 CCF와 reset/regulator/runtime PM이 어떤 순서로 맞물리는지 따라가는 예제입니다.

커널 명령줄 옵션과 런타임 제어

CCF 관련 커널 명령줄 옵션은 주로 부팅 초기 디버깅과 하드웨어 bring-up 단계에서 사용합니다.

런타임에도 debugfs를 통해 개별 clock의 상태를 세밀하게 확인할 수 있습니다.

# 개별 clock 디렉토리 탐색
ls /sys/kernel/debug/clk/uart0_gate/

# 출력 예:
# clk_accuracy  clk_enable_count  clk_flags  clk_max_rate
# clk_min_rate  clk_notifier_count  clk_parent  clk_phase
# clk_prepare_count  clk_protect_count  clk_rate

# 특정 clock의 enable count 확인
cat /sys/kernel/debug/clk/uart0_gate/clk_enable_count

# 특정 clock의 parent 확인
cat /sys/kernel/debug/clk/uart0_gate/clk_parent

# orphan clock 목록 확인 (parent를 못 찾은 clock)
cat /sys/kernel/debug/clk/clk_orphan_summary

# 전체 dump 결과에서 enable_count가 0이 아닌 clock만 필터링
awk 'NR==1 || $5 > 0' /sys/kernel/debug/clk/clk_summary

provider 구현자를 위한 체크리스트

CCU/CRU 드라이버를 구현하거나 수정할 때 빈번하게 발생하는 실수를 정리합니다.

참고자료

• docs.kernel.org — Common Clock Framework — CCF 공식 커널 API 문서입니다
• drivers/clk/clk.c — Bootlin Elixir — CCF 코어 구현체를 브라우저에서 탐색할 수 있습니다
• include/linux/clk-provider.h — Bootlin Elixir — clock provider API와 clk_ops 구조체 정의입니다
• include/linux/clk.h — Bootlin Elixir — clock consumer API 헤더 정의입니다
• LWN: The common clock framework — CCF 도입 당시의 설계 논의와 배경을 설명합니다
• LWN: Common clock framework merged for 3.4 — CCF가 메인라인에 합류한 과정을 다룹니다
• Clock DT Bindings — clock provider/consumer Device Tree 바인딩 디렉터리입니다
• drivers/clk/clk-divider.c — Bootlin Elixir — 기본 divider clock 타입의 구현 참고입니다
• drivers/clk/clk-mux.c — Bootlin Elixir — 기본 mux clock 타입의 구현 참고입니다
• drivers/clk/clk-gate.c — Bootlin Elixir — 기본 gate clock 타입의 구현 참고입니다
• drivers/clk/clk-fixed-rate.c — Bootlin Elixir — 가장 단순한 clock provider 구현으로, 처음 CCF를 공부할 때 참고하기 좋습니다

관련 문서

• Device Tree — clocks, clock-names, provider/consumer binding
• 전원 관리 — runtime PM과 clock gating, suspend/resume 시퀀스
• Regulator 프레임워크 — DVFS에서 CCF와 함께 움직이는 전압 레일, 전압-주파수 순서 규칙
• Reset Controller 프레임워크 — clock/reset 시퀀스 결합, deassert 타이밍
• ktime/Clock — timekeeper, clocksource와 CCF의 책임 구분
• 디바이스 드라이버 — consumer 드라이버의 리소스 관리와 probe 패턴
• PWM 서브시스템 — PWM consumer도 CCF로 source clock을 관리하는 경우가 많음
• Watchdog — watchdog timer의 source clock 관리와 CLK_IS_CRITICAL
• Industrial I/O (IIO) — ADC/DAC 샘플링 클록과 CCF 연동
• Backlight — backlight PWM의 parent clock 설정
• NVMEM 프레임워크 — efuse/OTP 읽기 시 clock enable이 필요한 하드웨어
• hwmon — 하드웨어 모니터링 센서의 bus clock 관리
• Serial / TTY 서브시스템 — UART baud rate와 CCF rate negotiation
• Kernel Objects (kobject) — 디바이스 모델 계층과 sysfs 구조