Runtime Services · Zephyr 3.7.0 LTS3 · source + context diagram

Timer / Workqueue

타이머 만료와 work 실행은 서로 다른 사건이다. IRQ에서의 제출, 큐의 중복 합침, 스레드 handler와 지연 작업의 수명을 따라간다.

기준 버전: Zephyr 3.7.0 LTS3 형식: 원본 코드 + 문맥 그림 + 상태표 핵심: expiry 횟수 ≠ handler 실행 횟수

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

만료와 실행은 서로 다른 사건

k_timer는 커널의 시스템 클록을 이용해 시간을 잰다. 만료하면 상태 카운터를 올리고, 등록된 expiry callback이 있다면 시스템 클록 인터럽트 핸들러에서 호출한다. expiry callback이 k_work_submit() 또는 k_work_submit_to_queue()를 호출하는 예제에서만 work item이 큐로 넘어간다. work handler는 앞선 항목이 처리된 뒤 workqueue의 스레드에서 실행된다. 따라서 만료 시각과 작업 시작 시각은 같지 않다.

그림 1. expiry callback이 매번 같은 work item을 제출할 때: 세 번의 만료와 한 번의 handler 실행
시스템 클록 IRQ에서 타이머 만료가 세 번 발생해도 이미 queued인 같은 work item은 하나로 유지되고, 앞선 작업이 끝난 뒤 workqueue 스레드에서 handler가 한 번 실행되는 두 문맥 시간표

이 그림은 세 번 모두 expiry callback이 같은 item을 제출하고, 그동안 item이 queued 상태로 남는 조건이다. 같은 work item이 이미 큐에 있으면 다시 제출해도 항목이 늘지 않는다. 반대로 handler 실행 중 재제출하면 다음 실행이 큐에 잡힐 수 있다. 매 만료를 빠짐없이 세어야 한다면 work item 자체를 이벤트 카운터로 취급해서는 안 된다. 좁은 화면에서는 그림을 좌우로 스크롤한다.

읽을 때의 기준: timer expiry, work queued, work running을 각각 다른 사건으로 기록한다. 하나의 API가 다른 두 사건의 시각이나 횟수를 보장한다고 추정하지 않는다.

고정된 Zephyr 3.7.0 원본

API 계약은 3.7.0 Timers와 3.7.0 Workqueue Threads에서, 실행 순서는 아래 고정 커밋 원본에서 확인한다. 링크의 줄 번호는 GitHub의 1부터 시작하는 줄 번호다.

원본확인할 경계
timeout.c:210–259sys_clock_announce()가 만료 timeout의 callback을 호출한다.
timer.c:27–110주기 재예약 뒤 status 증가, expiry callback, status 대기 스레드 깨우기 순서다. 증가 줄은 status += 1U, 호출 줄은 expiry_fn(timer)다.
timer.c:139–181재시작 시 이전 timeout을 제거하고 status를 초기화한다.
timer.c:194–304stop callback은 k_timer_stop() 호출자의 문맥이며, status getter와 동기 대기의 소비 동작은 별개다.
work.c:327–430이미 queued인 제출은 추가하지 않는다. k_work_submit_to_queue()와 system queue wrapper를 비교한다.
work.c:616–716queue thread가 queued 플래그를 지우고 running을 세운 뒤 handler(work)를 호출한다.
work.c:833–854work_timeout()은 지연 만료 시 handler 실행이 아니라 item 제출을 시도한다.
work.c:942–1063schedule, unschedule, reschedule, 비동기 cancel 경로를 비교한다.

소스 링크는 모두 Zephyr v3.7.0 태그의 고정 커밋을 가리킨다. 다른 릴리스의 같은 함수명에 줄 번호와 상태 규칙을 그대로 대입하지 않는다.

원본의 세 사용 예와 호출 조건

아래 세 조각은 원문에서 유지한 설명용 사용 예다. 커널 구현을 그대로 발췌한 코드는 아니며, 첫 조각의 sample_expiry와 두 번째의 debounce_handler는 응용 코드에서 정의해야 한다.

1. periodic timer

설명용 예제 · 관련 API/설정: kernel/timer.c
K_TIMER_DEFINE(sample_timer, sample_expiry, NULL);

k_timer_start(&sample_timer, K_MSEC(10), K_MSEC(10));
라인별 설명
sample_expiry

timer expiry callback이다. 길게 실행하거나 sleep한다고 가정하면 안 된다.

first duration

첫 만료 시점이다.

period

반복 주기다. 처리 시간이 주기를 넘으면 system behavior를 따로 분석해야 한다.

2. delayed work

설명용 예제 · 관련 API/설정: kernel/work.c
K_WORK_DELAYABLE_DEFINE(debounce_work, debounce_handler);

k_work_schedule(&debounce_work, K_MSEC(30));
라인별 설명
delayable

timeout과 work item을 결합한 object다.

debounce

이 schedule 예제는 첫 입력 후 30 ms 예약을 유지한다. 뒤따른 입력으로 마감을 옮기려면 reschedule을 선택한다.

handler

workqueue thread context라서 제한은 줄지만 system workqueue 점유 시간을 관리해야 한다.

3. ISR에서 마지막 입력 기준으로 다시 예약

설명용 예제 · 관련 API/설정: kernel/work.c
void gpio_isr(void)
{
        k_work_reschedule(&debounce_work, K_MSEC(30));
}
라인별 설명
reschedule

아직 delayed인 timeout의 마감을 새 입력 기준으로 옮긴다. 이미 queued/running인 handler를 되돌리지는 않는다.

ISR

짧은 ISR과 thread context handler를 연결한다.

30ms

하드웨어 신호 특성에서 나온 값이어야 한다. 임의 값이면 latency와 noise trade-off가 흔들린다.

함께 써야 하는 짧은 callback: 타이머 자체가 work를 자동으로 제출하지 않는다.

static void sample_expiry(struct k_timer *timer)
{
    (void)timer;
    /* 시스템 클록 IRQ: 잠들지 않고, 제출 결과를 요구사항에 맞게 기록한다. */
    int rc = k_work_submit(&sample_work);
    /* rc == 0: 이미 queued, 1: 새 제출, 2: running 중 재제출 */
}

sample_work는 미리 K_WORK_DEFINE 또는 k_work_init()으로 초기화해야 한다. 이 조각은 관측점 설명을 위한 발췌이며 그 자체로 완성된 번역 단위가 아니다. 지정 큐를 쓰면 k_work_submit_to_queue(&queue, &sample_work)를 호출하고, 큐를 먼저 시작해야 한다.

timeout에서 handler까지 소스 추적

  1. kernel/timeout.c의 sys_clock_announce()에서 만료 callback 호출을 찾는다.
  2. kernel/timer.c에서 주기 재예약, status 증가, expiry callback 순서를 확인한다. expiry callback이 없으면 work 제출도 없다.
  3. 응용 expiry callback의 k_work_submit() 또는 k_work_submit_to_queue() 결과를 기록한다. 두 함수 모두 handler를 호출자 문맥에서 직접 실행하지 않는다.
  4. kernel/work.c의 큐 처리에서 queued → running 플래그 변화와 handler 호출을 확인한다.
  5. 지연 작업은 별도 경로다. work_timeout()이 work를 큐에 제출한 뒤 queue thread가 실행한다.

빌드별 클록 해상도, workqueue 우선순위, 시스템 큐 사용 여부는 실제 보드 설정에서 확인한다. 이 절의 소스 경로만으로 특정 지연 시간을 보장할 수 없다.

callback 문맥과 타이머 상태

어느 문맥에서 실행되는가

지점실행 문맥허용 범위와 주의점
k_timer expiry callback시스템 클록 인터럽트 핸들러블로킹 작업을 하지 않는다. 짧은 상태 갱신이나 ISR 호출 가능 API로 후속 작업을 넘긴다.
k_timer stop callbackk_timer_stop() 호출자 문맥ISR에서 stop할 수 있으므로 stop callback도 ISR 호출 가능하게 작성한다.
k_work_submit()ISR 또는 스레드에서 호출 가능작업을 시스템 workqueue에 제출한다. handler를 즉시, 호출자 문맥에서 실행하는 함수가 아니다.
work handlerworkqueue 스레드스레드용 커널 API를 쓸 수 있지만 오래 블로킹하면 같은 큐의 뒤 항목이 지연된다.
k_timer_status_sync(), 동기식 work 취소스레드 전용완료 또는 만료를 기다릴 수 있다. ISR에서 기다리는 API로 사용하지 않는다.

시스템 workqueue는 여러 작업이 공유할 수 있다. 별도 큐는 메모리 비용이 있으므로, 공유 큐에서 함께 실행하면 다른 항목의 지연이 허용 범위를 넘는 경우에 근거를 두고 만든다.

k_timer: 기간, 주기, 상태는 서로 다르다

k_timer_start(timer, duration, period)에서 duration은 첫 만료의 지연 요청값, period는 후속 만료의 주기 요청값이다. period가 K_NO_WAIT 또는 K_FOREVER이면 한 번만 만료되는 타이머가 된다. 요청값은 타이머 tick 정밀도와 정렬 규칙의 영향을 받는다. 특히 CONFIG_TIMEOUT_64BIT 주기 재예약은 지연된 callback의 실제 진입 시각이 아니라 예정된 만료 시각을 기준으로 한다. 따라서 callback 시작 시각 사이의 실측 간격을 매번 정확한 주기나 엄격한 최소 간격으로 보장하지 않는다. 주기 재예약과 초기 duration의 호환용 tick 보정을 구분한다.

동작상태 카운터대기 중 스레드와 callback
시작 또는 실행 중 다시 시작0으로 초기화duration != K_FOREVER이면 새 기간과 주기로 다시 센다. 재시작만으로 status_sync 대기가 끝나지는 않는다.
만료1 증가expiry callback을 실행하고 대기 스레드를 깨운다. 주기가 있으면 다음 주기를 시작한다.
실행 중 중지기존 값 유지활성 타이머라면 stop callback을 호출하고 대기 스레드를 깨운다. 이미 큐에 제출된 work까지 취소하지는 않는다.
k_timer_status_get()값을 읽은 뒤 0으로 초기화읽기 자체가 소비 동작이므로 같은 타이머의 status 독자는 하나로 정한다.
k_timer_status_sync()멀티스레드 구성에서는 반환 후 0으로 초기화status가 0이고 타이머가 활성일 때만 만료 또는 중지를 기다린다. 이미 status가 양수이거나 타이머가 비활성이면 기다리지 않는다. 반환값 0은 중지 경로일 수 있다.

상태 카운터는 마지막 상태 읽기 또는 타이머 재시작 이후의 만료 횟수다. work handler가 몇 번 실행됐는지 나타내는 카운터가 아니다. 상태를 직접 읽는 독자와 동기화해서 읽는 독자가 경쟁하면 서로의 관측값을 지우므로 한 소유자를 정한다.

k_timer_start()는 duration == K_FOREVER이면 기존 timeout이나 status를 바꾸지 않고 반환한다. CONFIG_MULTITHREADING이 꺼진 구성의 k_timer_status_sync() 내부 경로는 일반 스레드 대기 경로와 다르므로, 이 글의 대기·초기화 설명을 그대로 적용하기 전에 해당 빌드 구성을 확인한다.

중복 제출과 handler 데이터 소유권

work item: 큐에 있음과 실행 중임이 겹칠 수 있다

K_WORK_DEFINE 또는 k_work_init()으로 handler를 지정한 뒤 제출한다. 이미 queued인 같은 work item을 다시 제출하면 큐 안의 위치와 개수는 그대로다. running 중에는 재제출되어 다음 실행을 기다릴 수 있다. 따라서 상태를 idle → queued → running이라는 단선적인 전이로만 그리면 재제출과 취소 상황을 놓친다.

k_work_submit() 반환값을 읽는 법

값3.7.0에서의 의미호출자가 판단할 것
0이미 큐에 제출되어 있었다.이번 요청 때문에 실행 횟수가 추가되었다고 세지 않는다.
1새로 큐에 들어갔다.handler 시작 시각은 큐 부하와 우선순위에 달려 있다.
2실행 중이던 항목이 다시 큐에 들어갔다. 지정 큐가 달라도 재진입을 피하려고 실행 중인 큐를 쓴다.현재 실행과 다음 실행을 별개로 취급한다.
음수취소 중이거나 큐가 draining/plugged 상태인 등의 제출 거절.무시하면 사건이 조용히 사라질 수 있다.

k_work_busy_get()과 k_work_is_pending()은 그 순간의 스냅샷이다. “idle이면 제출”처럼 확인과 행동 사이의 경쟁을 만들지 않는다. 또 pending인 work item을 다시 초기화하거나, handler가 읽을 데이터를 완료 전에 바꾸지 않는다. 데이터 공유가 필요하면 별도 큐·카운터·잠금 같은 소유권 규칙을 세운다.

핸들러가 읽는 구조체와 work item은 마지막 실행이 끝날 때까지 유효해야 한다. ISR 또는 다른 스레드가 동일 데이터를 업데이트해야 한다면 atomic, lock 또는 별도 이벤트 큐로 보호한다. k_work_busy_get()은 순간 상태를 보여줄 뿐, 그 뒤 안전한 수정 권한을 예약하지 않는다.

만료 한 번마다 정확히 하나의 처리가 필요하면 같은 work item의 중복 제출에 의존하지 않는다. 독립 이벤트를 queue로 전달하거나 카운터를 명시적으로 관리한다. k_timer_status_get()도 읽을 때 카운터를 0으로 초기화하므로 status 독자 하나를 정한다.

상태는 서로 겹칠 수 있다

관찰 상태일으킨 사건다음에 가능한 사건
timer armedk_timer_start()만료 또는 stop. 재시작은 status를 초기화한다.
work delayedk_work_schedule()/reschedule()마감 시 queued로 제출 시도. 중간 reschedule은 아직 미완료인 timeout을 교체한다.
work queued직접 제출 또는 지연 만료같은 item 재제출은 추가되지 않는다. queue thread가 꺼내면 running.
work runningqueue thread가 handler 호출동일 item을 다시 queued 또는 delayed로 예약할 수 있어 상태가 겹친다.
canceling비동기/동기 취소 요청실행 중 handler가 이미 진행 중일 수 있다. 객체 해제 전 완료 동기화가 필요하다.

한 줄짜리 idle → queued → running 화살표는 동시에 running+queued가 될 수 있는 v3.7.0 상태를 표현하지 못한다.

취소와 완료 대기는 서로 다른 API

API호출 문맥반환 시점과 주의
k_work_cancel_delayable()ISR 또는 스레드예약·queued 상태 취소를 시도하지만 실행 중 handler가 끝나기를 기다리지는 않는다. 이후 새 reschedule도 막지 않는다.
k_work_cancel_delayable_sync()스레드실행 중 handler가 끝나고 취소가 완료되기를 기다린다. 추가 제출 생산자도 별도로 멈춰야 한다.
k_work_flush_delayable()스레드아직 delayed이면 즉시 큐에 제출하고 마지막 제출분의 완료를 기다린다. 원래 마감을 유지하는 대기가 아니다.

동기 API의 k_work_sync 객체는 호출이 끝날 때까지 유효해야 한다. CONFIG_KERNEL_COHERENCE를 쓰는 아키텍처에서는 coherent memory 요구사항도 확인한다. 같은 work의 handler 안에서 그 work를 flush하면 정의되지 않은 동작이 될 수 있다.

증상별 확인 경계

증상먼저 확인할 경계관찰할 것
타이머가 만료됐는데 handler가 보이지 않음expiry → submit → queuedexpiry 진입 횟수, submit 반환값, 동일 item이 이미 queued인지 기록한다.
work가 늦게 시작함queued → running앞선 handler 실행 시간, workqueue 스레드 우선순위와 다른 스레드 부하를 본다.
debounce가 너무 일찍 또는 늦게 반응함schedule/reschedule → queue첫 입력과 마지막 입력 시각, 제출 예정 시각, 이미 queued였는지 구분한다.
중지 후에도 작업이 실행됨timer stop과 work canceltimer 중지 이전에 work가 제출됐는지, 취소 뒤 실행 중인 handler가 남았는지 확인한다.
종료 중 비정기적으로 데이터가 바뀜async cancel → 완료 확인k_work_cancel()/k_work_cancel_delayable()만 호출했는지, 스레드에서 동기식 완료 확인을 했는지 본다.

비동기 취소는 이미 실행 중인 handler가 끝날 때까지 기다리지 않는다. 스레드에서 객체나 handler 데이터의 수명을 끝내야 한다면 k_work_cancel_sync() 또는 k_work_cancel_delayable_sync()로 완료를 동기화한다. k_work_flush_delayable()은 예약된 작업을 즉시 제출한 뒤 완료를 기다리므로, 원래의 지연을 유지하며 기다리는 수단으로 사용하지 않는다.

잘못된 경계 가정

  • timer expiry callback에서 sleep하거나 긴 I/O를 수행한다. 이 callback은 시스템 클록 인터럽트 문맥이다.
  • k_work_submit()을 매번 호출했다는 이유로 매 만료마다 handler가 실행됐다고 센다. queued 중 중복은 합쳐진다.
  • handler 데이터가 pending인 동안 바뀌거나, work 객체를 다시 초기화한다. 큐에 남아 있거나 running인 소유자를 먼저 종료한다.
  • k_work_reschedule()만으로 이미 queued/running인 이전 handler가 취소됐다고 가정한다.
  • k_timer_stop()으로 이미 큐에 넘어간 work까지 멈췄다고 가정한다.
  • 비동기 cancel 후 곧바로 handler 데이터나 work storage를 해제한다. 취소 자체는 실행 중 handler 완료를 기다리지 않는다.

Linux 비교의 범위

Linux의 timer/workqueue도 시간을 알리는 경로와 스레드에서 일을 수행하는 경로를 분리해 생각할 수 있다. 그러나 이 글의 k_timer_status_get() 소비 semantics, k_work_reschedule()의 queued item 처리, Zephyr workqueue 반환값은 Zephyr 3.7.0 계약이다. Linux API의 같은 이름·비슷한 그림에 그대로 대입하지 않는다.

비교할 때는 API 이름보다 각각의 callback 문맥, 중복 제출 규칙, 취소가 보장하는 완료 범위를 원문에서 다시 확인한다.

지연 작업: 첫 입력과 마지막 입력

지연 작업: 첫 이벤트 기준인가, 마지막 이벤트 기준인가

k_work_delayable은 지정한 지연 후 work item을 큐에 제출한다. 지연이 끝나는 시각은 handler의 시작 시각과 다르다. k_work_schedule()은 이미 예약된 항목은 마감을 유지하고 이미 제출된 항목에는 아무 일도 하지 않으며, k_work_reschedule()은 예약된 마감을 새 지연으로 바꾼다.

입력 이벤트와 30 ms 지연k_work_schedule()k_work_reschedule()
t=0 ms: 첫 이벤트t=30 ms 제출 예약t=30 ms 제출 예약
t=10 ms: 둘째 이벤트기존 t=30 ms 유지t=40 ms로 변경
t=20 ms: 셋째 이벤트기존 t=30 ms 유지t=50 ms로 변경
선택 기준첫 미처리 이벤트로부터 일정 시간 뒤 제출마지막 이벤트 후 조용한 시간이 지난 뒤 제출

이 표는 항목이 계속 scheduled 상태인 설명용 일정이다. 이미 큐에 제출된 항목을 k_work_reschedule()이 큐에서 빼내지는 않고, 실행 중인 handler도 중단하지 않는다. 따라서 엄격하게 “마지막 입력 이후 30 ms 이전에는 절대 처리하지 않는다”는 계약이 필요하면 handler 측 시각 확인이나 별도 동기화 정책까지 설계해야 한다.

K_NO_WAIT를 주면 미예약 항목은 직접 큐에 제출된다. k_work_schedule()은 기존 예약을 유지하지만 k_work_reschedule()은 예약을 변경한다. 기존 상태에 따라 반환값이 달라지므로, 지연 값을 바꾸는 함수 호출만으로 실행 완료를 뜻한다고 해석하지 않는다.

k_work_schedule_for_queue()와 k_work_reschedule_for_queue()는 지연 후 보낼 큐를 명시한다. 기본 wrapper는 시스템 workqueue를 대상으로 한다. 마감은 큐 제출 목표이고 handler 시작 기한이 아니다.

중지 뒤에도 handler가 보이는 사례

주기 타이머의 expiry callback이 sample_work를 제출했다. 직후 스레드가 k_timer_stop()을 호출했지만, queue thread가 이전에 제출된 item을 나중에 꺼내 handler를 실행한다. stop은 미래의 타이머 만료를 막는 동작이지 work queue에 들어간 item의 취소가 아니다.

종료할 때는 먼저 추가 제출 경로를 막고 timer를 중지한다. SMP에서는 이미 실행 중인 expiry callback과 생산자도 별도 동기화해야 한다. 이미 제출된 work는 요구사항에 따라 k_work_cancel_sync()로 취소 완료를 기다리거나 k_work_flush()로 처리 완료를 기다린 뒤, handler 데이터의 수명을 끝낸다. 동기 API는 스레드 문맥에서 호출하고, 같은 handler가 자기 자신을 기다리게 하지 않는다.

측정 전에 정할 계약

  • 매 expiry를 모두 처리해야 하는가, 가장 최근 상태 한 번만 처리해도 되는가?
  • 측정값은 expiry 시각, submit 반환값, queue 진입, handler 시작·종료로 나눌 것인가?
  • 정상 최대 큐 대기와 handler 실행 시간은 얼마이며, 시스템 workqueue 공유가 적절한가?
  • status 소비자가 하나인가? stop/restart 시 카운터가 어떤 구간을 나타내는가?
  • drain/plug 중 지연 work의 만료가 제출 실패할 때 어떻게 감지하고 복구할 것인가?

코드 리뷰의 다섯 질문

  1. 만료 callback과 stop callback이 각각 어떤 문맥에서 실행되며, 내부 호출이 그 문맥에 맞는가?
  2. 매 만료마다 별도 처리가 필요한가, 아니면 같은 work item의 제출이 합쳐져도 되는가?
  3. 첫 이벤트 기준 마감에는 schedule, 마지막 이벤트 기준 마감에는 reschedule을 의도적으로 선택했는가?
  4. work handler가 공유 시스템 큐를 오래 점유하거나 잠금 때문에 다른 항목을 지연시키지는 않는가?
  5. 타이머 중지, work 취소, handler 데이터 해제 순서에서 실행 중인 work가 모두 끝났음을 확인하는가?

계측 로그를 네 사건으로 나누기

관측 시점기록분리할 원인
expiry callback타임스탬프, timer status 관측 정책클록 지연과 callback 자체 지연
submit 반환0/1/2/음수, 대상 queue중복 합침 또는 제출 거절
handler 시작타임스탬프, 선행 항목 소요 시간큐 대기와 스레드 스케줄링
handler 종료타임스탬프, 공유 데이터 세대실행 시간과 다음 제출의 데이터 경쟁

ISR에서 무거운 로그를 찍어 타이밍을 바꾸지 않도록 작은 카운터·trace를 사용하고, ISR-safe 여부를 실험 보드의 설정에서 확인한다.

실험 기록 양식

원본 양식을 유지하고, timer와 work의 서로 다른 시각을 비교할 필드를 덧붙였다.

[실험 주제] Timer / Workqueue
[Zephyr 버전] Zephyr 3.7.0 LTS3
[보드/SoC]
[west manifest revision]
[관련 Kconfig]
[관련 devicetree node]
[관찰한 원본 코드]
[예상 상태 전이]
[실제 상태 전이]
[실패 시 return/log/assert]
[latency 또는 memory 측정값]
[다음 실험]
[expiry callback 진입 시각 / 횟수]
[submit 반환값 / queue 대상]
[handler 시작·종료 시각]
[cancel/flush 뒤 객체 소유권 확인]

이 글의 상태 용어

용어뜻
expiry callbackk_timer가 만료되어 시스템 클록 인터럽트 핸들러에서 호출하는 함수.
stop callback활성 timer를 k_timer_stop()으로 중지할 때 호출자 문맥에서 호출하는 함수.
delayed지연 work의 timeout이 걸려 있는 상태. handler 실행 상태가 아니다.
queuedworkqueue에서 handler 실행 순서를 기다리는 상태.
runningqueue thread가 handler를 실행하는 상태. 같은 item의 queued 상태와 겹칠 수 있다.
flush / cancel sync스레드에서 완료를 기다리는 동기 API. delayable flush는 예약된 work를 즉시 제출할 수 있다.

다음 Zephyr RTOS 글