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

아티클
08/07/2023

메서드는 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 매개 변수를 통해 출력됩니다. 미니포트 드라이버는 이 주소를 사용하여 직접 프로그램 제어 아래의 매핑에 액세스합니다. 매핑이 포함된 페이지는 잠겨 있으며 드라이버가 매핑에 액세스할 때 페이지 오류가 발생하지 않습니다. 오디오 디바이스의 버스 master DMA 컨트롤러는 PhysicalAddress 매개 변수를 통해 출력되는 주소를 사용하여 매핑에 액세스합니다.

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

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

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

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

Flags 매개 변수는 에 대한 GetMapping 호출이 현재 매핑 IRP에 연결된 오디오 데이터 버퍼의 부분에서 최종 매핑을 검색했는지 여부를 나타냅니다. Flags가 매핑이 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 샘플 오디오 드라이버를 참조하세요. 샘플 코드는 를 호출하기 전에 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 대기 시간을 참조하세요.