Метод 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, для этого параметра. Ненулевое значение флага указывает, что сопоставление, полученное в этом вызове, является последним сопоставлением в пакете ввода-вывода. Этот флаг можно использовать для обозначения того, что оборудование должно прервать работу драйвера мини-порта при выполнении этого сопоставления. В ответ на прерывание драйвер мини-порта может получить новые сопоставления для доставки оборудования. Драйвер мини-порта не обязан использовать флаг таким образом.

Возвращаемое значение

GetMapping возвращает STATUS_SUCCESS, если вызов был выполнен успешно. В противном случае метод возвращает соответствующий код ошибки. В следующей таблице показаны некоторые из возможных кодов состояния возврата.

Код возврата	Описание
STATUS_NOT_FOUND	Сопоставление доступно не сразу, но драйвер порта вызовет IMiniportWavePciStream::MappingAvailable , когда сопоставление станет доступным.

Сопоставления, полученные с помощью GetMapping метода , должны быть освобождены путем вызова IPortWavePciStream::ReleaseMapping , если они не отозваны драйвером порта. Драйвер порта может отменять сопоставления, вызывая метод IMiniportWavePciStream::RevokeMappings потока.

Хранилище буфера для потока, воспроизводимого через контакт отрисовки драйвера минипорта, подключено к одному или нескольким irP. Каждый IRP содержит часть буферного хранилища для потока. Каждое хранилище буфера IRP является непрерывным в виртуальной памяти, но страницы памяти, составляющие буфер, в целом не сопоставляются с смежными расположениями в физической памяти. Хотя драйвер может использовать запрограммированные операции ввода-вывода для доступа к буферу через его сопоставление с виртуальной памятью, вместо этого контроллерУ DMA требуются физические сопоставления.

Драйвер порта WavePci использует GetMapping метод для предоставления буфера драйверу мини-порта в качестве последовательности физических сопоставлений. Обычное сопоставление имеет размер одной страницы памяти или меньше, хотя сопоставление может превышать размер страницы, если две или более страницы занимают смежные расположения в физической памяти.

Первоначальный вызов выводит GetMapping сопоставление в начале буфера. Каждый последующий вызов представляет GetMapping следующее последовательное сопоставление в буфере. После достижения конца буфера следующий GetMapping вызов выводит сопоставление в начале буфера, и последовательность сопоставления повторяется.

Адрес виртуальной памяти в режиме ядра для сопоставления выводится с помощью параметра VirtualAddress . Драйвер мини-порта использует этот адрес для доступа к сопоставлению под прямым управлением программы. Страница, содержащая сопоставление, заблокирована, и при доступе драйвера к сопоставлению не может возникнуть ошибка страницы. Контроллер DMA master звукового устройства использует адрес, который выводится с помощью параметра PhysicalAddress, для доступа к сопоставлению.

Параметр Tag — это значение PVOID, которое выбирает вызывающий объект для уникальной идентификации сопоставления:

Драйвер порта может использовать этот тег для идентификации сопоставления в последующем вызове IMiniportWavePciStream::RevokeMappings.
Драйвер мини-порта может использовать этот тег для идентификации сопоставления при последующем вызове IPortWavePciStream::ReleaseMapping.

Хотя тег определен как тип PVOID, драйвер порта никогда не пытается использовать это значение в качестве указателя и не требует, чтобы оно было допустимым указателем.

Типичный драйвер miniport WavePci ведет запись каждого получаемого сопоставления. Тег может быть указателем на запись или индексом на массив записей, например, в зависимости от реализации. Единственное требование для тега — это значение, которое можно привести к типу PVOID.

Параметр Flags указывает, был ли вызов , чтобы GetMapping получить окончательное сопоставление в части буфера звуковых данных, присоединенной к текущему IRP сопоставления. Если флаги указывают, что сопоставление является последним сопоставлением в IRP, драйвер минипорта может вооружить аппаратное прерывание, чтобы срабатывать, когда драйвер мини-порта завершает воспроизведение этого сопоставления. При срабатывании прерывания это событие сообщает драйверу мини-порта о том, что ему необходимо получить дополнительные сопоставления для добавления в очередь DMA. Параметр Flags обычно используется драйвером мини-порта, который управляет одним потоком воспроизведения из системного драйвера KMixer. KMixer использует несколько irP сопоставления (не менее трех в текущей реализации KMixer) для буферизации одного потока воспроизведения. Таким образом, если драйвер мини-порта создает аппаратное прерывание каждый раз, когда контроллер DMA завершает окончательное сопоставление в IRP, прерывания должны происходить достаточно часто, чтобы очередь DMA не голодала.

Параметр Flags обычно игнорируется драйверами мини-портов, которые управляют одним или несколькими потоками с аппаратным ускорением DirectSound (см. статью Аппаратное ускорение DirectSound в WDM Audio). В случае с буфером DirectSound весь буфер может быть присоединен к одному IRP. Если буфер большой и драйвер мини-порта планирует аппаратное прерывание только по достижении конца буфера, прерывания будут происходить так далеко друг от друга, что очередь DMA может голодать. Кроме того, если драйвер управляет большим количеством потоков, планирование аппаратного прерывания каждый раз, когда параметр Flags сообщает об окончательном условии сопоставления в потоке, может привести к такому количеству прерываний, что производительность может снизиться. В таких случаях драйвер мини-порта не должен полагаться на аппаратные прерывания для получения сопоставлений. Вместо этого он должен запланировать выполнение ЦП таймера через регулярные интервалы для получения сопоставлений.

Драйвер мини-порта, скорее всего, вызовет GetMapping метод SetState, Service или MappingAvailable объекта потока мини-порта (см. IMiniportWavePciStream).

Чтобы избежать потенциальных взаимоблокировок, драйвер адаптера должен избегать удержания спин-блокировки во время вызова GetMapping. Пример кода, использующий спин-блокировку для сериализации доступа к общим структурам данных и периферийным устройствам в многопроцессорной системе, см. в примере аудиодрайва ac97 в комплекте драйверов Microsoft Windows (WDK). Пример кода вызывает 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.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	portcls.h (включая Portcls.h)
IRQL	<=DISPATCH_LEVEL