IPortWavePciStream::GetMapping 메서드(portcls.h)

아티클
02/04/2022
읽는 데 14분 걸림

이 메서드는 GetMapping 포트 드라이버에서 매핑을 가져오고 태그를 매핑과 연결합니다.

구문

NTSTATUS GetMapping(
  [in]  PVOID             Tag,
  [out] PPHYSICAL_ADDRESS PhysicalAddress,
  [out] PVOID             *VirtualAddress,
  [out] PULONG            ByteCount,
  [out] PULONG            Flags
);

매개 변수

[in] Tag

매핑과 연결할 태그 값을 지정합니다. 포트 드라이버는 후속 IMiniportWavePciStream::RevokeMappings 호출에서 이 태그를 사용하여 해지할 매핑 목록에서 매핑을 식별할 수 있습니다. 미니포트 드라이버는 태그를 사용하여 매핑을 해제하는 IPortWavePciStream::ReleaseMapping 호출에서 매핑을 식별합니다.

[out] PhysicalAddress

실제 주소에 대한 출력 포인터입니다. 이 매개 변수는 메서드가 매핑의 실제 주소를 쓰는 호출자 할당 포인터 변수를 가리킵니다. 이 매개 변수에 유효한 NULL이 아닌 포인터 값을 지정합니다.

[out] VirtualAddress

가상 주소에 대한 출력 포인터입니다. 이 매개 변수는 메서드가 매핑의 가상 주소를 쓰는 호출자 할당 포인터 변수를 가리킵니다. 이 매개 변수에 유효한 NULL이 아닌 포인터 값을 지정합니다.

[out] ByteCount

바이트 수에 대한 출력 포인터입니다. 이 매개 변수는 메서드가 매핑에 바이트 수를 쓰는 호출자 할당 ULONG 변수를 가리킵니다. 이 매개 변수에 유효한 NULL이 아닌 포인터 값을 지정합니다.

[out] Flags

상태 플래그에 대한 출력 포인터입니다. 이 매개 변수는 메서드가 상태 플래그를 작성하는 호출자가 할당한 ULONG 변수를 가리킵니다. 이 매개 변수에 유효한 NULL이 아닌 포인터 값을 지정합니다. 0이 아닌 플래그 값은 이 호출에서 얻은 매핑이 I/O 패킷의 마지막 매핑임을 나타냅니다. 이 플래그를 사용하여 하드웨어가 이 매핑을 수행할 때 미니포트 드라이버를 중단해야 한다는 신호를 보낼 수 있습니다. 인터럽트 대응으로 미니포트 드라이버는 하드웨어에 전달하기 위한 새 매핑을 얻을 수 있습니다. 미니포트 드라이버는 이러한 방식으로 플래그를 사용할 의무가 없습니다.

반환 값

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

반환 코드	설명
STATUS_NOT_FOUND	매핑은 즉시 사용할 수 없지만, 매핑을 사용할 수 있게 되면 포트 드라이버는 IMiniportWavePciStream::MappingAvailable 을 호출합니다.

설명

메서드를 통해 GetMapping 얻은 매핑은 포트 드라이버에서 해지하지 않는 한 IPortWavePciStream::ReleaseMapping 을 호출하여 해제해야 합니다. 포트 드라이버는 스트림의 IMiniportWavePciStream::RevokeMappings 메서드를 호출하여 매핑을 취소할 수 있습니다.

미니포트 드라이버의 렌더링 핀을 통해 재생되는 스트림에 대한 버퍼 스토리지는 하나 이상의 IRP에 연결됩니다. 각 IRP에는 스트림에 대한 버퍼 스토리지의 일부가 포함됩니다. 각 IRP의 버퍼 스토리지는 가상 메모리에서 연속되지만 버퍼를 구성하는 메모리 페이지는 실제 메모리의 연속된 위치에 일반적으로 매핑되지 않습니다. 드라이버는 프로그래밍된 I/O를 사용하여 가상 메모리에 매핑을 통해 버퍼에 액세스할 수 있지만 DMA 컨트롤러에는 물리적 매핑이 대신 필요합니다.

WavePci 포트 드라이버는 이 메서드를 GetMapping 사용하여 물리적 매핑 시퀀스로 미니포트 드라이버에 버퍼를 노출합니다. 두 개 이상의 페이지가 실제 메모리의 인접 위치를 차지하는 경우 매핑이 페이지 크기를 초과할 수 있지만 일반적인 매핑은 하나의 메모리 페이지 이하입니다.

버퍼의 시작 부분에 매핑을 출력하는 GetMapping 초기 호출입니다. 각 연속 호출은 GetMapping 버퍼에 다음 순차적 매핑을 제공합니다. 버퍼의 끝에 도달한 후 다음 GetMapping 호출은 버퍼의 시작 부분에 매핑을 출력하고 매핑 시퀀스가 반복됩니다.

매핑의 커널 모드 가상 메모리 주소는 VirtualAddress 매개 변수를 통해 출력됩니다. 미니포트 드라이버는 이 주소를 사용하여 직접 프로그램 제어 아래의 매핑에 액세스합니다. 매핑이 포함된 페이지는 잠겨 있으며 드라이버가 매핑에 액세스할 때 페이지 오류가 발생하지 않습니다. 오디오 디바이스의 버스 마스터 DMA 컨트롤러는 PhysicalAddress 매개 변수를 통해 출력되는 주소를 사용하여 매핑에 액세스합니다.

Tag 매개 변수는 호출자가 매핑을 고유하게 식별하도록 선택하는 PVOID 값입니다.

포트 드라이버는 이 태그를 사용하여 IMiniportWavePciStream::RevokeMappings에 대한 후속 호출에서 매핑을 식별할 수 있습니다.
미니포트 드라이버는 이 태그를 사용하여 IPortWavePciStream::ReleaseMapping에 대한 후속 호출에서 매핑을 식별할 수 있습니다.

태그가 PVOID 형식으로 정의되어 있지만 포트 드라이버는 이 값을 포인터로 사용하려고 시도하지 않으며 유효한 포인터일 필요가 없습니다.

일반적인 WavePci 미니포트 드라이버는 수신하는 각 매핑의 레코드를 유지 관리합니다. 태그는 예를 들어 구현에 따라 레코드 배열에 대한 레코드 또는 인덱스 포인터일 수 있습니다. 태그에 대한 유일한 요구 사항은 PVOID 형식으로 캐스팅할 수 있는 값이라는 것입니다.

Flags 매개 변수는 현재 매핑 IRP에 GetMapping 연결된 오디오 데이터 버퍼 부분에서 최종 매핑을 검색하기 위한 호출인지 여부를 나타냅니다. 플래그가 매핑이 IRP의 마지막 매핑임을 나타내는 경우 미니포트 드라이버는 미니포트 드라이버가 해당 매핑 재생을 완료할 때 하드웨어 인터럽트를 작동하도록 무장할 수 있습니다. 인터럽트 발생 시 이 이벤트는 미니포트 드라이버에 DMA 큐에 추가하기 위해 더 많은 매핑을 획득해야 함을 알려줍니다. Flags 매개 변수는 일반적으로 KMixer 시스템 드라이버에서 단일 재생 스트림을 관리하는 미니포트 드라이버에서 사용됩니다. KMixer는 여러 매핑 IRP(현재 KMixer 구현에서 최소 3개)를 사용하여 단일 재생 스트림을 버퍼링합니다. 따라서 미니포트 드라이버가 DMA 컨트롤러가 IRP에서 최종 매핑을 완료할 때마다 하드웨어 인터럽트를 생성하는 경우 DMA 큐가 부족하지 않도록 인터럽트를 자주 발생시켜야 합니다.

Flags 매개 변수는 일반적으로 하나 이상의 DirectSound 하드웨어 가속 스트림을 관리하는 미니포트 드라이버에서 무시됩니다(WDM 오디오의 DirectSound 하드웨어 가속 참조). DirectSound 버퍼의 경우 전체 버퍼를 단일 IRP에 연결할 수 있습니다. 버퍼가 크고 미니포트 드라이버가 버퍼 끝에 도달할 때만 하드웨어 인터럽트를 예약하는 경우 인터럽트는 지금까지 DMA 큐가 굶어 죽을 수 있는 간격으로 발생합니다. 또한 드라이버가 많은 수의 스트림을 관리하는 경우 Flags 매개 변수가 스트림에서 최종 매핑 조건을 알릴 때마다 하드웨어 인터럽트를 예약하면 성능이 저하될 수 있는 많은 인터럽트를 생성할 수 있습니다. 이러한 상황에서 미니포트 드라이버는 하드웨어 인터럽트에서 매핑을 획득하지 않아야 합니다. 대신, 매핑을 얻기 위해 타이머 DPC가 일정한 간격으로 수행되도록 예약해야 합니다.

미니포트 드라이버는 미니포트 스트림 개체의 SetState, Service 또는 MappingAvailable 메서드를 호출하는 동안 호출 GetMapping 할 가능성이 가장 높습니다(IMiniportWavePciStream 참조).

잠재적 교착 상태를 방지하려면 어댑터 드라이버가 호출 GetMapping하는 동안 스핀 잠금을 유지하지 않아야 합니다. 스핀 잠금을 사용하여 다중 프로세서 시스템의 공유 데이터 구조 및 주변 디바이스에 대한 액세스를 직렬화하는 코드 예제는 Microsoft WDK(Windows Driver Kit)의 ac97 샘플 오디오 드라이버를 참조하세요. 샘플 코드는 호출하기 전에 KeReleaseSpinLock 을 호출하고 호출 GetMapping 후 KeAcquireSpinLock 을 호출 GetMapping합니다. 스핀 잠금을 해제하고 획득하기 위한 호출 사이에 드라이버 스레드는 스핀 잠금으로 보호되는 데이터 또는 주변 디바이스에 대한 단독 액세스 권한이 있다고 가정해서는 안 됩니다. 드라이버 검증 도구는 호출 중에 활성 스핀 잠금을 GetMapping확인합니다. 이 도구를 검색하면 0xC4(교착 상태 감지) 버그 검사가 생성됩니다.

일반적인 매핑의 크기는 하나의 메모리 페이지 이하이지만 오디오 버퍼의 일부가 실제 메모리에서 두 개 이상의 연속 페이지를 차지하는 경우 단일 매핑이 페이지 크기를 초과할 수 있습니다. 매핑이 클수록 블록 크기를 제한하는 디자인 결함이 있는 DMA 하드웨어에 문제가 발생할 수 있습니다. 예를 들어 DMA 컨트롤러가 단일 페이지의 최대 블록 크기를 처리할 수 있고 GetMapping 페이지보다 큰 매핑을 출력하는 경우 미니포트 드라이버는 매핑을 DMA 하드웨어가 처리할 수 있는 작은 블록으로 분할해야 합니다. 결과 블록 수가 DMA 하드웨어에서 사용 가능한 맵 레지스터 수를 초과하는 경우 드라이버는 단일 분산형/수집 DMA 작업에서 모든 블록을 큐에 대기할 수 없습니다. 이 경우 드라이버는 매핑의 큐에 묻지 않은 부분을 추적하고 추가 맵 레지스터를 사용할 수 있게 되면 나중에 나머지 블록의 DMA 전송을 시작해야 합니다.

Windows 98/Me, Windows 2000, Windows XP 및 Windows Server 2003 GetMapping 에서는 16페이지가 넘는 매핑을 출력하지 않습니다. 이 제한은 향후 Windows 릴리스에서 변경될 수 있습니다.

매핑에 대한 자세한 내용은 WavePci 대기 시간을 참조하세요.