Метод IPortWavePciStream::GetMapping (portcls.h)

2025-04-09

Метод 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 шины звукового устройства использует адрес, который выводится через параметр PhysicalAddress для доступа к сопоставлению.

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

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

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

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

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

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

Минипорт-драйвер, скорее всего, вызывается GetMapping во время вызова метода SetState, Service или MappingAvailable объекта miniport (см. 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.