Reset Controller 프레임워크

리눅스 reset controller 프레임워크를 "assert/deassert 몇 번 하는 API" 수준이 아니라, SoC 주변장치의 초기화와 복구를 표현하는 공통 상태 모델로 정리합니다. reset_control consumer API, shared/exclusive reset의 공식 의미, self-deasserting pulse reset, optional/array/acquire-release API, reset_controller_dev provider 등록, Device Tree의 resets/reset-names/#reset-cells 바인딩, clock/regulator/runtime PM과의 시퀀스, bootloader handoff, cold boot와 resume 차이, 실전 디버깅과 실패 패턴까지 자세히 다룹니다.

reset framework가 필요한 이유와 책임 경계

주변장치는 전원만 공급된다고 해서 자동으로 정상 동작하지 않습니다. 이전 부팅에서 남은 DMA 상태, internal state machine, firmware MCU, bus handshake, PHY calibration 상태가 뒤섞인 채 남아 있을 수 있습니다. 이때 reset line을 적절히 assert하거나 pulse를 걸어 known-good state로 되돌리는 것이 필요합니다. reset controller 프레임워크는 이 과정을 consumer-driver마다 제멋대로 구현하지 않도록 공통 API와 공통 DT binding으로 정리합니다.

공식 커널 문서는 reset controller API의 책임을 명확히 구분합니다. 특히 일부 reset controller 하드웨어가 system restart 기능도 같이 제공할 수는 있지만, system restart handler는 reset controller API의 범위 밖이라고 설명합니다. 즉 이 프레임워크는 "장치 블록을 known state로 되돌리는 것"이 주제이지, 시스템 전체 재부팅을 설명하는 프레임워크는 아닙니다.

consumer 관점의 공식 의미: exclusive와 shared

reset controller API는 reset control을 요청할 때부터 의미를 나눕니다. exclusive reset은 드라이버가 해당 control을 직접 제어한다고 가정하고, shared reset은 여러 소비자가 같은 control을 함께 사용하는 상황을 모델링합니다. 이 차이는 단순한 ownership 표시가 아니라, assert(), deassert(), reset()의 물리적 효과 자체를 바꿉니다.

공식 문서 기준으로 shared reset은 clock framework의 shared enable과 비슷합니다. 첫 번째 deassert만 실제 선을 deassert할 수 있고, 마지막 assert만 실제 선을 assert할 수 있습니다. 그래서 shared reset에서 reset_control_assert()를 호출했다고 해서 물리 선이 반드시 assert된다고 기대하면 안 됩니다. 다른 소비자가 계속 deassert를 요구하고 있으면 선은 여전히 deassert 상태일 수 있습니다.

level reset과 self-deasserting pulse reset

모든 reset이 "assert 상태를 유지했다가 deassert"되는 것은 아닙니다. 어떤 하드웨어는 self-clearing bit를 쓰며, 소프트웨어가 trigger를 한 번 쓰면 하드웨어가 내부적으로 pulse를 발생시키고 자동으로 원래 상태로 돌아옵니다. 공식 커널 문서는 이런 경우를 self-deasserting reset control로 설명하고, consumer는 reset_control_reset()으로 pulse를 요청한다고 정의합니다.

공식 문서는 일반적으로 self-deasserting pulse reset은 shared에 적합하지 않다고 설명합니다. 어느 consumer가 pulse를 요청해도 연결된 모든 주변장치가 reset되기 때문입니다. 다만 API는 shared pulse reset도 허용하며, 그 경우 첫 trigger만 실제 pulse를 내고 이후에는 모든 consumer가 reset_control_rearm()을 호출할 때까지 추가 pulse를 내지 않는 모델을 제공합니다.

consumer API 전체 지도

기본 getter 몇 개만 알아도 대부분의 드라이버는 동작하지만, 실제 API 표면은 더 넓습니다. exclusive/shared, optional, deasserted convenience, released/acquire-release, bulk array가 모두 존재합니다.

#include <linux/reset.h>

struct reset_control *rst;

rst = devm_reset_control_get_exclusive(dev, "core");
if (IS_ERR(rst))
    return dev_err_probe(dev, PTR_ERR(rst),
                         "failed to get core reset\n");

reset_control_assert(rst);
usleep_range(10, 20);
reset_control_deassert(rst);

optional reset도 매우 중요합니다. 공식 문서 기준으로 optional getter는 reset이 DT에 아예 없을 때 NULL을 반환하고, 이후 reset API들은 NULL을 quietly 처리합니다. 즉 "플랫폼 A에는 reset이 있지만 플랫폼 B에는 없다" 같은 변종을 ifdef 없이 같은 driver로 처리할 수 있습니다.

struct reset_control *phy_rst;

phy_rst = devm_reset_control_get_optional_exclusive(dev, "phy");
if (IS_ERR(phy_rst))
    return PTR_ERR(phy_rst);

/* phy_rst가 NULL이어도 API는 조용히 성공 */
reset_control_deassert(phy_rst);

shared reset의 정확한 의미와 금지 패턴

shared reset은 가장 자주 오해되는 부분입니다. 공식 문서는 shared reset에 대해 아래 제약을 분명히 둡니다.

/* 잘못된 기대: shared reset에서 assert()가 실제 reset을 보장한다고 가정 */
reset_control_assert(shared_rst);
/* 여기서 "레지스터 상태가 깨끗해졌을 것"이라고 가정하면 안 됨 */

/* 올바른 접근: shared line은 refcount 의미만 신뢰 */
reset_control_deassert(shared_rst);
/* 최소한 내 consumer가 reset에 잡혀 있지는 않음을 보장받음 */

또한 shared reset line에서 reset_control_reset()과 reset_control_rearm()를 썼다면, 공식 문서 기준으로 assert/deassert 모델과 섞어 쓰면 안 됩니다. driver가 "이 reset은 level 상태를 관리하는가, pulse를 트리거하는가"를 처음부터 하나로 결정해야 합니다.

array와 bulk reset: 편하지만 순서는 보장되지 않음

하나의 장치가 여러 reset line을 갖는 경우도 흔합니다. 예를 들어 USB 컨트롤러는 core reset, PHY reset, bus reset을 따로 가질 수 있습니다. 이런 경우 bulk API나 array handle이 편리합니다. 하지만 공식 문서는 reset control array API는 개별 control을 어떤 순서로 처리할지 보장하지 않는다고 명시합니다.

static struct reset_control_bulk_data rstcs[] = {
    { .id = "core" },
    { .id = "phy" },
};

ret = devm_reset_control_bulk_get_shared(dev, ARRAY_SIZE(rstcs), rstcs);
if (ret)
    return ret;

ret = reset_control_bulk_deassert(ARRAY_SIZE(rstcs), rstcs);
if (ret)
    return ret;

공식 문서는 array handle에 대해 reset_control_status()를 적용할 수 없다고도 설명합니다. 즉 array는 "묶음 처리"에는 좋지만, 개별 라인의 세밀한 상태 추적과 strict sequencing에는 적합하지 않습니다.

provider 관점: reset_controller_dev와 reset_control_ops

지금까지는 consumer 쪽만 봤지만, reset controller driver를 쓰려면 provider 인터페이스를 이해해야 합니다. 공식 문서는 provider driver가 struct reset_controller_dev를 채우고 reset_controller_register() 또는 devm_reset_controller_register()로 등록한다고 설명합니다. 실제 동작은 struct reset_control_ops의 콜백이 담당합니다.

#include <linux/reset-controller.h>

struct my_reset {
    struct reset_controller_dev rcdev;
    void __iomem *base;
    spinlock_t lock;
};

#define to_my_reset(_rcdev) container_of(_rcdev, struct my_reset, rcdev)

static int my_reset_assert(struct reset_controller_dev *rcdev, unsigned long id)
{
    struct my_reset *rst = to_my_reset(rcdev);
    unsigned long flags;
    u32 val;

    spin_lock_irqsave(&rst->lock, flags);
    val = readl(rst->base + 0x100);
    val |= BIT(id);
    writel(val, rst->base + 0x100);
    spin_unlock_irqrestore(&rst->lock, flags);
    return 0;
}

static int my_reset_deassert(struct reset_controller_dev *rcdev, unsigned long id)
{
    struct my_reset *rst = to_my_reset(rcdev);
    unsigned long flags;
    u32 val;

    spin_lock_irqsave(&rst->lock, flags);
    val = readl(rst->base + 0x100);
    val &= ~BIT(id);
    writel(val, rst->base + 0x100);
    spin_unlock_irqrestore(&rst->lock, flags);
    return 0;
}

static const struct reset_control_ops my_reset_ops = {
    .assert = my_reset_assert,
    .deassert = my_reset_deassert,
    .status = my_reset_status,
};

provider는 단순 비트 set/clear만 할 수도 있고, 하드웨어가 self-clearing pulse register를 제공한다면 .reset 콜백을 구현할 수도 있습니다. status 조회를 지원하지 않는 controller도 많으므로 .status는 optional인 경우가 흔합니다.

provider 등록과 DT xlate

Device Tree에서 consumer는 보통 resets = <&rst N> 형태로 provider를 참조합니다. provider는 자신이 phandle arguments를 몇 개 받는지 #reset-cells로 정의하고, 커널에서는 of_reset_n_cells와 of_xlate로 이를 해석합니다.

static int my_reset_probe(struct platform_device *pdev)
{
    struct my_reset *rst;

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

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

    rst->rcdev.owner = THIS_MODULE;
    rst->rcdev.ops = &my_reset_ops;
    rst->rcdev.of_node = pdev->dev.of_node;
    rst->rcdev.of_reset_n_cells = 1;
    rst->rcdev.nr_resets = 64;

    return devm_reset_controller_register(&pdev->dev, &rst->rcdev);
}

rst: reset-controller@ff730000 {
    compatible = "vendor,soc-reset";
    reg = <0x0 0xff730000 0x0 0x1000>;
    #reset-cells = <1>;
};

usb@12340000 {
    compatible = "vendor,my-usb";
    reg = <0x0 0x12340000 0x0 0x10000>;
    resets = <&rst 12>, <&rst 13>;
    reset-names = "core", "phy";
};

소비자 드라이버 구현 패턴

실전 consumer driver는 보통 다음 구조를 가집니다. reset만 따로 보는 것이 아니라 regulator, clock, runtime PM, firmware load와 한 흐름으로 다뤄야 합니다.

1. 필요한 reset handle을 얻습니다.
2. runtime PM 또는 power domain을 올립니다.
3. regulator와 clock을 준비합니다.
4. 필요 시 assert 후 최소 폭을 지킨 뒤 deassert합니다.
5. MMIO 초기화와 firmware download를 수행합니다.
6. 에러 시 되돌리는 순서를 명확히 정합니다.

static int my_ip_probe(struct platform_device *pdev)
{
    struct my_ip *priv;
    int ret;

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

    priv->core_rst = devm_reset_control_get_exclusive(&pdev->dev, "core");
    if (IS_ERR(priv->core_rst))
        return dev_err_probe(&pdev->dev, PTR_ERR(priv->core_rst),
                             "failed to get core reset\n");

    ret = pm_runtime_resume_and_get(&pdev->dev);
    if (ret)
        return ret;

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

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

    reset_control_assert(priv->core_rst);
    usleep_range(10, 20);

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

    ret = my_ip_hw_init(priv);
    if (ret)
        goto err_assert_rst;

    return 0;

err_assert_rst:
    reset_control_assert(priv->core_rst);
err_disable_clks:
    clk_bulk_disable_unprepare(priv->num_clks, priv->clks);
err_disable_regs:
    regulator_bulk_disable(priv->num_supplies, priv->supplies);
err_put_pm:
    pm_runtime_put(&pdev->dev);
    return ret;
}

위 코드는 보편적인 패턴일 뿐이며, 하드웨어에 따라 assert가 필요 없거나, bootloader가 이미 assert 상태를 보장하거나, reset이 pulse형이어서 reset_control_reset() 하나로 끝날 수도 있습니다. 중요한 것은 데이터시트 요구를 API 의미에 정확히 매핑하는 것입니다.

clock, regulator, runtime PM과의 순서

reset 문제는 사실상 시퀀스 문제인 경우가 많습니다. reset deassert는 대개 "이제 장치 내부 상태기가 돌아가기 시작한다"는 뜻이므로, 그 전에 bus clock과 core clock이 살아 있어야 하고, 필요한 전압 레일이 안정화되어 있어야 하며, PM domain이 register 접근을 허용해야 합니다.

resume 경로에서는 cold boot보다 더 미묘합니다. reset line을 유지해야 하는 장치도 있고, retention register를 믿지 못해 resume 때마다 pulse reset이 필요한 장치도 있습니다. 그래서 "cold boot에서 되면 끝"이 아니라 runtime suspend/resume까지 포함해서 시퀀스를 설계해야 합니다.

provider 내부 구현 패턴과 락

provider driver는 종종 shared MMIO register를 다룹니다. 예를 들어 reset bit와 clock gate bit가 같은 register bank에 있을 수 있고, 여러 reset line이 하나의 32비트 레지스터를 공유할 수 있습니다. 이때 provider가 자체 락을 두지 않으면 경쟁 조건으로 잘못된 비트가 깨질 수 있습니다.

static int my_reset_reset(struct reset_controller_dev *rcdev, unsigned long id)
{
    struct my_reset *rst = to_my_reset(rcdev);
    unsigned long flags;

    /* self-clearing pulse trigger 예시 */
    spin_lock_irqsave(&rst->lock, flags);
    writel(BIT(id), rst->base + 0x104);
    spin_unlock_irqrestore(&rst->lock, flags);

    /* 필요한 경우 완료 비트 polling */
    return 0;
}

provider가 .reset를 구현한다고 해서 항상 .assert/.deassert도 구현해야 하는 것은 아닙니다. 하드웨어가 pulse trigger만 제공한다면 .reset만 의미 있을 수 있습니다. 반대로 level reset만 지원하면 .assert/.deassert만 구현하고 .reset는 비워 둘 수 있습니다.

고급 API: released, acquire/release, rearm, status

실전에서는 드문 편이지만, 아래 API들을 알아두면 framework의 의미가 더 분명해집니다.

Device Tree binding 세부사항

consumer 노드가 여러 reset을 가질 때는 reset-names와 함께 쓰는 것이 좋고, provider 노드는 #reset-cells를 명확히 해야 합니다. 또한 어떤 SoC에서는 하나의 상위 노드가 clock provider와 reset provider를 동시에 제공하기도 합니다. 이 경우 같은 MMIO block에서 clock과 reset이 함께 관리되므로, CCF와 reset framework의 provider 드라이버가 분리되어도 register locking과 probe 순서는 신중히 설계해야 합니다.

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

ethernet@10020000 {
    compatible = "vendor,my-mac";
    clocks = <&ccu 4>, <&ccu 5>;
    clock-names = "stmmaceth", "ptp_ref";
    resets = <&ccu 9>;
    reset-names = "stmmaceth";
};

디버깅 절차와 관찰 포인트

reset 문제는 종종 "device not responding", "timeout", "register read returns 0xffffffff", "DMA never starts" 같은 비특이적 증상으로 나타납니다. 따라서 reset 자체만 보기보다, reset 전후의 power/clock/MMIO/interrupt 상태를 함께 기록하는 편이 훨씬 효과적입니다.

1. DT binding 확인
   resets, reset-names, provider #reset-cells가 실제 driver 기대와 맞는지 먼저 확인합니다.
2. probe ordering 확인
   provider가 먼저 probe되었는지, consumer가 -EPROBE_DEFER를 적절히 처리하는지 확인합니다.
3. 시퀀스 로깅
   regulator on, clock enable, reset deassert, MMIO init 순서를 로그로 남깁니다.
4. 딜레이 검증
   assert 폭과 deassert 후 안정화 시간이 데이터시트 최소값을 만족하는지 확인합니다.
5. resume와 cold boot 비교
   cold boot에서만 성공하고 resume에서 실패하면 retention/reset 복구 문제가 많습니다.

# DT에서 reset 관련 노드 찾기
grep -R "reset-names" /sys/firmware/devicetree/base 2>/dev/null

# dmesg에서 provider/consumer 초기화 추적
dmesg | grep -i -E "reset|deassert|assert|probe defer|clock|regulator"

# 소비자 노드의 리소스 확인
grep -R "resets" /sys/firmware/devicetree/base 2>/dev/null

provider가 status를 지원하면 훨씬 편하지만, 많은 reset controller는 status를 제공하지 않습니다. 이 경우 reset 상태는 MMIO side effect, register accessibility, interrupt arrival 여부로 간접 확인하는 수밖에 없습니다.

흔한 실패 패턴과 원인 추적

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

아래는 USB controller가 cold boot와 runtime resume에서 reset을 어떻게 다르게 다뤄야 하는지 보여 주는 예제입니다.

관련 문서

• Common Clock Framework — reset과 같이 맞물리는 clock 시퀀스
• Regulator 프레임워크 — reset 전후 전압 레일과 DVFS 순서
• Device Tree — resets, reset-names, #reset-cells 바인딩
• 전원 관리 — runtime PM, suspend/resume 복구
• 디바이스 드라이버 — probe/remove와 devm 리소스 관리
• USB — PHY/core reset과 suspend/resume 복구의 대표 사례