콘텐츠로 이동

에러 코드

모든 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) 사람이 읽을 설명 문자열
1
2
3
4
5
6
#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=<정수 값>) 형식입니다.


함께 보기