PALLOCATE_CONTIGUOUS_DMA_BUFFER 콜백 함수(hdaudio.h)

아티클
08/07/2023

루틴은 AllocateContiguousDmaBuffer 물리적 메모리의 연속된 단일 블록으로 구성된 DMA 버퍼를 할당합니다.

루틴에 대한 AllocateContiguousDmaBuffer 함수 포인터 형식은 다음과 같이 정의됩니다.

구문

PALLOCATE_CONTIGUOUS_DMA_BUFFER PallocateContiguousDmaBuffer;

NTSTATUS PallocateContiguousDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
        ULONG RequestedBufferSize,
  [out] PVOID *DataBuffer,
  [out] PHDAUDIO_BUFFER_DESCRIPTOR *BdlBuffer
)
{...}

매개 변수

[in] _context

HDAUDIO_BUS_INTERFACE_BDL 구조체의 Context 멤버에서 컨텍스트 값을 지정합니다.

[in] Handle

DMA 엔진 식별을 처리합니다. 이 핸들 값은 AllocateCaptureDmaEngine 또는 AllocateRenderDmaEngine에 대한 이전 호출에서 가져옵니다.

RequestedBufferSize

요청된 버퍼 크기를 바이트 단위로 지정합니다.

[out] DataBuffer

데이터 버퍼를 검색합니다. 이 매개 변수는 루틴이 데이터 버퍼의 시스템 가상 주소를 쓰는 호출자가 할당한 PVOID 변수를 가리킵니다.

[out] BdlBuffer

버퍼 설명자 목록(BDL)을 검색합니다. 이 매개 변수는 루틴이 BDL의 시스템 가상 주소를 쓰는 호출자가 할당한 PVOID 변수를 가리킵니다. BDL 할당 크기는 정확히 하나의 메모리 페이지이며 BDL은 페이지 경계에서 시작됩니다.

반환 값

AllocateContiguousDmaBuffer 는 호출이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 루틴이 적절한 오류 코드를 반환합니다. 다음 표에서는 가능한 반환 상태 코드 중 일부를 보여 줍니다.

반환 코드	설명
STATUS_UNSUCCESSFUL	호출자가 너무 높은 IRQL(인터럽트 요청 수준)에서 실행 중임을 나타냅니다.
STATUS_INSUFFICIENT_RESOURCES	버퍼 할당이 실패했음을 나타냅니다.
STATUS_INVALID_HANDLE	핸들 매개 변수 값이 잘못되었음을 나타냅니다.
STATUS_INVALID_PARAMETER	매개 변수 값 중 하나가 잘못되었음을 나타냅니다(잘못된 포인터).
STATUS_DEVICE_NOT_READY	하드웨어 프로그래밍 시간이 초과되었음을 나타냅니다. 이 경우 하드웨어가 손상된 상태일 수 있습니다.
STATUS_INVALID_DEVICE_REQUEST	스트림이 다시 설정 상태가 아니거나 버퍼가 DMA 엔진에 이미 할당되었음을 나타냅니다.

설명

루틴 AllocateContiguousDmaBuffer 은 SetupDmaEngineWithBdl 및 FreeContiguousDmaBuffer 루틴과 함께 사용됩니다. 이러한 세 가지 루틴은 hd Audio DDI의 HDAUDIO_BUS_INTERFACE_BDL 버전에서만 사용할 수 있습니다. 이 DDI에는 , SetupDmaEngineWithBdl 및 FreeContiguousDmaBuffer와 함께 AllocateContiguousDmaBuffer사용되지 않는 AllocateDmaBuffer 및 FreeDmaBuffer 루틴이 포함되지 않습니다. 이전에 할당된 DMA 버퍼를 사용하도록 DMA 엔진을 구성하는 SetupDmaEngineWithBdl과 달리 둘 다 DMA 버 AllocateDmaBuffer 퍼를 할당하고 버퍼를 사용하도록 DMA 엔진을 구성합니다. 자세한 내용은 두 DDI 버전 간의 차이점을 참조하세요.

AllocateContiguousDmaBuffer 는 지정된 DMA 엔진에 대한 데이터 버퍼를 할당합니다. 또한 BDL에 대한 메모리 페이지를 할당합니다. 호스트 프로세서 아키텍처에 따라 일반적인 페이지 크기는 4,096바이트 또는 8,192바이트일 수 있습니다. 데이터 버퍼는 물리적 메모리의 연속된 단일 블록으로 구성됩니다.

handle 매개 변수는 데이터 버퍼 및 BDL을 사용하는 DMA 엔진을 지정합니다. 루틴은 DMA 엔진의 크기, 맞춤 및 위치 요구 사항을 충족하는 스토리지를 할당합니다.

루틴이 데이터 버퍼 및 BDL에 할당하는 스토리지는 초기화되지 않습니다. 함수 드라이버는 SetupDmaEngineWithBdl 루틴에 제출하기 전에 BDL을 입력해야 합니다. 또한 함수 드라이버는 코덱을 프로그래밍하여 데이터 전송을 관리하고 스트림 식별자를 인식합니다.

정확한 간격으로 IOC 인터럽트 생성을 위해 함수 드라이버는 데이터 버퍼 할당을 특정 크기의 여러 조각으로 나누어야 할 수 있습니다. 각 조각은 BDL 항목으로 설명됩니다. 조각 크기를 조정하여 인터럽트 속도를 조정할 수 있습니다. 인텔 고화질 오디오 사양( Intel HD 오디오 웹 사이트 참조)에 따르면 각 조각은 128 바이트 경계에서 시작해야 하지만 이러한 맞춤 요구 사항은 조각의 길이에 적용되지 않습니다. 따라서 한 조각의 끝과 다음 조각의 시작 사이에 간격이 있을 수 있습니다. SetupDmaEngineWithBdl을 호출할 때 함수 드라이버는 BDL 항목에서 설명하는 개별 조각의 크기 합계를 나타내는 bufferSize 매개 변수의 값을 지정해야 합니다. 이 크기는 루틴의 requestedBufferSize 매개 변수에 AllocateContiguousDmaBuffer 지정된 바이트 수보다 작거나 같습니다.

DMA 엔진 핸들의 수명 동안 를 AllocateContiguousDmaBuffer 연속적으로 호출하여 새 DMA 버퍼를 할당할 수 있습니다. 그러나 를 호출 AllocateContiguousDmaBuffer하기 전에 이전에 할당된 DMA 버퍼는 먼저 FreeContiguousDmaBuffer를 호출하여 해제해야 합니다.

, SetupDmaEngineWithBdl 및 FreeContiguousDmaBuffer를 호출AllocateContiguousDmaBuffer하는 동안 DMA 엔진은 다시 설정 스트림 상태여야 합니다. DMA 엔진은XxxDmaEngine 할당 호출 직후 다시 설정 상태입니다. DMA 엔진을 실행 상태로 변경하려면 SetDmaEngineState를 호출합니다.

이 루틴은 실패하고 다음 상황 중 하나에서 STATUS_INVALID_DEVICE_REQUEST 오류 코드를 반환합니다.