The Common Clk Framework

공통 Clock 프레임워크

저자는 Mike Turquette `<mturquette@ti.com>`입니다. 이 문서는 공통 clock 프레임워크의 세부 사항과 플랫폼을 이 프레임워크로 이식하는 방법을 설명합니다.

아직 `include/linux/clk.h`의 clock API를 자세히 설명하는 문서는 아니지만, 향후 해당 정보가 포함될 수 있습니다.

도입과 인터페이스 분리

공통 clock 프레임워크는 여러 장치의 clock 노드를 제어하는 인터페이스입니다. clock gating, 속도 조정, mux 선택과 그 밖의 동작을 제공하며 `CONFIG_COMMON_CLK` 옵션으로 활성화합니다.

인터페이스는 서로의 세부 구현을 감춘 두 부분으로 나뉩니다. 프레임워크 쪽은 여러 플랫폼에 중복되던 회계와 기반 기능을 통합하는 공통 `struct clk` 정의와 `drivers/clk/clk.c`의 `clk.h` API 구현으로 구성됩니다. 이 API 구현은 `struct clk_ops`의 연산을 호출합니다.

하드웨어 쪽은 `struct clk_ops`에 등록하는 하드웨어별 콜백과 특정 clock을 모델링하는 하드웨어별 구조체로 구성됩니다. 이 문서에서 `.enable`, `.set_rate` 같은 `struct clk_ops` 콜백은 해당 하드웨어 구현을 뜻하며, `struct clk_foo`는 가상의 `foo` 하드웨어 고유 부분을 나타내는 약칭입니다.

`struct clk_hw`가 두 부분을 연결합니다. 이 구조체는 `struct clk_foo` 안에 들어가고 `struct clk_core`가 가리키므로 공통 clock 인터페이스의 두 영역 사이를 쉽게 오갈 수 있습니다.

공통 자료 구조와 API

다음은 간결하게 줄인 `drivers/clk/clk.c`의 공통 `struct clk_core` 정의입니다.

struct clk_core {
        const char                *name;
        const struct clk_ops        *ops;
        struct clk_hw                *hw;
        struct module                *owner;
        struct clk_core                *parent;
        const char                **parent_names;
        struct clk_core                **parents;
        u8                        num_parents;
        u8                        new_parent_index;
        ...
};

이 멤버들은 clock 트리 토폴로지의 핵심을 이룹니다. clock API는 `struct clk`에 작용하는 여러 드라이버용 함수를 정의하며, 해당 API는 `include/linux/clk.h`에 문서화되어 있습니다.

공통 `struct clk_core`를 사용하는 플랫폼과 장치는 `clk-provider.h`에 정의된 동작의 하드웨어 고유 부분을 수행하기 위해 `struct clk_core`의 `struct clk_ops` 포인터를 사용합니다.

struct clk_ops {
        int                (*prepare)(struct clk_hw *hw);
        void                (*unprepare)(struct clk_hw *hw);
        int                (*is_prepared)(struct clk_hw *hw);
        void                (*unprepare_unused)(struct clk_hw *hw);
        int                (*enable)(struct clk_hw *hw);
        void                (*disable)(struct clk_hw *hw);
        int                (*is_enabled)(struct clk_hw *hw);
        void                (*disable_unused)(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                (*init)(struct clk_hw *hw);
        void                (*debug_init)(struct clk_hw *hw,
                                      struct dentry *dentry);
};

하드웨어 clock 구현

공통 `struct clk_core`의 핵심은 `.ops`와 `.hw` 포인터입니다. 이 포인터는 `struct clk`의 공통 세부 사항과 하드웨어 고유 부분을 서로 추상화합니다. `drivers/clk/clk-gate.c`의 간단한 gate clock 구현은 다음과 같습니다.

struct clk_gate {
        struct clk_hw        hw;
        void __iomem    *reg;
        u8              bit_idx;
        ...
};

`struct clk_gate`는 `struct clk_hw hw`와 함께 어떤 레지스터와 비트가 clock gating을 제어하는지에 관한 하드웨어 지식을 담습니다. `enable_count`, `notifier_count` 같은 토폴로지 및 회계 정보는 필요하지 않으며 공통 프레임워크와 `struct clk_core`가 처리합니다.

드라이버 코드가 이 clock을 준비하고 활성화하는 시작점은 다음과 같습니다.

struct clk *clk;
clk = clk_get(NULL, "my_gateable_clk");

clk_prepare(clk);
clk_enable(clk);

`clk_enable()` 호출은 연산 테이블을 거쳐 gate 구현과 레지스터 비트 설정 함수로 이어집니다. 원문 호출 그래프를 exact 블록과 구조화 흐름으로 함께 보존합니다.

clk_enable(clk);
        clk->ops->enable(clk->hw);
        [resolves to...]
                clk_gate_enable(hw);
                [resolves struct clk gate with to_clk_gate(hw)]
                        clk_gate_set_bit(gate);

`clk_gate_set_bit()`은 대상 레지스터를 읽고 `bit_idx` 비트를 설정한 뒤 다시 기록합니다.

static void clk_gate_set_bit(struct clk_gate *gate)
{
        u32 reg;

        reg = __raw_readl(gate->reg);
        reg |= BIT(gate->bit_idx);
        writel(reg, gate->reg);
}

`to_clk_gate()`는 `container_of()`를 사용해 `struct clk_hw`에서 바깥 `struct clk_gate`를 얻습니다.

#define to_clk_gate(_hw) container_of(_hw, struct clk_gate, hw)

이 추상화 패턴은 모든 clock 하드웨어 표현에 사용됩니다.

새 clock 하드웨어 지원

새 clock 유형을 지원하려면 먼저 `include/linux/clk-provider.h` provider 헤더를 포함하면 됩니다.

#include <linux/clk-provider.h>

플랫폼용 clock 하드웨어 구조체는 `struct clk_hw`와 하드웨어 고유 데이터를 함께 담도록 정의합니다.

struct clk_foo {
        struct clk_hw hw;
        ... hardware specific data goes here ...
};

하드웨어 데이터를 사용하려면 해당 clock에 유효한 `struct clk_ops` 연산을 제공합니다.

struct clk_ops clk_foo_ops = {
        .enable                = &clk_foo_enable,
        .disable        = &clk_foo_disable,
};

각 연산은 `container_of()` 기반 변환으로 `struct clk_hw`에서 하드웨어 고유 구조체를 얻은 뒤 실제 하드웨어 작업을 수행하도록 구현합니다.

#define to_clk_foo(_hw) container_of(_hw, struct clk_foo, hw)

int clk_foo_enable(struct clk_hw *hw)
{
        struct clk_foo *foo;

        foo = to_clk_foo(hw);

        ... perform magic on foo ...

        return 0;
};

이어지는 행렬은 clock 하드웨어 기능별로 어떤 `clk_ops`가 필수인지 나타냅니다. `y`는 필수, `n`은 해당 콜백이 잘못되었거나 불필요함을 뜻하고, 빈 칸은 선택 사항이거나 개별 상황에 따라 판단해야 함을 뜻합니다.

clock 기능별 필수 연산과 등록

마지막으로 하드웨어 고유 등록 함수가 `struct clk_foo` 데이터를 채우고 공통 `struct clk` 매개변수를 프레임워크에 전달해 런타임에 clock을 등록합니다.

clk_register(...)

구현 예제는 `drivers/clk/clk-*.c`의 기본 clock 유형을 참조하십시오.

사용하지 않는 clock gating 비활성화 우회

개발 중에는 사용하지 않는 clock을 기본적으로 끄는 동작을 우회하는 것이 유용할 수 있습니다. 드라이버가 clock을 올바르게 활성화하지 않고 부트로더가 켜 둔 상태에 의존한다면, 자동 비활성화를 우회해 문제를 고치는 동안 드라이버 기능을 유지할 수 있습니다.

다음 커널 매개변수로 부팅하면 어떤 clock이 비활성화됐는지 확인할 수 있습니다.

tp_printk trace_event=clk:clk_disable

비활성화를 우회하려면 커널 bootargs에 `clk_ignore_unused`를 포함합니다.

prepare lock과 enable lock

공통 clock 프레임워크는 전역 잠금 두 개, 즉 prepare lock과 enable lock을 사용합니다.

enable lock은 spinlock이며 `.enable`, `.disable` 연산 호출 동안 유지됩니다. 따라서 이 연산은 잠들 수 없고 `clk_enable()`, `clk_disable()` API는 atomic context에서 호출할 수 있습니다.

`clk_is_enabled()`도 atomic context에서 사용할 수 있도록 설계됐습니다. 다만 enable lock을 잡은 상태로 결과를 다른 작업과 함께 사용하려는 경우가 아니라면 코어에서 lock을 유지할 실익은 없습니다. 함수 반환 후 잠금이 풀리면 활성 상태가 즉시 바뀔 수 있으므로, 사용자는 해당 상태를 이용하는 작업 동안 값이 변하지 않도록 읽기와 사용을 직접 동기화해야 합니다.

prepare lock은 mutex이며 그 밖의 모든 연산 호출 동안 유지됩니다. 이 연산들은 잠들 수 있고, 대응 API 함수는 atomic context에서 호출할 수 없습니다.

공유 리소스 보호와 재진입성

잠금 관점에서 clock 연산은 두 그룹으로 나뉩니다. 같은 그룹 연산끼리 공유하는 리소스는 여러 clock이 함께 사용하더라도 드라이버가 별도로 보호할 필요가 없습니다.

반면 두 그룹의 연산이 함께 사용하는 리소스는 드라이버가 보호해야 합니다. clock 속도와 enable 또는 disable 상태를 모두 제어하는 레지스터가 그 예입니다.

clock 프레임워크는 재진입 가능합니다. 드라이버는 clock 연산 구현 안에서 프레임워크 함수를 호출할 수 있으며, 한 clock의 `.set_rate` 안에서 다른 clock의 `.set_rate`가 호출될 수도 있습니다. 드라이버 구현은 이 경우를 고려해야 하지만 보통 코드 흐름은 드라이버가 통제합니다.

공통 clock 프레임워크 밖의 코드가 clock 연산이 사용하는 리소스에 접근할 때도 잠금을 고려해야 합니다. 이 문제는 문서 범위를 벗어납니다.