에러 코드
모든 C++ 진입점(HaDataTypeBits() 같은 헬퍼와 아래 문자열 변환 함수 제외)은 HaError를 반환합니다. 코드는 릴리즈 간에 안정적이며, 하나의
코드가 다른 의미로 재사용되지 않습니다.
분류와 처리 방법은 에러 처리에 있습니다.
인코딩
카테고리가 상위 비트에 실려 있어, 모든 코드를 나열하지 않고도 실패의 종류로 분기할
수 있습니다.
| 카테고리 |
인코딩 |
값 |
| 성공 |
0 |
0 |
| 공통 |
code |
1 – 65535 |
| 디바이스 |
(1 << 16) \| code |
0x1_0000 이상 |
| 메모리 |
(2 << 16) \| code |
0x2_0000 이상 |
| 커널 |
(3 << 16) \| code |
0x3_0000 이상 |
| 스트림 |
(4 << 16) \| code |
0x4_0000 이상 |
| 이벤트 |
(5 << 16) \| code |
0x5_0000 이상 |
공통
| 코드 |
이름 |
원인 |
조치 |
0 |
HaSuccess |
— |
— |
1 |
HaInvalidArgument |
디바이스와 무관한 인자의 범위 초과 또는 null 포인터 |
시그니처와 대조해 인자 확인 |
2 |
HaNotSupported |
해당 API·옵션·실행 경로를 지원하지 않음 |
지원 매트릭스 확인 |
3 |
HaTimeout |
제한 시간 내에 완료되지 않음 |
종료하지 않는 커널 확인. 문제 해결 참고 |
4 |
HaInternalError |
예기치 않은 런타임 상태 |
결함입니다. 로그를 수집해 보고 |
5 |
HaUnknownError |
분류되지 않은 실패 |
결함입니다. 로그를 수집해 보고 |
디바이스
| 코드 |
이름 |
원인 |
조치 |
HaDeviceError \| 1 |
HaDeviceNotAvailable |
디바이스가 없거나 열 수 없음 |
ha.ko 로드 여부와 /dev/ha* 접근 권한 확인 |
HaDeviceError \| 2 |
HaDeviceNotInitialized |
디바이스는 존재하지만 비활성 상태(예: 다른 스레드의 HaResetAllDevices() 이후 갱신되지 않음). VMM: HaVmmInitBlocks() 전에 매핑을 호출 |
해당 스레드에서 HaSetDevice()를 다시 호출. VMM은 호출 순서를 따를 것 |
HaDeviceError \| 3 |
HaDeviceNotReady |
초기화·리셋·로드가 진행 중 |
진행 중인 작업이 끝난 뒤 재시도 |
HaDeviceError \| 4 |
HaDeviceInvalidArgument |
디바이스 ID 범위 초과, null 포인터, 또는 호출 스레드에 현재 디바이스 자체가 없음(HaSetDevice()를 호출한 적 없음) |
HaGetDeviceCount()로 id 검증, 또는 해당 스레드에서 HaSetDevice()를 먼저 호출 |
HaDeviceError \| 5 |
HaDeviceAlreadyInitialized |
이미 초기화됨 |
대부분의 흐름에서 오류가 아님. 무시하거나 초기화 구조 조정 |
HaDeviceError \| 6 |
HaDeviceOpenFailed |
드라이버가 디바이스 open을 거부 |
디바이스 노드 권한과 다른 프로세스의 점유 여부 확인 |
HaDeviceError \| 7 |
HaDeviceCloseFailed |
close 실패 |
로그를 수집해 보고 |
HaDeviceError \| 8 |
HaDeviceResetFailed |
리셋 실패 |
드라이버 수준에서 재초기화가 필요할 수 있음 |
HaDeviceError \| 10 |
HaDeviceUnsupported |
해당 디바이스·버전·기능을 지원하지 않음 |
지원 매트릭스 확인 |
HaDeviceError \| 11 |
HaDeviceRegisterSetFailed |
디바이스 레지스터 설정 실패 |
페이징 설정을 확인. 디바이스가 거부하는 경우가 많음 |
HaDeviceError \| 12 |
HaDeviceInvalidValue |
런타임이 해석할 수 없는 값을 디바이스가 반환 |
로그를 수집해 보고 |
HaDeviceError \| 13 |
HaDeviceBusy |
디바이스가 아직 사용 중. 예: 열린 디바이스 핸들이 남아 있는 상태에서 ha_drv_deinit() 호출 |
모든 핸들을 ha_drv_close()로 닫은 뒤 다시 호출 |
메모리
| 코드 |
이름 |
원인 |
조치 |
HaMemoryError \| 1 |
HaMemoryInvalidAddress |
호스트·디바이스 포인터 불일치 또는 null 디바이스 포인터 |
direction 인자가 전달한 포인터와 맞는지 확인 |
HaMemoryError \| 2 |
HaMemoryAlignmentError |
정렬 제약 위반 |
메모리 모델의 DRAM 정렬 규칙 확인 |
HaMemoryError \| 3 |
HaMemoryInvalidArgument |
잘못된 크기, null 포인터, 레이아웃 rank·shape 불일치. VMM: 매핑의 block_size가 1이 아님, row_indices 누락 또는 0–1023 범위 밖, pool_base가 4 KiB 정렬이 아님 |
HaMemCpyNd()는 브로드캐스트하지 않습니다. 양쪽 rank와 shape이 같아야 함. VMM은 VMM API의 인자 설명 확인 |
HaMemoryError \| 4 |
HaMemoryAllocationFailed |
메모리 부족 또는 제약을 만족하는 블록 없음. VMM: pool_bytes가 요청 1개의 K+V 페이지보다 작음 |
큰 버퍼는 시작 시 한 번 할당. 문제 해결 참고. VMM은 풀을 키울 것 |
HaMemoryError \| 5 |
HaMemoryFreeFailed |
해제 실패 |
포인터가 할당으로 얻은 것인지, 이미 해제되지 않았는지 확인 |
HaMemoryError \| 6 |
HaMemoryCopyFailed |
전송 실패 |
대상이 부분적으로 쓰였다고 보고 처리 |
HaMemoryError \| 7 |
HaMemCpyNotSupported |
지원하지 않는 복사 조합. 예: 최소 크기 미만의 디바이스 간 N-D 전송 |
호스트를 경유하거나 집합 통신은 LCCL 사용 |
HaMemoryError \| 8 |
HaHostMemLimitExceeded |
설정한 한도(HA_HOST_MEM_MAX_BYTES, HA_MEMCPYND_STAGING_MAX_BYTES)가 호스트 메모리 할당을 거부함. 시스템 메모리 부족은 HaMemoryAllocationFailed |
환경 변수에서 한도를 늘리거나, 사용이 끝난 호스트 메모리를 해제 |
커널
| 코드 |
이름 |
원인 |
조치 |
HaKernelError \| 1 |
HaKernelInvalidArgument |
인자 목록이 커널과 맞지 않음(종류·개수·route), 이동된 인자 목록, 잘못된 커널 바이너리나 라이브러리 데이터 |
로그에 기록된 기대 규격과 전달 규격을 대조. 인자 목록 규칙은 Execution API 참고 |
HaKernelError \| 2 |
HaKernelUnsupported |
해당 커널이나 실행 경로를 지원하지 않음 |
지원 매트릭스 확인 |
HaKernelError \| 3 |
HaKernelExecutionFailed |
커널이 실행되어 실패했거나 디바이스 폴트 |
디바이스 상태가 보장되지 않음. 그 자리에서 재시도하지 말 것 |
HaKernelError \| 4 |
HaKernelNotFound |
커널 바이너리 경로가 해석되지 않음, 또는 커널 라이브러리에 그 이름의 커널이 없음 |
프로세스 작업 디렉토리 기준으로 경로 확인. 라이브러리 커널은 이름 확인 |
HaKernelError \| 5 |
HaKernelInvalidHandle |
커널 핸들이 해제되었거나, 디바이스 리셋으로 무효화되었거나, 로드된 적이 없음. 또는 라이브러리·라이브러리 커널 핸들이 HaLibraryLoadData()·HaLibraryGetKernel()(드라이버 API: ha_drv_library_*)에서 발급된 것이 아님 |
드라이버 API는 ha_drv_kernel_load_from_file() 또는 ha_drv_kernel_load_from_library()로 다시 로드. 라이브러리 핸들은 발급받은 값을 그대로 전달 |
HaKernelError \| 6 |
HaKernelNoBinaryForDevice |
커널 라이브러리에 실행 디바이스의 칩 세대용 커널 바이너리가 없음 |
해당 디바이스 버전을 포함해 라이브러리를 다시 빌드 |
HaKernelError \| 7 |
HaKernelLoadFailed |
디바이스가 커널 로드에 실패함(커널 메모리 부족 이외의 원인) |
디바이스 상태 확인. 커널 메모리 부족은 HaMemoryAllocationFailed |
스트림
| 코드 |
이름 |
원인 |
조치 |
HaStreamError \| 1 |
HaStreamInvalidHandle |
알 수 없거나 낡은 스트림 핸들 |
디바이스 리셋은 스트림을 무효화합니다 |
HaStreamError \| 2 |
HaStreamInvalidArgument |
잘못된 스트림 인자 |
|
HaStreamError \| 3 |
HaStreamCreationFailed |
생성 실패 |
디바이스당 제한은 10개 |
HaStreamError \| 4 |
HaStreamDestroyFailed |
파괴 실패 |
파괴 전에 동기화 |
HaStreamError \| 5 |
HaStreamSyncFailed |
동기화 실패 |
스트림의 작업이 실패함. 직전 연산 확인 |
HaStreamError \| 6 |
HaStreamNotReady |
오류가 아님. HaStreamQuery()가 진행 중임을 보고 |
다시 폴링 |
이벤트
| 코드 |
이름 |
원인 |
조치 |
HaEventError \| 1 |
HaEventInvalidHandle |
알 수 없거나 낡은 이벤트 핸들 |
디바이스 리셋은 이벤트를 무효화합니다 |
HaEventError \| 2 |
HaEventInvalidArgument |
잘못된 이벤트 인자 |
|
HaEventError \| 3 |
HaEventCreationFailed |
생성 실패 |
|
HaEventError \| 4 |
HaEventDestroyFailed |
파괴 실패 |
스트림이 기다리는 이벤트를 파괴하지 말 것 |
HaEventError \| 5 |
HaEventNotRecorded |
오류가 아님. 이 이벤트에 HaEventRecord()가 호출된 적 없음 |
대기·질의 전에 기록 |
HaEventError \| 6 |
HaEventNotReady |
오류가 아님. HaEventQuery()가 미완료임을 보고 |
다시 폴링 |
세 개의 코드는 정상 제어 흐름입니다
HaStreamNotReady, HaEventNotReady, HaEventNotRecorded는 질의 진입점이 상태를
알리는 값입니다. 0이 아닌 반환을 모두 치명적 오류로 취급하는 폴링 루프는 첫
회차에서 중단됩니다.
에러 이름 문자열
HaError는 비트로 묶인 값이라 정수로 출력하면 의미를 알기 어렵습니다(예: err=131078). 공개 헤더 ha_error.h의
두 함수로 문자열을 얻으십시오. 둘 다 lpu::runtime 네임스페이스에 있습니다.
| 함수 |
반환 |
const char *HaErrorName(HaError err) |
열거자 이름(예: "HaMemoryCopyFailed"). 테스트나 로그 검색에서 비교하기에 안정적입니다. 열거형 밖의 값이면 "HaUnrecognizedError" |
const char *HaErrorToString(HaError err) |
사람이 읽을 설명 문자열 |
| #include "ha_error.h"
HaError err = HaMemCpy(dst, src, size, HaMemCpyDirection::HostToDevice);
if (err != HaError::HaSuccess) {
std::fprintf(stderr, "copy failed: %s\n", lpu::runtime::HaErrorName(err));
}
|
hart 모듈의 Python 함수는 실패하면 RuntimeError를 발생시키며, 메시지는 <실패한 호출 설명>: <에러 이름> (err=<정수 값>) 형식입니다.
함께 보기