Workqueue (CMWQ)

Workqueue는 리눅스 커널에서 가장 범용적인 Bottom Half 메커니즘입니다. 프로세스(Process) 컨텍스트에서 실행되므로 슬립(Sleep), mutex, 메모리 할당(GFP_KERNEL)이 가능하며, Concurrency Managed Workqueue (CMWQ) 아키텍처로 커널이 worker pool을 자동 관리합니다. 이 문서에서는 workqueue_struct, worker_pool, work_struct의 내부 구조부터 alloc_workqueue() API, 동시성 제어, flush/cancel 패턴, ordered/delayed 워크큐, 디버깅(Debugging), PREEMPT_RT 호환성까지 전 영역을 다룹니다.

Workqueue 역사와 진화

리눅스 커널의 workqueue 메커니즘은 오랜 진화 과정을 거쳐 현재의 CMWQ 아키텍처에 이르렀습니다. 각 세대의 특징과 한계를 이해하면 CMWQ의 설계 동기를 더 깊이 파악할 수 있습니다.

레거시 API는 v5.x에서 완전히 제거되었습니다.

CMWQ 이전에는 드라이버마다 create_workqueue()로 전용 workqueue를 만드는 것이 일반적이었고, 이로 인해 시스템에 수백 개의 kworker 스레드가 생성되는 문제가 있었습니다. CMWQ는 worker pool을 중앙 집중 관리하여 이 문제를 해결했습니다.

CMWQ 아키텍처 개요

Concurrency Managed Workqueue (CMWQ)는 Linux 2.6.36에서 도입된 현대적 workqueue 아키텍처입니다. 기존의 singlethread/multithread workqueue를 대체하여, 커널이 worker pool을 중앙 관리하고 동시성을 자동 제어합니다.

CMWQ의 핵심 설계 원칙:

• 공유 worker pool: 모든 workqueue가 worker pool을 공유하여 커널 스레드 수 최소화
• 자동 동시성 관리: worker가 블록되면 새 worker를 자동 생성하여 CPU 유휴 방지
• Bound/Unbound 분리: CPU-bound 작업과 NUMA-aware unbound 작업 구분
• 속성 기반 매핑(Mapping): workqueue 플래그에 따라 적절한 worker pool에 자동 매핑

CMWQ 아키텍처 상세

CMWQ의 핵심은 workqueue_struct, pool_workqueue, worker_pool, worker 네 가지 구조체(Struct)의 관계입니다. 각 구조체의 역할과 연결 관계를 상세히 살펴봅니다.

/* kernel/workqueue.c, kernel/workqueue_internal.h — 간략화 */

/*
 * pool_workqueue (pwq): workqueue와 worker_pool을 연결하는 중간 구조체
 *
 * 각 workqueue는 CPU/NUMA 노드마다 하나의 pwq를 가짐
 * pwq는 해당 workqueue의 work가 특정 worker_pool에서
 * 실행될 때의 상태를 추적함
 */
struct pool_workqueue {
    struct worker_pool *pool;         /* 연결된 worker pool */
    struct workqueue_struct *wq;       /* 소속 workqueue */
    int nr_active;                     /* 현재 실행 중인 work 수 */
    int max_active;                    /* 최대 동시 실행 수 */
    struct list_head inactive_works;   /* max_active 초과 시 대기 리스트 */
    struct list_head pwqs_node;        /* wq->pwqs 연결 */
    int work_color;                    /* flush용 color 태그 */
    int flush_color;                   /* flush 진행 중 color */
    int refcnt;                        /* 참조 카운트 */
};

/*
 * worker 구조체: 실제 kworker 스레드를 표현
 */
struct worker {
    union {
        struct list_head entry;        /* idle_list 연결 */
        struct hlist_node hentry;     /* busy_hash 연결 */
    };
    struct work_struct *current_work;  /* 현재 실행 중인 work */
    work_func_t current_func;          /* 현재 실행 함수 */
    struct pool_workqueue *current_pwq; /* 현재 pwq */
    struct worker_pool *pool;          /* 소속 pool */
    struct task_struct *task;          /* kworker 태스크 */
    unsigned long last_active;          /* 마지막 활동 시각 (jiffies) */
    unsigned int flags;                 /* WORKER_* 플래그 */
    int id;                             /* kworker ID */
};

Worker Pool 관리

Worker pool은 CMWQ의 실행 엔진입니다. Bound pool과 Unbound pool로 나뉘며, 각각의 동시성 관리 방식이 다릅니다. 아래 다이어그램은 worker의 상태 전환과 pool의 동시성 관리 메커니즘을 보여줍니다.

/*
 * Worker Pool 유형:
 *
 * 1. Bound (Per-CPU) Pool:
 *    - 각 CPU에 2개: normal (nice=0) + highpri (nice=-20)
 *    - kworker/CPU:ID 또는 kworker/CPU:IDH (highpri)
 *    - 해당 CPU에서만 work 실행 → 캐시 친화적
 *
 * 2. Unbound Pool:
 *    - NUMA 노드별 생성, 속성(nice, cpumask)으로 관리
 *    - kworker/uPOOL:ID
 *    - 어떤 CPU에서든 실행 가능 → 부하 분산
 *    - long-running 또는 CPU-intensive 작업에 적합
 *
 * 동시성 관리:
 *    - 풀의 running worker가 모두 블록되면 새 worker 생성
 *    - idle worker는 일정 시간 후 소멸 (IDLE_WORKER_TIMEOUT: 300초)
 *    - manager worker가 pool을 관리 (worker 생성/소멸)
 */

/* kernel/workqueue.c 주요 구조체 (간략화) */
struct worker_pool {
    spinlock_t lock;
    int cpu;                      /* bound pool의 CPU, unbound는 -1 */
    int node;                     /* NUMA 노드 */
    int id;
    unsigned int flags;
    struct list_head worklist;    /* pending work items */
    int nr_workers;               /* 총 worker 수 */
    int nr_idle;                  /* idle worker 수 */
    int nr_running;               /* 실행 중인 worker 수 (atomic) */
    struct list_head idle_list;   /* idle worker 리스트 */
    struct timer_list idle_timer;
    struct timer_list mayday_timer;
};

Worker 스레드 생성과 소멸

/* kernel/workqueue.c — 간략화 */

/*
 * create_worker(): 새 kworker 스레드 생성
 *
 * 호출 조건:
 *   - worklist에 pending work가 있지만 nr_running == 0
 *   - manager worker가 maybe_create_worker()에서 판단
 *
 * 이름 규칙:
 *   Bound:   kworker/CPU:ID     (예: kworker/0:2)
 *            kworker/CPU:IDH    (highpri, 예: kworker/0:1H)
 *   Unbound: kworker/uPOOL:ID   (예: kworker/u8:3)
 */
static struct worker *create_worker(struct worker_pool *pool)
{
    struct worker *worker;

    worker = alloc_worker(pool->node);
    worker->pool = pool;
    worker->id = pool->worker_ida++;

    /* kthread 생성 */
    if (pool->cpu >= 0)
        worker->task = kthread_create_on_node(
            worker_thread, worker, pool->node,
            "kworker/%d:%d%s", pool->cpu, worker->id,
            pool->attrs->nice < 0 ? "H" : "");
    else
        worker->task = kthread_create_on_node(
            worker_thread, worker, pool->node,
            "kworker/u%d:%d", pool->id, worker->id);

    /* Bound pool: CPU에 고정 */
    if (pool->cpu >= 0)
        kthread_bind(worker->task, pool->cpu);

    worker_enter_idle(worker);
    wake_up_process(worker->task);
    return worker;
}

/*
 * idle_worker_timeout: idle worker 소멸 타이머
 *
 * IDLE_WORKER_TIMEOUT (300초) 동안 활동 없으면 소멸
 * 단, 풀에 최소 1개 idle worker는 항상 유지 (min_idle = 1)
 */
static void idle_worker_timeout(struct timer_list *t)
{
    struct worker_pool *pool = from_timer(pool, t, idle_timer);

    /* too_many_workers(): nr_idle > 2 && (nr_idle-2)*MAX_IDLE_WORKERS_RATIO >= nr_busy */
    while (too_many_workers(pool)) {
        struct worker *worker = list_last_entry(
            &pool->idle_list, struct worker, entry);
        destroy_worker(worker);
    }
}

Rescuer 스레드

/* kernel/workqueue.c — 간략화 */

/*
 * Rescuer Thread: WQ_MEM_RECLAIM 워크큐의 안전장치
 *
 * 메모리 부족으로 새 kworker 스레드를 생성할 수 없을 때,
 * rescuer가 대신 work를 처리하여 데드락을 방지합니다.
 *
 * 동작 흐름:
 * 1. mayday_timer 만료 → send_mayday() 호출
 * 2. rescuer 스레드가 깨어남
 * 3. 해당 pool의 worklist에서 work를 가져와 실행
 * 4. pool의 정상 worker가 복구되면 다시 대기
 *
 * 주의: rescuer는 workqueue당 1개만 존재하므로
 *       동시에 많은 work를 처리할 수 없음
 *       → 최소한의 진행(forward progress)만 보장
 */
static int rescuer_thread(void *__rescuer)
{
    struct worker *rescuer = __rescuer;
    struct workqueue_struct *wq = rescuer->rescue_wq;

    for (;;) {
        set_current_state(TASK_IDLE);
        /* mayday 시그널 대기 */
        if (list_empty(&wq->maydays))
            schedule();
        /* pool의 worklist에서 work 실행 */
        process_scheduled_works(rescuer);
    }
}

alloc_workqueue() API

/* workqueue 생성 */
struct workqueue_struct *alloc_workqueue(
    const char *fmt,          /* 이름 형식 (printf 스타일) */
    unsigned int flags,       /* WQ_* 플래그 조합 */
    int max_active,           /* Per-CPU 최대 동시 실행 work 수 */
    ...                       /* fmt 인자 */
);

/* 예제 */
struct workqueue_struct *my_wq;
my_wq = alloc_workqueue("my_driver_wq",
    WQ_UNBOUND | WQ_MEM_RECLAIM, 0);

alloc_workqueue 플래그 상세

WQ_UNBOUND (bit 1)

Per-CPU pool 대신 NUMA-aware unbound pool을 사용합니다. kworker가 특정 CPU에 고정되지 않아 스케줄러가 자유롭게 배치합니다. long-running 작업에 적합하며, bound pool의 concurrency 관리에 간섭하지 않습니다. WQ_CPU_INTENSIVE와 함께 사용할 수 없습니다(의미상 중복).

WQ_HIGHPRI (bit 4)

nice=-20 worker pool(highpri pool)을 사용합니다. 일반 worker pool(nice=0)보다 높은 스케줄링 우선순위를 가지며, kworker 이름에 H 접미사가 붙습니다(예: kworker/0:1H). 실시간 응답이 중요한 작업에 사용합니다.

WQ_CPU_INTENSIVE (bit 5)

bound pool에서만 의미가 있습니다. 해당 work를 concurrency 관리 대상에서 제외하여, CPU 점유로 인해 nr_running이 0이 되어도 새 worker를 생성하지 않습니다. CPU 연산이 주 작업인 경우 불필요한 worker 증식을 방지합니다.

WQ_MEM_RECLAIM (bit 3)

rescuer 스레드 생성을 보장합니다. 메모리 부족으로 새 worker를 생성할 수 없을 때 rescuer가 대신 처리합니다. 메모리 회수 경로(reclaim path)에서 사용하는 workqueue에 필수이며, 파일시스템, 블록 I/O, 스왑 관련 work에 반드시 설정해야 합니다.

WQ_FREEZABLE (bit 2)

시스템 suspend(freeze) 시 work 처리를 중단합니다. try_to_freeze_tasks()에서 workqueue를 동결하고, resume 시 자동으로 처리를 재개합니다. 사용자 공간 요청 처리, PM 관련 작업에 사용합니다.

WQ_SYSFS (bit 9)

/sys/devices/virtual/workqueue/<name>/ 디렉터리를 생성합니다. 런타임에 cpumask, max_active, nice를 변경할 수 있어 프로덕션 환경 튜닝에 유용합니다.

WQ_POWER_EFFICIENT (bit 7)

wq_power_efficient 커널 파라미터가 활성화되면 WQ_UNBOUND로 동작하고, 비활성 시 일반 bound workqueue로 동작합니다. 전력 효율이 중요한 모바일/임베디드 환경에 적합합니다.

max_active 동시성 제어

/*
 * max_active: Per-CPU 또는 Per-NUMA 동시 실행 work item 수 제한
 *
 * - 0: 기본값 (WQ_DFL_ACTIVE = 256)
 * - 1: 순차 실행 (alloc_ordered_workqueue)
 * - N: 최대 N개 동시 실행
 *
 * Bound (Per-CPU) workqueue:
 *   max_active=4 → 각 CPU에서 최대 4개 work 동시 실행
 *
 * Unbound workqueue:
 *   max_active=4 → 각 NUMA 노드에서 최대 4개 work 동시 실행
 *
 * 주의: max_active는 실행 중인 work만 제한
 *       pending(대기 중) work 수는 무제한
 */

/* 순차 실행이 필요한 경우 */
struct workqueue_struct *ordered_wq;
ordered_wq = alloc_ordered_workqueue("my_ordered", 0);
/* = alloc_workqueue("my_ordered", __WQ_ORDERED, 1) */

시스템 Workqueue

커널은 미리 생성된 시스템 workqueue를 제공합니다. 대부분의 경우 전용 workqueue를 만들 필요 없이 시스템 workqueue를 사용합니다.

시스템 workqueue 상세 비교:

schedule_work(&work)

system_wq에 큐잉합니다. 대부분의 드라이버에서 이것으로 충분하며, 짧은 작업이나 다른 서브시스템과의 간섭을 최소화할 때 사용합니다.

queue_work(system_highpri_wq, &work)

지연시간이 중요한 작업(인터럽트 후처리 등)에 사용합니다. nice=-20 worker에서 실행되어 일반 work보다 우선합니다.

queue_work(system_long_wq, &work)

장시간 실행될 수 있는 작업에 사용합니다. system_wq와 같은 pool이지만 의미적으로 분리되어 있습니다. WQ_CPU_INTENSIVE가 아니므로 concurrency 관리에 영향을 줄 수 있습니다.

queue_work(system_unbound_wq, &work)

CPU에 고정되지 않아야 하는 작업에 사용합니다. NUMA 로컬리티를 활용하며 스케줄러가 자유롭게 배치합니다.

전용 workqueue 생성이 필요한 경우:

• flush/cancel 시 다른 서브시스템에 영향이 없어야 할 때
• 특수 플래그 조합이 필요할 때 (WQ_UNBOUND | WQ_MEM_RECLAIM 등)
• max_active 제한으로 동시성 제어가 필요할 때
• /sys/kernel/debug/workqueue에서 독립 모니터링이 필요할 때
• WQ_SYSFS로 런타임 튜닝이 필요할 때

Work Item 생명주기

work_struct는 커널의 비동기 실행 단위입니다. 하나의 work item은 Idle → Pending → Running → Idle의 생명주기를 거치며, 중간에 취소(cancel)되거나 동기화(flush)될 수 있습니다. 아래 다이어그램은 전체 상태 전이를 보여줍니다.

Work Item 상태 전이:

1. Idle: work이 어떤 workqueue에도 없는 상태입니다.
2. queue_work() / schedule_work() 호출로 Pending 상태로 전환합니다. WORK_STRUCT_PENDING 비트가 set됩니다.
3. kworker가 dequeue하면 Running 상태로 전환합니다. PENDING 비트가 클리어되고 current_work = this가 설정됩니다.
4. 콜백이 완료되면 다시 Idle 상태로 돌아가며, 재큐잉이 가능합니다.

핵심 규칙:

• PENDING인 work를 다시 queue하면 no-op입니다 (중복 방지).
• Running 중에 queue하면 PENDING이 set되어 완료 후 재실행됩니다.
• 서로 다른 workqueue에 같은 work를 queue할 수 없습니다.

/* work_struct 내부 */
struct work_struct {
    atomic_long_t data;        /* flags + pool_workqueue 포인터 */
    struct list_head entry;     /* worklist 연결 */
    work_func_t func;           /* 콜백 함수 */
};

work_struct data 필드 비트 인코딩

work_struct의 data 필드는 하나의 atomic_long_t에 여러 정보를 멀티플렉싱(Multiplexing)하는 정교한 설계입니다. 하위 비트에는 상태 플래그를 저장하고, 상위 비트에는 pool_workqueue 포인터 또는 pool ID를 인코딩합니다. 이 설계로 단일 atomic 연산만으로 work의 상태 전이와 소속 추적이 가능합니다.

/*
 * work_struct.data 비트 레이아웃 (include/linux/workqueue.h):
 *
 * 비트 0: WORK_STRUCT_PENDING
 *   - 1 = work가 큐에 있거나 큐잉 예정
 *   - 0 = work가 idle이거나 실행 중
 *   - test_and_set_bit()으로 원자적 설정 → 중복 큐잉 방지
 *
 * 비트 1: WORK_STRUCT_DELAYED
 *   - delayed_work 전용 플래그
 *   - 1 = 타이머 대기 중 (아직 worklist에 없음)
 *
 * 비트 2: WORK_STRUCT_PWQ
 *   - 1 = 상위 비트가 pool_workqueue 포인터
 *   - 0 = 상위 비트가 pool ID (실행 중 또는 idle)
 *
 * 비트 3~(WORK_STRUCT_FLAG_BITS-1): WORK_STRUCT_COLOR
 *   - flush_workqueue()의 color 태깅에 사용
 *   - WORK_NR_COLORS(16) 순환 → 4비트
 *
 * 비트 WORK_STRUCT_FLAG_BITS~63: 포인터/ID
 *   - PWQ=1: pool_workqueue 포인터 (8바이트 정렬 보장)
 *   - PWQ=0: worker_pool ID (get_work_pool() 검색용)
 *
 * 핵심 설계 이점:
 * - 단일 atomic_long_t로 상태+소속을 관리
 * - test_and_set_bit 하나로 중복 큐잉 방지
 * - 별도 lock 없이 work 상태를 추적
 */

/* 비트 조작 매크로 */
#define WORK_STRUCT_PENDING_BIT   0
#define WORK_STRUCT_DELAYED_BIT   1
#define WORK_STRUCT_PWQ_BIT       2
#define WORK_STRUCT_COLOR_SHIFT   3

/* PENDING 비트 조작 예시 */
static inline bool work_pending(struct work_struct *work)
{
    return atomic_long_read(&work->data) & WORK_STRUCT_PENDING;
}

/* queue_work_on()에서의 중복 방지 핵심 코드 */
bool queue_work_on(int cpu, struct workqueue_struct *wq,
                   struct work_struct *work)
{
    /* test_and_set_bit: PENDING이 이미 1이면 false 반환 → 큐잉 안 함 */
    if (!test_and_set_bit(WORK_STRUCT_PENDING_BIT,
                          work_data_bits(work))) {
        __queue_work(cpu, wq, work);
        return true;
    }
    return false;
}

INIT_WORK / INIT_DELAYED_WORK 매크로(Macro) 분석

/*
 * INIT_WORK(): work_struct 초기화 매크로
 *
 * 반드시 queue_work() 전에 호출해야 함
 * 정적 초기화는 DECLARE_WORK() 사용
 */
INIT_WORK(&my_work, my_work_handler);
/* 내부 동작:
 *   1. work->data = WORK_STRUCT_NO_POOL (어떤 pool에도 없음)
 *   2. INIT_LIST_HEAD(&work->entry)  (연결 리스트 초기화)
 *   3. work->func = my_work_handler  (콜백 함수 등록)
 */

/* 정적 초기화 (글로벌/파일 스코프) */
static DECLARE_WORK(my_global_work, my_global_handler);
/* 컴파일 시점에 초기화, 모듈 로드 즉시 사용 가능 */

/* Delayed Work 초기화 */
INIT_DELAYED_WORK(&my_dwork, my_delayed_handler);
/* 내부: INIT_WORK + timer_setup(&dwork->timer, delayed_work_timer_fn) */

static DECLARE_DELAYED_WORK(my_global_dwork, my_global_delayed_handler);

queue_work() vs schedule_work()

/* include/linux/workqueue.h — 간략화 */

/* schedule_work(): system_wq에 큐잉 (편의 함수) */
static inline bool schedule_work(struct work_struct *work)
{
    return queue_work(system_wq, work);
}

/* queue_work(): 특정 workqueue에 큐잉 */
bool queue_work(struct workqueue_struct *wq,
               struct work_struct *work);

/* queue_work_on(): 특정 CPU에 큐잉 */
bool queue_work_on(int cpu, struct workqueue_struct *wq,
                   struct work_struct *work);

/* 반환값: true = 새로 큐잉됨, false = 이미 pending */

/* 전용 workqueue 사용 vs system_wq 기준:
 *
 * system_wq 사용 (schedule_work):
 *   - 짧은 작업, 다른 work와 간섭 적음
 *   - 대부분의 드라이버에서 적합
 *
 * 전용 workqueue 생성:
 *   - flush/cancel 시 다른 서브시스템에 영향 없어야 할 때
 *   - 특수 플래그 필요 (WQ_UNBOUND, WQ_MEM_RECLAIM 등)
 *   - max_active 제어 필요
 *   - /sys/kernel/debug/workqueue에서 독립 모니터링 필요
 */

Ordered 및 Delayed Workqueue

Workqueue의 실행 모드는 크게 Per-CPU (Bound), Unbound, Ordered로 나뉩니다. 각각의 동작 차이를 아래 다이어그램에서 비교합니다.

Ordered Workqueue

/* Ordered Workqueue: 큐잉 순서대로 하나씩 실행 */
struct workqueue_struct *owq;
owq = alloc_ordered_workqueue("my_ordered", 0);

/*
 * 특성:
 * - max_active = 1 → 동시에 하나의 work만 실행
 * - 큐잉 순서 보장 (FIFO)
 * - 내부적으로 __WQ_ORDERED 플래그 + unbound
 *
 * 사용 시나리오:
 * - 상태 머신 이벤트 처리 (순서 중요)
 * - 파일시스템 로그/저널 쓰기
 * - 하드웨어 초기화 시퀀스
 *
 * 주의: ordered wq는 WQ_UNBOUND를 암시적으로 포함
 *       → CPU 마이그레이션 가능 (특정 CPU 고정 아님)
 */

Delayed Work

/* include/linux/workqueue.h — 간략화 */

/* Delayed Work: 지정 시간 후 실행 */
struct delayed_work {
    struct work_struct work;
    struct timer_list timer;
    struct workqueue_struct *wq;
    int cpu;
};

/* 초기화 */
INIT_DELAYED_WORK(&dev->dwork, my_delayed_handler);

/* 큐잉: delay jiffies 후 실행 */
queue_delayed_work(my_wq, &dev->dwork,
    msecs_to_jiffies(100));    /* 100ms 후 */

/* 시스템 workqueue에 큐잉 */
schedule_delayed_work(&dev->dwork,
    msecs_to_jiffies(500));    /* 500ms 후 */

/* mod_delayed_work(): 이미 pending인 delayed work의 타이머 변경 */
mod_delayed_work(my_wq, &dev->dwork,
    msecs_to_jiffies(200));    /* 기존 타이머 취소 + 200ms로 재설정 */
/* 반환값: true = 기존 pending work를 변경, false = 새로 큐잉 */

/* 즉시 실행으로 변경 */
mod_delayed_work(my_wq, &dev->dwork, 0);
/* delay=0이면 가능한 빨리 실행 */

Delayed Work 내부 타이머(Timer) 연동

/*
 * delayed_work 내부 동작:
 *
 * queue_delayed_work(wq, &dwork, delay)
 *   │
 *   ├─ delay == 0?
 *   │   ├─ YES → queue_work(wq, &dwork.work)  // 즉시 큐잉
 *   │   └─ NO  → __queue_delayed_work():
 *   │             1. dwork->wq = wq
 *   │             2. dwork->cpu = current_cpu
 *   │             3. timer_setup(&dwork->timer, delayed_work_timer_fn)
 *   │             4. add_timer_on(&dwork->timer, cpu)
 *   │             // 타이머 만료 시 콜백:
 *   │
 *   ▼
 * delayed_work_timer_fn() (타이머 만료 시 호출)
 *   │
 *   ├─ WORK_STRUCT_DELAYED 클리어
 *   └─ __queue_work(dwork->cpu, dwork->wq, &dwork->work)
 *       // 이 시점에서 일반 work와 동일하게 처리
 *
 * 핵심:
 * - delayed_work = work_struct + timer_list + wq 포인터
 * - 타이머가 만료되면 일반 work로 전환하여 큐잉
 * - cancel_delayed_work()는 del_timer() + (선택적) cancel_work()
 * - mod_delayed_work()는 del_timer() + queue_delayed_work() 원자적 수행
 */

/* 주기적 작업 패턴 (자기 재큐잉) */
static void periodic_handler(struct work_struct *work)
{
    struct delayed_work *dwork = to_delayed_work(work);
    struct my_device *dev = container_of(dwork,
        struct my_device, periodic_work);

    /* 주기적 작업 수행 */
    do_periodic_check(dev);

    /* shutting_down 체크 후 자기 재큐잉 */
    if (!dev->shutting_down)
        queue_delayed_work(dev->wq, dwork,
            msecs_to_jiffies(1000));  /* 1초마다 */
}

Delayed Work 취소 경쟁 조건 분석

delayed_work는 타이머(Timer)와 work의 2단계 구조이므로 취소 시 미묘한 경쟁 조건(Race Condition)이 발생할 수 있습니다. 아래 다이어그램은 cancel_delayed_work() vs cancel_delayed_work_sync()의 차이와 각 시점에서의 동작을 상세히 보여줍니다.

/*
 * delayed_work 취소 패턴: 경쟁 조건 회피
 *
 * 패턴 1: shutdown 플래그 + cancel_delayed_work_sync()
 *   가장 안전하고 권장되는 패턴
 */
struct my_device {
    struct delayed_work poll_work;
    struct workqueue_struct *wq;
    atomic_t shutting_down;          /* atomic: IRQ에서도 접근 */
};

static void poll_handler(struct work_struct *work)
{
    struct delayed_work *dwork = to_delayed_work(work);
    struct my_device *dev = container_of(dwork,
        struct my_device, poll_work);

    do_poll_check(dev);

    /* atomic_read: shutdown 플래그 확인 후 재큐잉 결정 */
    if (!atomic_read(&dev->shutting_down))
        queue_delayed_work(dev->wq, dwork,
            msecs_to_jiffies(500));
}

static void my_device_stop(struct my_device *dev)
{
    /* 1. shutdown 플래그 설정 (재큐잉 방지) */
    atomic_set(&dev->shutting_down, 1);

    /* 2. sync 취소: 타이머 + 실행 중 콜백 모두 대기
     *    콜백이 실행 중이더라도, shutdown 플래그가 설정되어
     *    재큐잉하지 않으므로 cancel 이후 work가 다시 나타나지 않음 */
    cancel_delayed_work_sync(&dev->poll_work);
    /* 이 시점에서 work가 실행되지 않음을 100% 보장 */
}

/*
 * 패턴 2: disable_delayed_work_sync() 시뮬레이션
 *   flush 없이 영구적으로 비활성화 (커널 6.7+에서는 disable_work() 추가)
 */
static void my_device_suspend(struct my_device *dev)
{
    /* 재큐잉 방지 후 취소 — suspend 경로에서 안전 */
    atomic_set(&dev->shutting_down, 1);
    cancel_delayed_work_sync(&dev->poll_work);
}

static void my_device_resume(struct my_device *dev)
{
    /* 재활성화 + 재스케줄 */
    atomic_set(&dev->shutting_down, 0);
    queue_delayed_work(dev->wq, &dev->poll_work,
        msecs_to_jiffies(500));
}

/*
 * 패턴 3: mod_delayed_work()를 이용한 동적 주기 조정
 *   cancel 없이 타이머를 재설정하여 경쟁 조건 자체를 회피
 */
static void adjust_poll_interval(struct my_device *dev,
                               unsigned int new_ms)
{
    /* mod_delayed_work(): 기존 타이머 취소 + 새 delay로 재설정
     * cancel + re-queue의 원자적 수행
     * 경쟁 조건 없음 — 내부에서 lock으로 보호됨 */
    mod_delayed_work(dev->wq, &dev->poll_work,
        msecs_to_jiffies(new_ms));
}

ordered vs max_active=1의 차이

동기화 패턴: Cancel 및 Flush

취소 패턴

/* Work 취소: 동기적으로 완료 대기 */
bool cancel_work_sync(struct work_struct *work);
/*
 * - pending이면: dequeue 후 반환 (true)
 * - running이면: 완료를 기다린 후 반환 (false)
 * - idle이면: 즉시 반환 (false)
 * 주의: 슬립 가능! 인터럽트/atomic 컨텍스트에서 호출 불가
 */

/* Delayed Work 취소 */
bool cancel_delayed_work(struct delayed_work *dwork);
/* 비동기: 타이머만 취소, 이미 실행 중이면 대기 안 함 */

bool cancel_delayed_work_sync(struct delayed_work *dwork);
/* 동기: 타이머 취소 + 실행 중인 콜백 완료 대기 */

/* 안전한 드라이버 해제 패턴 */
static void my_remove(struct platform_device *pdev)
{
    struct my_device *dev = platform_get_drvdata(pdev);

    /* 1. 더 이상 새 work가 큐잉되지 않도록 플래그 설정 */
    dev->shutting_down = true;

    /* 2. 모든 work 취소 (실행 중이면 완료 대기) */
    cancel_work_sync(&dev->work);
    cancel_delayed_work_sync(&dev->dwork);

    /* 3. 이 시점에서 work 콜백이 실행되지 않음을 보장 */
}

Flush 패턴

/* include/linux/workqueue.h, kernel/workqueue.c — 간략화 */

/* flush_work(): 특정 work의 완료 대기 */
bool flush_work(struct work_struct *work);
/* pending/running work 완료를 기다림 */

/* flush_workqueue(): workqueue의 모든 pending work 완료 대기 */
void flush_workqueue(struct workqueue_struct *wq);
/* 호출 시점에 pending인 모든 work의 완료를 기다림 */
/* flush 후에 새로 큐잉된 work는 포함하지 않음 */

/* flush_scheduled_work(): system_wq flush */
void flush_scheduled_work(void);
/* 모듈 해제 시 system_wq에 큐잉된 work 정리용 */

/* drain_workqueue(): 모든 work 완료 대기 + 새 큐잉 차단 */
void drain_workqueue(struct workqueue_struct *wq);
/* destroy_workqueue() 전에 호출하여 잔여 work 처리 */

flush_workqueue() 내부 메커니즘 (color 기반): flush_workqueue()는 "color" 메커니즘으로 구현됩니다. flush 호출 시 현재 work_color를 기록하고 다음 color로 전진합니다. 새로 큐잉되는 work는 새 color를 받으므로, flush 중 새로 큐잉된 work와 기존 work를 구분할 수 있고, 여러 flush를 동시에 처리할 수 있습니다.

올바른 정리(cleanup) 패턴

/* 드라이버 제거 시 올바른 정리 순서 */
static void my_driver_remove(struct platform_device *pdev)
{
    struct my_device *dev = platform_get_drvdata(pdev);

    /* 1. 새로운 work 큐잉 방지 */
    dev->shutting_down = true;

    /* 2. pending delayed_work의 타이머 취소 + 실행 중 work 완료 대기 */
    cancel_delayed_work_sync(&dev->periodic_work);

    /* 3. 일반 work 취소 + 완료 대기 */
    cancel_work_sync(&dev->irq_work);

    /* 4. 커스텀 워크큐 파괴 (모든 work가 완료된 후) */
    if (dev->wq) {
        drain_workqueue(dev->wq);
        destroy_workqueue(dev->wq);
    }

    /* 5. 나머지 리소스 해제 */
    free_irq(dev->irq, dev);
}

디버깅 및 모니터링

Workqueue 관련 문제를 진단하려면 debugfs, sysfs, ftrace tracepoint, lockdep 등 여러 도구를 활용합니다. 아래 다이어그램은 문제 유형별 디버깅 접근 경로를 보여줍니다.

debugfs 기반 모니터링

# workqueue 상태 확인
cat /sys/kernel/debug/workqueue

# 출력 예시:
# workqueue           CPU  POOL  ACTIVE/MAX  WORKERS  FLAGS
# events               0     0      0/256      3
# events               1     2      0/256      2
# events_highpri       0     1      0/256      2     highpri
# my_driver_wq        -1    16      2/4        3     unbound

# kworker 스레드 확인
ps aux | grep kworker
# kworker/0:0   - CPU 0 bound worker
# kworker/0:0H  - CPU 0 highpri bound worker
# kworker/u8:0  - unbound worker (pool id=8)

# WQ_SYSFS가 설정된 workqueue의 런타임 설정
ls /sys/devices/virtual/workqueue/
# cpumask  max_active  nice

# 런타임 max_active 변경 (WQ_SYSFS 필요)
echo 8 > /sys/devices/virtual/workqueue/my_wq/max_active
cat /sys/devices/virtual/workqueue/my_wq/cpumask

# wq_watchdog: 정체된 work 탐지
# CONFIG_WQ_WATCHDOG=y + wq_watchdog_thresh_ms (기본 30초)
echo 10000 > /sys/module/workqueue/parameters/watchdog_thresh
# 10초 이상 실행 중인 work 경고

# workqueue tracepoint
echo 1 > /sys/kernel/debug/tracing/events/workqueue/workqueue_queue_work/enable
echo 1 > /sys/kernel/debug/tracing/events/workqueue/workqueue_execute_start/enable
echo 1 > /sys/kernel/debug/tracing/events/workqueue/workqueue_execute_end/enable
cat /sys/kernel/debug/tracing/trace

ftrace를 활용한 Work 실행 분석

# trace-cmd를 사용한 workqueue 이벤트 수집
trace-cmd record -e workqueue sleep 10
trace-cmd report | head -50

# 출력 예시:
# kworker/0:1  workqueue_execute_start: work struct ffff8881234 function my_work_handler
# kworker/0:1  workqueue_execute_end:   work struct ffff8881234 function my_work_handler

# 특정 함수의 work 실행 시간 측정
echo 'hist:keys=function:vals=hitcount:sort=hitcount.descending' > \
  /sys/kernel/debug/tracing/events/workqueue/workqueue_execute_start/trigger
cat /sys/kernel/debug/tracing/events/workqueue/workqueue_execute_start/hist

# perf를 사용한 workqueue 프로파일링
perf stat -e workqueue:workqueue_queue_work \
         -e workqueue:workqueue_execute_start \
         -e workqueue:workqueue_execute_end \
         -a sleep 10

# lockdep으로 flush 데드락 가능성 감지
# CONFIG_PROVE_LOCKING=y 빌드 후 자동 감지
# 의심 시 dmesg에서 "possible circular locking dependency detected" 확인
dmesg | grep -i "circular\|deadlock\|workqueue"

Best Practices

실전 드라이버 예제

#include <linux/module.h>
#include <linux/workqueue.h>
#include <linux/platform_device.h>

struct my_device {
    struct workqueue_struct *wq;
    struct work_struct irq_work;
    struct delayed_work monitor_work;
    bool shutting_down;
    int irq;
    void __iomem *regs;
};

/* IRQ bottom half: 인터럽트 후처리 */
static void my_irq_work_handler(struct work_struct *work)
{
    struct my_device *dev = container_of(work,
        struct my_device, irq_work);

    /* 프로세스 컨텍스트: mutex, 메모리 할당 가능 */
    mutex_lock(&dev->lock);
    process_hw_data(dev);
    mutex_unlock(&dev->lock);
}

/* 주기적 모니터링 */
static void my_monitor_handler(struct work_struct *work)
{
    struct delayed_work *dwork = to_delayed_work(work);
    struct my_device *dev = container_of(dwork,
        struct my_device, monitor_work);

    check_device_health(dev);

    if (!dev->shutting_down)
        queue_delayed_work(dev->wq, dwork,
            msecs_to_jiffies(5000));
}

/* IRQ 핸들러 (top half) */
static irqreturn_t my_irq_handler(int irq, void *data)
{
    struct my_device *dev = data;

    /* ACK 하드웨어 인터럽트 */
    writel(0x1, dev->regs + IRQ_ACK);

    /* bottom half로 지연: queue_work는 IRQ-safe */
    queue_work(dev->wq, &dev->irq_work);

    return IRQ_HANDLED;
}

/* 프로브: 초기화 */
static int my_probe(struct platform_device *pdev)
{
    struct my_device *dev;

    dev = devm_kzalloc(&pdev->dev, sizeof(*dev), GFP_KERNEL);

    /* workqueue 생성: unbound + rescuer 보장 */
    dev->wq = alloc_workqueue("my_dev_wq",
        WQ_UNBOUND | WQ_MEM_RECLAIM, 4);
    if (!dev->wq)
        return -ENOMEM;

    /* work 초기화 (큐잉 전 필수!) */
    INIT_WORK(&dev->irq_work, my_irq_work_handler);
    INIT_DELAYED_WORK(&dev->monitor_work, my_monitor_handler);

    /* 모니터링 시작 */
    queue_delayed_work(dev->wq, &dev->monitor_work,
        msecs_to_jiffies(5000));

    return 0;
}

/* 제거: 안전한 정리 */
static void my_remove(struct platform_device *pdev)
{
    struct my_device *dev = platform_get_drvdata(pdev);

    /* 1. 새 work 큐잉 방지 */
    dev->shutting_down = true;

    /* 2. 인터럽트 해제 (새 IRQ work 방지) */
    free_irq(dev->irq, dev);

    /* 3. delayed work 취소 + 완료 대기 */
    cancel_delayed_work_sync(&dev->monitor_work);

    /* 4. 일반 work 취소 + 완료 대기 */
    cancel_work_sync(&dev->irq_work);

    /* 5. workqueue 파괴 */
    destroy_workqueue(dev->wq);
}

PREEMPT_RT와 Workqueue

PREEMPT_RT(Real-Time) 커널은 리눅스의 결정적(Deterministic) 실시간 응답을 위한 패치셋으로, workqueue의 동작 방식에 근본적인 영향을 미칩니다. PREEMPT_RT는 Linux 5.15부터 메인라인에 점진적으로 병합되었으며, 6.x에서 대부분의 핵심 인프라가 통합되었습니다.

RT 커널에서의 Workqueue 변화

RT에서의 Spinlock 변환과 Worker Pool

/*
 * PREEMPT_RT의 spinlock 변환이 workqueue에 미치는 영향:
 *
 * 일반 커널:
 *   spinlock_t → 실제 spin, 인터럽트/선점 비활성화
 *   raw_spinlock_t → 실제 spin (RT에서도 동일)
 *
 * PREEMPT_RT:
 *   spinlock_t → rt_mutex 기반 (슬립 가능, 우선순위 상속)
 *   raw_spinlock_t → 실제 spin (짧은 임계 구간만)
 *
 * workqueue 내부에서:
 *   pool->lock: raw_spinlock_t → RT에서도 실제 spin (매우 짧은 구간)
 *   pwq->stats_lock: spinlock_t → RT에서 rt_mutex
 *
 * 핵심 포인트:
 *   - pool->lock이 raw_spinlock이므로 work 큐잉/디큐잉은 결정적
 *   - worker가 work 실행 중 다른 spinlock을 잡으면 RT에서 슬립 가능
 *   - 이때 wq_worker_sleeping()이 호출되어 pool의 nr_running 감소
 *   - pool이 새 worker를 깨워 동시성 유지
 */

/* kernel/workqueue.c — pool lock은 raw_spinlock */
struct worker_pool {
    raw_spinlock_t  lock;    /* RT에서도 spin — 임계 구간 최소화 */
    int             cpu;
    int             node;
    int             id;
    unsigned int    flags;
    /* ... */
};

/* RT에서 spinlock → rt_mutex 변환 예시:
 * 드라이버의 work 콜백에서 spinlock_t를 잡으면
 * RT에서는 슬립 가능 → wq_worker_sleeping() 트리거
 */
static void my_work_handler(struct work_struct *work)
{
    struct my_device *dev = container_of(work, struct my_device, work);

    spin_lock(&dev->lock);
    /* 일반 커널: spin 대기, 선점 비활성화
     * PREEMPT_RT: rt_mutex 대기, 슬립 가능 → pool에서 nr_running-- */
    dev->data = process_data(dev);
    spin_unlock(&dev->lock);
}

Worker 스레드 우선순위 제어

/*
 * RT 커널에서 kworker 우선순위 조정:
 *
 * 기본 kworker 우선순위:
 *   - normal pool: SCHED_NORMAL, nice=0
 *   - highpri pool: SCHED_NORMAL, nice=HIGHPRI_NICE_LEVEL (-20)
 *
 * RT 시스템에서 kworker에 RT 스케줄링 정책 설정:
 *   chrt -f -p  
 *
 * 주의: kworker는 pool 내에서 동적으로 생성/파괴됨
 * → pid가 바뀔 수 있으므로 cgroup으로 관리 권장
 */

/* 방법 1: cgroup을 이용한 kworker RT 우선순위 관리 */
# RT cgroup 생성
# mkdir /sys/fs/cgroup/cpu/rt_workers
# echo 950000 > /sys/fs/cgroup/cpu/rt_workers/cpu.rt_runtime_us
# echo  > /sys/fs/cgroup/cpu/rt_workers/cgroup.procs

/* 방법 2: 전용 workqueue + WQ_HIGHPRI */
struct workqueue_struct *rt_wq;
rt_wq = alloc_workqueue("rt_critical",
                        WQ_HIGHPRI | WQ_MEM_RECLAIM, 1);
/* nice=-20 worker 사용 → 일반 태스크보다 높은 우선순위
 * 단, 여전히 SCHED_NORMAL이므로 RT 태스크보다는 낮음 */

/* 방법 3: RT 태스크에서 flush_work() 회피 패턴 */
struct rt_safe_device {
    struct work_struct  work;
    struct completion   done;  /* flush 대신 completion 사용 */
    int                result;
};

static void rt_work_handler(struct work_struct *work)
{
    struct rt_safe_device *dev =
        container_of(work, struct rt_safe_device, work);
    dev->result = do_hardware_operation();
    complete(&dev->done);  /* RT 태스크 깨움 */
}

/* RT 태스크 측: */
init_completion(&dev->done);
queue_work(rt_wq, &dev->work);
/* flush_work() 대신 completion 대기
 * → 우선순위 상속이 동작하여 역전 방지 (RT에서 completion은 rt_mutex) */
wait_for_completion(&dev->done);

RT와 WQ_BH 상호작용

중요: WQ_BH work의 콜백은 여전히 softirq 규약을 따라야 합니다.

• spin_lock_bh() 사용 금지 (softirq 재진입이 아닙니다)
• 슬립 API 호출 금지 (RT에서 가능하더라도 이식성을 위해 사용하지 않습니다)
• GFP_KERNEL 할당 금지 (GFP_ATOMIC만 사용해야 합니다)

RT 환경 Best Practices

일반적인 버그 패턴

Workqueue 관련 버그는 커널 패닉, 메모리 손상, 데드락 등 심각한 결과를 초래합니다. 가장 빈번한 버그 패턴과 올바른 해결법을 상세히 분석합니다.

버그 1: work_struct를 포함한 구조체의 조기 해제 (Use-After-Free)

가장 빈번하고 위험한 workqueue 버그입니다. work_struct가 아직 큐에 있거나 실행 중인 상태에서 이를 포함한 구조체를 해제하면 Use-After-Free가 발생합니다.

/* ❌ 잘못된 코드: work 실행 중 구조체 해제 */
struct my_device {
    struct work_struct  work;
    void __iomem       *regs;
    int                data;
};

static void my_work_handler(struct work_struct *work)
{
    struct my_device *dev = container_of(work, struct my_device, work);
    dev->data = readl(dev->regs);  /* dev가 이미 해제되었다면? → 커널 패닉! */
}

static void bad_remove(struct pci_dev *pdev)
{
    struct my_device *dev = pci_get_drvdata(pdev);
    kfree(dev);  /* ❌ work가 아직 큐에 있거나 실행 중일 수 있음! */
}

/* ✅ 올바른 코드: cancel 후 해제 */
static void good_remove(struct pci_dev *pdev)
{
    struct my_device *dev = pci_get_drvdata(pdev);
    cancel_work_sync(&dev->work);  /* 실행 중이면 완료 대기, 큐에 있으면 제거 */
    kfree(dev);  /* 이제 안전하게 해제 */
}

버그 2: 스택에 work_struct 할당

work_struct는 worker 스레드가 나중에 접근하는 구조체이므로, 함수 스택에 할당하면 함수 반환 후 스택 프레임이 재사용될 때 메모리 손상이 발생합니다.

/* ❌ 잘못된 코드: 스택에 work_struct 할당 */
static int bad_function(void)
{
    struct work_struct work;  /* 스택 변수! */
    INIT_WORK(&work, my_handler);
    schedule_work(&work);
    return 0;
    /* 함수 반환 → 스택 프레임 해제 → kworker가 실행 시 → 스택 손상 */
}

/* ✅ 올바른 코드: 힙에 할당하거나 구조체 멤버로 포함 */

/* 패턴 A: 구조체 멤버 (가장 일반적) */
struct my_context {
    struct work_struct  work;
    int                param;
};

/* 패턴 B: 동적 할당 (일회성 work) */
static void onetime_handler(struct work_struct *work)
{
    struct my_context *ctx = container_of(work, struct my_context, work);
    do_something(ctx->param);
    kfree(ctx);  /* 콜백 내에서 해제 (자기 자신) */
}

static int good_function(int param)
{
    struct my_context *ctx = kmalloc(sizeof(*ctx), GFP_KERNEL);
    if (!ctx) return -ENOMEM;
    ctx->param = param;
    INIT_WORK(&ctx->work, onetime_handler);
    schedule_work(&ctx->work);
    return 0;
}

버그 3: Work 콜백에서 자기 Workqueue Flush (데드락)

work 콜백 함수 내에서 자신이 속한 workqueue를 flush하면 자기 자신의 완료를 기다리는 형태가 되어 교착(Deadlock)이 발생합니다.

/* ❌ 잘못된 코드: 콜백 내 자기 workqueue flush → 데드락 */
static struct workqueue_struct *my_wq;

static void my_work_func(struct work_struct *work)
{
    do_first_part();
    /* 이전 work들이 모두 완료될 때까지 대기하고 싶음 */
    flush_workqueue(my_wq);  /* ❌ 자기 자신도 이 workqueue에 속함!
                               * flush는 모든 pending work 완료를 대기
                               * 자기 자신의 완료도 대기 → 영원히 블록 */
    do_second_part();
}

/* ✅ 올바른 패턴: 2단계 work로 분리 */
static void phase1_work(struct work_struct *work)
{
    struct my_device *dev = container_of(work, struct my_device, work1);
    do_first_part();
    queue_work(my_wq, &dev->work2);  /* 2단계 work 큐잉 */
}

static void phase2_work(struct work_struct *work)
{
    struct my_device *dev = container_of(work, struct my_device, work2);
    do_second_part();  /* phase1 완료 후 자연스럽게 실행됨 */
}

/* ✅ 또는: flush_work()로 특정 work만 대기 (자기 자신 제외) */
static void my_work_func_fixed(struct work_struct *work)
{
    struct my_device *dev = container_of(work, struct my_device, work);
    flush_work(&dev->other_work);  /* ✅ 다른 work는 flush 가능 */
    do_combined_work();
}

버그 4: 교차 Flush 데드락 (A↔B)

/* ❌ 잘못된 코드: 두 workqueue 간 교차 flush → 데드락 */

/* work_a의 콜백 (wq_a에서 실행) */
static void work_a_func(struct work_struct *work)
{
    flush_workqueue(wq_b);  /* wq_b 완료 대기 */
}

/* work_b의 콜백 (wq_b에서 실행) */
static void work_b_func(struct work_struct *work)
{
    flush_workqueue(wq_a);  /* wq_a 완료 대기 → 데드락! */
}

/*
 * 시나리오:
 * CPU 0: work_a 실행 → flush_workqueue(wq_b) → wq_b 완료 대기
 * CPU 1: work_b 실행 → flush_workqueue(wq_a) → wq_a 완료 대기
 * → 서로 대기 → 교착
 *
 * CONFIG_LOCKDEP=y 에서 탐지됨:
 * ============================================
 * WARNING: possible recursive locking detected
 * ============================================
 */

/* ✅ 올바른 패턴: flush 대신 completion 또는 단방향 의존성 */

버그 5: 초기화 전 큐잉 / 이중 초기화

/* ❌ 버그 5a: INIT_WORK 전에 schedule_work 호출 */
struct my_device *dev = kzalloc(sizeof(*dev), GFP_KERNEL);
schedule_work(&dev->work);  /* ❌ work.func == NULL → 미정의 동작 */
INIT_WORK(&dev->work, handler);  /* 너무 늦음! */

/* ❌ 버그 5b: 큐잉된 상태에서 INIT_WORK 재호출 */
schedule_work(&dev->work);
/* ... work가 아직 pending 상태 ... */
INIT_WORK(&dev->work, new_handler);  /* ❌ 큐잉 상태 리셋 → 이중 큐잉 가능 */

/* ✅ 올바른 순서 */
struct my_device *dev = kzalloc(sizeof(*dev), GFP_KERNEL);
INIT_WORK(&dev->work, handler);       /* 반드시 먼저 초기화 */
schedule_work(&dev->work);             /* 그 다음 큐잉 */

/* 핸들러 변경이 필요하면: cancel 후 재초기화 */
cancel_work_sync(&dev->work);
INIT_WORK(&dev->work, new_handler);   /* 안전하게 재초기화 */
schedule_work(&dev->work);

버그 6: Atomic 컨텍스트에서 Flush/Cancel_sync

/* ❌ 잘못된 코드: 인터럽트 핸들러에서 flush */
static irqreturn_t my_irq_handler(int irq, void *data)
{
    struct my_device *dev = data;
    cancel_work_sync(&dev->work);  /* ❌ 인터럽트 컨텍스트에서 슬립!
                                    * cancel_work_sync()는 work 완료까지 대기
                                    * → 인터럽트 컨텍스트에서 슬립 → BUG */
    schedule_work(&dev->work);
    return IRQ_HANDLED;
}

/* ✅ 올바른 코드: atomic에서는 cancel_work() (non-sync) 사용 */
static irqreturn_t my_irq_handler_fixed(int irq, void *data)
{
    struct my_device *dev = data;
    /* cancel_work(): 큐에서 제거 시도만, 대기하지 않음 */
    cancel_work(&dev->work);  /* ✅ non-blocking */
    schedule_work(&dev->work);
    return IRQ_HANDLED;
}

/*
 * flush/cancel API의 컨텍스트 제약:
 *
 * | API                    | Atomic ctx | Process ctx | Work 콜백 내 |
 * |------------------------|:----------:|:-----------:|:----------:|
 * | schedule_work()        |     ✅     |     ✅      |    ✅      |
 * | cancel_work()          |     ✅     |     ✅      |    ✅      |
 * | cancel_work_sync()     |     ❌     |     ✅      |    ⚠️      |
 * | flush_work()           |     ❌     |     ✅      |    ⚠️      |
 * | flush_workqueue()      |     ❌     |     ✅      |    ❌      |
 * | destroy_workqueue()    |     ❌     |     ✅      |    ❌      |
 *
 * ⚠️ = 자기 자신 외의 work에 대해서만 안전
 */

버그 7: Delayed Work 재무장(Re-arm) 경쟁

/* ❌ 잘못된 코드: 주기적 delayed work에서 cancel 누락 */
static void periodic_handler(struct work_struct *work)
{
    struct delayed_work *dwork = to_delayed_work(work);
    struct my_device *dev = container_of(dwork, struct my_device, dwork);

    do_periodic_check(dev);
    schedule_delayed_work(&dev->dwork, HZ);  /* 1초 후 재스케줄 */
}

static void bad_remove(struct my_device *dev)
{
    cancel_delayed_work(&dev->dwork);  /* ❌ non-sync!
        * 타이머가 이미 만료되어 work가 실행 중이면?
        * → cancel은 실패 (이미 실행 중)
        * → 실행 중인 work가 schedule_delayed_work() 재호출
        * → dev 해제 후에 다시 실행됨! */
    kfree(dev);
}

/* ✅ 올바른 코드: cancel_delayed_work_sync() 사용 */
static void good_remove(struct my_device *dev)
{
    /* 방법 1: sync 버전으로 실행 완료까지 대기 + 재무장 방지 플래그 */
    dev->shutting_down = true;  /* work 콜백에서 확인 */
    cancel_delayed_work_sync(&dev->dwork);
    kfree(dev);
}

/* 개선된 주기적 핸들러: shutdown 플래그 확인 */
static void periodic_handler_fixed(struct work_struct *work)
{
    struct delayed_work *dwork = to_delayed_work(work);
    struct my_device *dev = container_of(dwork, struct my_device, dwork);

    do_periodic_check(dev);
    if (!dev->shutting_down)
        schedule_delayed_work(&dev->dwork, HZ);
}

버그 탐지 도구

WQ_BH: Bottom Half Workqueue (6.9+)

Linux 6.9에서 도입된 WQ_BH 플래그는 workqueue를 softirq 컨텍스트에서 실행할 수 있게 만드는 혁신적 변경입니다. 이는 오랜 숙원이었던 tasklet/softirq 기반 Bottom Half 처리를 workqueue 프레임워크로 통합하기 위한 핵심 기반입니다.

도입 배경

기존 tasklet은 여러 구조적 문제가 있었습니다:

• 직렬화(Serialization) 제약: 같은 tasklet은 시스템 전체에서 하나만 실행 — 멀티코어 확장성 부족
• API 불일치: workqueue와 완전히 다른 API — 코드 유지보수 부담
• 취소/동기화 미비: cancel_work_sync() 같은 안전한 취소 메커니즘 부재
• PREEMPT_RT 문제: RT 커널에서 스레드화 시 예측 불가능한 지연

WQ_BH는 workqueue의 풍부한 API와 관리 인프라를 유지하면서도 softirq 수준의 낮은 지연을 제공합니다.

시스템 BH Workqueue

/* kernel/workqueue.c — 시스템 BH workqueue 선언 */
struct workqueue_struct *system_bh_wq __read_mostly;
struct workqueue_struct *system_bh_highpri_wq __read_mostly;
EXPORT_SYMBOL_GPL(system_bh_wq);
EXPORT_SYMBOL_GPL(system_bh_highpri_wq);

/* 초기화 — init_workqueues()에서 */
system_bh_wq = alloc_workqueue("events_bh", WQ_BH, 0);
system_bh_highpri_wq = alloc_workqueue("events_bh_highpri",
                                        WQ_BH | WQ_HIGHPRI, 0);

tasklet에서 WQ_BH로 마이그레이션

/* === 기존: tasklet 방식 === */
static void my_tasklet_handler(unsigned long data)
{
    struct my_device *dev = (struct my_device *)data;
    /* Bottom Half 처리 */
}
DECLARE_TASKLET(my_tasklet, my_tasklet_handler, 0);

/* IRQ 핸들러에서 */
tasklet_schedule(&my_tasklet);

/* === 변환: WQ_BH 방식 === */
static void my_bh_handler(struct work_struct *work)
{
    struct my_device *dev = container_of(work, struct my_device, bh_work);
    /* 동일한 Bottom Half 처리 */
}

/* 초기화에서 */
INIT_WORK(&dev->bh_work, my_bh_handler);

/* IRQ 핸들러에서 */
queue_work(system_bh_wq, &dev->bh_work);

WQ_BH 제약사항

Affinity Scope (6.5+)

Linux 6.5에서 도입된 Affinity Scope는 unbound workqueue의 worker가 실행될 CPU 범위를 세밀하게 제어하는 메커니즘입니다. 캐시(Cache) 지역성과 처리량(Throughput) 사이의 균형을 워크로드 특성에 맞춰 조절할 수 있습니다.

스코프 유형

API와 sysfs 인터페이스

/* 커널 API — alloc_workqueue()에서 affinity scope 지정 */
enum wq_affn_scope {
    WQ_AFFN_CPU,      /* 단일 CPU */
    WQ_AFFN_SMT,      /* SMT 형제 */
    WQ_AFFN_CACHE,    /* LLC 캐시 공유 */
    WQ_AFFN_NUMA,     /* NUMA 노드 */
    WQ_AFFN_SYSTEM,   /* 전체 시스템 */
    WQ_AFFN_DFL,      /* 기본값 (= cache) */
};

/* workqueue 생성 시 affn_scope 설정 (6.5+) */
struct workqueue_struct *wq;
wq = alloc_workqueue("my_wq", WQ_UNBOUND, 0);
/* 기본 scope는 WQ_AFFN_DFL (= cache) */

# sysfs를 통한 런타임 affinity scope 확인 및 변경
# (WQ_SYSFS 플래그가 설정된 workqueue만 가능)

# 현재 affinity scope 확인
cat /sys/devices/virtual/workqueue/writeback/affinity_scope
# 출력 예: cache

# affinity scope를 numa로 변경
echo numa > /sys/devices/virtual/workqueue/writeback/affinity_scope

# 시스템 전체 기본값 확인/변경
cat /sys/devices/virtual/workqueue/cpumask
# 0000ffff (16-CPU 시스템)

스코프별 성능 특성

cache (기본값, 권장)

LLC 캐시를 공유하는 CPU 그룹 내에서 work를 실행합니다. 대부분의 워크로드에서 좋은 균형을 제공합니다. 예를 들어 4-코어 CCX에서 work가 해당 CCX 내 코어로 분산됩니다.

numa

대규모 메모리 할당/접근 패턴에 적합합니다. NUMA 원격 접근 페널티를 회피하며, 대용량 파일 I/O나 페이지 캐시 작업에 적합합니다.

system

부하가 불균형할 때 전체 CPU에 분산합니다. 캐시 지역성을 포기하는 대신 최대 처리량을 확보합니다. 네트워크 패킷 처리, 병렬 암호화 등에 사용합니다.

cpu / smt

매우 작은 work item에서 캐시 오염을 최소화합니다. 처리량이 제한될 수 있으므로 신중하게 사용해야 합니다.

스코프별 성능 비교 (참고 수치)

다음은 대표적인 2-소켓 NUMA 서버(16코어/소켓, LLC 4개)에서의 스코프별 상대 성능입니다. 워크로드에 따라 최적 스코프가 달라지므로 반드시 실측이 필요합니다.

Unbound Workqueue NUMA 배치

Unbound workqueue는 특정 CPU에 바인딩되지 않는 worker pool을 사용합니다. NUMA 시스템에서 이 pool의 배치 정책은 성능에 중대한 영향을 미칩니다. CMWQ는 NUMA 노드별로 worker pool을 분리하여 메모리 지역성을 보장합니다.

NUMA 노드별 풀 할당 정책

/*
 * Unbound Worker Pool NUMA 배치:
 *
 * alloc_workqueue(WQ_UNBOUND) 호출 시:
 * 1. workqueue_attrs (nice, cpumask, affn_scope) 결정
 * 2. 각 NUMA 노드에 대해 wq_calc_node_cpumask() 호출
 * 3. 노드의 online CPU와 workqueue cpumask의 교집합 계산
 * 4. 교집합이 비어있으면 → wq_cpumask 전체를 사용 (fallback)
 * 5. 교집합이 있으면 → 해당 노드 전용 pool_workqueue 생성
 * 6. 같은 attrs를 가진 pool이 이미 존재하면 공유 (refcount 증가)
 */

/* kernel/workqueue.c — NUMA 노드별 cpumask 계산 */
static bool wq_calc_node_cpumask(
    const struct workqueue_attrs *attrs,
    int node, int cpu_going_down,
    cpumask_t *cpumask)
{
    /* 해당 NUMA 노드의 online CPU 마스크 */
    if (!cpumask_and(cpumask, cpumask_of_node(node),
                      attrs->cpumask))
        goto use_dfl;

    /* cpu_going_down 제외 (hotplug 처리) */
    if (cpu_going_down >= 0)
        cpumask_clear_cpu(cpu_going_down, cpumask);

    /* affinity scope에 따른 추가 필터링 (6.5+) */
    if (wq_affn_scope_valid(attrs->affn_scope))
        apply_affn_scope(cpumask, attrs);

    if (cpumask_empty(cpumask))
        goto use_dfl;

    return true;

use_dfl:
    cpumask_copy(cpumask, attrs->cpumask);
    return false;
}

WQ_UNBOUND + __WQ_ORDERED 상호작용

/*
 * Ordered Workqueue와 NUMA:
 *
 * alloc_ordered_workqueue()는 내부적으로:
 *   alloc_workqueue(name, WQ_UNBOUND | __WQ_ORDERED, 1)
 *
 * __WQ_ORDERED 워크큐는 NUMA 분산을 하지 않습니다:
 * - max_active = 1 → 항상 하나의 work만 실행
 * - 단일 pool_workqueue만 사용 (NUMA 노드별 분리 없음)
 * - 순서 보장이 NUMA 지역성보다 중요
 *
 * 주의: ordered + NUMA 최적화가 필요하면
 *       직접 per-node ordered workqueue를 생성해야 함
 */
struct workqueue_struct *ordered_wq;
ordered_wq = alloc_ordered_workqueue("my_ordered", 0);
/* 내부: WQ_UNBOUND | __WQ_ORDERED, max_active=1 */

대규모 NUMA 시스템 최적화

# 4-NUMA 노드 시스템에서 unbound workqueue 최적화
# 각 NUMA 노드의 CPU 확인
lscpu | grep NUMA
# NUMA node0 CPU(s): 0-15
# NUMA node1 CPU(s): 16-31
# NUMA node2 CPU(s): 32-47
# NUMA node3 CPU(s): 48-63

# writeback workqueue의 affinity scope를 numa로 설정
echo numa > /sys/devices/virtual/workqueue/writeback/affinity_scope

# 특정 workqueue를 특정 NUMA 노드로 제한
echo 0000ffff > /sys/devices/virtual/workqueue/my_wq/cpumask
# Node 0 (CPU 0-15)에서만 실행

Worker Pool 내부 상세

worker_pool은 CMWQ의 실행 엔진입니다. 각 pool은 자체적으로 worker 스레드를 관리하며, 동시성 수준을 자동으로 조절합니다. 이 섹션에서는 pool의 내부 필드, worker 상태 전이, manager 역할을 상세히 분석합니다.

worker_pool 구조체 상세

/* kernel/workqueue.c — worker_pool 전체 필드 (v6.x) */
struct worker_pool {
    raw_spinlock_t lock;          /* pool 보호 잠금 */
    int cpu;                       /* bound pool: CPU 번호, unbound: -1 */
    int node;                      /* NUMA 노드 ID */
    int id;                        /* 풀 고유 ID (I: 열에 표시) */

    unsigned int flags;            /* POOL_MANAGER_ACTIVE 등 */

    struct list_head worklist;     /* 대기 중인 work_struct 리스트 */
    int nr_workers;                /* 전체 worker 수 */
    int nr_idle;                   /* idle worker 수 */

    /* 핵심: 동시성 관리 카운터 */
    int nr_running;                /* 현재 실행 중인 worker 수 */
                                    /* Bound pool: scheduler 콜백으로 정확히 추적 */
                                    /* nr_running == 0 && worklist 비어있지 않으면 */
                                    /* → 즉시 idle worker 깨움 또는 새 worker 생성 */

    struct list_head idle_list;    /* idle worker 리스트 (LRU 순서) */
    struct timer_list idle_timer;  /* 300초 후 idle worker 소멸 */
    struct timer_list mayday_timer;/* worker 생성 실패 시 재시도 */

    struct ida worker_ida;        /* worker ID 할당자 */
    struct workqueue_attrs *attrs; /* unbound: nice, cpumask, scope */
    struct hlist_node hash_node;  /* unbound pool 해시 테이블 */

    int refcnt;                    /* 참조 카운트 (공유 pool) */
    struct rcu_head rcu;           /* RCU 콜백 (안전 해제) */
};

Manager 역할: worker 생성과 소멸

/* kernel/workqueue.c — 간략화 */

/*
 * manage_workers() — Worker Pool의 핵심 관리 로직
 *
 * 호출 시점: worker_thread()에서 POOL_MANAGER_ACTIVE가 아닐 때
 * 관리자 역할을 맡은 worker가 실행
 *
 * 판단 기준:
 *   1. need_more_worker(): worklist 비어있지 않고 nr_running == 0
 *      → maybe_create_worker() 호출
 *   2. too_many_workers(): idle worker 과다
 *      → idle_timer에 의해 정리 (별도 타이머)
 */

static bool manage_workers(struct worker *worker)
{
    struct worker_pool *pool = worker->pool;

    if (pool->flags & POOL_MANAGER_ACTIVE)
        return false;

    pool->flags |= POOL_MANAGER_ACTIVE;

    /* worker 생성 필요 여부 판단 */
    maybe_create_worker(pool);

    pool->flags &= ~POOL_MANAGER_ACTIVE;
    return true;
}

static void maybe_create_worker(struct worker_pool *pool)
{
restart:
    /* nr_idle가 0이면 worker 생성 시도 */
    while (!may_start_working(pool)) {
        if (create_worker(pool) || !need_to_create_worker(pool))
            break;

        /* 생성 실패 — 잠시 후 재시도 */
        schedule_timeout_interruptible(CREATE_COOLDOWN);
        if (!need_to_create_worker(pool))
            break;
        goto restart;
    }
}

pool->lock contention 분석

pool->lock 경쟁 지점:

1. queue_work() → insert_work() — work 삽입 시
2. worker_thread() → process_one_work() — work 꺼내기 시
3. manage_workers() — worker 생성/소멸 판단 시
4. flush/cancel 경로 — 동기화 대기 시

경쟁 완화 설계:

• Bound pool: CPU별 독립 pool이므로 다른 CPU와 lock 경쟁이 없습니다.
• Unbound pool: 같은 NUMA 노드의 work가 같은 pool에 들어갑니다.
• try_to_grab_pending(): lock 없이 먼저 시도합니다 (낙관적 접근).

높은 contention 발생 시 대응 방법:

• unbound pool을 NUMA 노드별로 분리합니다 (affinity scope = numa).
• 커스텀 workqueue로 분리하여 pool 공유를 해소합니다.
• WQ_UNBOUND 대신 per-CPU workqueue를 고려합니다.

CPU Intensive Work

WQ_CPU_INTENSIVE 플래그가 설정된 workqueue에서 실행되는 work는 CMWQ 동시성 관리에서 특별 취급됩니다. 이 work가 오래 실행되어도 같은 pool의 다른 work 실행을 방해하지 않습니다.

동작 원리

/*
 * WQ_CPU_INTENSIVE 동작 원리:
 *
 * 일반 workqueue:
 *   - worker가 work 실행 시 pool->nr_running에 포함
 *   - nr_running > 0이면 새 worker를 깨우지 않음
 *   - 즉, 하나의 work가 오래 실행되면 다른 work 지연
 *
 * WQ_CPU_INTENSIVE:
 *   - worker가 work 실행 시작 시 nr_running에서 제외
 *   - pool->nr_running--; → 다른 work를 위한 worker 활성화 가능
 *   - work 완료 시 다시 nr_running++
 *
 * 즉, CPU-intensive work는 "보이지 않는 worker"가 되어
 * 다른 work의 실행을 블록하지 않습니다.
 */

/* kernel/workqueue.c — process_one_work() 내부 */
static void process_one_work(struct worker *worker,
                              struct work_struct *work)
{
    struct pool_workqueue *pwq = get_work_pwq(work);
    bool cpu_intensive = pwq->wq->flags & WQ_CPU_INTENSIVE;

    /* CPU-intensive: 동시성 카운터에서 제외 */
    if (cpu_intensive)
        worker_clr_flags(worker, WORKER_NOT_RUNNING);
        /* 이후 pool->nr_running은 이 worker를 세지 않음 */

    /* work 콜백 실행 */
    worker->current_func = work->func;
    worker->current_func(work);

    /* CPU-intensive: 다시 동시성 카운터에 포함 */
    if (cpu_intensive)
        worker_set_flags(worker, WORKER_NOT_RUNNING);
}

스케줄러(Scheduler) 연동: wq_worker_sleeping/running

/*
 * 스케줄러는 kworker 스레드가 슬립/깨어남을 workqueue에 알립니다.
 * 이를 통해 pool이 동시성 수준을 정확히 추적합니다.
 */

/* kernel/sched/core.c에서 호출 */
void wq_worker_sleeping(struct task_struct *task)
{
    struct worker *worker = kthread_data(task);
    struct worker_pool *pool = worker->pool;

    /* nr_running 감소 */
    if (atomic_dec_and_test(&pool->nr_running) &&
        !list_empty(&pool->worklist))
        /* nr_running이 0이 되면 idle worker 깨움 */
        wake_up_worker(pool);
}

void wq_worker_running(struct task_struct *task)
{
    struct worker *worker = kthread_data(task);

    if (!worker_test_flags(worker, WORKER_NOT_RUNNING))
        atomic_inc(&worker->pool->nr_running);
}

사용 사례

자동 CPU-Intensive 감지 (6.6+)

Linux 6.6부터 커널은 WQ_CPU_INTENSIVE 플래그가 설정되지 않은 workqueue에서도 콜백이 오래 실행되면 자동으로 CPU-intensive 상태로 전환합니다. 이 메커니즘은 cpu_intensive_thresh_us 파라미터로 제어됩니다.

/*
 * 자동 CPU-Intensive 감지 메커니즘 (kernel 6.6+):
 *
 * 동작 원리:
 * 1. worker가 process_one_work()에서 콜백 실행 시작
 * 2. 콜백 실행 시간이 cpu_intensive_thresh_us 초과 시
 * 3. 스케줄러 tick에서 wq_worker_tick() 콜백 호출
 * 4. 해당 worker를 자동으로 CPU-intensive로 전환
 * 5. pool->nr_running에서 제외 → 다른 work 처리 가능
 *
 * 설정:
 * /sys/module/workqueue/parameters/cpu_intensive_thresh_us
 * 기본값: 10000 (10ms)
 *
 * 0으로 설정하면 자동 감지 비활성화
 */

/* kernel/workqueue.c — wq_worker_tick() (스케줄러에서 호출) */
void wq_worker_tick(struct task_struct *task)
{
    struct worker *worker = kthread_data(task);
    struct pool_workqueue *pwq;

    if (!worker->current_func)
        return;  /* 콜백 실행 중이 아닌 경우 */

    pwq = worker->current_pwq;

    /* 이미 CPU-intensive 플래그가 설정된 경우 무시 */
    if (pwq->wq->flags & WQ_CPU_INTENSIVE)
        return;

    /* 실행 시간 확인: 임계값 초과 시 자동 전환 */
    if (worker_set_exec_deadline(worker)) {
        /* WORKER_CPU_INTENSIVE 설정 →
         * nr_running에서 제외 →
         * 다른 pending work를 위한 worker 활성화 */
        worker_set_flags(worker, WORKER_CPU_INTENSIVE);

        /* CONFIG_WQ_CPU_INTENSIVE_REPORT=y 시 경고 출력:
         * "workqueue: XXX [YYY] hogged CPU for >10000us N times,
         *  consider switching to WQ_CPU_INTENSIVE" */
    }
}

# 자동 CPU-intensive 감지 설정 (런타임)

# 현재 임계값 확인 (마이크로초)
cat /sys/module/workqueue/parameters/cpu_intensive_thresh_us
# 10000 (= 10ms 기본값)

# 임계값 변경: 5ms로 줄임 (더 적극적으로 감지)
echo 5000 > /sys/module/workqueue/parameters/cpu_intensive_thresh_us

# 비활성화: 0으로 설정
echo 0 > /sys/module/workqueue/parameters/cpu_intensive_thresh_us

# CONFIG_WQ_CPU_INTENSIVE_REPORT=y 빌드 시
# CPU-intensive로 자동 전환된 work function 확인:
dmesg | grep "hogged CPU"
# workqueue: writeback [wb_workfn] hogged CPU for >10000us 3 times,
#   consider switching to WQ_CPU_INTENSIVE

Workqueue 메모리 순서 보장

Workqueue는 work 큐잉부터 콜백 실행까지의 메모리 순서(Memory Ordering)를 보장합니다. 이 보장은 커널 개발자가 별도의 메모리 배리어(Memory Barrier) 없이도 안전하게 데이터를 공유할 수 있게 합니다.

보장 1: 큐잉 전 → 콜백 시작 (happens-before)

queue_work() 호출 전의 모든 메모리 쓰기는 콜백 함수 시작 시점에서 관찰 가능합니다. queue_work_on()의 test_and_set_bit()이 암시적 메모리 배리어를 제공하고, insert_work()의 wake_up_process()가 smp_wmb()를 포함하기 때문입니다.

보장 2: 콜백 완료 → flush/cancel 반환 (happens-before)

콜백 함수 내의 모든 메모리 쓰기는 flush_work()/cancel_work_sync() 반환 후 관찰 가능합니다. flush_work()의 wait_for_completion()이 smp_rmb()를 포함하기 때문입니다.

보장 3: ordered workqueue 순서

ordered workqueue에서 work A → work B 순서로 실행되면, A의 모든 메모리 쓰기는 B에서 관찰 가능합니다. 같은 worker 스레드에서 직렬 실행되므로 프로그램 순서(program order)가 보장됩니다.

/* 예시: 별도 배리어 없이 안전한 데이터 전달 */
struct data_transfer {
    struct work_struct work;
    char *buffer;       /* 큐잉 전 할당 */
    int length;
    int result;         /* 콜백에서 설정 */
};

/* 큐잉 측: 별도 smp_wmb() 불필요 */
static void submit_data(struct data_transfer *xfer,
                       const char *data, int len)
{
    xfer->buffer = kmemdup(data, len, GFP_KERNEL);
    xfer->length = len;
    /* queue_work()가 암시적 배리어를 제공하므로
     * buffer와 length가 콜백에서 보임을 보장 */
    queue_work(my_wq, &xfer->work);
}

/* 콜백: buffer/length가 최신값임을 보장 */
static void process_data(struct work_struct *work)
{
    struct data_transfer *xfer =
        container_of(work, struct data_transfer, work);

    /* xfer->buffer와 xfer->length는 최신값 보장 */
    xfer->result = do_transfer(xfer->buffer, xfer->length);
    kfree(xfer->buffer);
}

/* flush 측: result가 최신값임을 보장 */
static int wait_for_result(struct data_transfer *xfer)
{
    flush_work(&xfer->work);
    /* flush 반환 후 xfer->result가 최신값 보장 */
    return xfer->result;
}

메모리 압박/회수 경로에서의 Workqueue

WQ_MEM_RECLAIM 플래그는 메모리 회수 경로에서 workqueue가 데드락 없이 동작하도록 보장하는 핵심 메커니즘입니다. 이 플래그가 설정되면 workqueue에 전용 rescuer 스레드가 생성됩니다.

문제: 메모리 할당 실패와 데드락

메모리 압박 시나리오:

1. 블록 I/O writeback 경로가 work를 큐잉합니다.
2. work 실행을 위해 새 kworker 스레드가 필요합니다.
3. kthread_create()가 kmalloc()을 호출하지만 메모리가 부족합니다.
4. 메모리 회수를 위해 dirty 페이지 writeback이 필요합니다.
5. writeback은 work 실행에 의존하므로 데드락이 발생합니다.

해결: WQ_MEM_RECLAIM 플래그를 설정하면 rescuer 스레드가 생성됩니다. rescuer는 부팅 시 미리 생성되어 메모리 할당 없이 work를 처리할 수 있습니다.

rescuer_thread() 상세 동작

/* kernel/workqueue.c — rescuer 스레드 핵심 루프 */
static int rescuer_thread(void *__rescuer)
{
    struct worker *rescuer = __rescuer;
    struct workqueue_struct *wq = rescuer->rescue_wq;
    bool should_stop;

    set_user_nice(current, RESCUER_NICE_LEVEL); /* 높은 우선순위 */

repeat:
    set_current_state(TASK_IDLE);

    should_stop = kthread_should_stop();

    /* mayday 리스트 순회 */
    spin_lock_irq(&wq_mayday_lock);
    while (!list_empty(&wq->maydays)) {
        struct pool_workqueue *pwq;

        pwq = list_first_entry(&wq->maydays,
                                struct pool_workqueue, mayday_node);
        list_del_init(&pwq->mayday_node);
        spin_unlock_irq(&wq_mayday_lock);

        /* 해당 pool에 임시 합류하여 work 처리 */
        worker_attach_to_pool(rescuer, pwq->pool);
        process_scheduled_works(rescuer);
        worker_detach_from_pool(rescuer);

        spin_lock_irq(&wq_mayday_lock);
    }
    spin_unlock_irq(&wq_mayday_lock);

    if (should_stop)
        return 0;

    schedule();
    goto repeat;
}

실전 시나리오: 블록 I/O writeback

전력 관리와 Workqueue

Workqueue는 전력 관리(PM) 서브시스템과 밀접하게 상호작용합니다. suspend/resume 경로, CPU hotplug, idle 자원 회수까지 workqueue의 PM 통합 메커니즘을 상세히 분석합니다.

WQ_FREEZABLE: suspend 시 작업 동결

/* kernel/workqueue.c — 간략화 */

/*
 * WQ_FREEZABLE 워크큐:
 *
 * 시스템 suspend (pm_suspend) 시:
 * 1. freeze_workqueues_begin() 호출
 * 2. WQ_FREEZABLE 워크큐의 모든 pwq에 max_active = 0 설정
 * 3. 새 work는 큐잉되지만 실행되지 않음 (동결 상태)
 * 4. resume 시 thaw_workqueues() → max_active 복원 → 누적된 work 실행
 *
 * 사용 시점:
 * - suspend 중에 하드웨어 접근이 위험한 work
 * - 사용자 공간 의존 작업 (이미 frozen)
 * - 파일시스템 동기화 작업
 */

/* WQ_FREEZABLE workqueue 생성 예시 */
struct workqueue_struct *my_wq;
my_wq = alloc_workqueue("my_freezable",
                        WQ_FREEZABLE | WQ_MEM_RECLAIM, 0);

/* 시스템 제공 freezable workqueue */
extern struct workqueue_struct *system_freezable_wq;
extern struct workqueue_struct *system_freezable_power_efficient_wq;

wq_watchdog: worker pool 교착 감지

Workqueue Watchdog (CONFIG_WQ_WATCHDOG):

pool에 큐잉된 work가 지정 시간 이상 처리되지 않으면 경고를 출력합니다. 기본 임계값은 30초(workqueue.watchdog_thresh=30)입니다.

• 검사 주기: pool->watchdog_ts를 주기적으로 확인합니다.
• work가 완료되면 watchdog_ts를 갱신합니다.
• watchdog_ts가 임계값 이상 경과하면 BUG를 보고합니다.

출력 예시:

BUG: workqueue lockup - pool cpus=0 node=0 flags=0x0
     nice=0 stuck for 32s!

임계값 설정 방법:

• 부트 파라미터: workqueue.watchdog_thresh=60 (60초)
• 런타임: /sys/module/workqueue/parameters/watchdog_thresh

CPU Hotplug와 Worker 마이그레이션

/* kernel/workqueue.c — 간략화 */

/*
 * CPU Hotplug 시 Workqueue 동작 상세:
 *
 * CPU offline:
 * 1. workqueue_offline_cpu() 호출
 * 2. 해당 CPU의 bound pool에서 pending work를 unbound pool로 마이그레이션
 * 3. worker 스레드는 해당 CPU에서 unbind
 * 4. 진행 중인 work는 완료까지 허용 (drain)
 *
 * CPU online:
 * 1. workqueue_online_cpu() 호출
 * 2. bound pool 재활성화
 * 3. unbound pool의 cpumask 갱신 (새 CPU 포함)
 * 4. worker 스레드 재생성 (필요 시)
 *
 * 주의: ordered workqueue는 마이그레이션 중에도 순서 보장
 */

/* CPU hotplug 콜백 등록 (커널 내부) */
static int workqueue_prepare_cpu(unsigned int cpu);
static int workqueue_online_cpu(unsigned int cpu);
static int workqueue_offline_cpu(unsigned int cpu);

/* 드라이버에서 CPU hotplug를 고려한 workqueue 사용 패턴 */
static void my_work_handler(struct work_struct *work)
{
    int cpu = smp_processor_id();
    /* bound workqueue: 이 함수가 실행되는 CPU가 바뀔 수 있음!
     * CPU offline → drain → 다른 CPU에서 재실행 가능
     * Per-CPU 데이터 접근 시 주의 필요 */
    pr_debug("running on CPU %d\n", cpu);
}

/* CPU 고정이 필요한 경우: unbound WQ + cpumask 제어 */
struct workqueue_struct *pinned_wq;
pinned_wq = alloc_workqueue("pinned", WQ_UNBOUND | WQ_SYSFS, 0);
/* sysfs에서 cpumask 설정:
 * echo 0f > /sys/devices/virtual/workqueue/pinned/cpumask
 * → CPU 0-3에서만 실행 */

WQ_POWER_EFFICIENT 플래그

/*
 * WQ_POWER_EFFICIENT:
 *
 * workqueue.power_efficient 커널 파라미터가 활성화되면:
 *   WQ_POWER_EFFICIENT 워크큐 → WQ_UNBOUND로 동작
 *   → 스케줄러가 idle CPU를 깨우지 않고 busy CPU에서 실행
 *   → CPU가 C-state에 머물 수 있어 전력 절약
 *
 * 커널 cmdline: workqueue.power_efficient=1
 * (또는 CONFIG_WQ_POWER_EFFICIENT_DEFAULT=y)
 *
 * 주의: 지연 시간이 증가할 수 있음 (busy CPU 대기)
 */
struct workqueue_struct *pe_wq;
pe_wq = alloc_workqueue("my_pe_wq",
                        WQ_POWER_EFFICIENT | WQ_MEM_RECLAIM, 0);

/* 시스템 제공 power-efficient workqueue */
extern struct workqueue_struct *system_power_efficient_wq;

sysfs 인터페이스 상세

WQ_SYSFS 플래그가 설정된 workqueue는 /sys/devices/virtual/workqueue/ 아래에 디렉터리를 노출합니다. 이를 통해 운영 중인 시스템에서 workqueue 파라미터를 동적으로 조정할 수 있습니다.

디렉터리 구조

# WQ_SYSFS 플래그가 설정된 workqueue만 노출됨
ls /sys/devices/virtual/workqueue/
# writeback  events_power_efficient  crypto  ...

# 각 workqueue 디렉터리의 파일들
ls /sys/devices/virtual/workqueue/writeback/
# affinity_scope  cpumask  max_active  nice  numa  per_cpu  power  uevent

per-workqueue 설정 파라미터

운영 환경 동적 튜닝 사례

# 사례 1: writeback workqueue의 동시성 제한
# SSD에서 과도한 writeback으로 인한 I/O 폭주 방지
echo 8 > /sys/devices/virtual/workqueue/writeback/max_active
# 기본값 256 → 8로 제한

# 사례 2: 특정 workqueue를 특정 CPU 그룹에 격리
# CPU 0-3은 앱 전용, CPU 4-7은 커널 work 전용
echo f0 > /sys/devices/virtual/workqueue/writeback/cpumask
# 0xf0 = CPU 4-7

# 사례 3: workqueue worker 우선순위 조정
# 백그라운드 정리 작업의 우선순위를 낮춤
echo 10 > /sys/devices/virtual/workqueue/events_power_efficient/nice

# 사례 4: 전체 상태 확인 스크립트
for wq in /sys/devices/virtual/workqueue/*/; do
    name=$(basename "$wq")
    max=$(cat "$wq/max_active" 2>/dev/null)
    nice=$(cat "$wq/nice" 2>/dev/null)
    scope=$(cat "$wq/affinity_scope" 2>/dev/null)
    echo "$name: max_active=$max nice=$nice scope=$scope"
done

debugfs 디버그 정보

# /sys/kernel/debug/workqueue (CONFIG_DEBUG_WQ 필요)
# 모든 workqueue의 내부 상태 덤프

mount -t debugfs none /sys/kernel/debug 2>/dev/null
cat /sys/kernel/debug/workqueue

# 출력 예시:
# workqueue     flags  dfl  act  max
# writeback       U      8    8  256
# events          —    256  256  256
# events_highpri  H    256  256  256
# events_bh       B      0    0    0

Workqueue 트레이싱

workqueue 관련 문제 진단에는 다양한 트레이싱 도구를 활용할 수 있습니다. tracepoint, ftrace, perf, BPF 기반 분석까지 체계적으로 살펴봅니다.

Workqueue Tracepoint

# 사용 가능한 workqueue tracepoint 확인
ls /sys/kernel/debug/tracing/events/workqueue/
# workqueue_activate_work
# workqueue_execute_end
# workqueue_execute_start
# workqueue_queue_work

# 모든 workqueue 이벤트 활성화
echo 1 > /sys/kernel/debug/tracing/events/workqueue/enable
cat /sys/kernel/debug/tracing/trace_pipe

# 출력 예시:
#  kworker/0:1-28  workqueue_execute_start: work struct ffff8881234 function flush_to_ldisc
#  kworker/0:1-28  workqueue_execute_end:   work struct ffff8881234 function flush_to_ldisc

ftrace로 work function 실행 시간 측정

# function_graph 트레이서로 특정 work function 추적
cd /sys/kernel/debug/tracing

# function_graph 트레이서 설정
echo function_graph > current_tracer

# 특정 함수만 추적 (예: writeback 관련)
echo wb_workfn > set_graph_function

# 추적 시작
echo 1 > tracing_on
# ... (writeback 발생 대기) ...
echo 0 > tracing_on

cat trace
# 출력 예시:
#  3)               |  wb_workfn() {
#  3)   0.245 us    |    wb_do_writeback();
#  3)   0.890 us    |  }

BPF 기반 workqueue 지연 분석

/* bpftrace 원라이너: work 큐잉~실행 지연 히스토그램 */
/* bpftrace -e '
tracepoint:workqueue:workqueue_queue_work {
    @start[args->work] = nsecs;
}
tracepoint:workqueue:workqueue_execute_start {
    if (@start[args->work]) {
        @latency_us = hist((nsecs - @start[args->work]) / 1000);
        delete(@start[args->work]);
    }
}
END { clear(@start); }
' */

/* bpftrace: 가장 오래 실행되는 work function Top 10 */
/* bpftrace -e '
tracepoint:workqueue:workqueue_execute_start {
    @start[tid] = nsecs;
    @func[tid] = args->function;
}
tracepoint:workqueue:workqueue_execute_end {
    if (@start[tid]) {
        @duration[ksym(@func[tid])] =
            hist((nsecs - @start[tid]) / 1000);
        delete(@start[tid]);
        delete(@func[tid]);
    }
}
' */

/proc/workqueues 해석 가이드

# 실시간 workqueue 상태 확인
cat /proc/workqueues

# 출력 형식:
#  CPU  POOL  NICE  FLAGS  IDLE  ACT  REF  NAME
#    0     0     0      -     2    0    4  events
#    0     1   -20      -     1    0    3  events_highpri
#    *     4     0      U     3    0    8  writeback

# 필드 설명:
# CPU: 숫자=bound, *=unbound
# POOL: worker_pool ID
# NICE: 스레드 우선순위 (-20=highpri, 0=normal)
# FLAGS: U=unbound, H=highpri, B=bh
# IDLE: idle worker 수
# ACT: active (실행 중) work 수
# REF: 참조 카운트

실전 디버깅: kworker CPU 100%

# 문제: kworker/0:1이 CPU 100% 점유
# 원인 진단 절차:

# 1. 어떤 kworker가 문제인지 확인
top -b -n1 | grep kworker
# PID  USER  PR  NI  %CPU  COMMAND
# 1234 root  20   0  99.8  kworker/0:1

# 2. 해당 kworker가 실행 중인 함수 확인
cat /proc/1234/stack
# 또는
echo l > /proc/sysrq-trigger  # 모든 CPU의 backtrace

# 3. ftrace로 해당 worker의 실행 함수 추적
echo 1 > /sys/kernel/debug/tracing/events/workqueue/workqueue_execute_start/enable
echo "common_pid == 1234" > /sys/kernel/debug/tracing/events/workqueue/workqueue_execute_start/filter
cat /sys/kernel/debug/tracing/trace_pipe
# 어떤 work function이 반복 실행되는지 확인

# 4. perf로 함수별 CPU 사용량 프로파일링
perf top -p 1234 -g
# 또는 record + report
perf record -p 1234 -g -- sleep 5
perf report

커널 설정 총정리

Workqueue 관련 커널 설정은 빌드 시(Kconfig)와 런타임(커널 파라미터/sysfs)으로 나뉩니다. 프로덕션 환경에서의 권장 설정을 포함하여 정리합니다.

빌드 시 설정 (Kconfig)

런타임 설정 (커널 파라미터)

sysfs 런타임 조정

# watchdog 임계값 변경 (런타임)
echo 60 > /sys/module/workqueue/parameters/watchdog_thresh

# 시스템 전체 unbound workqueue cpumask
cat /sys/module/workqueue/parameters/cpu_intensive_thresh_us
# CPU-intensive 판단 임계값 (마이크로초)

# per-workqueue 파라미터 (WQ_SYSFS인 경우)
echo 16 > /sys/devices/virtual/workqueue/writeback/max_active
echo cache > /sys/devices/virtual/workqueue/writeback/affinity_scope

프로덕션 환경 권장 설정 체크리스트

# 프로덕션 서버 초기화 스크립트 예시
#!/bin/bash
# workqueue 프로덕션 튜닝

# watchdog 활성화
echo 30 > /sys/module/workqueue/parameters/watchdog_thresh

# NUMA 서버: writeback을 numa scope로
if [ -d /sys/devices/virtual/workqueue/writeback ]; then
    echo numa > /sys/devices/virtual/workqueue/writeback/affinity_scope 2>/dev/null
fi

# 모든 WQ_SYSFS workqueue 상태 로깅
for wq in /sys/devices/virtual/workqueue/*/; do
    name=$(basename "$wq")
    max=$(cat "$wq/max_active" 2>/dev/null || echo "N/A")
    logger "workqueue $name: max_active=$max"
done

핵심 함수 구현 분석

Workqueue의 동작을 완전히 이해하려면 세 가지 핵심 함수의 구현을 알아야 합니다: work를 큐에 넣는 __queue_work(), worker가 work를 꺼내 실행하는 process_one_work(), 그리고 worker 스레드의 메인 루프인 worker_thread()입니다. 이 섹션에서는 kernel/workqueue.c의 실제 구현을 기반으로 각 함수의 동작을 분석합니다.

__queue_work() 구현 분석

__queue_work()는 모든 work 큐잉 API(queue_work(), schedule_work() 등)의 최종 진입점입니다. 이 함수가 work를 적절한 worker pool에 삽입하고 worker를 깨우는 과정을 분석합니다.

/*
 * kernel/workqueue.c — __queue_work() 핵심 경로 분석 (v6.x 기준)
 *
 * 호출 체인: queue_work() → queue_work_on() → __queue_work()
 */
static void __queue_work(int cpu, struct workqueue_struct *wq,
                         struct work_struct *work)
{
    struct pool_workqueue *pwq;
    struct worker_pool *last_pool, *pool;
    unsigned int work_flags;
    unsigned int req_cpu = cpu;

    /*
     * 1단계: 이미 PENDING이면 즉시 반환 (중복 큐잉 방지)
     *
     * 호출자인 queue_work_on()에서 이미 test_and_set_bit으로
     * WORK_STRUCT_PENDING을 확인함. 여기서는 WARN으로 이중 체크
     */
    WARN_ON_ONCE(!irqs_disabled());

    /*
     * 2단계: work가 이전에 속했던 pool 확인 (hot path 최적화)
     *
     * work→data에 저장된 이전 pool_id로 last_pool을 조회.
     * 같은 CPU의 같은 pool이면 lock 재획득 없이 직접 삽입 가능.
     * 이는 같은 work가 반복 큐잉되는 패턴에서 성능을 향상시킴.
     */
    last_pool = get_work_pool(work);
    if (last_pool && last_pool != pwq->pool) {
        struct worker *worker;

        raw_spin_lock(&last_pool->lock);
        worker = find_worker_executing_work(last_pool, work);

        if (worker && worker->current_pwq->wq == wq) {
            /* 같은 WQ의 worker가 이 work를 실행 중
             * → 해당 pool에 재큐잉하여 직렬화 보장 */
            pwq = worker->current_pwq;
        }
        raw_spin_unlock(&last_pool->lock);
    }

    /*
     * 3단계: 목표 pool 결정 및 lock 획득
     *
     * Bound WQ: cpu_to_node(cpu)로 해당 CPU의 pool 선택
     * Unbound WQ: wq→numa_pwq_tbl[node]로 NUMA 노드 pool 선택
     */
    if (!(wq->flags & WQ_UNBOUND)) {
        if (req_cpu == WORK_CPU_UNBOUND)
            cpu = raw_smp_processor_id();
        pwq = per_cpu_ptr(wq->cpu_pwq, cpu);
    } else {
        pwq = unbound_pwq_by_node(wq, cpu_to_node(cpu));
    }

    pool = pwq->pool;
    raw_spin_lock(&pool->lock);

    /*
     * 4단계: max_active 체크 후 삽입 또는 보류
     *
     * pwq→nr_active < pwq→max_active 이면 즉시 worklist에 삽입.
     * 초과하면 inactive_works에 보류하여 나중에 activate.
     * ordered workqueue(max_active=1)에서 순서를 보장하는 핵심 메커니즘.
     */
    if (likely(pwq->nr_active < pwq->max_active)) {
        pwq->nr_active++;
        insert_work(pwq, work, &pool->worklist, work_flags);
    } else {
        list_add_tail(&work->entry, &pwq->inactive_works);
    }

    raw_spin_unlock(&pool->lock);
}

insert_work() 구현 분석

/*
 * kernel/workqueue.c — insert_work()
 * work를 pool의 worklist에 삽입하고 idle worker를 깨우는 함수
 */
static void insert_work(struct pool_workqueue *pwq,
                        struct work_struct *work,
                        struct list_head *head,
                        unsigned int extra_flags)
{
    /* work→data에 pwq 포인터와 color 정보 기록
     * 이 정보로 나중에 flush/cancel 시 work의 소속을 추적 */
    set_work_pwq(work, pwq, extra_flags);

    /* worklist에 삽입 (tail: FIFO 순서 보장) */
    list_add_tail(&work->entry, head);

    /* 유휴 worker가 있으면 깨워서 work 처리를 시작
     * wake_up_worker()는 idle_list의 첫 번째 worker를 깨움 */
    if (__need_more_worker(pool))
        wake_up_worker(pool);
}

/* __need_more_worker(): worklist가 비어있지 않고 실행 중인 worker가 없으면 true
 * 이 조건은 bound pool의 동시성 관리 핵심:
 * "항상 최소 1개의 worker가 실행 중이어야 합니다" */
static bool __need_more_worker(struct worker_pool *pool)
{
    return !list_empty(&pool->worklist) && !pool->nr_running;
}

process_one_work() 구현 분석

process_one_work()는 worker가 worklist에서 work를 하나 꺼내 실행하는 핵심 함수입니다. work 실행 전후의 상태 관리, 동시성 추적, flush 지원을 모두 이 함수에서 처리합니다.

/*
 * kernel/workqueue.c — process_one_work() 핵심 경로
 * worker가 work를 하나 꺼내 실행하는 함수
 */
static void process_one_work(struct worker *worker,
                             struct work_struct *work)
{
    struct pool_workqueue *pwq = get_work_pwq(work);
    struct worker_pool *pool = worker->pool;
    unsigned long irq_flags;

    /*
     * 1단계: busy_hash에 등록
     *
     * hash key = work 주소
     * flush_work()와 cancel_work_sync()가
     * 실행 중인 work를 찾을 때 busy_hash를 검색함
     */
    hash_add(pool->busy_hash, &worker->hentry,
             (unsigned long)work);

    /* 현재 실행 정보 기록 */
    worker->current_work = work;
    worker->current_func = work->func;
    worker->current_pwq = pwq;

    /*
     * 2단계: PENDING 비트 클리어 + pool→lock 해제
     *
     * 핵심 설계: PENDING을 클리어함으로써
     * "이 work는 이제 실행 중이지 pending이 아니다"를 표시.
     * 이 시점에서 같은 work를 다시 queue_work()하면
     * PENDING이 set되어 콜백 완료 후 재실행됨.
     *
     * pool→lock을 해제해야 콜백에서 블로킹 가능!
     */
    set_work_pool_and_clear_pending(work, pool->id);
    raw_spin_unlock_irq(&pool->lock);

    /*
     * 3단계: lockdep 주석 + 콜백 실행
     *
     * lock_map_acquire: lockdep이 work 콜백을 "잠금"으로 취급
     * → flush_work()가 이 "잠금"을 대기하므로
     * → 데드락 감지가 가능해짐
     */
    lock_map_acquire(&pwq->wq->lockdep_map);
    lock_map_acquire(&lockdep_map);

    /* 실제 콜백 실행 — 이곳이 사용자 코드 진입점 */
    trace_workqueue_execute_start(work);
    worker->current_func(work);
    trace_workqueue_execute_end(work, worker->current_func);

    lock_map_release(&lockdep_map);
    lock_map_release(&pwq->wq->lockdep_map);

    /*
     * 4단계: 정리 — pool→lock 재획득
     *
     * current_work = NULL로 설정하여 "실행 완료" 표시
     * busy_hash에서 제거
     * pwq_dec_nr_in_flight()로 nr_active 감소 + 대기 work 활성화
     */
    raw_spin_lock_irq(&pool->lock);

    hash_del(&worker->hentry);
    worker->current_work = NULL;
    worker->current_func = NULL;
    worker->current_pwq = NULL;

    /* nr_active 감소, inactive_works에서 다음 work 활성화 */
    pwq_dec_nr_in_flight(pwq, work_data);
}

worker_thread() 메인 루프 구현 분석

worker_thread()는 모든 kworker 스레드의 진입점입니다. 이 함수의 무한 루프가 work를 꺼내 실행하고, 유휴 시 슬립하며, 동시성을 관리하는 전체 흐름을 담당합니다.

/*
 * kernel/workqueue.c — worker_thread() 메인 루프
 * 모든 kworker 스레드가 실행하는 함수
 */
static int worker_thread(void *__worker)
{
    struct worker *worker = __worker;
    struct worker_pool *pool = worker->pool;

    /* PF_WQ_WORKER 설정 → 스케줄러가 이 태스크를 특별 취급
     * wq_worker_sleeping()/wq_worker_running() 콜백 활성화 */
    worker->task->flags |= PF_WQ_WORKER;

woke_up:
    raw_spin_lock_irq(&pool->lock);

    /* worker가 소멸 대상이면 정리 후 종료 */
    if (unlikely(worker->flags & WORKER_DIE)) {
        raw_spin_unlock_irq(&pool->lock);
        worker->task->flags &= ~PF_WQ_WORKER;
        return 0;
    }

    /* idle 상태에서 벗어남 */
    worker_leave_idle(worker);

recheck:
    /*
     * 핵심 루프: worklist가 비어있지 않으면 계속 처리
     *
     * need_more_worker()가 false인 경우:
     *   - worklist가 비어있거나
     *   - 다른 worker가 이미 실행 중 (nr_running > 0)
     *   둘 중 하나이면 이 worker는 작업할 필요 없음
     *
     * keep_working()이 true인 동안:
     *   - worklist에 work가 있고
     *   - 충분한 idle worker가 있으면 계속 처리
     */
    if (!need_more_worker(pool))
        goto sleep;

    /* manager 역할 확인: worker 생성이 필요하면 관리 수행 */
    if (unlikely(!may_start_working(pool)) &&
        manage_workers(worker))
        goto recheck;

    /*
     * work 처리 루프
     *
     * worklist에서 work를 하나씩 꺼내 process_one_work() 실행.
     * keep_working() 조건: worklist가 비어있지 않고
     * idle worker가 충분하면 계속 처리.
     * 이는 하나의 worker가 여러 work를 연속 처리하여
     * 컨텍스트 스위칭 오버헤드를 줄이는 최적화.
     */
    do {
        struct work_struct *work =
            list_first_entry(&pool->worklist,
                struct work_struct, entry);

        if (likely(!(*work_data_bits(work) & WORK_STRUCT_LINKED)))
            process_one_work(worker, work);
        else
            process_scheduled_works(worker);
    } while (keep_working(pool));

    /* CPU intensive work 여부 체크 (자동 감지) */
    worker->last_active = jiffies;

sleep:
    /*
     * 슬립 진입: idle 상태로 전환
     *
     * worker_enter_idle()가 idle_list에 추가하고
     * idle_timer를 설정 (300초 후 소멸 검사).
     * schedule()로 슬립하며, 새 work가 큐잉되면
     * insert_work()의 wake_up_worker()로 깨어남.
     */
    worker_enter_idle(worker);
    __set_current_state(TASK_IDLE);
    raw_spin_unlock_irq(&pool->lock);
    schedule();
    goto woke_up;
}

wq_worker_sleeping() / wq_worker_running(): 동시성 추적

CMWQ 동시성 관리의 비밀은 스케줄러 콜백에 있습니다. worker가 슬립하거나 깨어날 때 스케줄러가 이 콜백을 호출하여 pool->nr_running을 실시간으로 추적합니다.

/*
 * kernel/workqueue.c — 스케줄러 연동 콜백
 *
 * 이 두 함수가 CMWQ 동시성 관리의 핵심:
 * worker가 슬립(mutex_lock, msleep 등)하면 nr_running이 감소하고,
 * 0이 되면 대기 중인 work를 처리할 worker가 없으므로
 * 즉시 다른 idle worker를 깨움
 */

/* worker가 슬립할 때 스케줄러가 호출 (schedule() 직전) */
void wq_worker_sleeping(struct task_struct *task)
{
    struct worker *worker = kthread_data(task);
    struct worker_pool *pool;

    if (worker->flags & WORKER_NOT_RUNNING)
        return;  /* CPU_INTENSIVE work는 제외 */

    pool = worker->pool;

    /* nr_running 감소: 실행 중인 worker 하나 줄어듦 */
    if (atomic_dec_and_test(&pool->nr_running) &&
        !list_empty(&pool->worklist)) {
        /*
         * nr_running이 0이 되었고 worklist에 work가 있음
         * → 다른 idle worker를 즉시 깨워야 함
         *
         * 이것이 CMWQ의 핵심 동시성 보장:
         * "항상 최소 1개의 running worker가 있어야 합니다"
         */
        wake_up_worker(pool);
    }
}

/* worker가 깨어날 때 스케줄러가 호출 */
void wq_worker_running(struct task_struct *task)
{
    struct worker *worker = kthread_data(task);

    if (!(worker->flags & WORKER_NOT_RUNNING))
        atomic_inc(&worker->pool->nr_running);
}

try_to_grab_pending(): cancel 경로 구현

/*
 * kernel/workqueue.c — try_to_grab_pending()
 * cancel_work_sync()의 핵심 헬퍼
 *
 * work가 pending(큐에 대기 중)이면 직접 꺼내오고,
 * running(실행 중)이면 완료 대기를 위한 준비를 수행
 */
static int try_to_grab_pending(struct work_struct *work,
                               bool is_dwork,
                               unsigned long *irq_flags)
{
    struct worker_pool *pool;

    local_irq_save(*irq_flags);

    /* Fast path: PENDING 비트를 직접 클리어 시도
     * 성공하면 work가 아직 worklist에만 있었던 것
     * → 리스트에서 제거하면 취소 완료 */
    if (!test_and_set_bit(WORK_STRUCT_PENDING_BIT,
                          work_data_bits(work))) {
        /* work가 idle 상태였음 → grab 성공 (사실상 no-op) */
        return 0;
    }

    /* work가 pending 또는 running — pool을 찾아야 함 */
    pool = get_work_pool(work);
    if (!pool)
        goto fail;

    raw_spin_lock(&pool->lock);

    /* worklist에 있으면 (pending) 직접 제거 */
    if (*work_data_bits(work) & WORK_STRUCT_PENDING) {
        list_del_init(&work->entry);
        /* pwq→nr_active 감소 + inactive work 활성화 */
        pwq_dec_nr_in_flight(get_work_pwq(work),
                            *work_data_bits(work));

        /* PENDING 비트는 유지 — 호출자가 클리어
         * grab 성공: 1 반환 */
        raw_spin_unlock(&pool->lock);
        return 1;
    }

    /* running 상태 — 완료 대기가 필요
     * -EAGAIN 반환 → 호출자(cancel_work_sync)가
     * flush_work()로 완료 대기 */
    raw_spin_unlock(&pool->lock);
fail:
    local_irq_restore(*irq_flags);
    return -EAGAIN;
}

실전 구현 예시

다양한 시나리오에서 workqueue를 활용하는 실전 패턴을 분석합니다. 각 예시는 실제 커널 드라이버에서 사용되는 검증된 패턴을 기반으로 합니다.

예시 1: 네트워크 드라이버 — 링크 상태 변화 처리

네트워크 드라이버에서 PHY 링크 상태 변화는 인터럽트로 감지하지만, 실제 처리(미디어 타입 변경, 속도 협상, 상위 스택 알림)는 프로세스 컨텍스트가 필요합니다. Workqueue는 이 패턴에 적합합니다.

#include <linux/netdevice.h>
#include <linux/workqueue.h>
#include <linux/phy.h>

struct my_netdev_priv {
    struct net_device *ndev;
    struct work_struct link_work;       /* 링크 변화 처리 */
    struct delayed_work stats_work;     /* 주기적 통계 수집 */
    struct workqueue_struct *wq;
    spinlock_t hw_lock;                  /* 하드웨어 레지스터 보호 */
    void __iomem *regs;
    bool running;
    unsigned int link_status;
};

/* 링크 상태 변화 work 콜백 — 프로세스 컨텍스트 */
static void my_link_work_handler(struct work_struct *work)
{
    struct my_netdev_priv *priv =
        container_of(work, struct my_netdev_priv, link_work);
    struct net_device *ndev = priv->ndev;
    unsigned int status;

    /* 프로세스 컨텍스트이므로 mutex 획득, I2C 접근 가능 */
    rtnl_lock();

    /* PHY 상태 읽기 (MDIO 버스 접근 — 슬립 가능) */
    status = phy_read_status(ndev->phydev);

    if (priv->link_status != status) {
        priv->link_status = status;

        if (status & BMSR_LSTATUS) {
            /* 링크 업: MAC 설정 변경 (속도/듀플렉스) */
            my_configure_mac(priv, ndev->phydev->speed,
                            ndev->phydev->duplex);
            netif_carrier_on(ndev);
            netdev_info(ndev, "link up %dMbps %s-duplex\n",
                       ndev->phydev->speed,
                       ndev->phydev->duplex ? "full" : "half");
        } else {
            netif_carrier_off(ndev);
            netdev_info(ndev, "link down\n");
        }
    }

    rtnl_unlock();
}

/* 주기적 통계 수집 — delayed work 재큐잉 패턴 */
static void my_stats_work_handler(struct work_struct *work)
{
    struct delayed_work *dwork = to_delayed_work(work);
    struct my_netdev_priv *priv =
        container_of(dwork, struct my_netdev_priv, stats_work);
    unsigned long flags;

    /* 하드웨어 통계 카운터 읽기 */
    spin_lock_irqsave(&priv->hw_lock, flags);
    priv->ndev->stats.rx_packets += readl(priv->regs + RX_PKT_CNT);
    priv->ndev->stats.tx_packets += readl(priv->regs + TX_PKT_CNT);
    priv->ndev->stats.rx_errors  += readl(priv->regs + RX_ERR_CNT);
    /* 하드웨어 카운터는 읽으면 자동 클리어 (Read-to-Clear) */
    spin_unlock_irqrestore(&priv->hw_lock, flags);

    /* 동작 중이면 재스케줄 */
    if (priv->running)
        queue_delayed_work(priv->wq, dwork,
            msecs_to_jiffies(1000));
}

/* PHY 인터럽트 핸들러 (top half) */
static irqreturn_t my_phy_irq(int irq, void *data)
{
    struct my_netdev_priv *priv = data;

    /* 인터럽트 ACK (atomic 컨텍스트 — MMIO만 가능) */
    writel(PHY_IRQ_CLEAR, priv->regs + PHY_IRQ_STATUS);

    /* 프로세스 컨텍스트로 지연 처리 */
    queue_work(priv->wq, &priv->link_work);
    return IRQ_HANDLED;
}

/* ndo_open: 인터페이스 활성화 시 work 시작 */
static int my_ndo_open(struct net_device *ndev)
{
    struct my_netdev_priv *priv = netdev_priv(ndev);

    priv->running = true;

    /* 통계 수집 시작: 1초 후 첫 실행 */
    queue_delayed_work(priv->wq, &priv->stats_work,
        msecs_to_jiffies(1000));

    netif_start_queue(ndev);
    return 0;
}

/* ndo_stop: 인터페이스 비활성화 시 정리 */
static int my_ndo_stop(struct net_device *ndev)
{
    struct my_netdev_priv *priv = netdev_priv(ndev);

    netif_stop_queue(ndev);

    /* 재큐잉 중단 플래그 */
    priv->running = false;

    /* 실행 중인 work 완료 대기 */
    cancel_work_sync(&priv->link_work);
    cancel_delayed_work_sync(&priv->stats_work);

    return 0;
}

/* 프로브: 초기화 */
static int my_probe(struct pci_dev *pdev,
                   const struct pci_device_id *id)
{
    struct net_device *ndev;
    struct my_netdev_priv *priv;

    ndev = alloc_etherdev(sizeof(*priv));
    priv = netdev_priv(ndev);
    priv->ndev = ndev;

    /* WQ_MEM_RECLAIM: 네트워크 I/O가 메모리 회수에 필요할 수 있음
     * max_active=0 → 기본값 256 */
    priv->wq = alloc_workqueue("my_net_%s",
        WQ_MEM_RECLAIM, 0, pci_name(pdev));
    if (!priv->wq) {
        free_netdev(ndev);
        return -ENOMEM;
    }

    INIT_WORK(&priv->link_work, my_link_work_handler);
    INIT_DELAYED_WORK(&priv->stats_work, my_stats_work_handler);
    spin_lock_init(&priv->hw_lock);

    /* ... PCI 리소스, PHY 설정, register_netdev 등 ... */
    return 0;
}

예시 2: 비동기 프로브(Async Probe) 패턴

디바이스 프로브(probe)에서 펌웨어(Firmware) 로딩, I2C 센서 캘리브레이션 등 시간이 오래 걸리는 작업이 있을 때, workqueue를 활용한 비동기 프로브로 부팅 시간을 단축할 수 있습니다.

#include <linux/platform_device.h>
#include <linux/firmware.h>
#include <linux/workqueue.h>
#include <linux/completion.h>

struct my_sensor {
    struct device *dev;
    struct work_struct fw_load_work;
    struct completion fw_ready;
    const struct firmware *fw;
    void __iomem *regs;
    bool fw_loaded;
    int fw_error;
};

/* 비동기 펌웨어 로딩 work */
static void my_fw_load_work(struct work_struct *work)
{
    struct my_sensor *sensor =
        container_of(work, struct my_sensor, fw_load_work);
    int ret;

    /* request_firmware()는 슬립 가능 — 프로세스 컨텍스트 필수
     * 파일시스템 접근, 유저스페이스 헬퍼 호출 가능 */
    ret = request_firmware(&sensor->fw,
                          "my_sensor_v2.bin", sensor->dev);
    if (ret) {
        dev_err(sensor->dev,
               "firmware load failed: %d\n", ret);
        sensor->fw_error = ret;
        complete(&sensor->fw_ready);
        return;
    }

    /* 펌웨어를 하드웨어에 업로드 */
    my_upload_firmware(sensor, sensor->fw);
    release_firmware(sensor->fw);

    sensor->fw_loaded = true;
    dev_info(sensor->dev, "firmware loaded successfully\n");

    /* 대기 중인 코드(open 등)에 완료 알림 */
    complete(&sensor->fw_ready);
}

/* 프로브: 빠르게 반환하고 펌웨어 로딩은 비동기로 */
static int my_sensor_probe(struct platform_device *pdev)
{
    struct my_sensor *sensor;

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

    sensor->dev = &pdev->dev;

    /* 하드웨어 리소스 매핑 */
    sensor->regs = devm_platform_ioremap_resource(pdev, 0);
    if (IS_ERR(sensor->regs))
        return PTR_ERR(sensor->regs);

    init_completion(&sensor->fw_ready);
    INIT_WORK(&sensor->fw_load_work, my_fw_load_work);

    /* system_unbound_wq: CPU에 고정되지 않은 long-running 작업에 적합
     * 펌웨어 로딩은 수 초 소요될 수 있으므로 unbound가 적절 */
    queue_work(system_unbound_wq, &sensor->fw_load_work);

    platform_set_drvdata(pdev, sensor);

    /* 프로브 즉시 반환 → 다른 디바이스 프로브 진행 가능 */
    return 0;
}

/* 파일 오퍼레이션: 펌웨어 로딩 완료 후에만 사용 가능 */
static int my_sensor_open(struct inode *inode, struct file *file)
{
    struct my_sensor *sensor = /* ... */;

    /* 펌웨어 로딩 완료 대기 (최대 10초) */
    if (!wait_for_completion_timeout(&sensor->fw_ready,
            msecs_to_jiffies(10000))) {
        return -ETIMEDOUT;
    }

    if (sensor->fw_error)
        return sensor->fw_error;

    return 0;
}

static void my_sensor_remove(struct platform_device *pdev)
{
    struct my_sensor *sensor = platform_get_drvdata(pdev);

    /* 펌웨어 로딩이 진행 중이면 완료 대기 */
    cancel_work_sync(&sensor->fw_load_work);
}

예시 3: Work 배칭(Batching) 패턴

짧은 간격으로 반복되는 이벤트를 매번 처리하면 오버헤드가 큽니다. delayed_work를 활용하여 여러 이벤트를 하나의 work 실행으로 묶는(batch) 패턴을 구현할 수 있습니다.

#include <linux/workqueue.h>
#include <linux/atomic.h>

struct event_batcher {
    struct delayed_work batch_work;
    atomic_t pending_count;        /* 누적된 이벤트 수 */
    unsigned long batch_events[64]; /* 이벤트 비트맵 */
    spinlock_t lock;
    struct device *dev;
};

/* 배치 처리 콜백 — 누적된 이벤트를 한 번에 처리 */
static void batch_work_handler(struct work_struct *work)
{
    struct delayed_work *dwork = to_delayed_work(work);
    struct event_batcher *batcher =
        container_of(dwork, struct event_batcher, batch_work);
    unsigned long events[64];
    int count;

    /* 이벤트 스냅샷 획득 후 클리어 */
    spin_lock_bh(&batcher->lock);
    memcpy(events, batcher->batch_events, sizeof(events));
    memset(batcher->batch_events, 0, sizeof(batcher->batch_events));
    count = atomic_xchg(&batcher->pending_count, 0);
    spin_unlock_bh(&batcher->lock);

    if (count == 0)
        return;

    dev_dbg(batcher->dev,
           "processing batch: %d events\n", count);

    /* 비트맵에서 설정된 이벤트를 순회하며 처리 */
    for (int i = 0; i < 64; i++) {
        if (events[i])
            process_events_for_channel(batcher, i, events[i]);
    }
}

/* 이벤트 발생 시 호출 (인터럽트/atomic 컨텍스트 가능) */
static void batcher_notify_event(struct event_batcher *batcher,
                                int channel, int event_bit)
{
    unsigned long flags;

    /* 이벤트 기록: 비트맵에 누적 */
    spin_lock_irqsave(&batcher->lock, flags);
    set_bit(event_bit, &batcher->batch_events[channel]);
    spin_unlock_irqrestore(&batcher->lock, flags);

    atomic_inc(&batcher->pending_count);

    /* 10ms 디바운스(debounce): 이미 예약된 work가 있으면 무시
     * → 마지막 이벤트로부터 10ms 내 모든 이벤트가 배치됨
     *
     * mod_delayed_work()는 이미 예약된 타이머를 재설정하므로
     * "마지막 이벤트 + 10ms" 시점에 실행됨 */
    mod_delayed_work(system_wq, &batcher->batch_work,
                     msecs_to_jiffies(10));
}

/* 초기화 */
static void batcher_init(struct event_batcher *batcher,
                        struct device *dev)
{
    INIT_DELAYED_WORK(&batcher->batch_work, batch_work_handler);
    atomic_set(&batcher->pending_count, 0);
    spin_lock_init(&batcher->lock);
    batcher->dev = dev;
}

/* 정리 */
static void batcher_destroy(struct event_batcher *batcher)
{
    cancel_delayed_work_sync(&batcher->batch_work);
}

예시 4: Ordered Workqueue — 상태 머신 구현

순서가 중요한 작업(트랜잭션 로그 기록, 상태 전이 등)은 alloc_ordered_workqueue()로 생성한 ordered workqueue를 사용합니다. max_active=1로 동시 실행을 방지하여 별도의 동기화 없이 순서를 보장합니다.

#include <linux/workqueue.h>

/* 상태 머신 예: 디바이스 전원 상태 전이 */
enum power_state {
    POWER_OFF,
    POWER_STANDBY,
    POWER_ON,
    POWER_ERROR,
};

struct power_manager {
    struct workqueue_struct *state_wq;  /* ordered: 순차 실행 */
    enum power_state current_state;
    struct device *dev;
    void __iomem *regs;
};

/* 상태 전이 요청을 캡슐화하는 구조체 */
struct state_transition {
    struct work_struct work;
    struct power_manager *pm;
    enum power_state target;
    void (*callback)(int result, void *ctx);
    void *callback_ctx;
};

/* 상태 전이 work 콜백
 * ordered WQ에서 실행 → 동시에 하나만 실행됨
 * → current_state 접근에 별도 lock 불필요 */
static void state_transition_work(struct work_struct *work)
{
    struct state_transition *trans =
        container_of(work, struct state_transition, work);
    struct power_manager *pm = trans->pm;
    int ret = 0;

    dev_dbg(pm->dev, "state transition: %d → %d\n",
           pm->current_state, trans->target);

    /* 전이 유효성 검증 */
    if (!is_valid_transition(pm->current_state, trans->target)) {
        dev_warn(pm->dev, "invalid transition: %d → %d\n",
                pm->current_state, trans->target);
        ret = -EINVAL;
        goto out;
    }

    /* 하드웨어 상태 전이 수행 — 슬립 가능 */
    switch (trans->target) {
    case POWER_ON:
        ret = hw_power_on_sequence(pm);  /* msleep, regulator 등 */
        break;
    case POWER_STANDBY:
        ret = hw_enter_standby(pm);
        break;
    case POWER_OFF:
        hw_power_off(pm);
        break;
    default:
        ret = -EINVAL;
    }

    if (ret == 0)
        pm->current_state = trans->target;
    else
        pm->current_state = POWER_ERROR;

out:
    /* 완료 콜백 호출 (선택적) */
    if (trans->callback)
        trans->callback(ret, trans->callback_ctx);

    /* 동적 할당된 전이 요청 해제 */
    kfree(trans);
}

/* 비동기 상태 전이 요청 — IRQ 컨텍스트에서도 호출 가능 */
static int power_request_transition(struct power_manager *pm,
                                   enum power_state target,
                                   void (*cb)(int, void *),
                                   void *ctx)
{
    struct state_transition *trans;

    /* GFP_ATOMIC: 인터럽트 컨텍스트 가능 */
    trans = kmalloc(sizeof(*trans), GFP_ATOMIC);
    if (!trans)
        return -ENOMEM;

    trans->pm = pm;
    trans->target = target;
    trans->callback = cb;
    trans->callback_ctx = ctx;
    INIT_WORK(&trans->work, state_transition_work);

    /* ordered WQ: 큐잉 순서대로 하나씩 실행됨 */
    queue_work(pm->state_wq, &trans->work);
    return 0;
}

/* 초기화 */
static int power_manager_init(struct power_manager *pm,
                             struct device *dev)
{
    pm->dev = dev;
    pm->current_state = POWER_OFF;

    /* alloc_ordered_workqueue: max_active=1
     * → 상태 전이가 큐잉 순서대로 직렬화됨
     * WQ_MEM_RECLAIM: 메모리 부족 시에도 전이 보장 */
    pm->state_wq = alloc_ordered_workqueue("pm_state_%s",
        WQ_MEM_RECLAIM, dev_name(dev));
    if (!pm->state_wq)
        return -ENOMEM;

    return 0;
}

/* 해제 */
static void power_manager_destroy(struct power_manager *pm)
{
    /* drain: 큐에 남아있는 모든 전이 완료 후 파괴 */
    destroy_workqueue(pm->state_wq);
}

예시 5: devm 자동 정리 패턴

devm(Device-managed Resource) API와 workqueue를 함께 사용하면, 디바이스 제거 시 자동으로 workqueue를 정리할 수 있습니다. 수동 cleanup 코드의 실수를 줄이는 방어적 패턴입니다.

#include <linux/device.h>
#include <linux/workqueue.h>

/* devm으로 work_struct 자동 cancel을 위한 래퍼 */
struct devm_work_ctx {
    struct work_struct *work;
    struct delayed_work *dwork;
    struct workqueue_struct *wq;
};

/* devm 해제 액션: 디바이스 제거 시 자동 호출 */
static void devm_work_release(void *data)
{
    struct devm_work_ctx *ctx = data;

    /* work 정리 */
    if (ctx->dwork)
        cancel_delayed_work_sync(ctx->dwork);
    if (ctx->work)
        cancel_work_sync(ctx->work);
}

static void devm_wq_release(void *data)
{
    struct devm_work_ctx *ctx = data;

    if (ctx->wq)
        destroy_workqueue(ctx->wq);
}

/* devm work 등록 헬퍼: 디바이스 제거 시 자동 cancel */
static int devm_work_register(struct device *dev,
                             struct work_struct *work,
                             work_func_t func)
{
    struct devm_work_ctx *ctx;

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

    INIT_WORK(work, func);
    ctx->work = work;

    return devm_add_action_or_reset(dev, devm_work_release, ctx);
}

/* 사용 예시: 프로브에서 work 등록, 별도 cleanup 불필요 */
static int my_simple_probe(struct platform_device *pdev)
{
    struct my_device *dev;
    int ret;

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

    /* devm으로 work 등록 → remove에서 cancel 불필요 */
    ret = devm_work_register(&pdev->dev, &dev->event_work,
                            my_event_handler);
    if (ret)
        return ret;

    /* ... 나머지 초기화 ... */

    return 0;

    /* remove 함수에서 cancel_work_sync() 호출 불필요!
     * devm이 디바이스 제거 시 자동으로 처리
     *
     * 주의: devm action 순서는 등록 역순이므로,
     * work가 접근하는 리소스보다 work 해제가 먼저 실행됨 */
}

예시 6: RCU + Workqueue 조합 패턴

RCU(Read-Copy-Update) grace period 대기는 슬립이 필요하므로 인터럽트 컨텍스트에서 직접 수행할 수 없습니다. call_rcu()와 workqueue를 조합하면 RCU 콜백에서 블로킹 작업을 안전하게 처리할 수 있습니다.

#include <linux/rcupdate.h>
#include <linux/workqueue.h>
#include <linux/slab.h>

struct my_entry {
    struct rcu_head rcu;
    struct work_struct free_work;
    struct hlist_node node;
    void *large_buffer;       /* vfree 필요 (슬립 가능) */
    struct file *backing_file; /* fput 필요 */
    char key[64];
};

/* work 콜백: 프로세스 컨텍스트에서 안전하게 해제
 * RCU grace period 이후에 실행됨이 보장됨 */
static void my_entry_free_work(struct work_struct *work)
{
    struct my_entry *entry =
        container_of(work, struct my_entry, free_work);

    /* 슬립 가능한 해제 작업 */
    vfree(entry->large_buffer);  /* vmalloc'd memory → 슬립 가능 */
    fput(entry->backing_file);   /* 파일 참조 해제 → 슬립 가능 */
    kfree(entry);
}

/* RCU 콜백: softirq 컨텍스트에서 호출됨 → 슬립 불가
 * work를 스케줄하여 프로세스 컨텍스트로 지연 */
static void my_entry_rcu_free(struct rcu_head *rcu)
{
    struct my_entry *entry =
        container_of(rcu, struct my_entry, rcu);

    /* RCU 콜백은 softirq → schedule_work로 지연 */
    INIT_WORK(&entry->free_work, my_entry_free_work);
    schedule_work(&entry->free_work);
}

/* 엔트리 삭제 (write-side) */
static void my_remove_entry(struct my_entry *entry)
{
    /* RCU 보호 하에 리스트에서 제거 */
    hlist_del_rcu(&entry->node);

    /* grace period 후 RCU 콜백 호출
     * → RCU 콜백에서 work 스케줄
     * → work에서 실제 메모리 해제 */
    call_rcu(&entry->rcu, my_entry_rcu_free);
}

/* 읽기 경로 (read-side, lock-free) */
static struct my_entry *my_lookup(const char *key)
{
    struct my_entry *entry;

    rcu_read_lock();
    hlist_for_each_entry_rcu(entry, &my_hash_table[hash], node) {
        if (strcmp(entry->key, key) == 0) {
            rcu_read_unlock();
            return entry;
        }
    }
    rcu_read_unlock();
    return NULL;
}

예시 7: 서브시스템 워크큐 — 블록 I/O flush 패턴

블록 디바이스 드라이버에서 디스크(Disk) 캐시 flush 작업은 잠재적으로 수 초가 소요됩니다. WQ_MEM_RECLAIM | WQ_UNBOUND 조합으로 메모리 압박 환경에서도 안전하게 동작하는 패턴을 구현합니다.

#include <linux/blkdev.h>
#include <linux/workqueue.h>

struct my_blk_device {
    struct gendisk *disk;
    struct workqueue_struct *flush_wq;
    struct work_struct flush_work;
    struct work_struct error_work;
    spinlock_t queue_lock;
    struct list_head pending_ios;
    atomic_t error_count;
    void __iomem *regs;
    bool removing;
};

/* 캐시 flush work — 수 초 소요 가능 */
static void my_flush_handler(struct work_struct *work)
{
    struct my_blk_device *bdev =
        container_of(work, struct my_blk_device, flush_work);
    struct list_head batch;
    unsigned long flags;

    INIT_LIST_HEAD(&batch);

    /* pending I/O를 로컬 리스트로 이동 (lock 최소화) */
    spin_lock_irqsave(&bdev->queue_lock, flags);
    list_splice_init(&bdev->pending_ios, &batch);
    spin_unlock_irqrestore(&bdev->queue_lock, flags);

    /* 하드웨어 flush 명령 (블로킹 — DMA 완료 대기) */
    writel(FLUSH_CMD, bdev->regs + CMD_REG);
    if (my_wait_for_completion(bdev, msecs_to_jiffies(5000))) {
        /* flush 완료 — pending I/O 완료 처리 */
        complete_pending_ios(&batch, 0);
    } else {
        /* 타임아웃 — 에러로 완료 */
        complete_pending_ios(&batch, -EIO);
        atomic_inc(&bdev->error_count);
        queue_work(bdev->flush_wq, &bdev->error_work);
    }
}

/* 에러 복구 work — 디바이스 리셋 + 재초기화 */
static void my_error_handler(struct work_struct *work)
{
    struct my_blk_device *bdev =
        container_of(work, struct my_blk_device, error_work);

    dev_err(disk_to_dev(bdev->disk),
           "device error, initiating reset (%d errors)\n",
           atomic_read(&bdev->error_count));

    /* 하드웨어 리셋 시퀀스 (msleep 포함) */
    my_hw_reset(bdev);
    my_hw_reinit(bdev);

    atomic_set(&bdev->error_count, 0);
}

/* 초기화 */
static int my_blk_init(struct my_blk_device *bdev)
{
    /* WQ_MEM_RECLAIM: 블록 I/O는 메모리 회수 경로의 핵심
     *   → 메모리 부족 시에도 flush가 완료되어야 회수 진행
     *   → rescuer 스레드가 forward progress 보장
     *
     * WQ_UNBOUND: flush는 수 초 소요 → bound pool에 간섭 방지
     *
     * max_active=2: flush + error 동시 처리 허용
     *   (일반적으로 flush 1개 + error 1개)  */
    bdev->flush_wq = alloc_workqueue("my_blk_flush",
        WQ_MEM_RECLAIM | WQ_UNBOUND, 2);
    if (!bdev->flush_wq)
        return -ENOMEM;

    INIT_WORK(&bdev->flush_work, my_flush_handler);
    INIT_WORK(&bdev->error_work, my_error_handler);
    spin_lock_init(&bdev->queue_lock);
    INIT_LIST_HEAD(&bdev->pending_ios);

    return 0;
}

/* 해제 */
static void my_blk_exit(struct my_blk_device *bdev)
{
    bdev->removing = true;

    /* 실행 중인 work 완료 대기 */
    cancel_work_sync(&bdev->flush_work);
    cancel_work_sync(&bdev->error_work);

    destroy_workqueue(bdev->flush_wq);
}

Work 비활성화 API (6.7+)

Linux 6.7에서 도입된 disable_work()/enable_work() API는 work를 일시적으로 비활성화하는 공식 메커니즘을 제공합니다. 이전에는 cancel_work_sync() + shutdown 플래그로 구현했던 패턴을 커널이 직접 지원합니다.

/* kernel/workqueue.c — 간략화 */

/*
 * disable_work() / enable_work() API (kernel 6.7+):
 *
 * disable_work_sync(&work):
 *   - work를 비활성화 상태로 전환
 *   - 실행 중인 콜백이 있으면 완료 대기 (sync)
 *   - 비활성화 상태에서 queue_work()를 호출해도 큐잉되지 않음
 *   - 중첩(nested) 가능: disable 횟수를 카운트
 *
 * enable_work(&work):
 *   - disable 카운터 감소
 *   - 카운터가 0이 되면 활성화 상태로 복귀
 *   - 비활성화 중 시도된 큐잉이 있으면 자동으로 큐잉됨
 *
 * disable_delayed_work_sync(&dwork):
 *   - delayed_work 버전: 타이머 + work 모두 비활성화
 *
 * enable_delayed_work(&dwork):
 *   - delayed_work 재활성화
 */

/* 사용 예시: suspend/resume에서 work 비활성화 */
struct my_device {
    struct work_struct event_work;
    struct delayed_work monitor_work;
};

static int my_suspend(struct device *dev)
{
    struct my_device *mydev = dev_get_drvdata(dev);

    /* 6.7+ 방식: 명시적 비활성화
     * - 실행 중인 콜백 완료 대기
     * - 이후 queue_work() 호출은 no-op
     * - enable 호출 시 자동 재활성화 */
    disable_work_sync(&mydev->event_work);
    disable_delayed_work_sync(&mydev->monitor_work);

    return 0;
}

static int my_resume(struct device *dev)
{
    struct my_device *mydev = dev_get_drvdata(dev);

    /* 재활성화: disable 중 큐잉 시도가 있었으면 자동 실행 */
    enable_work(&mydev->event_work);
    enable_delayed_work(&mydev->monitor_work);

    /* 모니터링 재개 */
    schedule_delayed_work(&mydev->monitor_work,
        msecs_to_jiffies(1000));

    return 0;
}

/*
 * disable_work_sync() vs cancel_work_sync() 비교:
 *
 * | 기능                    | cancel_work_sync | disable_work_sync |
 * |------------------------|:----------------:|:-----------------:|
 * | 실행 중 콜백 대기        |       ✅         |       ✅          |
 * | 향후 큐잉 차단          |       ❌         |       ✅          |
 * | 중첩(nested) 지원       |       ❌         |       ✅          |
 * | 복원(enable) API        |       ❌         |       ✅          |
 * | 비활성화 중 큐잉 보존    |       ❌         |       ✅          |
 *
 * cancel_work_sync(): 일회성 취소 → 재사용하려면 다시 queue_work()
 * disable_work_sync(): 일시 중단 → enable_work()로 복원
 */

참고자료

커널 공식 문서

• Concurrency Managed Workqueue (cmwq) — kernel.org — CMWQ 공식 설계 문서로, 워커 풀(Worker Pool) 아키텍처와 플래그(Flag) 의미를 설명합니다
• Workqueue API Reference — kernel.org — alloc_workqueue, queue_work, flush_workqueue 등 공식 API 레퍼런스입니다
• Workqueue Sysfs Interface — kernel.org — /sys/devices/virtual/workqueue/ 아래 sysfs 튜닝 인터페이스를 설명합니다

LWN.net 기사

• Concurrency-managed workqueues (LWN, 2010) — Tejun Heo가 설계한 CMWQ의 초기 제안과 동기를 다룬 핵심 기사입니다
• Working on workqueues (LWN, 2009) — 기존 워크큐의 문제점과 CMWQ 도입 배경을 정리한 기사입니다
• The workqueue API changes in 3.7 (LWN, 2012) — alloc_workqueue 플래그 변경 및 WQ_UNBOUND 개선 사항을 다룹니다
• Workqueue items of interest (LWN, 2016) — 워크큐 디버깅 개선과 watchdog 기능 추가를 다룬 기사입니다
• BH workqueues (LWN, 2023) — WQ_BH 플래그 도입으로 tasklet을 워크큐로 대체하는 방안을 소개합니다
• Workqueue affinity scopes (LWN, 2023) — Unbound 워크큐의 affinity_scope 매개변수와 NUMA 최적화를 설명합니다

커널 소스 코드

• kernel/workqueue.c — 워크큐 핵심 구현체로, worker_thread 루프와 풀 관리 로직이 포함되어 있습니다
• include/linux/workqueue.h — work_struct, delayed_work, workqueue_struct 등 핵심 자료 구조와 매크로 정의입니다
• kernel/workqueue_internal.h — worker, worker_pool 등 내부 자료 구조 정의입니다
• Documentation/core-api/workqueue.rst — 커널 소스 트리 내 CMWQ 문서 원본입니다

발표 및 컨퍼런스

• Tejun Heo — CMWQ Design Notes — CMWQ 설계자인 Tejun Heo의 원본 설계 문서입니다
• Kernel Recipes 2018 — Workqueue: Pair your work items! (Tejun Heo) — 워크큐 활용 패턴과 주의사항을 다룬 발표입니다

서적

• Linux Kernel Development, 3rd Edition (Robert Love, Addison-Wesley, 2010) — Chapter 8 "Bottom Halves and Deferring Work"에서 워크큐의 기본 개념과 사용법을 설명합니다
• Linux Device Drivers, 3rd Edition (Corbet, Rubini, Kroah-Hartman, O'Reilly, 2005) — Chapter 7 "Time, Delays, and Deferred Work"에서 워크큐 API를 다룹니다
• Understanding the Linux Kernel, 3rd Edition (Bovet & Cesati, O'Reilly, 2005) — Chapter 4 "Interrupts and Exceptions"에서 지연 처리 메커니즘을 설명합니다
• Professional Linux Kernel Architecture (Wolfgang Mauerer, Wrox, 2008) — 워크큐 내부 구현과 스케줄링 상호작용을 상세히 다룹니다
• Linux Kernel Networking: Implementation and Theory (Rami Rosen, Apress, 2014) — 네트워크 서브시스템에서의 워크큐 활용 사례를 포함합니다

블로그 및 튜토리얼

• EmbeTronicX — Workqueue in Linux Kernel — 워크큐 기본 사용법과 예제 코드를 단계별로 설명합니다
• Kernel Docs Mirror — Concurrency Managed Workqueue — kernel.org 문서의 미러 버전으로, 오프라인 참고에 유용합니다