PALLOCATE_DMA_BUFFER 콜백 함수(hdaudio.h)

아티클
02/26/2024

루틴은 AllocateDmaBuffer DMA 엔진에 대한 시스템 메모리에 데이터 버퍼를 할당합니다.

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

구문

PALLOCATE_DMA_BUFFER PallocateDmaBuffer;

NTSTATUS PallocateDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  SIZE_T RequestedBufferSize,
  [out] PMDL *BufferMdl,
  [out] PSIZE_T AllocatedBufferSize,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

매개 변수

[in] _context

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

[in] Handle

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

[in] RequestedBufferSize

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

[out] BufferMdl

할당된 버퍼가 포함된 실제 메모리 페이지를 검색합니다. 이 매개 변수는 루틴이 버퍼를 설명하는 MDL(메모리 설명자 목록)에 대한 포인터를 쓰는 호출자 할당 PMDL 변수를 가리킵니다.

[out] AllocatedBufferSize

할당된 버퍼 크기(바이트)를 검색합니다. 이 매개 변수는 호출자가 할당한 SIZE_T 변수를 가리키며, 이 변수는 루틴이 할당된 버퍼의 크기를 씁니다.

[out] StreamId

스트림 식별자를 검색합니다. 이 매개 변수는 루틴이 스트림에 할당하는 스트림 식별자를 작성하는 호출자가 할당한 UCHAR 변수를 가리킵니다.

[out] FifoSize

DMA 엔진의 FIFO 크기(바이트)를 검색합니다. 이 매개 변수는 루틴이 FIFO 크기를 쓰는 호출자가 할당한 ULONG 변수를 가리킵니다.

반환 값

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

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

설명

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

DMA 엔진이 requestBufferSize 매개 변수에 요청된 크기의 버퍼를 사용할 수 없는 경우 루틴은 요청된 크기에 최대한 가까운 버퍼를 할당합니다.

오디오 또는 모뎀 코덱의 함수 드라이버는 코덱을 프로그래밍하여 데이터 전송을 관리하고 스트림 식별자를 인식합니다.

루틴은 버퍼가 포함된 실제 메모리 페이지를 나열하는 MDL을 출력합니다. 버퍼 기본 주소는 목록의 첫 번째 실제 페이지 시작과 일치합니다.

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

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

FIFO 크기는 DMA 엔진이 내부 버퍼에 보유할 수 있는 최대 바이트 수입니다. 하드웨어 구현에 따라 DMA 엔진의 FIFO 크기는 정적이거나 스트림 형식의 변경 내용에 따라 동적으로 다를 수 있습니다. FIFO 크기에 대한 자세한 내용은 Intel HD 오디오 웹 사이트의 Intel 고화질 오디오 사양을 참조하세요.

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

이전에 할당된 DMA 버퍼는 FreeDmaBuffer를 호출하여 해제되지 않았습니다.
스트림이 다시 설정이 아닌 상태에 있습니다.

Windows Server 2003, Windows XP, Windows 2000 및 Windows Me/98에서 WDM 오디오 드라이버는 NewStream 메서드(핀 생성 시) 또는 SetFormat 메서드를 실행하는 동안(HD Audio DDI에서XxxDmaEngine 할당 루틴 중 하나를 호출한 후) 이 루틴을 호출합니다. 자세한 내용은 IMiniportWavePci::NewStream 및 IMiniportWavePciStream::SetFormat을 참조하세요.