4. 스트림과 이벤트¶
드라이버 API의 모든 비동기 작업은 스트림에 순서대로 큐잉됩니다. 호스트에서 완료를 기다리거나 상태를 조회할 때는
스트림·이벤트·디바이스 모두 ha_drv_wait 하나를 씁니다. 스트림과 이벤트는 같은 함수(ha_drv_obj_create /
ha_drv_obj_destroy)로 생성·파괴하며, 전용 함수가 없는 스트림 작업은 ha_drv_stream_post로 큐잉합니다.
Contents¶
| Section | Objective |
|---|---|
| 4.1 스트림 (Stream) | 스트림 생성, 기본 스트림(HA_STREAM_DEFAULT), 개수 제한, 스트림 작업 |
| 4.2 이벤트 (Event) | 이벤트 기록과 스트림 간 종속성 대기 규칙 |
| 4.3 동기화 지점 (Synchronization) | ha_drv_wait의 다섯 가지 동기화 모드와 순번(seq) 기반 완료 검증 |
4.1 스트림 (Stream)¶
스트림은 디바이스에서 작업이 직렬로 처리되는 순서 보장 큐(Queue)입니다. 같은 스트림에 큐잉된 커널 실행과 메모리 복사는 등록된 순서대로 실행되며, 서로 다른 스트림 사이에는 이벤트로 연결하지 않는 한 실행 순서가 보장되지 않습니다.
1 2 3 4 5 6 7 8 9 10 | |
| API | 동기 여부 | 동작 |
|---|---|---|
ha_drv_obj_create() + HA_OBJ_STREAM |
Sync | 디바이스에 명시적 스트림 생성 |
ha_drv_obj_destroy() + HA_OBJ_STREAM |
Sync | 스트림에 남은 작업이 끝날 때까지 기다린 뒤 파괴 |
ha_drv_stream_post() |
Async | 스트림 작업(HaDrvStreamOp) 하나를 큐에 등록 |
ha_drv_wait() + HA_WAIT_STREAM_SYNC |
Sync | 큐잉된 모든 작업이 완료될 때까지 호스트 대기 |
ha_drv_wait() + HA_WAIT_STREAM_QUERY |
Sync | 스트림 오류가 있으면 그 오류, 없으면 유휴일 때 HaSuccess, 진행 중이면 HaStreamNotReady |
기본 스트림 (Default Stream)¶
스트림 인자에 HA_STREAM_DEFAULT를 넘기면 호출 스레드가 해당 디바이스에서 쓰는 기본 스트림을 가리킵니다(CUDA의
CU_STREAM_PER_THREAD에 대응). 기본 스트림은 처음 쓸 때 자동 생성됩니다. 스레드가 끝나면 남은 작업이 모두 끝난
뒤 회수되며, 그 전까지는 HA_WAIT_DEVICE_SYNC의 동기화 대상에 포함됩니다.
- 스레드별 독립성: 서로 다른 두 스레드가 각각
HA_STREAM_DEFAULT를 쓰면 서로 다른 스트림이므로 실행 순서가 보장되지 않습니다. 스레드 간 순서가 필요하면 명시적 스트림을 공유하거나 이벤트로 동기화하십시오. - 런타임 API와의 관계: 같은 프로세스에서 런타임 API가 같은 스레드·디바이스에서 쓰는 기본 스트림과 같은 스트림입니다. 단, 한 디바이스에서 두 API를 섞어 쓰지는 마십시오(1.2절 참고).
스트림 개수 제한 (Stream Count Limit)¶
명시적 스트림은 디바이스당 최대 10개까지 동시에 둘 수 있습니다. 기본 스트림은 이 한도에 포함되지 않고, 같은
디바이스에서 런타임 API로 만든 스트림은 포함됩니다. 한도에 이르면 ha_drv_obj_create가 HaStreamCreationFailed를
반환합니다.
스트림 작업 (Stream Operations)¶
메모리 복사를 포함해 커널 실행 외의 스트림 작업은 HaDrvStreamOp 구조체에 작업 종류와 페이로드를 담아
ha_drv_stream_post로 큐잉합니다.
| 작업 종류 | 동작 |
|---|---|
HA_STREAM_OP_MEMCPY |
호스트↔디바이스 또는 디바이스 내부 데이터 복사 |
HA_STREAM_OP_FREE |
선행 작업이 끝난 뒤 메모리를 비동기로 반환(3.1절 참고) |
HA_STREAM_OP_LOAD_FILE |
파일 디스크립터에서 디바이스 메모리로 직접 DMA 로드(3.3절 참고) |
HA_STREAM_OP_MARKER |
부수 효과 없이 순번(seq)만 차지. 동기화 기준점으로 사용 |
HA_STREAM_OP_SET_SAMPLING |
토큰 샘플링 파라미터를 후속 커널 실행과 순서를 맞춰 적용 |
HA_STREAM_OP_RECORD_EVENT |
스트림의 현재 지점에 이벤트 기록(4.2절 참고) |
HA_STREAM_OP_WAIT_EVENT |
이벤트가 완료될 때까지 이 스트림의 후속 작업 보류(4.2절 참고) |
1 2 3 4 5 | |
4.2 이벤트 (Event)¶
이벤트는 스트림의 특정 실행 지점을 표시하는 객체입니다. 한 스트림이 이벤트를 기록(Record)하면, 다른 스트림이나
호스트가 그 지점의 완료를 기다릴(Wait) 수 있습니다. 드라이버 이벤트(HaDrvEvent)는 런타임
이벤트(HaEvent_t)와 별개 객체입니다.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | |
| API | 동기 여부 | 동작 |
|---|---|---|
ha_drv_obj_create() + HA_OBJ_EVENT |
Sync | 이벤트 객체 생성 |
ha_drv_stream_post() + HA_STREAM_OP_RECORD_EVENT |
Async | 이벤트 기록 작업을 스트림에 등록 |
ha_drv_stream_post() + HA_STREAM_OP_WAIT_EVENT |
Async | 스트림의 후속 작업이 이 이벤트를 기다리게 함. 호스트는 기다리지 않음 |
ha_drv_wait() + HA_WAIT_EVENT_SYNC |
Sync | 기록 지점이 완료될 때까지 호스트 대기 |
ha_drv_wait() + HA_WAIT_EVENT_QUERY |
Sync | 완료면 HaSuccess, 진행 중이면 HaEventNotReady |
ha_drv_obj_destroy() + HA_OBJ_EVENT |
Sync | 이벤트 파괴. 기록된 이벤트면 기록 작업이 디바이스에 전달될 때까지 기다린 뒤 해제 |
이벤트 기록과 대기 규칙¶
- 1회 기록 제한: 이벤트는 수명 동안 한 번만 기록할 수 있습니다. 같은 이벤트를 다시 기록하면
HaEventInvalidArgument로 거부됩니다. - 자기 대기 금지: 이벤트를 기록한 스트림이 자기 이벤트를 기다리도록 큐잉하면 끝나지 않으므로
HaStreamInvalidArgument로 거부됩니다. - 기록 전 대기 금지: 한 번도 기록하지 않은 이벤트를 스트림 작업이나
ha_drv_wait로 기다리면HaEventNotRecorded를 반환합니다.
4.3 동기화 지점 (Synchronization)¶
호스트의 완료 대기와 상태 조회는 ha_drv_wait로 처리합니다. kind 인자가 대기 대상과 블로킹 여부를 정합니다.
스트림 모드에는 stream만, 이벤트 모드에는 event만 넘기고 나머지 인자는 HA_STREAM_DEFAULT나 nullptr로 둡니다.
디바이스 모드는 두 인자 모두 비워 둡니다. 맞지 않는 조합은 HaInvalidArgument입니다. timeout_ms는 SYNC 모드에만
쓰이며, 음수면 호스트 쪽 시간 제한 없이 기다립니다. HA_WAIT_STREAM_SYNC에서는 ha_drv_wait()의 마지막 인자 out_synced_seq로
이번 동기화가 받은 순번을 돌려받을 수 있습니다(선택).
동기화 모드 (kind) |
대상 | 동작 |
|---|---|---|
HA_WAIT_STREAM_SYNC |
스트림 | 호출 이전에 큐잉된 모든 작업이 완료될 때까지 블로킹 |
HA_WAIT_STREAM_QUERY |
스트림 | 블로킹 없이 상태 조회. 스트림 오류가 있으면 그 오류, 완료면 HaSuccess, 진행 중이면 HaStreamNotReady |
HA_WAIT_EVENT_SYNC |
이벤트 | 기록 지점의 작업이 완료될 때까지 블로킹 |
HA_WAIT_EVENT_QUERY |
이벤트 | 블로킹 없이 상태 조회. 완료면 HaSuccess, 대기 중이면 HaEventNotReady |
HA_WAIT_DEVICE_SYNC |
디바이스 | 호출 시점에 디바이스에 있는 모든 스트림을 동기화. 명시적 스트림, 모든 스레드의 기본 스트림, 종료된 스레드의 기본 스트림이 대상이며 첫 번째 오류를 반환 |
참고: 호출 이후의 작업
어떤 동기화 모드든 ha_drv_wait 호출 이후에 새로 큐잉되는 작업은 대기 대상에 포함되지 않습니다.
순번(seq)을 활용한 완료 검증¶
ha_drv_stream_post가 out_seq로 돌려준 순번과 ha_drv_wait(HA_WAIT_STREAM_SYNC)가 out_synced_seq로 돌려준
순번을 비교하면 특정 스트림 작업이 완료되었는지 판별할 수 있습니다. 동기화가 HaSuccess를 반환했다면
out_synced_seq보다 작은 seq의 작업은 모두 완료된 것입니다. out_synced_seq는 대기 전에 기록되므로 동기화가
실패해도 값이 채워집니다. 큐잉에 실패한 작업은 순번을 소비하지 않습니다.
스트림 작업의 순번과 ha_drv_wait가 돌려주는 out_synced_seq
1 2 3 4 5 6 7 | |
다음 단계¶
- 에러 처리와 리셋 — 스트림 오류와 디바이스 리셋
- Driver API: Streams & Events — 함수별 시그니처