MSI-X 설정하기 INF

[npu_driver_HW_Reg]
HKR, "Interrupt Management", 0x00000010
HKR, "Interrupt Management\MessageSignaledInterruptProperties", 0x00000010
HKR, "Interrupt Management\MessageSignaledInterruptProperties", "MSISupported", 0x00010001, 1
HKR, "Interrupt Management\MessageSignaledInterruptProperties", "MessageNumberLimit", 0x00010001, 4

INF 파일에 [npu_driver_HW_Reg]섹션에 위처럼 설정하였다. 레지스트리의 컴퓨터\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Enum Path에 저장이 된다.

Enum은 경로는 윈도우가 인식한 모든 하드웨어 장치의 정보가 열거되어 있는 핵심 레지스트리 위치이다.

하위 키 구조로는 버스 유형(PCI 등) -> 기기 식별자(ID) -> 인스턴스 ID 순으로 내려간다.

위 사진을 보면 실제로 google coral tpu 장치가 PCI로 인식이 되어서 하드웨어 하위 키로 인스턴스 ID를 생성하는 것을 확인할 수 있다.

HKR, "Interrupt Management", 0x00000010을 해석해 보면, "0x00000010이라는 플래그 명령에 따라 Device Parameters\Interrupt Management 라는 레지스트리 경로(키)를 만들어라" 이다.

HKR, "Interrupt Management\MessageSignaledInterruptProperties", 0x00000010 이것의 의미도 동일하게 Device Parameters\Interrupt Management\MessageSignaledInterruptProperties을 만들라는 것이다.

HKR, "Interrupt Management\MessageSignaledInterruptProperties", "MSISupported", 0x00010001, 1 이것의 의미는, "Device Parameters\Interrupt Management\MessageSignaledInterruptProperties으로 접근해서 MSISupported의 값을 만들고 DWORD타입으로 실제 값을 1로 주어라"라는 의미로 해석하면 된다.

HKR, "Interrupt Management\MessageSignaledInterruptProperties", "MessageNumberLimit", 0x00010001, 4 이것의 의미도 마찬가지로 MessageNumberLimit 값에 실제로 4라는 값을 설정해라는 것이다.

최종적으로 생성된 값들을 확인하면 아래와 같다.

그러면 이후에 PnP 매니저가 리소스 결정 및 할당할 때, MSISupproted값이 1로 되어있는 것을 확인하게 되면 레거시 인터럽트 방식 대신에 MSI리소스를 할당해 준다.

EvtDeviceAdd에서 Interrupt Object 생성

WdfInterruptCreate MSDN 위 WdfInterruptCreate함수의 MSDN을 확인해보니 아래와 같이 쓰여져 있다.

일반적으로는 EvtDeviceAdd에서 인터럽트 객체를 만들지만, EvtDevicePrepareHardware에서도 호출할 수 있다는 것 같다. 이 부분은 좀 더 학습해야 할 부분인 것 같다. 지금은 EvtDeviceAdd에서 생성하는 것을 다루도록 하겠다.

INF에 설정한 인터럽트 개수만큼 Object를 생성해 주었다.

{
    deviceContext->IsrCallCount = 0;
    for (ULONG i = 0; i < 4; ++i) {
        WDF_INTERRUPT_CONFIG interruptConfig;
        WDF_INTERRUPT_CONFIG_INIT(&interruptConfig,
            npudriverEvtInterruptIsr,
            npudriverEvtInterruptDpcNew);
        interruptConfig.EvtInterruptEnable  = npudriverEvtInterruptEnable;
        interruptConfig.EvtInterruptDisable = npudriverEvtInterruptDisable;
        status = WdfInterruptCreate(device, &interruptConfig,
            WDF_NO_OBJECT_ATTRIBUTES, &deviceContext->Interrupts[i]);
        if (!NT_SUCCESS(status)) {
            DbgPrint("[%s] WdfInterruptCreate[%lu] failed: 0x%x\n",
                __FUNCTION__, i, status);
            return status;
        }
        DbgPrint("[%s] WdfInterruptCreate[%lu] OK (Interrupts[%lu]=%p)\n",
            __FUNCTION__, i, i, deviceContext->Interrupts[i]);
    }
}

이렇게 해두면 WDF가 내부적으로 인터럽트 오브젝트와 인터럽트 벡터를 연결해서 npu가 인터럽트를 발생시켰을 때, 등록한 ISR이 호출된다고 한다.

등록되는 과정은 추후에 더 자세히 다루도록 하겠다.

결론

npu driver를 개발하며 MSI-X에 대한 개념을 익혔지만 내부적으로 어떻게 동작이 되고 사용이 되는지 좀 더 자세히 알아보았다.

추가로 ISR, DPC 내부에서 로직을 어떻게 처리하는지, WDF 내부에서 어떻게 미리 생성한 Interrupt Object와 연결해 주는지에 대해서 자세히 알아봐야겠다.

EvtDeviceAdd는 언제 호출이 될까?

DriverEntry가 끝나면 드라이버는 메모리에 로드되어있지만, 아직 이 드라이버가 제어할 실제 NPU 하드웨어 장치와는 연결되지 않은 상태이다.

1. PDO의 존재 드라이버가 로드되기 전, PCIe 버스 드라이버는 이미 NPU(디바이스)를 발견하고 커널 내부에 PDO(물리 장치 객체)라는 하드웨어 뼈대를 만들어둔다.
2. PnP 매니저의 매칭 PnP 매니저는 DriverEntry를 마친 NPU 드라이버 객체(Driver Object)와 이미 만들어진 PDO를 서로 매칭시켜준다.
3. EvtDeviceAdd 호출 PnP 매니저는 DriverEntry가 STATUS_SUCCESS를 반환하면 EvtDeviceAdd를 호출해준다.

EvtDeviceAdd의 매개변수

실제 npu_driver 소스를 보겠다.

NTSTATUS
npudriverEvtDeviceAdd(
    _In_ WDFDRIVER Driver,
    _Inout_ PWDFDEVICE_INIT DeviceInit
)
{
    NTSTATUS status;

    UNREFERENCED_PARAMETER(Driver);
    PAGED_CODE();    

    DbgPrint("[%s] Entry\n", __FUNCTION__);

    status = npudriverCreateDevice(DeviceInit);

    DbgPrint("[%s] Exit\n", __FUNCTION__);

    return status;
}

매개변수로 WDFDRIVER 와 PWDFDEVICE_INIT를 받는다. 특히 PWDFDEVICE_INIT은 생명 주기가 특이한데 WdfDeviceCreate을 호출하기 전에 사용된다. 아래와 같이 사용한다.

WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
pnpPowerCallbacks.EvtDevicePrepareHardware = npudriverEvtDevicePrepareHardware;
pnpPowerCallbacks.EvtDeviceReleaseHardware= npudriverEvtDeviceReleaseHardware;

WdfDeviceInitSetPnpPowerEventCallbacks(DeviceInit, &pnpPowerCallbacks);

// Set up file object config with cleanup callback
WDF_FILEOBJECT_CONFIG_INIT(&fileObjectConfig, NULL, NULL, npudriverEvtFileCleanup);
WdfDeviceInitSetFileObjectConfig(DeviceInit, &fileObjectConfig, WDF_NO_OBJECT_ATTRIBUTES);

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&deviceAttributes, DEVICE_CONTEXT);

status = WdfDeviceCreate(&DeviceInit, &deviceAttributes, &device);

디바이스 생성 전에만 쓰이는 임시 설정 바구니로 알고 있으면 된다.

WDFDRIVER는 DriverEntry에서 생성한 객체인데 EvtDeviceAdd에서는 크게 사용할 일이 없어서 UNREFERENCED_PARAMETER 처리해두었다.

EvtDeviceAdd 내부에서 해야하는 일

EvtDeviceAdd가 호출되었을 때, 해야 하는 일은 크게 아래와 같다.

1. WdfDevice 생성
2. 디바이스 컨텍스트 초기화
3. Interrupt 초기화
4. I/O Queue 생성
5. 인터페이스 생성(유저 모드에서 사용)

Interrupt 초기화를 하는 이유에 대해서는 인터럽트 MSI-X에 대한 고찰에서 다룬다.

유저 모드 어플리케이션에서 Device의 핸들을 얻어서 IRP를 발생시키는데, WDF가 IRP를 WDFREQUEST로 래핑을 해준다. Device에 연결된 I/O Queue에 들어가게 되는데, 따라서 Device 생성 시점에, Queue를 만들어준다.

// 인터페이스 핸들 생성 
status = WdfDeviceCreateDeviceInterface(device, &GUID_DEVINTERFACE_npudriver, NULL);    

if (NT_SUCCESS(status))
{
    // Initialize the I/O Queue
    WDF_IO_QUEUE_CONFIG queueConfig;
    WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(&queueConfig, WdfIoQueueDispatchSequential);
    queueConfig.EvtIoDeviceControl = npudriverEvtIoDeviceControl;

    status = WdfIoQueueCreate(device, &queueConfig, WDF_NO_OBJECT_ATTRIBUTES, &deviceContext->IoQueue);
    if (!NT_SUCCESS(status)) {
        DbgPrint("[%s] WdfIoQueueCreate failed: 0x%x\n", __FUNCTION__, status);
        return status;
    }
}

Device.c 소스

결론

EvtDeviceAdd가 어느 시점에 호출되고 내부에서 어떤 기능을 수행하는지 알아보았다. 일단 기능이 동작하도록 했었는데 내부적으로 Driver가 어떻게 동작하는지 자세히 알아볼 예정이다. 화이팅!

inf 파일은 언제 %SystemRoot%\Inf로 복사가 될까?

%SystemRoot% -> C:\Windows를 의미

사용자가 장치 관리자에서 드라이버 업데이트를 누르거나, CLI에서 pnputil /add-driver npu_driver.inf 명령어를 실행하는 순간 드라이버 스테이징 또는 사전 설치가 발생한다. 이 과정에서 복사가 일어난다.

장치가 실제로 컴퓨터에 장착되었을 때, OS가 드라이버를 1초 만에 찾아서 로드할 수 있도록 정렬해 두는 것이라고 한다.

언제 레지스트리에 등록이 될까??

경로: HKLM\SYSTEM\CurrentControlSet\Services

INF 파일이 %SystemRoot%\Inf에 복사되었다고 해서 바로 레지스트리에 서비스가 등록되는 것은 아니다. 레지스트리 등록은 장치락 실제로 시스템에 인식되어 드라이버와 짝지어지는 시점에 일어난다.

장착된 device의 하드웨어 ID를 추출하여 OS가 %SystemRoot\Inf 폴더에서 찾아서, 해당 하드웨어 ID와 일치하는 [Manufacturer] 섹션을 가진 INF 파일을 찾아낸다. 일치하는 INF를 찾으면, 그 내부의 명세서대로 레지스트리에 서비스를 생성하고 장치 정보를 등록한다.

실제로 npu를 장착하고 장치 관리자에서 하드웨어 ID를 확인하면 위 사진과 같다. 그렇다면 INF 파일의 [Manufacturer] 섹션을 확인해 보겠다.

Manufacturer 섹션을 확인해 보면 모델 이름이 나오고 해당 모델 이름을 가진 섹션을 찾아가 보면 [Standard.NTamd64.10.0...16299]을 확인할 수 있다. 내용을 보면 PCI\VEN_1AC1&DEV_089A&SUBSYS_089A1AC1&REV_00으로 나와있는 것을 확인할 수 있는데 이 부분은 개발자가 하드웨어 ID를 입력해서 넣어준 부분이다. 따라서 npu device에 올릴 드라이버를 지정해 준 것으로 볼 수 있다.

레지스트리에 등록되는 내용은 뭘까?

HKLM\SYSTEM\CurrentControlSet\Services를 살펴보면 npu_driver가 레지스트리에 등록된 것을 확인할 수 있다.

Enum

Enum키는 드라이버가 현재 어떤 실제 하드웨어 장치들을 지배하고 있는지 역으로 추적할 수 있게 해주는 연결고리라고 보면 된다.

0의 경우 장치 인스턴스 ID를 저장한다. 현재는 npu 카드 하나만 꽂았기 때문에 0만 존재하지만 여러 카드를 꽂게 되면 여러 개로 등록된다고 한다.

Parameters

parameters키는 온전히 NPU 드라이버 개발자를 위한 키라고 보면 된다. 드라이버가 로드될 때 참조해야 하는 각종 커스텀 설정이나 환경 변수 값들을 저장하는 곳이다.

driver install sections

; -------------- npu_driver driver install sections
[npu_driver_Service_Inst]
DisplayName    = %npu_driver.SVCDESC%
ServiceType    = 1               ; SERVICE_KERNEL_DRIVER
StartType      = 3               ; SERVICE_DEMAND_START
ErrorControl   = 1               ; SERVICE_ERROR_NORMAL
ServiceBinary  = %13%\npu_driver.sys

위 내용은 Pnp관리자가 설치 단계에서 레지스트리에 서비스 명세서를 적을 때 사용이 된다.

위에 레지스트리 값들에 맵핑 시켜준다고 보면 된다. 그 후 실제로 실행 타이밍에(드라이버가 로드될 때) 레지스트리에 적힌 이 값들을 보면서 설정한 데로 동작한다.

결론

inf 파일이 driver 개발함에 있어서 필요하다는 것은 알고 있었는데 어떻게 동작하는지는 몰랐다. 이번 포스팅을 하면서 알게 된 것 같다.

PCIe 장치 주소 체계

BDF에 대해서 간략히 설명하겠다. Bus -> 도시 Device -> 건물 Function -> 층 으로 간단하게 이해하면 된다.

Bus는 총 256개, 버스당 최대 Device 32개, 디바이스당 최대 8개의 Function을 가질 수 있다.

Function마다 Configuration Space가 존재한다. 따라서 BDF를 통해서 찾아갈 수 있다.

예시 사진은 아래와 같다.

Bus -> Device -> Function 순으로 나열되어 있는 것을 확인할 수 있다.

RWEVERYTHING

https://rweverything.com/

PCIe 하드웨어의 Config Space를 확인하기 위해서 설치했다. 위 홈페이지에서 Download하면 된다.

Configuration Space

위 사진처럼 구성이 된다고 한다. RWEverything을 통해서 확인해보면 좋을 것 같다.

실제 Configuration Space

아래 사진은 RWEverything으로 읽은 실제 Google Coral TPU PCIE의 Configuration Space이다.

개발한 npu driver에서는 BAR2를 Device Context에 저장해놓고 사용한다. 실제 PA 값을 비교해 보기 위해서 WinDbg를 활용해 보겠다.

case CmResourceTypeMemory:
    // save BAR2
    if (descriptor->u.Memory.Length == 0x100000) {
        DbgPrint(" (Memory) Start=0x%llx Length=0x%lx\n",
          descriptor->u.Memory.Start.QuadPart,
          descriptor->u.Memory.Length);

        deviceContext->Bar2Length = descriptor->u.Memory.Length;

        deviceContext->Bar2BaseAddress = MmMapIoSpace(
            descriptor->u.Memory.Start,
            descriptor->u.Memory.Length,
            MmNonCached
        );
    }

Length를 통해서 BAR2를 얻어온다. 이때, 찍히는 로그를 확인해 보겠다.

위처럼 0xa0000000으로 확인이 되었다. RWEverything으로 확인을 할 수 있다.

BAR 레지스터의 bit4~31이 Base Address 필드이며, 0xA00000C에서 하위 4비트를 마스킹 하면 실제 물리 주소 0xA0000000을 얻을 수 있다. B0 = 0 이므로 Memory Space, 즉 MMIO로 접근하는 영역임을 알 수 있다.

결론

추가로 PCIe의 Configuration Space에서 Vendor ID, Device ID 등 여러 정보가 있고 필요하면 직접 확인할 수 있을 것 같다.

정확히 모르는 부분을 계속 공부해야겠다.

하지만 매 추론마다 발생하는 유저-커널 모드 스위치(Mode Switch) 는 고성능 처리에 있어 불필요한 비용입니다. 비록 스레드 컨텍스트 스위치보다 오버헤드가 적다 해도, 실시간 추론이 반복되는 환경에서는 무시할 수 없는 병목이 됩니다. 따라서 향후 런타임이 직접 하드웨어를 제어하는 방식으로 개선할 계획입니다.

그 전초 단계로, 이번 포스팅에서는 비트스트림 분석을 통해 NPU가 어떻게 DMA와 Zero-copy로 대용량 데이터를 효율적으로 처리하는지 그 내부 메커니즘을 자세히 살펴보겠습니다.

descriptor ring

// Device.c
{
    PHYSICAL_ADDRESS maxAddr;
    maxAddr.QuadPart = 0xFFFFFFFFLL;
    deviceContext->DescRingBase =
        deviceContext->DmaAdapter->DmaOperations->AllocateCommonBufferEx(
            deviceContext->DmaAdapter,
            &maxAddr,
            PAGE_SIZE,
            &deviceContext->DescRingLogicalAddress,
            FALSE,                /* CacheEnabled = FALSE → uncached */
            MM_ANY_NODE_OK);
}

AllocateCommonBufferEx을 호출하여 DescRingBase의 kva를 얻고 있다.

CacheEnabled를 FALSE로 설정하지 않으면 드라이버(CPU)가 명령(Descriptor)을 작성했는데, 아직 CPU 캐시에만 머물고 실제 RAM에 안 올라간 상태인 경우 NPU가 정상적으로 동작하지 않을 수 있다.

    {
        PHYSICAL_ADDRESS descPhys = MmGetPhysicalAddress(deviceContext->DescRingBase);
        deviceContext->DescRingDeviceVA = (UINT64)4096 * PAGE_SIZE;  // 0x1000000
        deviceContext->DescRingTail = 0;
        apex_write_register(deviceContext->Bar2BaseAddress,
            APEX_REG_PAGE_TABLE + (4096 * 8), descPhys.QuadPart | 1);
        {
            UINT64 rb = apex_read_register(deviceContext->Bar2BaseAddress,
                APEX_REG_PAGE_TABLE + (4096 * 8));
            DbgPrint("[%s] DescRing: VA=%p PA=0x%llx DeviceVA=0x%llx PTE[4096] write=0x%llx readback=0x%llx %s\n",
                __FUNCTION__, deviceContext->DescRingBase, descPhys.QuadPart,
                deviceContext->DescRingDeviceVA, descPhys.QuadPart | 1, rb,
                (rb == (UINT64)(descPhys.QuadPart | 1)) ? "OK" : "MISMATCH");
        }
    }

MmGetPhysicalAddress api를 통해서 PA를 얻어왔는데 MSDN을 확인하니 아래와 같다.

찾아본 결과 원격 pc에 VT-d(Intel Virtualization Technology for Directed I/O)가 꺼져있어서 동작한 거라고 한다. 추후 테스트 예정

중요한 것은 아래 코드이다.

apex_write_register(deviceContext->Bar2BaseAddress,
    APEX_REG_PAGE_TABLE + (4096 * 8), descPhys.QuadPart | 1);

PTE의 시작 offset 값에 4096 인덱스 지점에 PA를 맵핑해주었다. 4096 * 8로 표현한 이유는 PTE가 8byte이기 때문이다.

windbg에 출력되는 로그를 확인해보았다.

의문점 왜 bit0를 |1 연산을 하는지?

칩의 MMU에게 해당 엔트리는 사용할 수 있다 라고 표현하는 것이라고 한다. 물리 주소는 항상 4KB(페이지) 정렬이다. 페이지 시작 주소의 하위 12비트는 무조건 0이라고 볼 수 있다. 따라서 bit0가 1일 때, 유효한 매핑으로 상위 비트의 PA로 접근하는 것이다.

bitstream device VA

그러면 bitstream의 deviceVA는 어떻게 넘기는 것일까? 라는 궁금증이 발생한다.

UINT32 slot0 = pDc->DescRingTail % 256;

ring[slot0].address = pIn->BitstreamDeviceVA;
ring[slot0].size_in_bytes = (UINT32)pIn->BitstreamSize;
ring[slot0].reserved = 0;
pDc->DescRingTail++;
KeMemoryBarrier();    // ring write 가 chip 보다 먼저 보이도록

apex_write_register(bar2, APEX_REG_INSTR_QUEUE_TAIL, pDc->DescRingTail % 256);

위 코드처럼 링버퍼의 address 필드에 BitstreamVA를 넣어서 해당하는 tail을 레지스터에 써주면 된다.

그러면 또다시 bitstream의 device VA를 chip은 어떻게 알 수 있는가?라는 의문이 든다. 그것은 바로 PTE 맵핑이다.

가속기(chip)는 pa를 직접 가지고 있지 않고 MMU를 통해서 PTE를 참조하여 PA를 얻는다. 정확히 google coral tpu가 어떻게 동작하는지는 알 수 없지만 접근하고자 하는 위치의 va를 알고 있다면 pte를 통해 pa를 얻어서 접근한다고 이해했다.

// Queue.c IOCTL_ALLOC_IO_BUFFERS 
WdfSpinLockAcquire(pDC->PageTableLock);
for (j = 0; j < pageCount; j++) {
    UINT64 pagePa = basePa + ((UINT64)j << PAGE_SHIFT);
    apex_write_register(
        pDC->Bar2BaseAddress,
        APEX_REG_PAGE_TABLE + ((startPte + j) * 8),
        pagePa | 0x1ULL
    );
}
WdfSpinLockRelease(pDC->PageTableLock);

pageCount만큼 PTE에 맵핑해주는 코드이다.

결론

npu driver를 개발하면서 가장 낯설게 느껴졌던 부분은 위처럼 hardware가 mmu를 통해 pte를 참조해 실제 접근할 pa를 얻는 것이다. hardware가 직접 pa를 들고 있으면 되는 거 아닌가?라는 생각이 들 수 있다. 3가지 이유로 pte 맵핑을 사용한다.

1. 메모리 파편화 흩어진 물리 메모리를 하나처럼 보이기 위해서이다. 윈도우에서는 10MB의 메모리를 할당하면, 실제 RAM에서는 4kb 단위로 여기저기 흩어져서 할당될 확률이 높다. 따라서 PTE가 있다면 가상 주소 하나만 던져주게 되면 조각난 PA들을 연결해서 읽을 수 있다.

2. 하드웨어 보호 격리 NPU는 엄처난 속도로 메로리를 읽고 쓴다. 만약 코드에 버그가 있어서 하드웨어가 잘못된 주소에 접근한다면 시스템 전체에 문제가 발생할 것이다. 따라서 PTE에 등록해 준 영역 안에서만 놀 수 있도록 한다.

3. 유연한 메모리 관리 (Zero-copy) 데이터를 옮기지 않고, PTE의 물리 주소 값만 바꿔주면 하드웨어 입장에서는 데이터가 이동한 것처럼 보인다.

알아야 할 것이 많지만 재밌는 것 같다.

구현 흐름

npu_driver에 ioctl handler, hardware register offset, init 을 해준다. npu runtime dll에서는 온도 값을 읽는 IOCTL을 래핑 한다. python gui 에서 npu runtime dll을 로드하여 호출해 준다.

linux driver 소스 참고

gasket-driver 소스를 참고하였다.

변환 공식

// linux
  static int adc_to_millic(int adc) {
      return (662 - adc) * 250 + 550;
  }
  static int millic_to_adc(int millic) {
      return (550 - millic) / 250 + 662;
  }

하드웨어로부터 읽은 값을 온도 값으로 변환해 주는 공식인 것 같다.

우리 쪽 소스에도 동일하게 추가했다.

// windows
static inline INT32 apex_adc_to_millic(UINT32 adc) {
    return (662 - (INT32)adc) * 250 + 550;
}
static inline UINT32 apex_millic_to_adc(INT32 millic) {
    return (UINT32)((550 - millic) / 250 + 662);
}

IOCTL 핸들러

// linux
  case ATTR_TEMP:
      value = gasket_dev_read_32(gasket_dev, APEX_BAR_INDEX,
                                 APEX_BAR2_REG_OMC0_DC);
      value = (value >> 16) & ((1 << 10) - 1);    // ★ bits [25:16]
      ret = scnprintf(buf, PAGE_SIZE, "%i\n", adc_to_millic(value));
      break;

gasket driver의 IOCTL 핸들러 부분이다. 32비트 레지스터 값을 읽은 뒤 온도 부분 10비트만 파싱 하는 내용이다.

// windows
#define APEX_OMC_DC_ADC_SHIFT          16
#define APEX_OMC_DC_ADC_MASK           0x3FF  // 10-bit 
#define APEX_OMC_DC_ADC_FROM_REG(r)    (((UINT32)(r) >> APEX_OMC_DC_ADC_SHIFT) & APEX_OMC_DC_ADC_MASK)

값을 16비트 우측으로 shift 시킨 뒤, 10비트를 가져오는 방법을 매크로로 표현했다.

초기화

gasket에서 사용한 초기화 방식을 그대로 모방하였다.

// linux
  static void enable_thermal_sensing(struct gasket_dev *gasket_dev) {
      // Enable thermal sensor clocks
      gasket_read_modify_write_32(gasket_dev, APEX_BAR_INDEX,
                                  APEX_BAR2_REG_OMC0_D0, 0x1, 1, 7);
      // Enable thermal sensor (ENAD ENVR ENBG)
      gasket_read_modify_write_32(gasket_dev, APEX_BAR_INDEX,
                                  APEX_BAR2_REG_OMC0_D8, 0x7, 3, 0);
      // 100us settle
      schedule_timeout(usecs_to_jiffies(100));
      // Enable OMC thermal sensor controller
      gasket_read_modify_write_32(gasket_dev, APEX_BAR_INDEX,
                                  APEX_BAR2_REG_OMC0_DC, 0x1, 1, 0);
  }

npu driver의 preparehardware 쪽에 추가하였다.

// windows 
    {
        PVOID bar2 = deviceContext->Bar2BaseAddress;
        apex_rmw_register_32(bar2, APEX_REG_OMC0_D0, 1, APEX_OMC_D0_CLK_EN_WIDTH, APEX_OMC_D0_CLK_EN_SHIFT);
        apex_rmw_register_32(bar2, APEX_REG_OMC0_D8, APEX_OMC_D8_SENSOR_EN_VAL, APEX_OMC_D8_SENSOR_EN_WIDTH, APEX_OMC_D8_SENSOR_EN_SHIFT);
        KeStallExecutionProcessor(APEX_OMC_SENSOR_SETTLE_US);
        apex_rmw_register_32(bar2, APEX_REG_OMC0_DC, 1, APEX_OMC_DC_CTRL_EN_WIDTH, APEX_OMC_DC_CTRL_EN_SHIFT);
        DbgPrint("[thermal] sensor enabled\n");
    }

최종 로직

// windows npu driver 
case IOCTL_GET_TEMPERATURE:
{
    PDEVICE_CONTEXT pDC = DeviceGetContext(device);
    PVOID bar2 = pDC->Bar2BaseAddress;

    if (bar2 == NULL) {
        status = STATUS_DEVICE_NOT_READY;
        break;
    }

    WDFMEMORY outMem;
    IOCTL_GET_TEMPERATURE_OUT* pOut = NULL;
    status = WdfRequestRetrieveOutputMemory(Request, &outMem);
    if (!NT_SUCCESS(status)) break;
    pOut = (IOCTL_GET_TEMPERATURE_OUT*)WdfMemoryGetBuffer(outMem, NULL);
    if (pOut == NULL) { status = STATUS_INVALID_PARAMETER; break; }

    UINT32 reg = apex_read_register_32(bar2, APEX_REG_OMC0_DC);
    UINT32 adc = APEX_OMC_DC_ADC_FROM_REG(reg);
    pOut->raw_adc = adc;
    pOut->millic = apex_adc_to_millic(adc);
    DbgPrint("[thermal] reg=0x%x adc=%u millic=%d\n", reg, adc, pOut->millic);  // ← 임시

    bytesReturned = sizeof(IOCTL_GET_TEMPERATURE_OUT);
    status = STATUS_SUCCESS;

    break;
}

32bit 레지스터 값을 읽는다. 읽은 값을 비트 연산하여 온도 값을 읽어준 뒤, 공식에 넣어서 user buffer space에 넘겨주는 코드이다.

결과

하단에 온도가 표시되도록 하였다.

추가로 데모 영상은 아래에서 확인할 수 있다.

결론

user space에서 hardware를 컨트롤하기 위해서 runtime을 통해 요청하고 driver에서는 실제 hardware의 register를 읽어서 다시 userspace로 보내주는 이 과정이 조금은 이해가 되는 것 같다.

https://github.com/wangki-kyu/npu_driver

기능

runtime dll의 가장 큰 역할은 npu_driver와의 통신을 래핑 하는 것이다. 즉 IOCTL 명령을 추상화하여 사용하도록 한다. 크게 3가지 기능이 필요할 것 같다.

1. init(memory allocate)
2. infer (descriptor submit)
3. free (memory free)

일단 동작을 하는지 확인하기 위해 만드는 것이므로 범용적이라기보다는 SSD model을 포커싱하여 만들었다.

기능 구현

기존 코드를 거의 복사해서 붙여 넣었다. 헤더의 경우 아래와 같이 선언해 주었다.

// Initialize a runtime instance for the face SSD model.
//   model_path_utf8   : UTF-8 path to ssd_mobilenet_v2_face_*.tflite
//   anchors_bin_path_utf8 : UTF-8 path to anchors.bin (float32 [num_anchors][4])
//   out_handle        : on success, receives a non-NULL handle
NPU_API npu_status_t npu_runtime_init_face_ssd(
    const char*   model_path_utf8,
    const char*   anchors_bin_path_utf8,
    npu_handle_t* out_handle);

// Query model input dimensions (w, h, c). Bytes = w * h * c.
NPU_API npu_status_t npu_runtime_get_input_size(
    npu_handle_t h,
    uint32_t* out_w,
    uint32_t* out_h,
    uint32_t* out_c);

// Run one inference.
//   image_rgb       : RGB uint8 packed, must be exactly w*h*c bytes
//   image_byte_len  : length of image_rgb (sanity check)
//   out_dets        : caller-allocated array of `max` entries (may be NULL if max==0)
//   max             : capacity of out_dets
//   out_count       : actually written (always <= max)
NPU_API npu_status_t npu_runtime_infer_image(
    npu_handle_t     h,
    const uint8_t*   image_rgb,
    uint32_t         image_byte_len,
    npu_detection_t* out_dets,
    uint32_t         max,
    uint32_t*        out_count);

// Release all resources held by the handle (chip buffers, device handle, COM).
// Safe to call with NULL.
NPU_API void npu_runtime_free(npu_handle_t h);

정의 부분은 복잡하기 때문에 아래 github을 확인하면 된다.

실제 사용

카메라를 사용하여 실시간으로 추론을 테스트하기 위해서 python을 선택했다. opencv를 손쉽게 사용할 수 있고 ctypes를 활용해 손쉽게 dll을 사용할 수 있기 때문이다. 또한 agent의 도움을 받아 빠르게 결과를 확인할 수 있다.

정확히 얼굴을 찾는 것을 확인할 수 있다. 그러나 여기서 문제점이 발생했다. 특정 시점이 되면 추론에 실패하고 driver에서 에러를 뱉었다.

문제 해결

[DIE] infer failed at frame=128 infer_count=127
[DIE] uptime since loop start: 0.98s (last interval)
[DIE] error: infer_image failed (status=6): IOCTL_INFER_NEW failed, GetLastError=483
Traceback (most recent call last):
  File "C:\work\real\npu_runtime_camera.py", line 198, in <module>
    sys.exit(main())
  File "C:\work\real\npu_runtime_camera.py", line 140, in main
    dets = npu.infer(rgb, max_dets=50)
  File "C:\work\real\npu_runtime_demo.py", line 115, in infer
    raise RuntimeError(f"infer_image failed (status={st}): {self.last_error()}")

위와 같은 에러 로그가 발생했다. 확인 결과 128프레임에 죽는 현상이 계속해서 발생했다.

한 프레임마다 infer를 하는데 tail이 증가하도록 되어있다. tail에 써주는 csr이 최대 0 ~ 255 까지만 받을 수 있도록 설계되어 있는 것을 확인했다. 코드에

apex_write_register(bar2, APEX_REG_INSTR_QUEUE_TAIL, pDc->DescRingTail);

한 번 제출 시, param cache와 infer descriptor를 2개씩 제출하기 때문에 2씩 증가한다. 따라서 pDc->DescRingTail을 % 256 연산을 해야 한다.

apex_write_register(bar2, APEX_REG_INSTR_QUEUE_TAIL, pDc->DescRingTail % 256);

위처럼 코드를 변경하니 문제가 발생하지 않았다!!!

결론

npu driver가 잘 동작한다!! 너무 기쁘다.

수정 및 개선해야 할 부분이 많다. anchor 및 quant params 값들을 하드 코딩 형태로 사용하고 있는 점도 수정해야 한다. 또한 byte-identical을 위해서 넣어두었던 로깅 코드들도 제거해야 하고 param cache descriptor도 infer 마다 하기 때문에 최초에 한번 하도록 수정해야 한다.

https://github.com/wangki-kyu/npu_driver/tree/main/npu_runtime

그렇다면 어떻게 convert_scores 값이 쓰레기 값이 아닌지 알 수 있었던 내용을 작성해 보겠다.

libedgetpu의 output buffer

당연히 추론 이후의 output buffer의 Byte-identical을 진행해서 다른 내용을 확인했기에 개발 중인 npu driver의 output buffer에 쓰레기 값이 들어왔을 것이라고 판단한 것이다.

테스트를 하기 위해 가설을 세웠다.

혹시 exe0의 param data의 값이 libedgetpu에서 wrong 값이 들어간다면?

테스트를 위해서 exe0의 param 값에 0xcc값을 채워서 빌드 후 테스트했다. 결과가 너무 충격적이라서 소리를 질렀다.

우리의 convert_scores와 비슷한 패턴으로 나오는 것이었다. 뭐지 싶었다. 그러면 우리가 넣어주는 exe0의 param 값이 정상적으로 안 들어가는 건가?라는 생각을 했다.

좀 이상해서 Squeeze1 값도 비교해 보기 위해서 dump를 찍어서 확인했더니 동일한 것이다!! 그러면 우리가 비교했던 값은 무엇인가?라는 생각이 들었다.

convert scores는 잘못이 없었다.

libedgetpu로 로그만 추가한 상태로 추론을 해보았다. 정상적으로 동작이 되었고 로그를 확인하니 여전히 우리와 같은 값이 나오는 것이었다.

그러면 npu driver가 정상적으로 추론 값을 받고 있는 건가? 라는 생각이 들었다. 동시에 Squeeze1과 convert_scores 값을 해석하는 방식이 잘못된 건가? 라는 생각을 했다.

그러면 convert_scores 값은 유의미한 값이고 full dump를 찍어보자

  [uniform] convert_scores: 2025 / 2034 anchors match 'ff 00 80 80'
  [diff-anchor] idx=143  : ff 01 80 80
  [diff-anchor] idx=146  : ff 01 80 80
  [diff-anchor] idx=200  : fb 05 80 80
  [diff-anchor] idx=203  : 01 ff 80 80   ← ★
  [diff-anchor] idx=206  : 02 fe 80 80   ← ★
  [diff-anchor] idx=263  : 80 80 80 80
  [diff-anchor] idx=266  : 80 80 80 80
  [diff-anchor] idx=1278 : f6 0a 80 80
  [diff-anchor] idx=1284 : f6 0a 80 80

full dump를 찍었더니 4byte 씩 패턴을 보였고 다른 것들이 발견되었다. 0xff / 256 = 0.996은 pycoral의 detection score 0.9961과 byte-identical 하다는 것을 발견했다. 즉 head 256 byte만 보고 다 균일이다 = 망가졌다라고 잘못 읽었던 것이다. 2034 anchor 중 9 개만 의미 있는 값을 갖고 있었고, 그 9개가 head 256 byte 안에 없었던 것뿐이다.

chip은 처음부터 정확한 답을 보내고 있었다.

그러면 box 좌표는 어디서 오는가

score는 byte 자체에서 풀렸다. 그런데 detection 결과의 box 같은 좌표는 chip output 어디에도 명시되어 있지 않다. Squeeze1의 byte를 dequant 해도 그냥 4개의 float일뿐 픽셀이 안 나온다.

anchor 0 의 Squeeze1: 94 88 73 4b dequant: dy=+0.43, dx=-0.87, dh=-3.14, dw=-7.47 이게 픽셀이 아니면 어떤 보정값 같은데, 출발점이 되는 좌표가 chip output에 없다.

그러면 box 좌표 만들기에 chip output 외에 더 필요한 정보가 있는 거 아닌가?

tflite graph 까보기

chip 다음에 어떤 op가 실행되는지 알아야 했다. tflite schema.fbs 를 받아서 flatc로 모델을 JSON으로 변환한 후, op chain만 추출하는 extract_op_chain.py 를 작성해서 돌렸다.

  op[0] 'edgetpu-custom-op'
     OUT: 2(Squeeze1), 4(convert_scores)
  op[1] 'DEQUANTIZE'
     IN : 2(Squeeze1)         OUT: 3(Squeeze2)
  op[2] 'DEQUANTIZE'
     IN : 4(convert_scores)   OUT: 5(convert_scores1)
  op[3] 'TFLite_Detection_PostProcess'
     IN : 3(Squeeze2), 5(convert_scores1), 1(anchors)   ← ★
     OUT: 6, 7, 8, 9

tflite 모델 파일(.tflite)은 일종의 연산 설계도(Graph)인데, 이걸 JSON으로 변환해서 열어보면 모델 내부에서 데이터가 어떤 순서로 흐르고, 어떤 Op들이 체인처럼 엮여서 실행되는지 그 지도를 100% 명확하게 까볼 수 있다.

• 0단계: PCIe 가속기 칩이 담당한 연산
• 1단계 & 2단계: 칩이 내뱉는 무식한 바이트 데이터들을 cpu가 알아들을 수 있게 부동소수점으로 변환하는 과정
• 3단계: 대망의 최종 후처리 단계

사실 tflite model에 대해서 깊이 있게 아는 것이 아니라 정확히는 모르겠다. 하지만 찾아본 결과 2,034개의 anchor 박스마다 각각 4개(x,yu,w,h)의 기본 규격 좌표를 미리 기억하고 있는 고정된 데이터 테이블이 있다고 한다. buf=1의 의미는 모델 안에 const data가 들어있다는 의미라고 보면 된다.

즉, 최종 얼굴 사각형 박스는 칩이 주는 게 아니라, 모델 파일에 적혀 있던 2,034개의 고정 앵커 좌표에다가 칩이 실시간으로 뱉어낸 미세 조정값(Squeeze1)을 수학적으로 합성해서 cpu가 만들어내고 있었던 것이다!!!!

anchors와 quant params 추출

standalone으로 우리가 만든 c++ 모듈에서 동작시키기 위해서는 3개의 const 값이 필요하다.

1. anchors의 실제 byte (2034 * 4 float32 = 32544 byte)
2. Squeeze1의 quant params (scale, zero_point)
3. convert_scores의 quant params

extract_postproc_deps.py를 ai 도움을 받아 작성하여 한 번에 추출했다.

# 결과 
 anchors.bin               32544 bytes float32
 Squeeze1       scale=0.10822763  zp=144
 convert_scores scale=0.00390625  zp=0
 anchor[203]    = [yc=0.175, xc=0.375, h=0.2828, w=0.1414]

anchor[203] 좌표를 픽셀로 풀면 (yc=56, xc=120, h=90, w=45) 의 세로 직사각형 — karina 얼굴 근처에 미리 정의된 prior box.

anchor + Squeeze1의 합성

표준 SSD MobileNet 의 box decode 공식이 있다. 이걸 그대로 사용했다.

  ycenter = anchor.yc + (dy / 10.0f) * anchor.h;
  xcenter = anchor.xc + (dx / 10.0f) * anchor.w;
  h       = exp(dh / 5.0f) * anchor.h;
  w       = exp(dw / 5.0f) * anchor.w;

  out[0] = ycenter - h / 2;   // ymin
  out[1] = xcenter - w / 2;   // xmin
  out[2] = ycenter + h / 2;   // ymax
  out[3] = xcenter + w / 2;   // xmax

이 공식의 수학적 의미를 깊게 알지는 못한다. 그냥 anchor의 좌표에서 chip이 보낸 보정값만큼 조정해서 진짜 box를 만든다 정도로 이해하고 사용했다. 아직 공부할게 너무 많다..

계산 결과로는 다음과 같다.

  ycenter = 0.175 + 0.022 * 0.2828 = 0.181
  xcenter = 0.375 + 0.130 * 0.1414 = 0.393
  h       = exp(-0.108) * 0.2828   = 0.254
  w       = exp(0.433)  * 0.1414   = 0.218

  box (normalized) : (0.054, 0.284) - (0.308, 0.502)
  box (320x320 px) : (90, 17) - (160, 98)

opencv로 시각화

driver가 만든 box는 320*320 model space의 normalized 좌표이다. 원본 이미지에 그리려면 추론 시 letterbox 전처리를 역으로 풀어야 한다.

scale = min(320 / srcW, 320 / srcH) newW = int(srcW * scale) newH = int(srcH * scale) x0 = int(round(max(0, min(d.xmin * 320, newW)) / scale)) y0 = int(round(max(0, min(d.ymin * 320, newH)) / scale)) ... cv2.rectangle(img, (x0, y0), (x1, y1), (0, 0, 255), 2)

결과

눈물이 났다.

결론

4월 말부터 이 프로젝트를 했으니 약 3주가 넘게 흘렀다. 처음 해보는 영역이라서 너무 어려웠고 방향성을 몰랐지만 그래도 첫 번째 목표인 추론에 성공하였다.

지금은 특정 model에 대해서 의존성이 강하게 만들었는데 범용으로 사용할 수 있도록 runtime을 만들 예정이다. 또한 ai agent의 도움을 많이 받았는데 모르는 부분을 공부로 채워나가야겠다.

https://github.com/wangki-kyu/npu_driver https://github.com/wangki-kyu/libedgetpu

libedgetpu 가 queue / status block 메모리 잡는 방식

먼저 정상 동작하는 libedgetpu가 instruction queue ring 과 status block 을 어떻게 잡는지 확인했다.소스 경로는 driver/kernel/kernel_coherent_allocator.cc 와 windows 전용 driver/kernel/windows/kernel_coherent_allocator_windows.cc 을 참고하면 된다.

 // kernel_coherent_allocator.cc:42~
  ioctl_buffer.enable = 1;
  ioctl_buffer.size   = size_bytes;   // 16KB (queue 4KB + status 4KB + padding)
  ioctl(fd, GASKET_IOCTL_CONFIG_COHERENT_ALLOCATOR, &ioctl_buffer);
  dma_address_ = ioctl_buffer.dma_address;   // ← coral.sys 가 dma_alloc_coherent 로 받은 PA

  // windows 전용
  apex_memmap_ioctl.dev_dma_addr = dma_address;
  ioctl(fd, GASKET_IOCTL_MAP_UMDMA_VIEW, &apex_memmap_ioctl);
  return (char*)apex_memmap_ioctl.virtaddr;   // user-mode UC view

요약하면 이렇다

• libedgetpu user-mode는 coral.sys 한테 IOCTL 로 위임
• coral.sys (kernel) 가 DMA-coherent (uncached) 메모리를 잡음 (linux의 dma_alloc_coherent 등가)
• 잡은 메모리를 user-mode 에 UC view로 mmap 해서 돌려줌

chip이 ring descriptor를 fetch 하거나 status block에 DMA write 할 때, CPU cache 와 sync 가 hardware 차원에서 보장 된다.

우리 driver의 문제

반면 우리 npu driver의 Device.c를 보면 두 군데가 그냥 cacheable pool 로 잡혀 있었다.

  // Device.c:593 (변경 전)
  deviceContext->DescRingBase = ExAllocatePoolWithTag(NonPagedPoolNx, PAGE_SIZE, 'DRNG');

  // Device.c:620 (변경 전)
  deviceContext->StatusBlockBase = ExAllocatePoolWithTag(NonPagedPoolNx, PAGE_SIZE, 'SBLK');

NonPagedPoolNx는 nonpaged (page-out 안됨) 이긴 한데 cache attribute 가 cacheable 이다. PCIe device가 직접 DMA write 한 데이터를 CPU가 cache 에서 stale 값 읽을 가능성이 있다.

가설은 두 가지이다.

1. status block stale read - chip 이 inference 끝나고 completed_head_pointer를 status block 에 write 해도, 우리 driver가 cache 에서 stale 0을 읽어서 completion 감지 못함
2. descriptor ring stale fetch - 우리가 cache 에만 descriptor 16b 를 write 하고 PCIe로 chip이 PA fetch 했을 때 stale garbage 를 가져감 -> 잘못된 DMA

증상이랑 부합한다.

수정 - alloc / free 교체

 1. DescRing 할당

  // Device.c:593 (변경 후)
  {
      PHYSICAL_ADDRESS lo, hi, none;
      lo.QuadPart   = 0;
      hi.QuadPart   = 0xFFFFFFFFLL;   // < 4GB. chip MMU 32-bit PA 제약
      none.QuadPart = 0;
      deviceContext->DescRingBase = MmAllocateContiguousMemorySpecifyCache(
          PAGE_SIZE, lo, hi, none, MmNonCached);
  }
  if (deviceContext->DescRingBase == NULL) {
      DbgPrint("[%s] Failed to allocate descriptor ring\n", __FUNCTION__);
      return STATUS_INSUFFICIENT_RESOURCES;
  }
  RtlZeroMemory(deviceContext->DescRingBase, PAGE_SIZE);

  hi.QuadPart = 0xFFFFFFFFLL 가 중요하다. chip MMU 가 32-bit PA 만 받기 때문에 4GB 미만 영역에서 잡아야 한다.

  2. StatusBlock 할당

  // Device.c:620 (변경 후)
  {
      PHYSICAL_ADDRESS lo, hi, none;
      lo.QuadPart   = 0;
      hi.QuadPart   = 0xFFFFFFFFLL;
      none.QuadPart = 0;
      deviceContext->StatusBlockBase = MmAllocateContiguousMemorySpecifyCache(
          PAGE_SIZE, lo, hi, none, MmNonCached);
  }
  if (deviceContext->StatusBlockBase == NULL) {
      DbgPrint("[%s] Failed to allocate status block\n", __FUNCTION__);
      MmFreeContiguousMemory(deviceContext->DescRingBase);   // ← 이것도 교체
      deviceContext->DescRingBase = NULL;
      return STATUS_INSUFFICIENT_RESOURCES;
  }

  3. Cleanup path

  ExFreePoolWithTag 였던 free 도 전부 MmFreeContiguousMemory 로 교체. tag 인자가 없어서 더 깔끔하다.

  // Device.c:1149 (변경 후)
  if (deviceContext->DescRingBase != NULL) {
      MmFreeContiguousMemory(deviceContext->DescRingBase);
      deviceContext->DescRingBase = NULL;
  }
  if (deviceContext->StatusBlockBase != NULL) {
      MmFreeContiguousMemory(deviceContext->StatusBlockBase);
      deviceContext->StatusBlockBase = NULL;
  }

결과

여전히 쓰레기 값이 나온다.. 또 다음 가설을 설정 후, 테스트해야겠다.. 화이팅

libedgetpu 코드 수정 및 빌드

https://github.com/wangki-kyu?tab=repositories 해당 github에 fork로 windows build가 성공되도록 수정해 놓았다. 원하는 로그 및 코드를 수정해서 테스트할 수 있는 환경이다.

libedgetpu에 코드를 추가한 뒤, docker를 통해 빌드를 했다. 명령어는 아래와 같다.

docker run --rm -v "E:/work/project/libedgetpu:C:/workspace" -w C:/workspace libedgetpu-windows:latest cmd /c build.bat

약 3~5분 정도 기다리면 빌드가 완료된다.

빌드된 결과물을 사용 환경으로 옮겨주는 작업을 해주면 된다.

input bin 생성하기

간단하게 coral.sys를 등록하고 추론을 돌려주면 된다.

현재 개발 중인 npu driver가 설치되어 있는데 이 부분을 google에서 제공해 주는 coral.sys로 업데이트 해주면 된다.

제거 후 업데이트하여 정상적으로 설치된 것을 확인할 수 있다.

python으로 미리 만들어놓은 코드를 사용해 얼굴 인식 추론을 하면 된다. 카리나 사진으로 테스트를 해보았다. 테스트 결과는 아래와 같다.

정상적으로 얼굴이 인식이 되었고 opencv를 활용해 인식된 Box 좌표로 얼굴 부분을 강조하도록 했다.

추가로 C:\temp\하위에 input bin파일이 생성된 것을 확인할 수 있다.

input bin 파일 읽어서 사용하기

기존 코드에 아래와 같이 define을 통해 분기 처리했다.

    #define USE_LIBEDGETPU_INPUT 1
    {
        UINT imgSide = static_cast<UINT>(std::sqrt(static_cast<double>(INPUT_SIZE) / 3.0));
        if (imgSide * imgSide * 3 != INPUT_SIZE) {
            std::cout << "[main] WARNING: input size " << INPUT_SIZE
                      << " is not square*3 — falling back to imgSide=" << imgSide << std::endl;
        }

#if USE_LIBEDGETPU_INPUT
        {
            const char* libe_input_path = "C:\\temp\\libe_input_raw.bin";
            FILE* f = nullptr;
            fopen_s(&f, libe_input_path, "rb");
            if (f) {
                size_t r = fread(pInputBuf, 1, INPUT_SIZE, f);
                fclose(f);
                std::cout << "[main] USE_LIBEDGETPU_INPUT=1 — loaded " << r << "/"
                          << INPUT_SIZE << " bytes from " << libe_input_path << std::endl;
                if (r != INPUT_SIZE) {
                    std::cout << "[main] FAIL: libe input file size mismatch — expected "
                              << INPUT_SIZE << " B" << std::endl;
                    goto cleanup;
                }
            } else {
                std::cout << "[main] FAIL: " << libe_input_path
                          << " not found — run libedgetpu first to generate it" << std::endl;
                goto cleanup;
            }
        }
#else
        std::cout << "[main] loading image (target " << imgSide << "x" << imgSide << ")" << std::endl;
        if (!LoadJpegToRGB(L".\\assets\\karina.jpg", pInputBuf, imgSide, imgSide)) {
            std::cout << "[main] FAIL: image load" << std::endl;
            goto cleanup;
        }
#endif
    }

빌드 후, 테스트를 진행하였다.

CRC 값은 0xf993d860로 동일하게 나왔는데 여전히 convert_scores값이 쓰레기 값이 나왔다.

결론

실제 추론이 성공하는 input data를 사용해서도 추론이 안된 것을 보면 npu driver에서 정상적으로 Weight(가중치) 값을 사용하지 못하거나, 추론이 정상적으로 발생되지 않는 것으로 볼 수 있다.

아쉽지만 좋은 시도였다..

다른 방법도 시도해 봐야겠다....

분석하기

분석하기 전에 아래와 같은 내용을 알아야 하는 것 같다.

정상 동작하는 코드와 npu driver 코드에 input dump 출력 코드를 작성하고 돌려서 비교했다.

libedgetpu CRC32=0xf993d860 TAIL: 00 00 00 00 00 00 00 ... npu_driver CRC32=0x68ea0706 TAIL: 34 3c 35 34 3c 35 34 ...

HEAD / MID 는 일치하는데 TAIL만 달랐다.

libedgetpu의 경우는 letterbox 방식이고 npu_driver에서는 stretch 방식의 resize를 하는 것 같다. SSD backbone은 receptive field가 전체 이미지라서 입력이 조금만 달라도 score head 전체가 흔들린다고 한다. 따라서 정상적으로 추론이 안될 수 있다.

결론

코드를 수정하여 동일한 포맷으로 만들었지만, 여전히 정확한 추론이 되지 않는다. 하나씩 다른 점을 찾아보면서 가설을 제거해 나가야겠다.

추론 값

위 사진은 추론 값이다. 이전에 발생했던 infeed fault 나 outfeed fault같은 에러가 발생하지 않았고 정상적으로 chip이 dma 방식으로 output buffer에 값을 적어준 것 을 확인할 수 있다.

일단 Squeeze1과 convert_scores는 SSD(SingleShot Multibox Dector계열의 객체 인식 모델에서 포스트 프로세싱 단계 직전의 raw data 상태일 때의 이름이다.

1. Sqeeuze1 (Bounding Box Locations) 모델이 예측한 각 Anchor Box들이 실제 객체의 위치에 맞게 수정된 좌표값이다.
2. convert_scores (Classification Scores) 이 텐서는 각 후보 박스가 특정 클래스(사물 종류)일 확률을 담고 있다.

가설 검증

param data를 chip이 읽지 않는지 검증하기 위해서 pte에 mapping된 param buffer를 0으로 채운 뒤, 추론을 돌려보았다.

memset(pParamData, 0x00, model.parameters.size());          // weight 를 전부 0 으로
memset(pExe0ParamData, 0x00, model.exe0_parameters.size()); // exe0 보조도 0

output buffer의 값이 변경된 것을 확인할 수 있다. 결론적으로 chip이 cache된 parameters 값을 참조하고 있다고 생각할 수 있다.

Sqeeuze1 정상인지 검사

python으로 해당 raw 데이터를 box 좌표로 변환해서 실제로 동일한 이미지 사진에 정상적으로 그려지는지 검증을 해보려고 한다. 하나씩 변수를 제거해나가는 부분이 이 작업의 매력인 것 같다. claude code를 적극적으로 사용하고 있다.

테스트 결과 아래와 같이 나왔다.

현재 Squeeze1값도 비정상이라는 것을 확인할 수 있다.

결론

chip이 비정상적인 추론 결과를 output buffer에 넣어준 거라고 봐야한다. 무엇이 잘못되었는지 좀 더 확인해 봐야겠다...

진행 상황

전체적인 플로우는 완성이 된 것 같다. 대략적인 작업 단계는 다음과 같다.

• contiguous allocate memory
• input, output 등 필요한 메모리 할당 및 memcpy
• tflite model bitstream patch
• coral tpu pte mapping
• 필요한 csr 초기화 및 세팅
• param cache descriptor 제출
• infer bitstream descriptor 제출
• descriptor 제출에 대한 interrupt 처리, isr, dpc
• 추론 데이터 확인하기 output buffer

중간중간에 더 많은 로직들이 필요하다. 오픈소스인 libedgetpu와 linux driver인 gasket을 참고를 많이 했다. 그리고 실제 windows driver인 coral.sys를 디컴파일링하여 ai agent에게 분석을 요청해 유의미한 값을 찾아내기도 하였다.

https://github.com/google-coral/libedgetpu https://github.com/google/gasket-driver

특히 libedgetpu의 소스를 수정하여 필요한 로그를 찍어서 확인해 보고 싶은 상황이 있었다. 그러나 해당 소스는 관리를 하지 않는 상태였다. 따라서 README에 나온 방식으로 빌드가 되지 않았다. 따라서 fork를 떠서 필요한 내용을 수정해서 빌드를 진행했고, 그 과정에서 docker windows container, docker build, bazel 등 여러 도구를 활용하여 빌드에 성공했고 로그를 남길 수 있었다. 해당 내용도 포스팅을 할 예정이다. libedgetpu docker + bazel build

이슈

bitstream align 6bit

가장 크게 막혔던 부분은 bitstream align 문제였다. 이것을 해결하기 위해 일주일은 넘는 시간이 소요되었다. libedgetpu에서 bitstream을 patch한 모습과 개발 중인 npu_driver에서 bitstream을 patch 한 모습을 비교하기 위해 full dump를 로깅하였고 유의미한 차이점을 발견하였다. libedgetpu에서는 6bit를 남겨두고 오프셋 위치에 정확히 patch를 하는데 우리 소스에서는 6bit 부분을 오버라이트하여 패치하는 문제가 있었던 것이다. 이 부분을 해결하니 output va로 값이 쓰여지지 않는 문제만 빼고는 해결이 되었다. bitstream align 문제 해결

Descriptor struct size issue

가속기(하드웨어)에게 일을 시키기 위해서는 descriptor를 제출해야 한다.

typedef struct {
                UINT64 address;
                UINT64 size_in_bytes;
                UINT32 reserved;
            } HOST_QUEUE_DESC;

위처럼 사용하고 있었는데 libedgetpu 소스에는 size_in_bytes의 타입이 UINT64가 아닌 UINT32여서 변경해 주었다.

그 외에도 많은 이슈가 있었다. 관련 내용들은 포스팅을 할 예정이다.

현재 상황

간단하게 로그를 보면 정확한 추론 값을 얻지 못하는 것을 확인할 수 있다.

얼굴 인식 모델이므로 박스 좌표 값을 얻어와야 한다. 위 내용을 해결하기 위해서 디버깅 및 시간을 투자해야 할 것 같다.

결론

완벽하지는 않지만 그래도 많은 진척이 있는 것 같다. 완벽히 이해를 했다기보다는 이제 좀 driver에 친숙해졌다? 라는 느낌이다. 빨리 정확한 추론 값을 얻어서 어플리케이션단에서 실시간으로 얼굴을 추론해 블러 처리하는 기능을 구현하고 싶다.

화이팅!

edgetpu compile 된 tflite

기본적인 tflite 파일의 경우 edgetpu compiler로 한 번 더 가공해 주어야 한다. 일반적인 CPU나 GPU와는 완전히 다른 Edge TPU만의 독특한 하드웨어 가속 구조에 맞춰 연산 과정을 최적화하고 배치하기 위해서이다. 특징을 표로 정리하면 아래와 같다.

fbs 파일 컴파일하여 header 파일 생성하기

libedgetpu 저장소 내의 executable.fbs는 일반적인 .tflite 모델을 위한 것이 아니라, 오직 Edge TPU 컴파일러를 거친 컴파일된 모델 전용이다. fbs 파일로 header 파일을 뽑아내야 하는데 그러기 위해서는 flatc.exe 컴파일러가 필요하다. Release에서 다운로드하여 설치할 수 있다.

flatc --cpp --gen-object-api --no-includes your_file.fbs

위 명령어를 통해서 .h파일을 뽑아낼 수 있다.

executable_generated.h 파일이 생성되는데 내부에서 flatbuffers dependency가 필요해서 FlatBuffers 소스의 include도 필요하다.

libedgetpu fbs 구조

우리는 tflite 모델의 bitstream을 구해야한다. 아래 스키마를 확인해보겠다.

// Holds information for an instruction bitstream chunk.
table InstructionBitstream {
  // Encoded bitstream for a real hardware.
  bitstream:[ubyte];

  // Offset (in bits) of various fields in the instruction bit stream. These
  // fields are filled in by the driver before sending the instruction stream
  // to the hardware.
  field_offsets:[FieldOffset];
}

field_offsets는 FieldOffset의 배열로 보인다. 그러면 FieldOffset을 확인해보면 된다.

// Holds offset information of a field in an instruction bit stream chunk.
table FieldOffset {
  // Linker metadata.
  meta:Meta;

  // Bit offset.
  offset_bit:int;
}

meta필드를 확인할 수 있다. 그러면 Meta가 무엇인지 확인해보자.

// Linker metadata. Enums for various special fields in the encoded instruction
// stream that will be populated by the driver at run time.
table Meta {
  // Indicates which base address this metadata is targeting.
  desc:Description;

  // For input/output/scratch, provides batch information.
  // Parameter will not contain batch.
  batch:int;

  // Name of the input/output layer for input/output activations. Parameter and
  // scratch should not have this field.
  name:string;

  // Tells which bit position to update.
  position:Position;
}

enum Description : short {
  // Bundle::Alu::MOVI instruction to load output activation base address.
  BASE_ADDRESS_OUTPUT_ACTIVATION = 0,

  // Bundle::Alu::MOVI instruction to load input activation base address.
  BASE_ADDRESS_INPUT_ACTIVATION = 1,

  // Bundle::Alu::MOVI instruction to load parameter base address.
  BASE_ADDRESS_PARAMETER = 2,

  // Bundle::Alu::MOVI instruction to load scratch buffer base address.
  BASE_ADDRESS_SCRATCH = 3,
}

enum Position : short {
  // Lower 32-bit of 64-bit address.
  LOWER_32BIT = 0,

  // Upper 32-bit of 64-bit address.
  UPPER_32BIT = 1,
}

Meta는 또 Descriptor 필드를 가지는데 이는 output, input 등 여러 정보에 대한 base address에 대한 정보인 것 같다. 즉 Descriptor를 보고서 해당 오프셋 위치에는 어떤 base address를 넣어야 하는지 결정할 수 있는 것이다.

정리를 하면, 각 모델마다 bitstream에 input, output, parameter, scratch에 대한 base address를 넣어주고 bitstream을 device에게 넘긴다. device(hardware)는 bitstream에서 필요한 주소를 얻어 host ram에 접근하여 cpu의 개입 없이 데이터를 가져오거나 쓸 수 있다.

결론

kmdf로 google coral tpu의 windows driver를 개발하고 있는데 bitstream을 넘기는 것부터가 고비였다. 하지만 조금씩 이해를 하고 있는 것 같다.

마치 protobuffer처럼 edgetpu는 FlatBuffers를 사용하는 것 같다. IDL에 대해 익숙하여 빨리 이해할 수 있었던 것 같다.

천천히 이해하면서 개발을 해야겠다.

Google Coral M.2 Accelerator

[정품] 구글 코랄 Coral 미니 PCIe M.2 가속기 B/M G650-04686-01 위 제품을 구매하였다. USB 모델도 있었지만 PCIe Driver를 만들어보기 위해서 해당 제품을 구매했다.

코랄은 4 TOPS의 연산 능력(Int8 특화)을 가진다. 일반적인 CPU나 GPU가 부동소수점 연산을 주로 하는 것과 달리, Edge TPU는 모델 양자화를 통해 크기를 줄인 모델을 극도로 빠르게 처리한다. MobileNet V2 기준 400FPS로 실시간 영상 분석 시 지연 시간이 거의 느껴지지 않는 수준이다.

이전 사용한 Pico와 달리 Coral은 진짜 딥러닝 모델등을 PC급 환경에서 실시간으로 돌리기 위한 도구이다.

Coral M.2 슬롯에 장착하기

사용 중인 메인보드를 확인하기 위해서 win+r을 누르고 아래와 같이 입력해주면 알 수 있습니다.

사용 중인 메인보드 스펙을 인터넷에서 찾아 몇 개의 M.2 슬롯을 제공해 주는지 확인해 볼 수 있다. 더 자세히 확인해 보고 싶다면 HWiINFO64를 설치하면 된다.

3개의 M.2 슬롯을 사용하고 있고 모두 SSD로 활용중이다. 남은 슬롯은 그래픽카드가 가리고 있어 분리 후 장착해 주었다.

장치 관리자에서 정상적으로 인식된 것을 확인했다.

문제 발생

USB 처럼 당연히 virtual box로 Passthrough가 될줄 알았는데 PCIe의 경우 현재 버전에서 지원을 하지 않는다고 한다. virtual box 6.x.x 버전에서 삭제되었는데 지원하더라도 linux만 지원을 한다고 했다.

vmware도 알아봤는데 역시나 일반적으로는 Passthrough가 어렵다고 하였다. 결국 방법은 메인 PC에 Coral TPU를 장착하여 사용하고 노트북에서 개발하여 원격으로 디버깅하거나 Coral을 장착한 새로운 PC가 필요했다.

다행히 집에 남는 Desktop이 있어서 코랄을 옮겨서 설치해준 뒤, 개발 환경을 구축해주었다.

원격 데스크톱 설정

virtual box가 아닌 실제 pc에 원격으로 접속해야 하므로 원격 데스크톱을 설정해 주었다. tailscale을 설치해 줘서 외부에서 원격으로 접속할 수 있도록 설정해 주었다. 노트북으로 카페나 외부에서 안전하게 접속할 수 있다. virtual box를 사용할 때는 노트북으로 외부에서 접속하기 까다로워서 불편했지만 이제는 손쉽게 이용할 수 있을 것 같다. 집에서는 내부망이므로 더욱 손쉽게 접근할 수 있다.

https://www.coral.ai/docs/m2/get-started/#2-install-the-pcie-driver-and-edge-tpu-runtime 위 문서를 확인하면 ProductID가 089a인 것을 확인할 수 있다. 실제로 확인해 보면 다음과 같다.

결론

역시 초기 세팅 및 환경설정이 개발의 절반이라는 게 맞는 말이다. Virtual Box에서 Passthrough가 되지 않아서 당황했지만 다행히 남는 pc가 있어서 무사히 세팅한 것 같다. Linux Driver는 OpenSource라서 참고하면서 KMDF로 DMA, ISR, DPC 등 여러 커널 드라이버 개발 방식을 배우며 만들어야겠다.

전체 흐름도

KMDF pico driver 구조

중요한 포인트는 어플리케이션에서 Interrupt read 관련 IOCTL 요청을 할 때 받은 reuqest를 바로 완료 처리하지 않고 PendingQueue에 담아준다. 그리고 pico mcu로부터 온도 센서 값을 수신할 때 호출되는 콜백에서 Pending Queue 내부의 request를 꺼내서 완료 처리해 주면 된다.

status = WdfIoQueueRetrieveNextRequest(pDeviceContext->PendingQueue, &request);
if (!NT_SUCCESS(status)) {
    DbgPrint("[picodriverEvtInterruptReadComplete] No pending request, discarding data\n");
    return;
}

// App의 output buffer에 interrupt 데이터 복사
status = WdfRequestRetrieveOutputBuffer(request, NumBytesTransferred, &outBuffer, NULL);
if (!NT_SUCCESS(status)) {
    DbgPrint("[picodriverEvtInterruptReadComplete] WdfRequestRetrieveOutputBuffer failed 0x%x\n", status);
    WdfRequestComplete(request, status);
    return;
}

RtlCopyMemory(outBuffer, WdfMemoryGetBuffer(Buffer, NULL), NumBytesTransferred);
WdfRequestCompleteWithInformation(request, STATUS_SUCCESS, NumBytesTransferred);

위 코드를 참고하면 된다.

결과적으로 어플리케이션 레벨에서 icotl로 요청한 request가 있어야 실시간으로 읽어갈 수 있는 점에서 bulk 통신으로 폴링 방식으로 읽는 방식과 크게 다르지는 않다.

*Application 레벨에서는 요청-응답 구조로 Polling과 유사해 보이지만, USB 버스 레벨에서는 디바이스가 준비됐을 때만 전송이 발생하므로 불필요한 버스 점유가 없다는 점에서 본질적으로 다르다. *

어플리케이션 구조

어플리케이션 레벨의 동작을 간략히 설명하겠다. OnInitDialoge에서 interrupt read init을 통해서 DeviceIoCotrol로 비동기 요청을 하고 콜백을 등록을 해준다. 콜백이 호출되면 postmessage를 통해서 gui thread로 메시지를 넘겨준다. 해당 메시지에 연결된 핸들러가 호출이 되면서 ui control을 업데이트해준다.

테스트

pico를 복합장치로 설정했기에 cdc 인터페이스로 시리얼 통신으로 실제 로그를 받아 볼 수 있다. pico에서 보내는 로그와 어플리케이션인 mfc에서 실시간으로 온도 데이터를 수신 테스트를 하였다. 중간에 이미지를 bulk endpoint로 보내서 얼굴 인식하도록 하였고 받은 추론 값으로 블러처리도 진행하였다. interrupt 방식은 문제 없는 것을 확인할 수 있다.

결론

pico mcu를 활용한 프로젝트를 마무리할 예정이다.

1. mcu 전용으로 만든 model embed
2. kmdf driver usb 개발
3. tinyusb를 활용하여 vendor specific, cdc interface로 복합 장치 구현
4. bulk, interrupt endpoint 통신

이외에도 정말 많은 시간이 들어갔다. led 디버깅을 하면서 불편해 cdc 인터페이스를 추가한 것, driver 개발하며 bosd 발생으로 windbg로 덤프 분석 및 실시간 커널 디버깅 등등 개발에 필요한 지식이 정말 많다는 것을 깨달았다. 프로젝트를 진행하며 https://www.youtube.com/@%EC%9D%B4%EB%B4%89%EC%84%9D-d6u 해당 유튜브 채널이 정말로 도움이 많이 되었다. windows kernel과 driver 개발이 접근하기 쉽지는 않다.

다음 프로젝트로는 실제 가속기를 활용할 예정이다. 위 가속기를 가지고 PCIe driver를 kmdf로 만들 것이다. usb보다 훨씬 난이도가 높다고 한다. 화이팅!

https://github.com/wangki-kyu/pico_usb_vendor https://github.com/wangki-kyu/pico_driver

interrupt endpoint 추가

vendor specific interface에 interrupt endpoint를 추가한 뒤, 다시 장치 인식을 시켜주었다.

const uint8_t desc_configuration[] = {
    // Config number, interface count, string index, total length, attribute, power in mA
    TUD_CONFIG_DESCRIPTOR(1, ITF_NUM_TOTAL, 0, CONFIG_TOTAL_LEN, 0x00, 100),

    // CDC first (IAD is automatically included by TUD_CDC_DESCRIPTOR)
    TUD_CDC_DESCRIPTOR(ITF_NUM_CDC_CMD, 0, EPNUM_CDC_NOTIF, 8, EPNUM_CDC_OUT, EPNUM_CDC_IN, 64),

    // 2. Vendor Interface (수동 정의)
    // Interface Descriptor
    9, TUSB_DESC_INTERFACE, ITF_NUM_VENDOR, 0, 3, // bNumEndpoints를 3으로 설정 (Bulk 2 + Int 1)
    TUSB_CLASS_VENDOR_SPECIFIC, 0x00, 0x00, 0,    // Vendor Class, Subclass, Protocol, String Index

    // Endpoint: Bulk IN
    7, TUSB_DESC_ENDPOINT, EPNUM_VENDOR_IN, TUSB_XFER_BULK, 64, 0, 0,
    // Endpoint: Bulk OUT
    7, TUSB_DESC_ENDPOINT, EPNUM_VENDOR_OUT, TUSB_XFER_BULK, 64, 0, 0,
    // Endpoint: Interrupt IN (온도 데이터용)
    7, TUSB_DESC_ENDPOINT, EPNUM_VENDOR_INT_IN, TUSB_XFER_INTERRUPT, 8, 0, 10
};

장치 관리자에서 정상으로 인식이 되어, usbview로 확인해보았다.

정상적으로 Endpoint가 추가된 것을 확인할 수 있다.

온도 센서 보내기

문제가 발생하였다.

void send_temperature_data_interrupt(float temperature)
    {
        static uint8_t data[3];
        data[0] = 0xBB;                                                  // Different marker for interrupt data
        data[1] = (uint8_t)temperature;                                  // Integer part
        data[2] = (uint8_t)((temperature - (uint8_t)temperature) * 100); // Fractional part

        // Use low-level endpoint transfer API for interrupt endpoint
        if (!usbd_edpt_busy(0, EPNUM_VENDOR_INT_IN))
        {
            usbd_edpt_xfer(0, EPNUM_VENDOR_INT_IN, data, sizeof(data));
            printf("[TEMP] Interrupt sent: %.2f°C\n", temperature);
            fflush(stdout);
        } else {
            printf("EP 0x84 is busy!\n");
            fflush(stdout);
        }
    }

위처럼 코딩을 한 뒤, main loop에서 1초마다 호출하도록 설정했는데 장치가 인식을 하지 못하였다. usbd_edpt_xfer 함수를 주석하니 아래와 같이 cdc로 로그를 확인할 수 있었다.

온도 센서로부터 정상으로 데이터를 읽어 보내주는 것을 확인하였다. interrupt가 bulk랑 같이 동시에 잘 동작하는지 확인하기 위해서 얼굴 인식 추론을 하였다.

이미지의 얼굴 부분을 얼추 인식하여 블러처리한 결과이다. 그런데 로그를 확인해보니 이상한 점을 발견하였다.

분명 bulk endpoint를 통해서 추론 결과 값을 전달해주는데 interrupt endpoint가 busy한 상태가 되었다.

곰곰히 생각을 해보니 endpoint를 추가해주면서 kmdf driver 단에서 read pipe에 문제가 생겼을 수 있다는 생각을 하였다. pico_driver 코드를 확인해보니 역시나 read pipe가 interrupt endpoint로 설정되고 있었다.

// Get pipes
for (pipeIndex = 0; pipeIndex < numEndpoints; pipeIndex++) {
    WDF_USB_PIPE_INFORMATION pipeInfo;
    WDFUSBPIPE pipe;

    WDF_USB_PIPE_INFORMATION_INIT(&pipeInfo);
    pipe = WdfUsbInterfaceGetConfiguredPipe(usbInterface, pipeIndex, &pipeInfo);

    if (pipe != NULL) {
        DbgPrint("Pipe %d: EndpointAddress=0x%02x, Direction=%s\n",
            pipeIndex,
            pipeInfo.EndpointAddress,
            USB_ENDPOINT_DIRECTION_IN(pipeInfo.EndpointAddress) ? "IN" : "OUT");

        // Store bulk IN and OUT pipes
        if (USB_ENDPOINT_DIRECTION_IN(pipeInfo.EndpointAddress)) {
            pDeviceContext->ReadPipe = pipe;
            DbgPrint("Stored READ pipe (IN endpoint 0x%02x)\n", pipeInfo.EndpointAddress);
        }
        else {
            pDeviceContext->WritePipe = pipe;
            DbgPrint("Stored WRITE pipe (OUT endpoint 0x%02x)\n", pipeInfo.EndpointAddress);
        }
    }
}

windbg로 로그를 확인해 보니 아래와 같다.

마지막에 read pipe로 0x84를 저장하는 것을 확인했다. interrupt read pipe를 context에 저장하도록 로직을 변경해 주면 될 것 같다.

kmdf 소스 수정

if (pipe != NULL) {
    DbgPrint("Pipe %d: EndpointAddress=0x%02x, Direction=%s\n",
        pipeIndex,
        pipeInfo.EndpointAddress,
        USB_ENDPOINT_DIRECTION_IN(pipeInfo.EndpointAddress) ? "IN" : "OUT");

    // Store bulk IN and OUT pipes
    if (USB_ENDPOINT_DIRECTION_IN(pipeInfo.EndpointAddress)) {
        if (pipeInfo.EndpointAddress == 0x83) {
            pDeviceContext->ReadPipe = pipe;
            DbgPrint("Stored READ pipe (IN endpoint 0x%02x)\n", pipeInfo.EndpointAddress);
        }
        else if (pipeInfo.EndpointAddress == 0x84) {
            pDeviceContext->InterruptReadPipe = pipe;
            DbgPrint("Stored Interrupt READ pipe (IN endpoint 0x%02x)\n", pipeInfo.EndpointAddress);
        }
    }
    else {
        pDeviceContext->WritePipe = pipe;
        DbgPrint("Stored WRITE pipe (OUT endpoint 0x%02x)\n", pipeInfo.EndpointAddress);
    }
}

typedef struct _DEVICE_CONTEXT
{
    WDFUSBDEVICE UsbDevice;
    WDFUSBINTERFACE UsbInterface;
    WDFUSBPIPE WritePipe;
    WDFUSBPIPE ReadPipe;
    WDFUSBPIPE InterruptReadPipe;
    ULONG PrivateDeviceData;  // just a placeholder

} DEVICE_CONTEXT, *PDEVICE_CONTEXT;

InterruptReadPipe를 추가해 주었다. windbg로 로그를 확인해 보면 정상적으로 잘 저장된 것을 확인할 수 있다.

interrupt endpoint와 bulk endpoint가 각각 동작하는지 테스트해 보았다.

사소한 이슈가 하나 더 발생하였다. 시작부터 busy가 발생하였다. 문제는 pico 쪽에서 사용하는 tud_vendor_n_write 함수에 있었다. vendor_specific의 경우 기본적으로 out endoint 1, in endpoint 1로 구성하는 게 기본이다. 현재 2개의 in endpoint가 설정되어 있기에 늦게 설정된 0x84 interrupt endpoint로 내보내고 있던 것이었다.

따라서 api가 아닌 더 저수준의 함수를 호출하도록 변경했다.

if (!usbd_edpt_busy(0, 0x83)) {
    usbd_edpt_claim(0, 0x83);
    usbd_edpt_xfer(0, 0x83, response, 64);
}

다시 테스트를 진행하엿다.

bulk endoint와 interrupt endpoint가 각각의 transfer 통로로 동작하는 것을 확인하였다.

문제점2

여전히 busy가 발생하며 통신이 되지 않았다. 찾아보니 usb 인터럽트는 장치가 호스트를 방해해서 먼저 말을 거는 게 아니라, 호스트가 아주 짧은 간격으로 계속 물어봐 주는 정기점검 방식이라고 한다. 완전 착각하고 있었다. 즉, kmdf pico driver에서 interrupt read pipe로 읽고 있지 않아서 발생한 문제라고 판단했다.

UNREFERENCED_PARAMETER(Device);
NTSTATUS status;
WDF_USB_CONTINUOUS_READER_CONFIG readerConfig;
ULONG bufferSize = 64;  // Typical interrupt endpoint size

DbgPrint("[picodriverStartInterruptRead] Starting interrupt continuous reader\n");

// Configure continuous reader
WDF_USB_CONTINUOUS_READER_CONFIG_INIT(&readerConfig,
                                     picodriverEvtInterruptReadComplete,
                                     DeviceContext,
                                     bufferSize);

// Set number of reader buffers (WDF will manage multiple buffers)
readerConfig.NumPendingReads = 2;

// Start the continuous reader (configure it first)
status = WdfUsbTargetPipeConfigContinuousReader(
    DeviceContext->InterruptReadPipe,
    &readerConfig
);

if (!NT_SUCCESS(status)) {
    DbgPrint("[picodriverStartInterruptRead] WdfUsbTargetPipeConfigContinuousReader failed 0x%x\n", status);
    return status;
}

DbgPrint("[picodriverStartInterruptRead] Continuous reader configured\n");

// CRITICAL: Start the I/O target to actually begin polling the interrupt endpoint
// Without this, the host will NOT send IN tokens to the device
status = WdfIoTargetStart(WdfUsbTargetPipeGetIoTarget(DeviceContext->InterruptReadPipe));

if (!NT_SUCCESS(status)) {
    DbgPrint("[picodriverStartInterruptRead] WdfIoTargetStart failed 0x%x\n", status);
    return status;
}

DbgPrint("[picodriverStartInterruptRead] I/O Target started - polling interrupt endpoint (0x84)\n");
return STATUS_SUCCESS;

WdfUsbTargetPipeConfigContinuousReader를 등록해 주고 WdfIoTargetStart을 호출해 주면 pico 쪽에서 설정한 주기로 읽어온다고 한다.

테스트를 해보았다.

windbg driver log

pico 0x84 interrupt endpoint send

정상으로 보내는 것을 확인했다.

변경된 소스는 깃헙에서 확인할 수 있다.

https://github.com/wangki-kyu/pico_usb_vendor https://github.com/wangki-kyu/pico_driver

결론

usb 인터럽트는 일반적으로 하드웨어 인터럽트와는 다른 개념인 것 같다. 문제를 해결해 나가는 게 정말 재밌는 것 같다. 이제 어플리케이션 레벨에서 실시간 온도를 읽어서 gui로 보여주는 것을 개발하고 마무리하려고 한다.

문제점

현재 pico에 tinyusb를 사용하여 vendor specific interface로 driver와 통신하고 있다. 개발을 진행하며 너무나 불편한 점이 많았다. pico에 올린 펌웨어 내용을 디버깅할 수 없었다. 익숙한 개발 환경이 아니라서 잘 못하는 걸 수도 있는데 일단 한번 올리고 나면 디버깅을 하기 힘들었다. LED 색상을 통해 해봤는데 컴퓨터를 부실뻔했다.

USB 복합 장치 구성하기

그래서 찾아보니 USB 장치의 경우 물리적 하드웨어 내에 여러 개의 인터페이스가 존재한다. 호스트(PC)에 연결했을 때, 장치 관리자에서 CDC 용 가상 COM 포트와 Vendor-Specific 장치가 각각 독립적으로 나타날 수 있다고 한다.

위 사진처럼 USB Composite Device 하위에 여러 장치가 나타나는 것을 말한다. pico의 경우 printf를 호출하면 내부적으로 표준 출력(stdout)이 USB CDC Serial로 리다이렉션되어 PC의 터미널에서 내용을 볼 수 있다고 한다.

소스레벨에서는 tusb_config.h와 usb_descriptor.c를 수정해주면 된다. 자세한 내용은 깃헙을 참조하면 된다. https://github.com/wangki-kyu/pico_usb_vendor

Serial 연결 하기

pico에 소스를 올리게 되면 다음과 같은 동작을 예상할 수 있다. vendor specific interface로 인식된 장치의 경우 직접 만든 driver가 올라갈 것이고 CDC 인터페이스는 usbser.sys 드라이버가 자동을 로드되어 가상 COM 포트를 생성할 것이다.

장치 관리자를 확인해보니 정확히 로드가 잘 된 것을 확인할 수 있다.

속성에서 하드웨어 ID를 확인해 보면 기존과 다르게 MI_02가 붙은 것을 확인할 수 있다. Multiple Interface의 약자로 해당 장치가 복합 장치일 때, 몇 번째 인터페이스인지를 나타내는 식별자라고 한다.

USB Device Viewer를 확인해 보면 정확히 볼 수 있다.

InterfaceNuber가 0x02이고 InterfaceClass가 0xFF로 vendor specific인 것을 확인할 수 있다. 동일하게 가상 COM 장치도 확인해보겠다.

역시 MI_00이 붙은 것을 확인할 수 있다. USB Device Viewer로 확인해보면 아래와 같다.

python으로 serial 읽기

pico에서의 설정은 깃헙을 참조하면 된다. printf를 호출했을 때 Serial로 받을 수 있으므로 테스트를 해봐야 한다.

import serial
import time

# 포트 설정 (COM27)
PORT = 'COM27'
BAUD = 115200

try:
    # timeout을 설정해야 장치가 응답 없을 때 무한 대기에 빠지지 않습니다.
    ser = serial.Serial(PORT, BAUD, timeout=1)
    print(f"Connected to {PORT}")

    while True:
        if ser.in_waiting > 0:  # 읽을 데이터가 있을 때만 처리
            try:
                # decode('utf-8', 'ignore')를 써야 이상한 바이트가 섞여도 안 죽습니다.
                line = ser.readline().decode('utf-8', 'ignore').strip()
                if line:
                    print(f"[LOG] {line}")
            except Exception as e:
                print(f"Read error: {e}")

        time.sleep(0.01)  # CPU 점유율 과다 방지

except serial.SerialException as e:
    print(f"Could not open port {PORT}: {e}")
except KeyboardInterrupt:
    print("\nStop logging.")
finally:
    if 'ser' in locals() and ser.is_open:
        ser.close()

PORT는 현재 가상 장치의 COM을 확인하고 입력해 주면 된다. 실행해 주면 정상적으로 COM27에 연결이 된 것을 확인할 수 있다.

test 영상입니다.

https://github.com/wangki-kyu/pico_usb_vendor https://github.com/wangki-kyu/pico_driver

결론

led 디버깅으로 답답한 부분을 해결할 수 있었다. 기존에 이미지 추론이 되지 않아서 너무 답답했는데 이유를 알 수가 없었다. 로깅으로 확인하니 이미지가 정상적으로 수신되고 있지 않았다.

cmd + image data를 붙여서 보냈는데 모든 수신에서 cmd를 체크하니 정상적인 로직을 태우지 못했던 것이다. 수정을 하여 정상으로 수신하도록 하였다.

cdc를 통한 디버깅을 할 수 있음으로 인해 개발 난이도가 확 낮아진 느낌이다. 나이스

Dump 설정 방법

VM에서 bsod가 발생했다. 별다른 설정한적 없었지만 C:\windows를 확인하니 MiniDump 폴더에 미니 덤프가 생성된 것을 확인할 수 있다.

레지스트리에서 HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\CrashControl 경로에서 덤프 저장 경로 및 덤프 파일 종류를 설정할 수 있다.

CrashDumpEnabled가 3으로 설정된 것은 MiniDump를 생성한다는 의미이다. https://learn.microsoft.com/ko-kr/troubleshoot/windows-server/performance/memory-dump-file-options 공식 사이트에서 자세한 내용을 확인할 수 있다.

MiniDump 분석하기

!analyze -v

첫 번째로 해야하는 것은 !analyze -v 명령어를 통해서 분석을 하는 것이다.

공부를 하면서 안것인데 빨간 박스인 WDF_VIOLATION (10d)가 오류가 난 원인인 것이다. Bug Check Code라고도 하는데 MSDN을 통해 보면 각 코드에 대해서 Argument가 정의 되어있다. https://learn.microsoft.com/ko-kr/windows-hardware/drivers/debugger/bug-check-0x10d---wdf-violation

Arg1이 0x3이므로 Arg2가 WDFREQUEST HANDLE인 것을 확인할 수 있다. 즉 이번 fault가 발생한 원인은 미해결 참조 때문이고 Arg3를 보면 남아있는 참조 수가 1이라고 나와있는 것을 볼 수 있다.

이 힌트를 보고 대략적으로 왜 문제가 발생했는지 1차적으로 알 수 있다.

k(호출스택) 확인

k 명령어를 입력하면 호출스택을 확인할 수 있다.

pdb를 symbol로 등록해놓은 상태라서 정확히 개발 중인 pico_driver의 어떤 함수에서 발생한지 확인할 수 있다. PicoInferenceReadComplete함수에서 발생한 것을 한눈에 확인할 수 있다.

소스 분석

IOCTL을 처리하는 소스에 브레이크를 잡은 뒤, 다시 상황을 재현하기 위해서 재시작하여 windbg로 분석한다.

dv 명령어로 현재 로컬 변수들을 확인할 수 있다. mfc에서 image 64*64 bytes + cmd 구조로 총 4097 byte를 보냈는데 정확한 것을 확인할 수 있다.

PINFERENCE_CONTEXT infContext = (PINFERENCE_CONTEXT)ExAllocatePoolWithTag(NonPagedPool, sizeof(INFERENCE_CONTEXT), 'ifnc');
if (!infContext) {
    DbgPrint("[pico_driver] ERROR: Failed to allocate inference context\n");
    status = STATUS_INSUFFICIENT_RESOURCES;
    WdfRequestComplete(Request, status);
    return;
}

Context를 만들어서 힙 할당을 통해서 Request를 새로 만들어주는 로직을 사용했다. 그러나 디버깅을 통해 확인할 결과 Request는 Complete Rountine에 등록한 콜백함수의 매개변수로 동일한 Request가 들어온다는 것을 확인하여 재사용하도록 했다.

위 다이어그램의 흐름처럼 정상적으로 동작하는 것을 확인하였다.

결론

커널 crash가 발생하여 bsod가 발생하든 appication을 개발 중 process가 crash가 발생하든 dump를 분석하여 어느 곳에서 문제가 발생했는지 분석할 수 있다는 자신감이 있는 것 같다. 물론 모든 명령어를 알지는 못하지만 ai를 활용하여 검색하면서 디버깅한다면 해결할 수 있을 것이다.

pico driver 개발 흐름

1단계: Device 생성

PnP 매니저가 새 하드웨어를 감지하면 디바이스 생성을 요청한다. 드라이버는 WDFDEVICE 객체를 만들고 EvtDevicePrepareHardware 콜백을 등록한다.

2단계: 리소스 할당 및 Pipe 저장

이 단계가 중요하다. 시스템 디바이스에 I/O 리소스를 할당한 후 호출된다. 드라이버는 이 콜백에서 USB 인터페이스와 엔드포인트 정보를 얻을 수 있다. 여기서 device conetxt에 앞으로 통신에 활용할 Pipe를 저장한다. 이렇게 해야 이후에 IOCTL 요청이 들어왔을 때, Context에서 꺼내 Bulk 통신을 진행할 수 있다.

user mode application

user mode에서 IOCTL 요청으로 led를 제어할 수 있도록 간단하게 코드를 작성했다.

int main()
{
    std::cout << "Pico Driver Test Application" << std::endl;
    std::cout << "=============================" << std::endl;

    // Find and open the pico driver device
    HANDLE hDevice = FindPicoDriverDevice();

    if (hDevice != INVALID_HANDLE_VALUE) {
        std::cout << "\nDriver handle obtained successfully!" << std::endl;

        // LED Control Examples
        DWORD bytesReturned = 0;
        UCHAR command = 0;
        UCHAR status = 0;

        // Turn LED ON
        std::cout << "\nTurning LED ON..." << std::endl;
        command = LED_ON;
        if (DeviceIoControl(hDevice, IOCTL_PICO_TEST_WRITE, &command, sizeof(command), NULL, 0, &bytesReturned, NULL)) {
            std::cout << "LED ON - Success!" << std::endl;
        } else {
            std::cerr << "LED ON - Failed: " << GetLastError() << std::endl;
        }

        Sleep(1500);

        // Turn LED OFF
        std::cout << "\nTurning LED OFF..." << std::endl;
        command = LED_OFF;
        if (DeviceIoControl(hDevice, IOCTL_PICO_TEST_WRITE, &command, sizeof(command), NULL, 0, &bytesReturned, NULL)) {
            std::cout << "LED OFF - Success!" << std::endl;
        } else {
            std::cerr << "LED OFF - Failed: " << GetLastError() << std::endl;
        }

        CloseHandle(hDevice);
    } else {
        std::cerr << "\nFailed to find or open the pico driver device." << std::endl;
        return 1;
    }

    MessageBox(NULL, L"test", L"test", 0);

    return 0;
}

FindPicoDriverDevice() 이 함수는 root_path/include/utils.hpp 에 작성해두었다. GUID를 활용하여 Device Handle을 얻어오는 함수이다. 빌드를 한 후 vm으로 파일을 옮겨서 테스트 해보았다.

driver github

문제 발생

LED를 켜기 위해서는 0x01 1바이트를 던져주면 되는데 pico에서 반응이 없었다. 그리고 device handle을 얻은 뒤 최초 ioctl 요청은 성공했는데 두 번째 요청에서 timeout을 걸어도 아무런 반응이 없었다. windbg로 디버깅을 해도 잡을 수 없었다.

하드웨어 스펙 차이 명시

일단 첫 번째 문제는 하드웨어 타겟에 맞지 않는 PIN 번호 설정이었다. 실제로 내가 산 pico 보드는 Waveshare RP2040 Zero 모델인데 기본 Pico 보드의 내장 led pin을 사용하고 있어서 25 -> 16으로 변경해주었다.

LED 구동 방식의 차이(WS2812B)

일반적인 LED는 단순히 High/Low 신호만 주면 켜지지만, WS2812B ARGB는 데이터라인 하나로 색상 정보를 직렬 전송해야 하는 프로토콜 기반 LED이다. 단순히 핀을 켜는 것이 아니라, Pico SDK에서 제공하는 PIO나 전용 라이브러리를 사용하여 타이밍에 맞춰 데이터를 밀어 넣어줘야 한다.

초기화 시 동작 확인

보드가 정상적으로 동작하고 로드가 되었는지 확인하기 위해서 LED 점멸 3회를 하도록 코드에 넣어줬다.

for (int i = 0; i < 3; i++) {
        // Turn LED on
        led_on();
        sleep_ms(200);  // Wait 200ms with LED on

        // Turn LED off
        led_off();
        sleep_ms(200);  // Wait 200ms with LED off
    }

buffer 초기화

첫 번째 LED ON 명령: 성공 두 번째 LED OFF 명령: 무한 대기 (타임아웃)

TinyUSB의 OUT endpont 수신 콜백에서 하드웨어 버퍼를 명시적으로 비우지 않아 발생한 문제이다.

// 기존
void tud_vendor_rx_cb(uint8_t itf, uint8_t const* buffer, uint16_t bufsize) {
    // buffer 파라미터로만 데이터 읽음
    uint8_t command = buffer[0];

    // ❌ 하드웨어의 실제 버퍼는 여전히 "데이터 있음" 상태
    // ❌ OUT endpoint는 "아직 처리 중" 상태로 유지됨
}

// 수정 후 
void tud_vendor_rx_cb(uint8_t itf, uint8_t const* buffer, uint16_t bufsize) {
    // Explicitly read from buffer to clear hardware buffer and arm OUT endpoint
    uint8_t dummy[64];
    tud_vendor_n_read(itf, dummy, bufsize);

    // Extract command byte from read data
    uint8_t command = dummy[0];

    // Queue command for main loop to process
    // This avoids blocking operations in USB interrupt handler
    if (command <= 0x02) {  // Valid commands: 0x00, 0x01, 0x02
        pending_command = command;
    }
}

tud_vendor_n_read 을 명시적으로 호출해 주어서 매개변수로 받아온 버퍼의 데이터를 임시 버퍼로 옮겨준다. 물론 성능을 위해서는 최소한의 copy를 해야 하지만 지금은 테스트성으로 만드는 것이므로 추후에 성능 최적화는 할 예정이다.

문제 해결

하드웨어 버퍼를 명시적으로 비우니 정상적으로 동작이 되었다. 간단하게 MFC로 만들어서 테스트도 해보았다.

테스트 영상

https://github.com/wangki-kyu/pico_usb_vendor https://github.com/wangki-kyu/pico_driver