커널 API 레퍼런스

커널 코드 리뷰에서 반복해서 등장하는 함수, 매크로, 심볼을 컨텍스트 중심으로 대규모 정리했습니다. 각 항목은 "언제 쓰는가", "자주 나는 실수", "대체 API", "소스 경로"를 함께 담아 실전 참고서로 바로 사용할 수 있게 구성했습니다.

핵심 | 이 문서를 빠르게 읽는 법

이 페이지(Page)는 "API 목록"이 아니라 "의사결정 지원서"입니다. 각 표는 같은 구조(언제 사용/실수 패턴/대체안)로 작성되어 있으므로, 문제가 발생했을 때 아래 순서로 접근하면 가장 빠릅니다.

1. 문맥 확인
   현재 코드가 프로세스 문맥인지, IRQ 문맥인지, sleep 가능한지 먼저 확정합니다.
2. 반환 규약 확인
   호출 API가 NULL 반환형인지 ERR_PTR 반환형인지 먼저 고정합니다.
3. 짝 API 확인
   할당/해제, lock/unlock, get/put 쌍이 모두 존재하는지 체크합니다.
4. 실수 패턴 역검증
   표의 "실수 패턴" 열을 기준으로 현재 코드가 이미 같은 실수를 반복하는지 확인합니다.
5. 대체안 검토
   현재 경로가 문맥과 맞지 않으면 즉시 "대체/보완" API로 치환 전략을 세웁니다.

핵심 | API 선택 의사결정 플로우

실무 체크포인트: 코드 리뷰 전에 문맥, 반환규약, 해제쌍 3가지를 PR 설명에 먼저 명시하세요.

핵심 | 빠른 이동 인덱스

검색형 레퍼런스로 사용할 때는 아래 인덱스에서 도메인을 먼저 고르고, 해당 카탈로그로 바로 이동하세요.

핵심 | 개요

아래 다이어그램은 함수, 매크로, 심볼이 어떻게 연결되는지 보여줍니다. 함수는 동작 단위, 매크로는 규약 단축, 심볼은 모듈 간 계약입니다.

실무 체크포인트: 신규 심볼 export 전에는 반드시 기존 내부 함수로 대체 가능한지 먼저 확인하세요.

/* 실패 경로를 먼저 설계한 전형적인 초기화 패턴 */
static int __init sample_init(void)
{
    int ret;

    ret = register_chrdev(0, "sample", &fops);
    if (ret < 0)
        return ret;

    if (unlikely(!ready)) {
        unregister_chrdev(ret, "sample");
        return -EINVAL;
    }

    pr_info("sample initialized\n");
    return 0;
}

핵심 | 로깅과 출력 함수

로깅 API는 단순 출력 함수가 아니라 장애 대응 속도를 결정하는 운영 인터페이스입니다. 이 표는 로그 레벨 선택, 디바이스 컨텍스트 포함 여부, 폭주 억제 전략을 함께 판단하기 위한 기준으로 읽어야 합니다. 특히 핫패스에서는 정보량보다 샘플링 정책과 레이트 리밋이 우선입니다.

실무 체크포인트: 실패 로그에는 반드시 "실패 동작 + 식별자 + errno"를 한 줄에 남기고, 정상 경로 로그는 기본적으로 억제하세요.

/* 로그 레벨 실전 사용 예시 */
#define pr_fmt(fmt) KBUILD_MODNAME ": " fmt

static int demo_hw_init(struct device *dev)
{
    u32 status = readl(base + STATUS_REG);

    if (!(status & HW_READY_BIT)) {
        dev_err(dev, "hw not ready, status=0x%08x\n", status);
        return -ETIMEDOUT;
    }

    if (status & HW_DEGRADED_BIT)
        dev_warn(dev, "hw running in degraded mode\n");

    dev_info(dev, "hw init ok, version=%u\n",
             (status >> 16) & 0xFF);

    dev_dbg(dev, "full status register: 0x%08x\n", status);
    return 0;
}

/* pr_fmt 매크로 — 모듈명 자동 접두사 */
/* 출력: "demo_drv: hw init ok, version=3" */

/* 레이트 리밋 패턴 — 핫패스 로그 폭주 방지 */
static void demo_handle_error(int err_code)
{
    pr_err_ratelimited("hw error %d (further messages suppressed)\n",
                       err_code);
}

/* 동적 디버그 — 런타임 토글 */
/* echo 'module demo_drv +p' > /sys/kernel/debug/dynamic_debug/control */
pr_debug("packet rx: len=%u proto=0x%04x\n", len, proto);

핵심 | 메모리 할당/해제

메모리 API 선택은 크기보다 실행 문맥과 회수 전략을 먼저 결정해야 안전합니다. 같은 할당이라도 sleep 가능 여부와 reclaim 허용 범위가 다르면 실패 확률과 지연(Latency) 특성이 크게 달라집니다. 표를 볼 때는 "할당 성공"보다 "실패 시 되돌리기"가 닫히는지부터 확인해야 합니다.

실무 체크포인트: 모든 할당 지점에 대응하는 해제 API를 함수 단위가 아니라 실패 경로 단위로 짝지어 점검하세요.

/* 메모리 할당 실전 패턴 — 문맥별 GFP 선택 */

/* 프로세스 문맥: GFP_KERNEL (sleep 가능, reclaim 허용) */
static int demo_probe_alloc(struct device *dev)
{
    struct demo_priv *p = devm_kzalloc(dev, sizeof(*p), GFP_KERNEL);
    if (!p)
        return -ENOMEM;

    /* 사용자 제어 크기 — kcalloc로 오버플로 방지 */
    p->entries = devm_kcalloc(dev, p->num_entries,
                              sizeof(*p->entries), GFP_KERNEL);
    if (!p->entries)
        return -ENOMEM;

    return 0;
}

/* IRQ/softirq 문맥: GFP_ATOMIC (sleep 불가) */
static irqreturn_t demo_irq(int irq, void *dev_id)
{
    struct demo_event *evt;

    evt = kmalloc(sizeof(*evt), GFP_ATOMIC);
    if (!evt) {
        /* 할당 실패 허용 — 이벤트 드롭 */
        pr_warn_ratelimited("event alloc failed\n");
        return IRQ_HANDLED;
    }
    /* evt 처리 후 kfree */
    return IRQ_HANDLED;
}

/* 파일시스템 문맥: GFP_NOFS (재진입 방지) */
void *buf = kmalloc(4096, GFP_NOFS);
/* GFP_NOFS: 메모리 회수 시 파일시스템 콜백 금지 */

핵심 | 사용자 공간(User Space) 접근

사용자 공간 접근 API는 보안 경계와 오류 전파 규약이 동시에 걸린 고위험 구간입니다. 표의 핵심은 복사 함수 선택 자체보다 반환값 해석과 부분 복사 처리 규칙을 고정하는 데 있습니다. 주소 검증과 실제 복사는 별개의 단계라는 점을 항상 분리해서 보아야 합니다.

실무 체크포인트: `copy_*_user` 반환값을 무시하는 코드는 기능 동작과 무관하게 즉시 수정 대상으로 분류하세요.

/* copy_from_user / copy_to_user 안전 패턴 */
static ssize_t demo_write(struct file *f,
                          const char __user *ubuf,
                          size_t count, loff_t *ppos)
{
    struct demo_dev *d = f->private_data;
    char kbuf[128];
    size_t len;

    /* 크기 제한 검증 */
    len = min(count, sizeof(kbuf) - 1);

    /* 반환값 반드시 검사: 0이면 성공, 양수이면 복사 실패 바이트 수 */
    if (copy_from_user(kbuf, ubuf, len))
        return -EFAULT;

    kbuf[len] = '\0';

    mutex_lock(&d->lock);
    strscpy(d->label, kbuf, sizeof(d->label));
    mutex_unlock(&d->lock);

    return len;
}

static ssize_t demo_read(struct file *f,
                         char __user *ubuf,
                         size_t count, loff_t *ppos)
{
    struct demo_dev *d = f->private_data;
    char kbuf[128];
    ssize_t len;

    mutex_lock(&d->lock);
    len = scnprintf(kbuf, sizeof(kbuf), "%s\n", d->label);
    mutex_unlock(&d->lock);

    return simple_read_from_buffer(ubuf, count, ppos, kbuf, len);
}

/* get_user / put_user — 스칼라 값 단일 전송 */
static long demo_ioctl(struct file *f, unsigned int cmd,
                      unsigned long arg)
{
    struct demo_dev *d = f->private_data;
    u32 val;

    switch (cmd) {
    case DEMO_GET_STATUS:
        if (put_user(d->status, (u32 __user *)arg))
            return -EFAULT;
        return 0;
    case DEMO_SET_MODE:
        if (get_user(val, (u32 __user *)arg))
            return -EFAULT;
        if (val > DEMO_MODE_MAX)
            return -EINVAL;
        d->mode = val;
        return 0;
    default:
        return -ENOTTY;
    }
}

핵심 | 에러 처리 매크로

에러 처리 매크로는 코드 스타일이 아니라 함수 계약을 표현하는 수단입니다. 포인터 계열과 정수 계열 계약을 혼동하면 정상 경로에서도 잘못된 분기가 만들어져 장애를 유발합니다. 이 섹션은 "검사 매크로 선택"보다 "반환 계약 명시"를 먼저 수행하는 기준으로 사용해야 합니다.

실무 체크포인트: 포인터 반환 함수 선언부 주석에 `NULL` 계열인지 `ERR_PTR` 계열인지를 명시하고 그 규약만 허용하세요.

/* ERR_PTR / IS_ERR / PTR_ERR 완전 패턴 */
static struct demo_obj *demo_create(const char *name)
{
    struct demo_obj *obj;

    if (!name || !*name)
        return ERR_PTR(-EINVAL);

    obj = kzalloc(sizeof(*obj), GFP_KERNEL);
    if (!obj)
        return ERR_PTR(-ENOMEM);

    obj->name = kstrdup(name, GFP_KERNEL);
    if (!obj->name) {
        kfree(obj);
        return ERR_PTR(-ENOMEM);
    }
    return obj;
}

/* 호출자: IS_ERR + PTR_ERR 조합 */
static int demo_setup(void)
{
    struct demo_obj *obj;

    obj = demo_create("sensor0");
    if (IS_ERR(obj)) {
        pr_err("create failed: %ld\n", PTR_ERR(obj));
        return PTR_ERR(obj);
    }
    /* obj 사용 */
    return 0;
}

/* PTR_ERR_OR_ZERO: 포인터→int 변환 단축 */
static int demo_get_clk(struct device *dev)
{
    struct clk *c = devm_clk_get(dev, "core");
    return PTR_ERR_OR_ZERO(c);  /* 성공=0, 실패=음수 errno */
}

/* goto cleanup 단계별 에러 처리 — 3단계 자원 할당 */
static int demo_complex_init(struct device *dev)
{
    struct demo_priv *priv;
    void __iomem *base;
    int ret;

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

    base = devm_ioremap_resource(dev,
                platform_get_resource(to_platform_device(dev), IORESOURCE_MEM, 0));
    if (IS_ERR(base))
        return PTR_ERR(base);  /* devm가 priv 정리 */

    priv->clk = devm_clk_get_enabled(dev, "bus");
    if (IS_ERR(priv->clk))
        return PTR_ERR(priv->clk);  /* devm가 base+priv 정리 */

    dev_info(dev, "init complete, base=%pR\n", base);
    return 0;
}

핵심 | 자료구조 매크로

자료구조 매크로는 성능 최적화 수단이 아니라 불변식 유지 수단입니다. 순회, 삽입, 삭제에서 한 단계만 어긋나도 use-after-free나 순회 손상이 즉시 발생하므로, 매크로의 전제 조건을 먼저 확인해야 합니다. 특히 RCU, 리스트 safe 순회, ID 할당 회수는 수명주기 규약과 함께 검토해야 합니다.

실무 체크포인트: 순회 중 삭제 가능성이 있으면 기본 순회 매크로 대신 safe 변형을 우선 검토하세요.

/* list_head 기본 패턴 — 삽입/순회/안전 삭제 */
struct demo_item {
    struct list_head node;
    int id;
    char name[32];
};

static LIST_HEAD(demo_list);
static DEFINE_MUTEX(demo_list_lock);

/* 삽입 */
static int demo_add(int id, const char *name)
{
    struct demo_item *item;

    item = kzalloc(sizeof(*item), GFP_KERNEL);
    if (!item)
        return -ENOMEM;

    item->id = id;
    strscpy(item->name, name, sizeof(item->name));

    mutex_lock(&demo_list_lock);
    list_add_tail(&item->node, &demo_list);
    mutex_unlock(&demo_list_lock);
    return 0;
}

/* 안전 삭제 — list_for_each_entry_safe 필수 */
static void demo_remove_all(void)
{
    struct demo_item *item, *tmp;

    mutex_lock(&demo_list_lock);
    list_for_each_entry_safe(item, tmp, &demo_list, node) {
        list_del(&item->node);
        kfree(item);
    }
    mutex_unlock(&demo_list_lock);
}

/* container_of 역추적 — 타이머 콜백에서 부모 구조체 접근 */
static void demo_timer_cb(struct timer_list *t)
{
    struct demo_dev *d = container_of(t, struct demo_dev, poll_timer);
    schedule_work(&d->poll_work);
}

/* hlist — 해시 테이블 삽입/탐색 패턴 */
#define DEMO_HASH_BITS  8
static DEFINE_HASHTABLE(demo_htable, DEMO_HASH_BITS);

struct demo_entry {
    struct hlist_node hnode;
    u32 key;
    u64 value;
};

static void demo_ht_insert(struct demo_entry *e)
{
    hash_add(demo_htable, &e->hnode, e->key);
}

static struct demo_entry *demo_ht_find(u32 key)
{
    struct demo_entry *e;
    hash_for_each_possible(demo_htable, e, hnode, key) {
        if (e->key == key)
            return e;
    }
    return NULL;
}

/* XArray — 인덱스 기반 저장/조회/순회 */
static DEFINE_XARRAY(demo_xa);

static int demo_xa_store(unsigned long idx, struct demo_obj *obj)
{
    void *old = xa_store(&demo_xa, idx, obj, GFP_KERNEL);
    return xa_err(old);
}

static void demo_xa_dump(void)
{
    struct demo_obj *obj;
    unsigned long idx;

    xa_for_each(&demo_xa, idx, obj)
        pr_info("xa[%lu] = %s\n", idx, obj->name);
}

핵심 | 락/동기화

락 선택은 동시성 제어와 지연 특성을 함께 결정하는 아키텍처 선택입니다. 이 표는 락의 이름을 외우기보다 호출 문맥, 임계영역 길이, sleep 가능 여부를 먼저 고정하기 위한 기준입니다. 락 자체보다 락 순서와 해제 경로 대칭성을 함께 확인해야 교착과 경합(Contention) 회귀를 줄일 수 있습니다.

실무 체크포인트: 새 락을 도입할 때 기존 락과의 획득 순서를 문서화하고 lockdep 경고 가능성을 사전에 점검하세요.

핵심 | 원자 연산/배리어

원자 연산과 배리어는 "동작한다"가 아니라 "가시성 계약이 맞다"를 검증해야 하는 영역입니다. `READ_ONCE`/`WRITE_ONCE`는 컴파일러 최적화(Compiler Optimization) 제어이고, 순서 보장(Ordering)은 acquire/release 또는 메모리 배리어(Memory Barrier)가 담당한다는 역할 분리가 핵심입니다. 락리스 코드에서는 재시도 루프와 수명주기 조건을 반드시 함께 설계해야 합니다.

실무 체크포인트: 락리스 변경에는 쌍이 되는 acquire/release 지점을 코드 리뷰 항목으로 고정하세요.

/* refcount_t 안전 패턴 — atomic_t 대신 사용 */
struct demo_conn {
    refcount_t refcnt;
    struct rcu_head rcu;
    char name[32];
};

static struct demo_conn *demo_conn_get(struct demo_conn *c)
{
    if (c && refcount_inc_not_zero(&c->refcnt))
        return c;
    return NULL;
}

static void demo_conn_release(struct rcu_head *rcu)
{
    struct demo_conn *c = container_of(rcu, struct demo_conn, rcu);
    kfree(c);
}

static void demo_conn_put(struct demo_conn *c)
{
    if (refcount_dec_and_test(&c->refcnt))
        call_rcu(&c->rcu, demo_conn_release);
}

/* acquire/release 쌍 — 락리스 게시 패턴 */
static struct config *shared_cfg;

/* 게시자 */
static void demo_publish_config(struct config *new_cfg)
{
    /* new_cfg 필드를 먼저 채운 후 release로 게시 */
    smp_store_release(&shared_cfg, new_cfg);
}

/* 소비자 */
static struct config *demo_read_config(void)
{
    return smp_load_acquire(&shared_cfg);
}

/* try_cmpxchg 락리스 갱신 루프 */
static void demo_atomic_max(atomic_t *v, int new_val)
{
    int old = atomic_read(v);

    while (old < new_val) {
        if (try_cmpxchg(&v->counter, &old, new_val))
            break;
        /* old는 try_cmpxchg가 현재 값으로 갱신 */
    }
}

핵심 | 스케줄링/대기

대기와 스케줄링 API는 CPU 사용률보다 깨어남 조건의 정확성이 먼저입니다. 대기 큐(Wait Queue), 타임아웃, 인터럽트 가능 여부를 혼동하면 간헐적 행과 응답 지연이 발생합니다. 이 섹션은 "어떻게 기다릴지"보다 "누가 어떤 조건에서 깨우는지"를 먼저 고정하는 용도로 읽어야 합니다.

실무 체크포인트: wait 계열 호출에는 대응되는 wake 경로와 종료 조건을 같은 패치(Patch) 안에서 함께 제시하세요.

/* wait_event + wake_up 조건 대기 패턴 */
static DECLARE_WAIT_QUEUE_HEAD(demo_wq);
static bool data_ready;

/* 생산자 — 데이터 준비 후 깨우기 */
static void demo_produce(void)
{
    /* ... 데이터 채움 ... */
    WRITE_ONCE(data_ready, true);
    wake_up_interruptible(&demo_wq);
}

/* 소비자 — 인터럽트 가능 대기 */
static int demo_consume(void)
{
    int ret;

    ret = wait_event_interruptible(demo_wq,
                                   READ_ONCE(data_ready));
    if (ret)
        return -ERESTARTSYS;  /* 시그널로 중단됨 */

    WRITE_ONCE(data_ready, false);
    /* ... 데이터 소비 ... */
    return 0;
}

/* completion — 초기화 완료 동기화 */
static DECLARE_COMPLETION(hw_init_done);

static int hw_init_thread(void *arg)
{
    /* 하드웨어 초기화 수행 */
    msleep(200);
    complete(&hw_init_done);
    return 0;
}

static int demo_wait_hw(void)
{
    unsigned long timeout;

    timeout = wait_for_completion_timeout(&hw_init_done,
                                          msecs_to_jiffies(5000));
    if (!timeout) {
        pr_err("hw init timed out\n");
        return -ETIMEDOUT;
    }
    return 0;
}

/* kthread 완전 수명주기 */
static struct task_struct *demo_task;

static int demo_kthread_fn(void *data)
{
    while (!kthread_should_stop()) {
        if (wait_event_interruptible(demo_wq,
                READ_ONCE(data_ready) || kthread_should_stop()))
            continue;
        if (kthread_should_stop())
            break;
        /* 작업 수행 */
        WRITE_ONCE(data_ready, false);
    }
    return 0;
}

static int __init demo_start(void)
{
    demo_task = kthread_run(demo_kthread_fn, NULL, "demo_worker");
    return IS_ERR(demo_task) ? PTR_ERR(demo_task) : 0;
}

static void __exit demo_stop(void)
{
    if (demo_task)
        kthread_stop(demo_task);  /* 스레드 종료 대기 */
}

핵심 | 모듈/디바이스 수명주기

모듈/디바이스 수명주기 API는 등록 성공보다 정리 순서의 일관성이 중요합니다. probe/remove, init/exit, get/put 경계가 어긋나면 언로드 실패와 참조 누수가 장기적으로 누적됩니다. 표를 볼 때는 "생성 경로"와 "실패 경로"를 항상 쌍으로 확인해야 합니다.

실무 체크포인트: `devm_*` 사용 범위를 먼저 결정하고 수동 해제 API와 혼용하지 않도록 경계를 명확히 하세요.

/* module_param — 런타임 파라미터 노출 */
static int debug_level = 0;
module_param(debug_level, int, 0644);
MODULE_PARM_DESC(debug_level, "Debug verbosity (0=off, 1=basic, 2=verbose)");

static char *device_name = "demo";
module_param(device_name, charp, 0444);
MODULE_PARM_DESC(device_name, "Device name prefix");

/* 사용: insmod demo.ko debug_level=2 device_name=mydev */
/* sysfs: /sys/module/demo/parameters/debug_level (읽기+쓰기) */
/* sysfs: /sys/module/demo/parameters/device_name (읽기 전용) */

/* devm_* 리소스 관리 — 수동 해제 불필요 */
static int demo_all_devm(struct platform_device *pdev)
{
    struct device *dev = &pdev->dev;
    struct demo_priv *p;
    void __iomem *base;
    struct clk *clk;

    /* 모든 할당이 devm — probe 실패 시 자동 역순 해제 */
    p = devm_kzalloc(dev, sizeof(*p), GFP_KERNEL);       /* ① */
    base = devm_platform_ioremap_resource(pdev, 0);    /* ② */
    clk = devm_clk_get_enabled(dev, "core");            /* ③ */

    /* ③ 실패 시: ②+① 자동 해제 */
    /* remove 시: ③→②→① 역순 자동 해제 */

    if (!p)
        return -ENOMEM;
    if (IS_ERR(base))
        return PTR_ERR(base);
    if (IS_ERR(clk))
        return PTR_ERR(clk);

    return 0;
}

핵심 | 타이머(Timer)/워크큐

타이머와 워크큐는 비동기 실행의 편의성만큼 종료 시점 관리가 어렵습니다. 스케줄링 시점보다 취소, 동기 삭제, flush 순서를 먼저 설계해야 use-after-free를 예방할 수 있습니다. 특히 자기 워커 문맥에서 동기 취소 호출 여부를 반드시 검토해야 합니다.

실무 체크포인트: 객체 해제 전 `del_timer_sync`/`cancel_*_sync`/`flush_*` 순서를 문서로 고정하세요.

/* 타이머 완전 패턴 — 주기적 폴링 + 안전 종료 */
struct demo_poller {
    struct timer_list timer;
    void __iomem *base;
    bool active;
};

static void demo_poll_cb(struct timer_list *t)
{
    struct demo_poller *p = from_timer(p, t, timer);
    u32 status;

    status = readl(p->base + STATUS_REG);
    if (status & ERROR_BIT)
        pr_warn("hw error detected: 0x%x\n", status);

    /* 재스케줄: 100ms 후 */
    if (READ_ONCE(p->active))
        mod_timer(&p->timer, jiffies + msecs_to_jiffies(100));
}

static void demo_poll_start(struct demo_poller *p)
{
    WRITE_ONCE(p->active, true);
    timer_setup(&p->timer, demo_poll_cb, 0);
    mod_timer(&p->timer, jiffies + msecs_to_jiffies(100));
}

static void demo_poll_stop(struct demo_poller *p)
{
    WRITE_ONCE(p->active, false);
    del_timer_sync(&p->timer);  /* 콜백 완료까지 대기 */
}

/* hrtimer — 나노초 정밀 타이머 */
static struct hrtimer demo_hrt;

static enum hrtimer_restart demo_hrt_cb(struct hrtimer *timer)
{
    /* 1ms 주기 작업 */
    do_periodic_work();
    hrtimer_forward_now(timer, ms_to_ktime(1));
    return HRTIMER_RESTART;
}

static void demo_hrt_init(void)
{
    hrtimer_init(&demo_hrt, CLOCK_MONOTONIC, HRTIMER_MODE_REL);
    demo_hrt.function = demo_hrt_cb;
    hrtimer_start(&demo_hrt, ms_to_ktime(1), HRTIMER_MODE_REL);
}

static void demo_hrt_exit(void)
{
    hrtimer_cancel(&demo_hrt);
}

핵심 | 디버깅(Debugging)/트레이싱

디버깅 API는 문제를 빨리 찾기 위한 도구이지만 잘못 쓰면 시스템 자체를 불안정하게 만듭니다. 임시 추적, 상시 관측, 운영 경보를 목적별로 분리하고 오버헤드(Overhead) 상한을 먼저 정해야 합니다. 이 표는 계측 정확도와 운영 안전성의 균형을 맞추는 기준으로 사용해야 합니다.

실무 체크포인트: `trace_printk` 같은 임시 도구는 리뷰 단계에서 반드시 제거 여부를 체크리스트로 확인하세요.

/* 디버깅 API 실전 사용 패턴 */

/* lockdep 검증 — 함수 진입 시 락 보유 확인 */
static void demo_update_locked(struct demo_dev *d, u32 val)
{
    lockdep_assert_held(&d->lock);  /* 락 미보유 시 경고 */
    d->reg_val = val;
    writel(val, d->base + DATA_REG);
}

/* WARN_ON_ONCE — 불변식 위반 1회 경고 */
static void demo_enqueue(struct demo_queue *q, struct demo_item *item)
{
    if (WARN_ON_ONCE(q->count >= q->capacity)) {
        /* 복구 가능 — 경고만 남기고 리턴 */
        return;
    }
    q->items[q->count++] = item;
}

/* tracepoint 정의 — include/trace/events/demo.h */
/*
 * TRACE_EVENT(demo_rx_packet,
 *     TP_PROTO(struct sk_buff *skb, int len),
 *     TP_ARGS(skb, len),
 *     TP_STRUCT__entry(
 *         __field(int, len)
 *         __string(dev, skb->dev->name)
 *     ),
 *     TP_fast_assign(
 *         __entry->len = len;
 *         __assign_str(dev, skb->dev->name);
 *     ),
 *     TP_printk("dev=%s len=%d", __get_str(dev), __entry->len)
 * );
 */

/* dump_stack — 호출 경로 즉시 확인 (디버그 전용) */
if (unexpected_state)
    dump_stack();  /* dmesg에 call trace 출력 */

핵심 | 심볼 Export/네임스페이스

심볼 export는 코드 재사용 편의가 아니라 모듈 간 ABI 계약을 외부에 공개하는 행위입니다. 한 번 노출된 인터페이스는 유지 비용이 커지므로, 최소 공개 원칙과 네임스페이스 정책을 동시에 적용해야 합니다. 이 표는 "export 가능 여부"보다 "내부화 가능성"을 먼저 검토하는 흐름으로 읽어야 합니다.

실무 체크포인트: 새 export에는 사용 모듈, 제거 불가능성, 네임스페이스 선택 근거를 커밋 메시지에 함께 남기세요.

핵심 | 버전/호환성 보조 매크로

호환성 매크로는 분기문 추가 도구가 아니라 유지보수 비용 제어 장치입니다. 버전 비교, Kconfig 조건, 컴파일 타임 검증을 혼용하면 백포트와 장기 유지에서 오류가 누적됩니다. 이 표는 런타임 분기보다 빌드 타임 계약을 우선 고정하는 기준으로 사용해야 합니다.

실무 체크포인트: 버전 조건을 추가할 때는 제거 시점과 대상 안정 커널 범위를 주석에 함께 기록하세요.

/* 버전/호환성 매크로 실전 사용 */

/* IS_ENABLED — Kconfig 조건 분기 (if문, #ifdef 불필요) */
static void demo_optional_feature(void)
{
    if (IS_ENABLED(CONFIG_DEMO_ADVANCED)) {
        /* CONFIG_DEMO_ADVANCED=y 또는 =m 일 때만 실행 */
        enable_advanced_mode();
    }
    /* 비활성 시 컴파일러가 dead code 제거 — 링크 에러 없음 */
}

/* BUILD_BUG_ON — 컴파일 타임 불변식 검사 */
BUILD_BUG_ON(sizeof(struct demo_msg) != 64);
/* 구조체 크기가 64가 아니면 빌드 실패 */

static_assert(sizeof(u64) == 8,
             "u64 must be 8 bytes");

/* GENMASK / BIT / FIELD_PREP / FIELD_GET — 레지스터 비트 조작 */
#define REG_MODE_MASK   GENMASK(7, 4)    /* 비트 7:4 */
#define REG_ENABLE_BIT  BIT(0)           /* 비트 0 */

static void demo_set_mode(void __iomem *base, u32 mode)
{
    u32 val = readl(base + CTRL_REG);

    val &= ~REG_MODE_MASK;
    val |= FIELD_PREP(REG_MODE_MASK, mode);
    val |= REG_ENABLE_BIT;

    writel(val, base + CTRL_REG);
}

static u32 demo_get_mode(void __iomem *base)
{
    u32 val = readl(base + CTRL_REG);
    return FIELD_GET(REG_MODE_MASK, val);
}

핵심 | 핵심 묶음 해설

앞의 핵심 묶음 표는 "자주 쓰는 API 리스트"가 아니라 "실수 예방 인덱스"입니다. 실무에서는 다음 세 가지 축을 동시에 맞춰야 안정적인 코드가 됩니다.

• 문맥 축 — sleep 가능 여부와 인터럽트 상태가 API 선택을 결정합니다.
• 수명 축 — 객체 생성부터 해제까지 참조/락/타이머의 종료 순서를 고정해야 합니다.
• 관측 축 — 문제를 찾기 쉬운 로그/트레이스 포인트를 처음부터 배치해야 운영 비용이 줄어듭니다.

즉, "컴파일이 된다"는 기준만으로는 충분하지 않습니다. "실패 경로가 닫혔는가", "문맥 위반이 없는가", "운영 중 원인 추적이 가능한가"까지 포함해 API를 선택해야 합니다.

핵심 | 도메인별 예제

핵심 항목을 실제 코드 흐름으로 묶는 예제입니다. 아래 3개 패턴은 드라이버 리뷰에서 자주 보는 전형적인 형태입니다.

예제 1: probe 경로 (devm + ERR_PTR + 로그)

static int demo_probe(struct platform_device *pdev)
{
    struct device *dev = &pdev->dev;
    struct demo_dev *d;
    int irq, ret;

    d = devm_kzalloc(dev, sizeof(*d), GFP_KERNEL);
    if (!d)
        return -ENOMEM;

    irq = platform_get_irq(pdev, 0);
    if (irq < 0)
        return irq;

    ret = devm_request_irq(dev, irq, demo_irq, 0, "demo", d);
    if (ret)
        return ret;

    dev_info(dev, "demo probe complete\\n");
    return 0;
}

예제 2: 락리스 플래그 전달 (READ_ONCE/WRITE_ONCE)

static bool stop_flag;

static int worker_thread(void *arg)
{
    while (!READ_ONCE(stop_flag)) {
        do_one_job();
        cond_resched();
    }
    return 0;
}

static void stop_worker(void)
{
    WRITE_ONCE(stop_flag, true);
}

예제 3: 심볼 export + 네임스페이스

int demo_calc_crc(const void *buf, size_t len)
{
    if (!buf || !len)
        return -EINVAL;
    return crc32_le(~0U, buf, len);
}
EXPORT_SYMBOL_NS_GPL(demo_calc_crc, DEMO_CORE);

/* 소비 모듈 */
MODULE_IMPORT_NS(DEMO_CORE);

확장 | 컨텍스트별 API 선택 매트릭스

같은 함수라도 실행 문맥이 다르면 안전성이 달라집니다. 아래 표는 코드 리뷰에서 가장 먼저 확인해야 하는 "문맥-API 적합성" 규칙입니다.

확장 | GFP 플래그 실전 카탈로그

메모리 할당 실패의 절반은 플래그 선택 오류에서 시작됩니다. 아래는 실무에서 반복되는 결정표입니다.

/* 컨텍스트별 API 사용 예시 비교 */

/* 1. 프로세스 문맥 — sleep 가능 */
mutex_lock(&dev->lock);
buf = kmalloc(size, GFP_KERNEL);
if (!buf) { mutex_unlock(&dev->lock); return -ENOMEM; }
mutex_unlock(&dev->lock);

/* 2. 하드IRQ — sleep 금지, 최소 작업 */
static irqreturn_t demo_isr(int irq, void *data)
{
    struct demo_dev *d = data;
    u32 status = readl(d->regs + REG_STATUS);

    if (!(status & IRQ_PENDING))
        return IRQ_NONE;

    writel(status, d->regs + REG_ACK);
    this_cpu_inc(d->stats->irqs);
    queue_work(d->wq, &d->rx_work);   /* 무거운 처리는 워크큐로 */
    return IRQ_HANDLED;
}

/* 3. 소프트IRQ (NAPI) — sleep 금지, atomic 할당만 */
spin_lock(&ring->lock);
skb = netdev_alloc_skb(ndev, len);  /* GFP_ATOMIC 내부 */
spin_unlock(&ring->lock);

확장 | 락 선택 매트릭스

락 선택 매트릭스는 성능 최적화 표가 아니라 실패 모드 비교표입니다. 각 락의 장점보다 우선해서, 어떤 워크로드에서 기아·경합·지연이 발생하는지를 먼저 확인해야 합니다. 선택 이후에는 락 교체 기준과 관측 지표를 함께 정의해야 회귀를 빠르게 감지할 수 있습니다.

실무 체크포인트: 락 변경 패치에는 최소 하나의 경합 지표와 회귀 기준을 함께 첨부하세요.

/* spinlock + IRQ 보호 패턴 — 프로세스+인터럽트 공유 데이터 */
struct demo_ring {
    spinlock_t lock;
    u32 head, tail;
    u8 buf[256];
};

/* IRQ 핸들러: spin_lock만 (IRQ는 이미 비활성) */
static irqreturn_t demo_irq_handler(int irq, void *dev_id)
{
    struct demo_ring *ring = dev_id;

    spin_lock(&ring->lock);
    ring->buf[ring->head++ & 0xFF] = inb(0x60);
    spin_unlock(&ring->lock);
    return IRQ_HANDLED;
}

/* 프로세스 문맥: spin_lock_irqsave 필수 (IRQ와 경쟁) */
static ssize_t demo_read(struct file *f, char __user *ubuf,
                         size_t cnt, loff_t *off)
{
    struct demo_ring *ring = f->private_data;
    unsigned long flags;
    u8 byte;

    spin_lock_irqsave(&ring->lock, flags);
    if (ring->head == ring->tail) {
        spin_unlock_irqrestore(&ring->lock, flags);
        return 0;
    }
    byte = ring->buf[ring->tail++ & 0xFF];
    spin_unlock_irqrestore(&ring->lock, flags);

    if (copy_to_user(ubuf, &byte, 1))
        return -EFAULT;
    return 1;
}

/* mutex 일반 패턴 — sleep 가능 드라이버 제어 경로 */
static DEFINE_MUTEX(demo_cfg_lock);

static int demo_update_config(struct demo_dev *d, u32 new_val)
{
    mutex_lock(&demo_cfg_lock);
    d->config_val = new_val;
    writel(new_val, d->base + CFG_REG);
    (void)readl(d->base + CFG_REG);  /* posted write flush */
    mutex_unlock(&demo_cfg_lock);
    return 0;
}

/* seqlock 읽기 재시도 패턴 */
static seqlock_t demo_seq;
static struct timespec64 demo_ts;

static struct timespec64 demo_get_ts(void)
{
    struct timespec64 ts;
    unsigned seq;

    do {
        seq = read_seqbegin(&demo_seq);
        ts = demo_ts;
    } while (read_seqretry(&demo_seq, seq));
    return ts;
}

확장 | 반환값 계약 카탈로그

실무 체크포인트: 포인터 반환 API는 함수 주석에 NULL 또는 ERR_PTR 규약을 명시하고 시작하세요.

확장 | 비차단(Non-blocking) 경로 전용 API

비차단 경로는 평균 성능보다 최악 지연을 제한하는 것이 우선 목표입니다. 따라서 "성공률을 높이는 API"보다 "실패를 빠르게 표면화하는 API"를 선택해야 합니다. 표의 각 항목은 대체 경로 설계를 포함해야 의미가 있으므로 fallback 없는 사용은 금지에 가깝게 다뤄야 합니다.

실무 체크포인트: non-blocking 경로에는 실패 시 defer할 큐 또는 재시도 정책을 코드로 명시하세요.

/* 비차단 경로 — GFP_ATOMIC + 실패 defer 패턴 */
static void demo_irq_alloc(struct demo_dev *d, size_t len)
{
    struct demo_buf *buf;

    buf = kmalloc(sizeof(*buf) + len, GFP_ATOMIC);
    if (!buf) {
        /* 할당 실패 — 워크큐로 지연 처리 */
        atomic_inc(&d->alloc_fails);
        schedule_work(&d->retry_work);
        return;
    }
    buf->len = len;
    list_add_tail(&buf->node, &d->rx_list);
}

/* spin_trylock 비차단 락 — 실패 시 후처리 큐잉 */
static void demo_try_update(struct demo_dev *d)
{
    if (!spin_trylock(&d->stats_lock)) {
        /* 락 획득 실패 — per-CPU 카운터에 임시 저장 */
        this_cpu_inc(d->pending_updates);
        return;
    }
    d->stats.total += this_cpu_read(d->pending_updates);
    this_cpu_write(d->pending_updates, 0);
    spin_unlock(&d->stats_lock);
}

확장 | 핵심 API 소스 경로 맵

소스 경로 맵은 API 사용법보다 구현 근거를 빠르게 찾기 위한 역추적(Backtrace) 인덱스입니다. 리뷰에서 의견이 갈리면 표의 헤더와 구현 경로를 동시에 열어 계약과 실제 동작을 교차 확인해야 합니다. 특히 인라인 헤더 매크로는 호출부만 보면 의미가 왜곡되기 쉬워 원본 정의 확인이 필수입니다.

실무 체크포인트: 동작 논쟁이 발생하면 헤더 선언과 구현 경로를 함께 링크해 근거 기반으로 결론을 내리세요.

확장 | 고밀도 실전 스니펫

고밀도 스니펫은 복붙 예제가 아니라 실패 경로 템플릿을 압축한 참고 코드입니다. 각 스니펫은 정상 경로보다 unwind, 참조 반납, 동기화 종료 조건을 보여주는 데 목적이 있습니다. 적용 시에는 변수명보다 제어 흐름과 정리 순서를 우선 이식해야 합니다.

실무 체크포인트: 스니펫 적용 후에는 의도적으로 중간 실패를 주입해 unwind 경로가 닫히는지 먼저 검증하세요.

스니펫 1: 단계별 unwind 템플릿

static int demo_open(struct inode *inode, struct file *filp)
{
    struct demo_ctx *ctx;
    int ret;

    ctx = kzalloc(sizeof(*ctx), GFP_KERNEL);
    if (!ctx)
        return -ENOMEM;

    mutex_init(&ctx->lock);

    ret = alloc_ring(ctx);
    if (ret)
        goto err_destroy_lock;

    ret = register_fastpath(ctx);
    if (ret)
        goto err_free_ring;

    filp->private_data = ctx;
    return 0;

err_free_ring:
    free_ring(ctx);
err_destroy_lock:
    mutex_destroy(&ctx->lock);
err_free_ctx:
    kfree(ctx);
    return ret;
}

스니펫 2: RCU 리스트 갱신 패턴

void demo_insert(struct demo_node *n)
{
    spin_lock(&demo_lock);
    list_add_rcu(&n->link, &demo_head);
    spin_unlock(&demo_lock);
}

struct demo_node *demo_find(int id)
{
    struct demo_node *pos, *ret = NULL;

    rcu_read_lock();
    list_for_each_entry_rcu(pos, &demo_head, link) {
        if (READ_ONCE(pos->id) == id) {
            /* 예제 가정: demo_node는 refcount_t refcnt를 가진다 */
            if (refcount_inc_not_zero(&pos->refcnt))
                ret = pos;
            break;
        }
    }
    rcu_read_unlock();
    return ret;
}

확장 | 코드 리뷰 규칙

아래 규칙은 스타일 가이드가 아니라 장애 예방을 위한 최소 수용 기준입니다. 규칙 간 우선순위는 문맥 안전성, 수명주기 완결성, 관측 가능성 순서로 해석해야 합니다. 규칙 위반이 불가피한 경우에는 예외 근거와 복구 계획을 패치 설명에 반드시 포함해야 합니다.

실무 체크포인트: 리뷰 단계에서 규칙 위반 항목은 "후속 수정"으로 미루지 말고 같은 변경 집합에서 닫으세요.

• 규칙 1 — 포인터 반환 함수는 선언 바로 위 주석에 반환 규약(NULL/ERR_PTR)을 고정합니다.
• 규칙 2 — 락 획득/해제는 함수 단위가 아니라 경로 단위로 표로 정리합니다.
• 규칙 3 — IRQ 경로는 100줄을 넘기지 않고, 복잡 로직은 워크큐로 이관합니다.
• 규칙 4 — copy_from_user 반환값을 무시하는 코드는 즉시 수정 대상으로 분류합니다.
• 규칙 5 — devm_*와 수동 해제를 한 함수에서 혼용하지 않습니다.
• 규칙 6 — 신규 export 심볼에는 "왜 export가 필요한지"를 커밋 메시지에 명시합니다.
• 규칙 7 — likely/unlikely는 프로파일링(Profiling) 근거가 있을 때만 허용합니다.
• 규칙 8 — WARN_ON는 운영 경보 노이즈를 고려해 한정적으로 사용합니다.
• 규칙 9 — 타임아웃 상수는 매직넘버 대신 의미 있는 이름으로 분리합니다.
• 규칙 10 — 로그 메시지는 "무엇이 실패했는지 + 식별자 + errno"를 함께 출력합니다.
• 규칙 11 — 메모리 해제는 정상 경로와 실패 경로 모두를 단위 테스트 시나리오로 검증합니다.
• 규칙 12 — 트레이스 포인트 추가 시 이벤트 필드 ABI 안정성을 검토합니다.

확장 | 문제 유형별 즉시 대응 인덱스

문제 대응 인덱스는 원인 추정을 빠르게 좁히기 위한 초기 분류표입니다. 증상과 의심 지점을 1:1로 고정하지 말고, 표를 시작점으로 삼아 로그·트레이스·락 상태를 교차 확인해야 합니다. 특히 간헐 장애는 단일 도구 결과로 결론 내리지 않는 것이 중요합니다.

실무 체크포인트: 1차 대응에서 최소 두 가지 독립 증거를 확보한 뒤 수정 방향을 결정하세요.

확장 | 네트워킹 카탈로그

네트워킹 경로는 패킷(Packet)당 수백 ns 단위 최적화가 필요하므로, API 선택 기준을 명확히 고정해야 합니다.

skb 수명주기/조작

NAPI/수신 경로

송신/큐 제어

해시/체크섬/오프로드

XDP/소켓/라우팅/conntrack

/* NAPI poll 최소 패턴 */
static int demo_poll(struct napi_struct *napi, int budget)
{
    int work_done = 0;

    while (work_done < budget && rx_has_packet()) {
        struct sk_buff *skb = build_skb(rx_pop(), 0);
        if (!skb)
            break;
        napi_gro_receive(napi, skb);
        work_done++;
    }

    if (work_done < budget) {
        napi_complete_done(napi, work_done);
        enable_irq(demo_irq);
    }
    return work_done;
}

확장 | 파일시스템 카탈로그

파일시스템 코드는 락 계층, 페이지 캐시(Page Cache), writeback 경계가 복잡하므로 VFS 진입점과 address_space 연계를 함께 확인해야 합니다.

inode/dentry

슈퍼블록/마운트

읽기/쓰기

페이지 캐시/writeback

디렉터리/권한/sync

/* 최소 VFS 연산자 골격 */
static const struct file_operations demo_fops = {
    .owner = THIS_MODULE,
    .read_iter = generic_file_read_iter,
    .write_iter = generic_file_write_iter,
    .mmap = generic_file_mmap,
    .llseek = generic_file_llseek,
    .fsync = generic_file_fsync,
};

확장 | 메모리 관리 카탈로그

메모리 관리 경로는 할당 정책, reclaim 압력, TLB/페이지 테이블(Page Table) 동기화까지 동시에 고려해야 합니다.

페이지 할당/해제

folio/매핑

VMA/fault

reclaim/슬랩

DMA/핀/NUMA

/* folio writeback 패턴 — bio 제출 + 오류 경로 포함 */
static int demo_writepage(struct folio *folio,
                          struct writeback_control *wbc)
{
    struct inode *inode = folio->mapping->host;
    struct block_device *bdev = inode->i_sb->s_bdev;
    sector_t sector;
    struct bio *bio;

    folio_lock(folio);

    /* 블록 매핑 조회 */
    sector = demo_folio_to_sector(folio);
    if (sector == (sector_t)-1) {
        folio_unlock(folio);
        return -EIO;
    }

    folio_start_writeback(folio);
    folio_unlock(folio);

    /* bio 생성 및 제출 */
    bio = bio_alloc(bdev, 1, REQ_OP_WRITE | REQ_SYNC, GFP_NOFS);
    bio->bi_iter.bi_sector = sector;
    bio_add_folio_nofail(bio, folio, folio_size(folio), 0);
    bio->bi_end_io = demo_writeback_endio;
    bio->bi_private = folio;

    submit_bio(bio);
    return 0;
}

static void demo_writeback_endio(struct bio *bio)
{
    struct folio *folio = bio->bi_private;

    if (bio->bi_status) {
        folio_set_error(folio);
        mapping_set_error(folio->mapping,
                         blk_status_to_errno(bio->bi_status));
    }
    folio_end_writeback(folio);
    bio_put(bio);
}

확장 | 스토리지 I/O 카탈로그

스토리지 경로는 bio/request/queue 경계와 완료 처리 규약이 핵심입니다. 특히 실패 경로와 타임아웃 회수 정책을 반드시 포함해야 합니다.

bio 생성/관리

request/큐

완료/오류/통계

/* bio 제출 최소 패턴 */
static void demo_submit_read(struct block_device *bdev,
                              sector_t sector, struct page *page)
{
    struct bio *bio = bio_alloc(bdev, 1, REQ_OP_READ, GFP_KERNEL);

    bio->bi_iter.bi_sector = sector;
    __bio_add_page(bio, page, PAGE_SIZE, 0);
    bio->bi_end_io = demo_bio_done;
    submit_bio(bio);
}

static void demo_bio_done(struct bio *bio)
{
    if (bio->bi_status)
        pr_err("bio error: %d\n",
               blk_status_to_errno(bio->bi_status));
    bio_put(bio);
}

확장 | 보안/LSM 카탈로그

보안 경로는 훅 호출 순서, cred 수명주기, 정책 캐시 일관성(Cache Coherency)을 동시에 고려해야 합니다.

credential/권한

LSM 훅

audit/IMA/키

하드닝/보호

/* cred 변경 안전 패턴 */
static int demo_elevate(void)
{
    struct cred *new;
    int ret;

    new = prepare_creds();
    if (!new)
        return -ENOMEM;

    /* capability 추가 검증 */
    if (!ns_capable(new->user_ns, CAP_SYS_ADMIN)) {
        abort_creds(new);
        return -EPERM;
    }

    commit_creds(new);
    return 0;
}

확장 | 가상화(Virtualization)/KVM 카탈로그

KVM 경로는 VM-Exit 처리 비용, vCPU 동기화, 메모리 슬롯 일관성이 성능과 안정성을 동시에 좌우합니다.

/* KVM run 루프 개념 스니펫 */
for (;;) {
    int r = kvm_arch_vcpu_ioctl_run(vcpu);
    if (r < 0)
        break;

    switch (vcpu->run->exit_reason) {
    case KVM_EXIT_IO:
        handle_pio(vcpu);
        break;
    case KVM_EXIT_MMIO:
        handle_mmio(vcpu);
        break;
    case KVM_EXIT_HLT:
        return;
    default:
        trace_kvm_exit(vcpu->run->exit_reason);
        break;
    }
}

확장 | 인터럽트/타이머 카탈로그

인터럽트 경로는 지연과 안정성이 직결되므로 핸들러 최소화, 하단 처리 분리, 타이머 취소 순서가 핵심입니다.

IRQ 등록/관리

softirq/tasklet

타이머/hrtimer

지연/IPI/기타

/* 스레드 IRQ + hrtimer 조합 패턴 */
static irqreturn_t demo_hard_isr(int irq, void *data)
{
    struct demo_dev *d = data;
    u32 status = readl(d->regs + IRQ_STATUS);

    if (!(status & DEMO_IRQ_MASK))
        return IRQ_NONE;

    writel(status, d->regs + IRQ_ACK);
    return IRQ_WAKE_THREAD;  /* 후반 처리 위임 */
}

static irqreturn_t demo_thread_isr(int irq, void *data)
{
    struct demo_dev *d = data;

    mutex_lock(&d->lock);       /* sleep 가능 */
    demo_process_data(d);
    mutex_unlock(&d->lock);
    return IRQ_HANDLED;
}

/* 등록 */
devm_request_threaded_irq(dev, irq,
    demo_hard_isr, demo_thread_isr,
    IRQF_SHARED, "demo", d);

확장 | 드라이버 버스(PCI/I2C/SPI) 카탈로그

버스 드라이버는 열거, 자원 매핑, 전원관리, 오류 복구를 일관된 순서로 처리해야 안정적입니다.

PCI

I2C/SPI

공통 리소스(클럭/리셋/레귤레이터/GPIO)

/* PCI 드라이버 probe 최소 골격 */
static int demo_pci_probe(struct pci_dev *pdev,
                           const struct pci_device_id *id)
{
    struct demo_dev *d;
    int ret;

    ret = pcim_enable_device(pdev);
    if (ret)
        return ret;

    ret = dma_set_mask_and_coherent(&pdev->dev, DMA_BIT_MASK(64));
    if (ret)
        return ret;

    ret = pcim_iomap_regions(pdev, BIT(0), "demo");
    if (ret)
        return ret;

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

    d->regs = pcim_iomap_table(pdev)[0];
    pci_set_master(pdev);
    pci_set_drvdata(pdev, d);

    ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_MSI | PCI_IRQ_LEGACY);
    if (ret < 0)
        return ret;

    dev_info(&pdev->dev, "probe complete\n");
    return 0;
}

/* I2C regmap 패턴 */
static const struct regmap_config demo_regmap_cfg = {
    .reg_bits = 8,
    .val_bits = 8,
    .max_register = 0xFF,
};

static int demo_i2c_probe(struct i2c_client *client)
{
    struct regmap *map;
    unsigned int val;

    map = devm_regmap_init_i2c(client, &demo_regmap_cfg);
    if (IS_ERR(map))
        return PTR_ERR(map);

    regmap_read(map, 0x00, &val);
    dev_info(&client->dev, "chip id: 0x%x\n", val);
    return 0;
}

확장 | 컨테이너(Container)/cgroups 카탈로그

컨테이너 경로는 namespace 격리(Isolation)와 cgroup 자원 제어가 결합되어 동작합니다. 계층별 책임을 분리해서 봐야 원인 분석이 빠릅니다.

namespace

cgroup core/attach

자원 제어(mem/cpu/io)

PSI/freezer/디버그

확장 | 전원관리/열 카탈로그

전원과 열 관리(Thermal Management)는 성능/안정성/수명에 동시에 영향을 주므로 PM 런타임, cpufreq, thermal 정책의 연결을 함께 봐야 합니다.

runtime PM

시스템 suspend/resume

cpufreq/idle/OPP

thermal/powercap

wakeup/QoS/진단

확장 | 관측성(perf/ftrace/eBPF) 카탈로그

관측성은 "무엇을, 얼마나, 어디서" 수집할지 설계가 먼저입니다. 이벤트 스키마와 오버헤드 제어를 함께 정의해야 합니다.

ftrace/tracepoint

perf

eBPF/kprobe

static key/통계/디버그

/* DEFINE_EVENT tracepoint 정의 패턴 */

/* include/trace/events/demo.h */
#undef TRACE_SYSTEM
#define TRACE_SYSTEM demo

#if !defined(_TRACE_DEMO_H) || defined(TRACE_HEADER_MULTI_READ)
#define _TRACE_DEMO_H
#include <linux/tracepoint.h>

TRACE_EVENT(demo_op,
    TP_PROTO(const char *name, int ret),
    TP_ARGS(name, ret),
    TP_STRUCT__entry(
        __string(name, name)
        __field(int, ret)
    ),
    TP_fast_assign(
        __assign_str(name);
        __entry->ret = ret;
    ),
    TP_printk("name=%s ret=%d", __get_str(name), __entry->ret)
);

#endif
#include <trace/define_trace.h>

/* 사용 측 */
trace_demo_op("write", ret);

# ftrace 실전 사용 예시

# 1. 함수 추적 활성화
echo demo_probe > /sys/kernel/debug/tracing/set_ftrace_filter
echo function > /sys/kernel/debug/tracing/current_tracer
echo 1 > /sys/kernel/debug/tracing/tracing_on

# 2. tracepoint 이벤트 활성화
echo 1 > /sys/kernel/debug/tracing/events/demo/demo_op/enable
cat /sys/kernel/debug/tracing/trace_pipe

# 3. 인터럽트 off 지연 추적
echo irqsoff > /sys/kernel/debug/tracing/current_tracer
echo 1 > /sys/kernel/debug/tracing/tracing_on
cat /sys/kernel/debug/tracing/trace  # 최대 지연 확인

확장 | 컴파일러/링커(GCC/binutils) 카탈로그

빌드 옵션은 런타임 동작을 바꾸므로 경고/최적화/보안 옵션과 ELF 결과물을 함께 점검해야 합니다.

확장 | 네트워크 프로토콜(TCP/UDP/Netfilter) 카탈로그

프로토콜 경로는 상태 전이, 타이머, conntrack, NAT 훅 순서가 복합적으로 얽혀 있습니다. 경로별 핵심 API를 함께 봐야 회귀를 줄일 수 있습니다.

확장 | 파일시스템(ext4/XFS/Btrfs) 카탈로그

파일시스템 경로는 저널링/트랜잭션/지연할당/extent 트리 동작을 함께 이해해야 디스크 손상 없이 성능을 올릴 수 있습니다.

확장 | 디바이스 특화(GPU/V4L2/ALSA) 카탈로그

미디어/그래픽/오디오 서브시스템은 사용자 ABI 호환성과 DMA 버퍼 공유 규약이 핵심입니다.

확장 | 문자열/버퍼 조작 카탈로그

커널 문자열 API는 사용자 공간 libc와 계약이 다릅니다. 특히 NUL 종료 보장, 버퍼 오버런 방지, 반환값 규약이 함수마다 다르므로 표의 "반환값" 열을 가장 먼저 확인해야 합니다. strscpy는 strlcpy/strncpy를 대체하는 커널 권장 API입니다.

실무 체크포인트: 새 코드에서 strcpy/strncpy/strlcpy를 발견하면 strscpy로 교체 가능 여부를 먼저 검토하세요.

복사/복제

포맷 출력

비교/검색/분리

변환

메모리/소거/해시

/* strscpy + scnprintf 조합 패턴 */
static ssize_t demo_show(struct device *dev,
                         struct device_attribute *attr,
                         char *buf)
{
    struct demo_dev *d = dev_get_drvdata(dev);
    char name[64];
    ssize_t ret;

    ret = strscpy(name, d->label, sizeof(name));
    if (ret < 0)
        strscpy(name, "(truncated)", sizeof(name));

    return scnprintf(buf, PAGE_SIZE,
                     "name=%s ver=%u\n", name, d->version);
}

/* kasprintf 동적 할당 패턴 */
char *label = kasprintf(GFP_KERNEL, "%s-%d", prefix, idx);
if (!label)
    return -ENOMEM;
/* ... 사용 ... */
kfree(label);

/* kstrtoul 변환 패턴 */
unsigned long val;
int ret = kstrtoul(buf, 0, &val);
if (ret)
    return ret;
if (val > MAX_LIMIT)
    return -ERANGE;

확장 | Per-CPU 변수 카탈로그

Per-CPU 변수는 락 없이 CPU별 독립 데이터를 관리하는 핵심 기법입니다. 성능 카운터, 통계, 캐시에 자주 사용되지만, 선점(preemption) 제어를 빠뜨리면 잘못된 CPU 데이터에 접근하는 미묘한 버그가 발생합니다. 이 표는 "어떤 접근 API를 쓸지"보다 "선점 보호를 어떻게 보장할지"를 먼저 고정하는 기준으로 읽어야 합니다.

실무 체크포인트: Per-CPU 변수 접근 시 get_cpu()/put_cpu() 또는 this_cpu_* 시리즈의 선점 보호 범위를 반드시 확인하세요.

선언/할당

this_cpu 연산

타 CPU 접근/집계

/* Per-CPU 카운터 패턴 */
static DEFINE_PER_CPU(u64, demo_packets);
static DEFINE_PER_CPU(u64, demo_bytes);

static void demo_account(unsigned int len)
{
    this_cpu_inc(demo_packets);
    this_cpu_add(demo_bytes, len);
}

static u64 demo_total_packets(void)
{
    u64 sum = 0;
    int cpu;

    for_each_possible_cpu(cpu)
        sum += per_cpu(demo_packets, cpu);
    return sum;
}

/* 동적 per-cpu 할당 패턴 */
int __percpu *counters = alloc_percpu(int);
if (!counters)
    return -ENOMEM;

this_cpu_inc(*counters);

/* 정리 */
free_percpu(counters);

확장 | 알림 체인(Notifier Chain) 카탈로그

알림 체인은 커널 서브시스템 간 이벤트 전파 메커니즘입니다. CPU hotplug, 네트워크 인터페이스 상태 변화, reboot 등의 시스템 이벤트를 구독/통지하는 표준 패턴입니다. 체인 유형(blocking/atomic/raw/SRCU)에 따라 콜백 내부에서 sleep 가능 여부가 달라지므로, 등록 시 체인 유형을 먼저 확인해야 합니다.

실무 체크포인트: 콜백 내부에서 sleep이 필요하면 반드시 blocking notifier를 사용하고, atomic notifier 체인에 등록하지 마세요.

/* netdev notifier 최소 패턴 */
static int demo_netdev_event(struct notifier_block *nb,
                              unsigned long event, void *ptr)
{
    struct net_device *dev = netdev_notifier_info_to_dev(ptr);

    switch (event) {
    case NETDEV_UP:
        pr_info("device %s up\n", dev->name);
        break;
    case NETDEV_DOWN:
        pr_info("device %s down\n", dev->name);
        break;
    }
    return NOTIFY_DONE;
}

static struct notifier_block demo_nb = {
    .notifier_call = demo_netdev_event,
};

/* init */
register_netdevice_notifier(&demo_nb);
/* exit */
unregister_netdevice_notifier(&demo_nb);

확장 | sysfs/procfs/debugfs 인터페이스 카탈로그

커널-사용자 공간 인터페이스는 용도에 따라 sysfs(장치 속성), procfs(프로세스/시스템 정보), debugfs(디버그 전용)로 분리합니다. 인터페이스 선택을 잘못하면 ABI 유지 비용이 불필요하게 높아지거나, 디버그 전용 정보가 영구 ABI로 굳어지는 문제가 발생합니다.

실무 체크포인트: 새 인터페이스를 추가할 때 "이것이 안정 ABI여야 하는가?"를 먼저 결정하세요. 디버그/개발 전용이면 debugfs, 장치 속성이면 sysfs, 커널 전역 정보면 procfs가 원칙입니다.

sysfs 속성

procfs 인터페이스

debugfs 인터페이스

/* sysfs 속성 패턴 */
static ssize_t status_show(struct device *dev,
                           struct device_attribute *attr,
                           char *buf)
{
    struct demo_dev *d = dev_get_drvdata(dev);
    return sysfs_emit(buf, "%u\n", READ_ONCE(d->status));
}
static DEVICE_ATTR_RO(status);

/* seq_file 패턴 */
static int demo_seq_show(struct seq_file *m, void *v)
{
    struct demo_entry *e = v;
    seq_printf(m, "%-16s %8u %8u\n", e->name, e->rx, e->tx);
    return 0;
}

/* debugfs 디렉터리+파일 패턴 */
static struct dentry *demo_debugfs;

static int __init demo_debugfs_init(void)
{
    demo_debugfs = debugfs_create_dir("demo", NULL);
    debugfs_create_u32("counter", 0444, demo_debugfs, &demo_cnt);
    debugfs_create_bool("enabled", 0644, demo_debugfs, &demo_en);
    return 0;
}

static void __exit demo_debugfs_exit(void)
{
    debugfs_remove_recursive(demo_debugfs);
}

확장 | 참조 카운팅(kref/kobject) 카탈로그

참조 카운팅은 커널 객체의 수명주기 계약을 코드로 표현하는 핵심 패턴입니다. kref는 단순 참조 카운팅, kobject는 sysfs 노출과 계층 관리를 추가합니다. 참조 카운팅 버그는 UAF(use-after-free)나 메모리 누수로 직결되므로, get/put 경로의 대칭성을 가장 먼저 검증해야 합니다.

실무 체크포인트: 모든 get 호출에 대응하는 put 경로가 정상/실패/종료 경로 모두에서 도달 가능한지 확인하세요.

kref 수명주기

kobject/kset

refcount 원시 API

/* kref 기본 수명주기 패턴 */
struct demo_obj {
    struct kref refcount;
    char *name;
    struct list_head link;
};

static void demo_release(struct kref *ref)
{
    struct demo_obj *obj = container_of(ref, struct demo_obj, refcount);
    kfree(obj->name);
    kfree(obj);
}

static struct demo_obj *demo_create(const char *name)
{
    struct demo_obj *obj = kzalloc(sizeof(*obj), GFP_KERNEL);
    if (!obj)
        return NULL;

    obj->name = kstrdup(name, GFP_KERNEL);
    if (!obj->name) {
        kfree(obj);
        return NULL;
    }
    kref_init(&obj->refcount);
    return obj;
}

static void demo_get(struct demo_obj *obj) { kref_get(&obj->refcount); }
static void demo_put(struct demo_obj *obj) { kref_put(&obj->refcount, demo_release); }

확장 | MMIO/PIO 접근 카탈로그

MMIO(Memory-Mapped I/O)와 PIO(Port I/O)는 하드웨어 레지스터 접근의 두 축입니다. MMIO는 메모리 주소 공간(Address Space)에 매핑된 레지스터에 접근하고, PIO는 x86의 IN/OUT 명령어 기반입니다. 접근 너비(8/16/32/64비트), 순서 보장(relaxed 여부), 엔디안(Endianness) 변환이 핵심 체크 포인트입니다.

실무 체크포인트: MMIO 접근에는 readl/writel을 기본으로 사용하고, 핫패스에서만 readl_relaxed를 검토하세요. 직접 포인터 역참조로 레지스터를 읽지 마세요.

MMIO 접근

PIO/추상화 접근

블록 접근/배리어/regmap

/* MMIO 레지스터 접근 기본 패턴 */
static void __iomem *base;

/* 레지스터 읽기/쓰기 래퍼 */
static inline u32 demo_read(u32 offset)
{
    return readl(base + offset);
}

static inline void demo_write(u32 offset, u32 val)
{
    writel(val, base + offset);
}

/* 비트필드 조작 패턴 */
#define REG_CTRL         0x00
#define CTRL_ENABLE      BIT(0)
#define CTRL_MODE_MASK   GENMASK(3, 1)

static void demo_set_mode(u32 mode)
{
    u32 val = demo_read(REG_CTRL);
    val &= ~CTRL_MODE_MASK;
    val |= FIELD_PREP(CTRL_MODE_MASK, mode);
    val |= CTRL_ENABLE;
    demo_write(REG_CTRL, val);
    /* posted write flush */
    (void)demo_read(REG_CTRL);
}

확장 | DMA 매핑 카탈로그

DMA 매핑은 CPU와 디바이스 간 메모리 가시성 계약입니다. 스트리밍 매핑(map/unmap), 일관성 매핑(alloc_coherent), DMA 풀 패턴을 용도에 따라 분리해야 하며, 방향(direction) 플래그와 dma_mask 설정을 먼저 고정해야 합니다. 매핑 에러 검사를 생략하면 무효 DMA 주소로 인한 데이터 손상이 발생합니다.

실무 체크포인트: 모든 dma_map_* 호출 직후 dma_mapping_error를 검사하세요. 이 검사가 누락된 코드는 즉시 수정 대상입니다.