커널 필수 함수·매크로·심볼 레퍼런스

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

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

이 페이지는 "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"를 한 줄에 남기고, 정상 경로 로그는 기본적으로 억제하세요.

핵심 | 메모리 할당/해제

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

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

핵심 | 사용자 공간 접근

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

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

핵심 | 에러 처리 매크로

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

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

핵심 | 자료구조 매크로

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

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

핵심 | 락/동기화

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

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

핵심 | 원자 연산/배리어

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

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

핵심 | 스케줄링/대기

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

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

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

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

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

핵심 | 타이머/워크큐

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

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

핵심 | 디버깅/트레이싱

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

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

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

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

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

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

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

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

핵심 | 핵심 묶음 해설

앞의 핵심 묶음 표는 "자주 쓰는 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);

확장 | 락 선택 매트릭스

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

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

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

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

확장 | 비차단 경로 전용 API

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

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

확장 | 핵심 API 소스 경로 맵

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

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

확장 | 고밀도 실전 스니펫

고밀도 스니펫은 복붙 예제가 아니라 실패 경로 템플릿을 압축한 참고 코드입니다. 각 스니펫은 정상 경로보다 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는 프로파일링 근거가 있을 때만 허용합니다.
• 규칙 8 — WARN_ON는 운영 경보 노이즈를 고려해 한정적으로 사용합니다.
• 규칙 9 — 타임아웃 상수는 매직넘버 대신 의미 있는 이름으로 분리합니다.
• 규칙 10 — 로그 메시지는 "무엇이 실패했는지 + 식별자 + errno"를 함께 출력합니다.
• 규칙 11 — 메모리 해제는 정상 경로와 실패 경로 모두를 단위 테스트 시나리오로 검증합니다.
• 규칙 12 — 트레이스 포인트 추가 시 이벤트 필드 ABI 안정성을 검토합니다.

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

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

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

확장 | 네트워킹 카탈로그

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

/* 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;
}

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

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

/* 최소 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/페이지 테이블 동기화까지 동시에 고려해야 합니다.

/* folio + writeback 최소 패턴 */
static int demo_write_folio(struct folio *folio)
{
    folio_lock(folio);
    folio_mark_dirty(folio);
    /* 실제 디바이스 I/O 제출 생략 */
    folio_unlock(folio);
    return 0;
}

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

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

/* 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 수명주기, 정책 캐시 일관성을 동시에 고려해야 합니다.

/* 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;
}

확장 | 가상화/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 + 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 드라이버 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;
}

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

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

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

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

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

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

/* 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_* 시리즈의 선점 보호 범위를 반드시 확인하세요.

/* 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 속성 패턴 */
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 기본 수명주기 패턴 */
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는 메모리 주소 공간에 매핑된 레지스터에 접근하고, PIO는 x86의 IN/OUT 명령어 기반입니다. 접근 너비(8/16/32/64비트), 순서 보장(relaxed 여부), 엔디안 변환이 핵심 체크 포인트입니다.

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

/* 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를 검사하세요. 이 검사가 누락된 코드는 즉시 수정 대상입니다.

/* DMA 스트리밍 매핑 패턴 */
dma_addr_t dma_handle;
void *buf = kmalloc(BUF_SIZE, GFP_KERNEL);
if (!buf)
    return -ENOMEM;

dma_handle = dma_map_single(dev, buf, BUF_SIZE, DMA_TO_DEVICE);
if (dma_mapping_error(dev, dma_handle)) {
    kfree(buf);
    return -EIO;
}

/* 디바이스에 DMA 전송 시작 */
start_dma_transfer(dma_handle, BUF_SIZE);

/* 완료 후 해제 */
dma_unmap_single(dev, dma_handle, BUF_SIZE, DMA_TO_DEVICE);
kfree(buf);

/* 일관성 메모리 패턴 (descriptor ring) */
dma_addr_t ring_dma;
struct demo_desc *ring;

ring = dma_alloc_coherent(dev, ring_size, &ring_dma, GFP_KERNEL);
if (!ring)
    return -ENOMEM;

/* ring 사용 — CPU와 디바이스 모두 동일 내용 참조 */
ring[0].addr = cpu_to_le64(data_dma);
ring[0].len  = cpu_to_le32(data_len);

/* 해제 */
dma_free_coherent(dev, ring_size, ring, ring_dma);

확장 | 펌웨어 로딩 카탈로그

펌웨어 로딩은 디바이스 초기화 경로의 외부 의존성을 관리하는 API입니다. 로딩 시점(probe/resume), 실패 정책(선택적/필수), 보안 검증을 함께 결정해야 합니다. 특히 initramfs에 펌웨어가 포함되지 않으면 시스템 부팅이 실패할 수 있으므로, fallback 전략이 필수입니다.

실무 체크포인트: 펌웨어 경로/이름을 하드코딩하지 말고 MODULE_FIRMWARE로 선언하여 빌드 시스템에서 추적 가능하게 하세요.

/* 펌웨어 로딩 기본 패턴 */
static int demo_load_fw(struct device *dev)
{
    const struct firmware *fw;
    int ret;

    ret = request_firmware(&fw, "demo/fw.bin", dev);
    if (ret) {
        dev_err(dev, "firmware load failed: %d\n", ret);
        return ret;
    }

    if (fw->size < sizeof(struct demo_fw_hdr)) {
        dev_err(dev, "firmware too small: %zu\n", fw->size);
        ret = -EINVAL;
        goto out;
    }

    /* 펌웨어를 디바이스에 전송 */
    ret = demo_upload_fw(dev, fw->data, fw->size);

out:
    release_firmware(fw);
    return ret;
}

MODULE_FIRMWARE("demo/fw.bin");

확장 | 실전 함정 패턴 모음

코드 리뷰에서 반복적으로 발견되는 실전 함정을 패턴화한 모음입니다. 각 항목은 "컴파일은 통과하지만 장애를 유발하는" 코드를 중심으로, 잘못된 코드와 올바른 수정을 나란히 제시합니다. 새 패치를 제출하기 전에 이 목록을 체크리스트로 역검증하면 리뷰 지적의 상당수를 선제적으로 제거할 수 있습니다.

실무 체크포인트: 아래 패턴 중 하나라도 현재 코드에 존재하면, 기능 동작과 무관하게 즉시 수정 우선순위로 분류하세요.

/* 함정 #2 krealloc 원본 보호 패턴 */
void *tmp = krealloc(buf, new_size, GFP_KERNEL);
if (!tmp) {
    /* buf는 여전히 유효 — 기존 데이터 보존 */
    pr_warn("realloc failed, keeping old buffer\n");
    return -ENOMEM;
}
buf = tmp;

/* 함정 #9 올바른 unwind 순서 */
static int demo_init(void)
{
    int ret;

    ret = step_a_init();     /* 1번째 */
    if (ret)
        return ret;

    ret = step_b_init();     /* 2번째 */
    if (ret)
        goto undo_a;

    ret = step_c_init();     /* 3번째 */
    if (ret)
        goto undo_b;

    return 0;

undo_b:
    step_b_exit();           /* 역순: 2번 해제 */
undo_a:
    step_a_exit();           /* 역순: 1번 해제 */
    return ret;
}

/* 함정 #8 올바른 게시 순서 */
WRITE_ONCE(shared_data, new_value);
smp_store_release(&data_ready, 1);

/* 읽기 측 */
if (smp_load_acquire(&data_ready))
    use(READ_ONCE(shared_data));

운영 | 보안 취약점 대응 플레이북

취약점 대응은 탐지 속도보다 재현 가능성과 완화 우선순위가 중요합니다. 아래 표는 커널 취약점 대응의 실전 기준 절차입니다.

/* UAF 완화 예시: refcount로 수명주기 보호 */
struct demo_obj {
    refcount_t refcnt;
    spinlock_t lock;
    struct rcu_head rcu;
};

static bool demo_get(struct demo_obj *o)
{
    return refcount_inc_not_zero(&o->refcnt);
}

static void demo_put(struct demo_obj *o)
{
    if (refcount_dec_and_test(&o->refcnt))
        kfree_rcu(o, rcu);
}

운영 | 커널 패닉/크래시 즉시 대응 절차

패닉 대응은 "재부팅"보다 "증거 보존"이 먼저입니다. 아래 절차는 운영 현장에서의 우선순위를 반영합니다.

운영 | 성능 튜닝 체크리스트 (워크로드별)

성능 튜닝은 워크로드 유형별 병목이 다르므로 단일 "최적화 옵션"이 없습니다. 측정 지표를 먼저 고정한 뒤 조정해야 합니다.

운영 | 적용 순서 해설

문서를 읽고 실제 코드/시스템에 반영할 때는 아래 순서를 추천합니다. 이 순서는 장애 위험을 낮추고 롤백을 쉽게 만듭니다.

1. 관측 먼저
   로그 레벨, tracepoint, 기본 메트릭을 먼저 켭니다. 관측 없는 최적화는 회귀를 숨깁니다.
2. 안전성 다음
   반환값 규약, 락 순서, 해제 경로를 고정합니다. 성능 이전에 crash/UAF를 먼저 제거합니다.
3. 성능 마지막
   핫패스에 한정해서 튜닝합니다. 모든 경로를 동시에 건드리면 원인 분리가 불가능해집니다.
4. 롤백 준비
   변경 전/후 수치를 저장하고 즉시 되돌릴 스위치(sysctl/module param)를 남깁니다.

운영 | 실전 체크리스트

이 체크리스트는 문서 전반의 규약을 배포 직전 점검 항목으로 재구성한 것입니다. 각 항목은 단독 통과보다 항목 간 정합성이 중요하며, 하나라도 누락되면 장애 전파 경로가 열릴 수 있습니다. 운영 반영 전에는 기능 테스트와 별도로 이 목록을 독립 검증해야 합니다.

실무 체크포인트: 체크리스트 점검 결과를 릴리스 노트에 남겨 회귀 시점 추적이 가능하도록 관리하세요.

• 포인터 반환 API는 IS_ERR() 또는 NULL 규약을 문서로 고정했는가?
• 락 획득 순서와 해제 순서를 함수 주석 또는 설계 문서에 명시했는가?
• copy_from_user / copy_to_user 반환값을 모두 처리했는가?
• devm_*와 수동 해제 API를 혼용하지 않았는가?
• 심볼 export는 최소 범위만 공개하고 네임스페이스를 설정했는가?
• 로그 레벨이 운영 기준에 맞고 폭주 억제 전략이 있는가?