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

아티클
02/07/2025

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 매개 변수는 GetMapping 호출이 현재 매핑 IRP에 연결된 오디오 데이터 버퍼 부분에서 최종 매핑을 검색했는지 여부를 나타냅니다. 플래그 매핑이 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 드라이버 키트)의 ac97 샘플 오디오 드라이버를 참조하세요. 샘플 코드는 GetMapping 호출하기 전에 KeReleaseSpinLock 호출하고 GetMapping호출한 후 KeAcquireSpinLock 호출합니다. 스핀 잠금을 해제하고 획득하기 위한 호출 사이에 드라이버 스레드는 스핀 잠금으로 보호되는 데이터 또는 주변 기기에 대한 단독 액세스 권한이 있다고 가정해서는 안 됩니다. 드라이버 검증 도구 도구는 GetMapping호출하는 동안 활성 스핀 잠금을 확인합니다. 이를 감지하면 0xC4(교착 상태 검색) 버그 검사가 생성됩니다.

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

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

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