5. 에러 처리와 리셋¶
드라이버 API의 모든 함수는 HaError 표준 상태 코드를 반환합니다. 비동기 작업의 실행 실패는 호출 즉시 드러나지 않고
스트림에 오류 상태로 남았다가 이후의 대기(Wait) 시점에 감지되며, 디바이스 리셋은 대상 디바이스의 모든 하위 핸들을
일괄 무효화합니다. 에러 코드 상세 목록은 에러 코드 레퍼런스를 참고하십시오.
Contents¶
| Section | Objective |
|---|---|
| 5.1 반환 규약 (Return Contract) | 실패 시 출력 인자와 순번(seq)의 상태 |
| 5.2 스트림 오류 (Sticky Error) | 비동기 실행 실패가 스트림에 남는 스티키 에러(Sticky Error) 동작 |
| 5.3 디바이스 리셋 (Device Reset) | 재초기화 시 하위 객체 무효화 범위와 블로킹 해제 동작 |
5.1 반환 규약 (Return Contract)¶
- 반환 타입: 대부분의 드라이버 API 함수는 성공 또는 실패를 나타내는
HaError를 반환합니다. 단, 일부 조회 함수(ha_drv_scan_devices,ha_drv_get_device_id,ha_drv_is_ready)는 결과 값을 직접 반환합니다. - 실패 시 출력 인자: 실패한 호출은 출력 인자를 그대로 두기도 하고 일부 값을 쓰기도 합니다. 출력 인자는
반환값이
HaSuccess일 때만 사용하십시오.ha_drv_wait의out_synced_seq는 예외로, 동기화가 실패해도 값이 기록됩니다(스트림과 이벤트의 동기화 지점). - 실패한 큐잉: 큐잉 단계에서 실패한 작업은 스트림에 들어가지 않으며 순번(
seq)을 소비하지 않습니다. - 반환은 작업 완료가 아닙니다: 큐잉 계열 함수의
HaSuccess는 작업이 큐에 등록되었다는 뜻일 뿐입니다. 실제 실행 결과는 이후의 동기화 시점에 확인해야 합니다.
5.2 스트림 오류 (Sticky Error)¶
스트림에서 실행 중인 비동기 작업이 실패하면, 스트림은 최초 오류만 기록해 보관합니다. 이후 해당 스트림에서 다른 오류가
발생하더라도 새로 기록하지 않으며, ha_drv_wait 호출과 작업 큐잉은 같은 오류 코드를 계속 반환합니다. 남은 오류를 지우는 함수는 없습니다. 명시적
스트림은 파괴한 뒤 새로 만들고, 기본 스트림에 남은 오류는 디바이스 리셋으로 정리합니다.
비동기 작업의 실패는 큐잉한 함수가 아니라 다음 동기화 대기 시점에 드러나므로, 동기화 결과를 항상 확인해야 합니다.
1 2 3 4 5 6 7 8 9 | |
5.3 디바이스 리셋 (Device Reset)¶
ha_drv_reset(dev)는 대상 디바이스의 작업을 멈추고 큐에 남은 명령을 비운 뒤, 메모리 풀을 해제하고 디바이스를
강제로 재초기화합니다. 마지막으로 그 디바이스의 모든 스트림(기본 스트림 포함), 이벤트, 커널 핸들을 해제합니다.
리셋에 따른 하위 핸들 무효화
리셋 이전에 얻은 스트림, 이벤트, 메모리 할당, 커널 핸들은 리셋 후 모두 무효가 됩니다. 최상위 디바이스
핸들(HaDrvDev)만 유효하게 남습니다. 리셋 후 디바이스를 다시 쓰려면 필요한 하위 객체를 다시 만들고 커널을 다시
로드해야 합니다. 디바이스에 속하지 않는 커널 라이브러리 핸들(HaLibrary_t)과 라이브러리 커널 핸들(HaKernel_t)은
리셋 후에도 유효하므로, 라이브러리 커널은 ha_drv_kernel_load_from_library()로 다시 로드하기만 하면 됩니다.
1 2 3 4 5 | |
리셋 후에도 유효한 핸들과 다시 만들어야 하는 하위 객체
- 리셋 중 호출: 리셋이 진행되는 동안 그 디바이스를 다루는 함수(할당, 복사, 큐잉, 대기, 객체 생성 등)는
HaDeviceNotReady를 반환합니다. - 블로킹 중인 호출: 리셋이 디바이스를 중단하면 그 디바이스에서 블로킹 대기 중이던 호출(동기화 대기, 커널
업로드 대기 등)이 깨어나
HaDeviceNotReady를 반환합니다. 리셋은 이 호출들이 반환하기를 정해진 시간만큼 기다리며, 그 안에 반환하지 않은 호출이 쓰는 객체는 해제하지 않고 남겨 둡니다. 남긴 객체는 다음 리셋이나 종료 때 해제됩니다. - 리셋 실패: 리셋 자체가 실패하면
HaDeviceResetFailed를 반환하지만, 위의 자원 정리는 그대로 수행됩니다.
| API | 동기 여부 | 동작 |
|---|---|---|
ha_drv_reset() |
Sync | 디바이스 강제 재초기화와 하위 핸들 일괄 무효화 |
ha_drv_is_ready() |
Sync | 디바이스가 해제되지 않았고 핸들이 유효한지 확인. 리셋 진행 여부는 반영하지 않음 |
다음 단계¶
- 에러 코드 —
HaError전체 목록 - Driver API: Device Handle —
ha_drv_reset시그니처