콘텐츠로 이동

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
HaStream_t stream = HA_STREAM_DEFAULT;
ha_drv_obj_create(dev, HA_OBJ_STREAM, reinterpret_cast<void **>(&stream));

ha_drv_memcpy(dev, dev_in, reinterpret_cast<HaDevicePtr>(host_in), n, HaMemCpyDirection::HostToDevice, stream);
ha_drv_kernel_launch(dev, stream, k, args);
ha_drv_memcpy(dev, reinterpret_cast<HaDevicePtr>(host_out), dev_out, n, HaMemCpyDirection::DeviceToHost, stream);

// 이 동기화 시점에 큐잉된 세 작업이 모두 완료됩니다.
ha_drv_wait(dev, stream, nullptr, HA_WAIT_STREAM_SYNC, -1, nullptr);
ha_drv_obj_destroy(dev, HA_OBJ_STREAM, stream);
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
HaDrvStreamOp op{HA_STREAM_OP_MEMCPY, {}};
op.memcpy = {dst, src, n, HaMemCpyDirection::DeviceToDevice};

uint64_t seq = 0;
ha_drv_stream_post(dev, stream, &op, &seq);   // seq: 이 작업에 부여된 스트림 내 순번

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
HaDrvEvent done = nullptr;
ha_drv_obj_create(dev, HA_OBJ_EVENT, reinterpret_cast<void **>(&done));

// 1. producer 스트림에서 커널을 실행하고 이벤트를 기록합니다.
ha_drv_kernel_launch(dev, producer, k1, args1);
HaDrvStreamOp record{HA_STREAM_OP_RECORD_EVENT, {}};
record.event.event = done;
ha_drv_stream_post(dev, producer, &record, nullptr);

// 2. consumer 스트림이 producer의 그 지점 완료를 기다리게 합니다.
HaDrvStreamOp wait{HA_STREAM_OP_WAIT_EVENT, {}};
wait.event.event = done;
ha_drv_stream_post(dev, consumer, &wait, nullptr);
ha_drv_kernel_launch(dev, consumer, k2, args2);

// 3. 또는 호스트가 기다립니다.
ha_drv_wait(dev, HA_STREAM_DEFAULT, done, HA_WAIT_EVENT_SYNC, -1, nullptr);
ha_drv_obj_destroy(dev, HA_OBJ_EVENT, done);
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의 대기 범위

스트림 작업의 순번과 ha_drv_wait가 돌려주는 out_synced_seq

1
2
3
4
5
6
7
HaDrvStreamOp marker{HA_STREAM_OP_MARKER, {}};
uint64_t marker_seq = 0;
ha_drv_stream_post(dev, stream, &marker, &marker_seq);

uint64_t synced_seq = 0;
ha_drv_wait(dev, stream, nullptr, HA_WAIT_STREAM_SYNC, -1, &synced_seq);  // 마지막 인자 = out_synced_seq
// marker_seq < synced_seq: marker 이전에 큐잉된 모든 작업이 완료됨

다음 단계