Поделиться через

Интерфейсы драйверов WDI IHV

Минипорт WDI IHV похож на любой другой минипорт NDIS, и он будет следовать рекомендациям по разработке и документации для любого мини-порта NDIS. Обязанности нативного драйвера минипорта WLAN для обработчиков NDIS разделяются между компонентом MS и драйвером WDI IHV. Компонент WLAN Microsoft удовлетворяет требованиям NDIS, применимым ко всем минипортам типа Wi-Fi, чтобы каждому IHV не приходилось повторно выполнять всю эту работу. Сопоставление и изменение поведения обработчиков NDIS для нативного минипорта WLAN IHV при применении к минипорту WDI IHV описаны ниже.

Установка драйвера

Нет изменений в том, как драйвер минипорта WDI IHV загружается и устанавливается в системе. Процесс INF и установки аналогичен процессу установки минипорта драйвера IHV Native WLAN. Как и существующие драйверы NDIS, когда драйвер IHV необходимо загрузить для работы с адаптером WLAN IHV, операционная система вызывает подпрограмму DriverEntry драйвера IHV miniport.

DriverEntry

Операционная система напрямую вызывает подпрограмму DriverEntry минипорт-драйвера WDI IHV. Минипорт IHV следует большинству рекомендаций функции DriverEntry обычного минипорта NDIS. Одним из исключений является то, что вместо вызова NdisMRegisterMiniportDriver, минипорт IHV вызывает NdisMRegisterWdiMiniportDriver, чтобы сообщить операционной системе, чтобы включить компонент WLAN Microsoft.

Основные параметры для NdisMRegisterWdiMiniportDriverприведены ниже.

  • NDIS_MINIPORT_DRIVER_CHARACTERISTICS: это оригинальная структура NDIS, которую собственный минипорт Wi-Fi использует для регистрации в NDIS. Для модели WDI большинство параметров обработчика являются необязательными. Единственными обязательными обработчиками являются MINIPORT_OID_REQUEST_HANDLER и MINIPORT_DRIVER_UNLOAD. MINIPORT_OID_REQUEST_HANDLER используется для передачи сообщений WDI драйверу IHV. Если указан любой другой обработчик, компонент Microsoft WLAN обычно вызывает его после выполнения собственной обработки.
  • NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS. Это новый набор обработчиков, которые должен реализовать драйвер мини-порта WDI. Он используется драйвером IHV для регистрации дополнительных обработчиков для пути управления и полного набора обработчиков для пути данных.

Когда минипорт IHV вызывает NdisMRegisterWdiMiniportDriver, компонент WLAN Microsoft обновляет обработчики NDIS_MINIPORT_DRIVER_CHARACTERISTICS и вызывает NDIS NdisMRegisterMiniportDriver. Обновления выполняются таким образом, чтобы компонент Microsoft WLAN мог перехватывать обработчики, для которых он может предоставить помощь или упростить взаимодействие с мини-драйвером WDI IHV.

Ниже приведен типичный поток процесса DriverEntry для драйвера минипорта WDI IHV.

поток драйвера wdi.

Дополнительные сведения о DriverEntry см. в разделе (разделах) DriverEntry для минипорт-драйверов NDIS.

MiniportSetOptions

Как показано на приведенной выше схеме DriverEntry, если минипорт WDI IHV зарегистрировал обработчик MiniportSetOptions, операционная система вызывает его в контексте драйвера минипорта, вызывающего NdisMRegisterWdiMiniportDriver.

Если драйвер минипорт-драйвера IHV регистрирует любые опциональные обработчики с помощью NdisSetOptionalHandlers, эти обработчики могут не быть последовательно упорядочены через слой WDI компонентом Майкрософт. Поэтому компонент IHV отвечает за обработку любых требований синхронизации для этих обработчиков.

MiniportInitializeEx

Модель WDI разделяет поведение MiniportInitializeEx на несколько вызовов интерфейса WDI.

  1. Вызов MiniportWdiAllocateAdapter.

    Когда операционная система находит экземпляр оборудования IHV, это первый вызов в драйвер минипорта WDI IHV. В этом вызове мини-порт WDI выполняет действия, необходимые для создания программного представления (MiniportAdapterContext) устройства. Он также определяет сведения об устройстве для заполнения структуры NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES. Фактическая инициализация устройства и стека Wi-Fi выполняется позже, когда компонент Майкрософт отправляет команды WDI для выполнения конкретных инициализаций.

    Используя данные, полученные из драйвера минипорта WDI IHV, компонент Майкрософт вызывает NdisMSetMiniportAttributes и задает NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES на NDIS. Большинство полей NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES заполняются по умолчанию компонентом Майкрософт. Драйвер IHV должен заполнить поля MiniportAdapterContext и InterfaceType.

    После того как этот вызов возвращается из мини-драйвера IHV, он начинает получать команды WDI через обработчик MiniportOidRequest. Во время этого вызова компонент Майкрософт может не выполнять операции сброса и восстановления, поэтому любые действия, выполняемые здесь, должны быть быстрыми и надежными.

  2. Вызов MiniportWdiOpenAdapter.

    После MiniportWdiAllocateAdapterкомпонент Майкрософт вызывает MiniportWdiOpenAdapter для загрузки прошивки и инициализации оборудования.

  3. Несколько команд WDI выполняются через MiniportOidRequest.

    После MiniportWdiOpenAdapterкомпонент Microsoft отправляет следующие задачи/свойства/вызовы минипорту IHV.

    1. Вызовите MiniportWdiTalTxRxInitialize, чтобы инициализировать путь данных и обработчики обмена.
    2. Вызовите OID_WDI_GET_ADAPTER_CAPABILITIES, чтобы получить возможности адаптера.
    3. Вызовите OID_WDI_SET_ADAPTER_CONFIGURATION для настройки адаптера.
    4. Если радиостанция еще не находится в ожидаемом состоянии, вызовите OID_WDI_TASK_SET_RADIO_STATE, чтобы задать исходное состояние.
    5. Вызовите MiniportWdiTalTxRxStart, чтобы настроить путь к данным.
    6. Вызовите OID_WDI_TASK_CREATE_PORT для создания начального порта.

    Другие команды также могут быть отправлены в компонент IHV в рамках обработки MiniportInitializeEx компонента Майкрософт. Однако до вызова MiniportWdiStartOperation компонент Майкрософт не отправляет никаких задач, требующих беспроводной связи. За исключением того, что OID_WDI_TASK_OPEN всегда отправляется первым, порядок остальных команд или вызовов может изменяться.

    Используя данные, полученные из минипортовского драйвера WDI IHV, компонент Майкрософт вызывает NdisMSetMiniportAttributes и задает NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES и NDIS_MINIPORT_ADAPTER_NATIVE_802_11_ATTRIBUTES на NDIS.

  4. Вызов MiniportWdiStartOperation.

    Это необязательный обработчик мини-порта WDI внутри NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS, который драйвер IHV может использовать для выполнения любых дополнительных задач MiniportInitializeEx. Его также можно использовать минипортом IHV в качестве указания на то, что компонент Майкрософт завершил инициализацию минипорта и минипорт может начать любые необходимые фоновые действия.

    На схеме ниже показан поток MiniportInitializeEx.

    поток инициализации мини-порта wdi.

    Если промежуточная операция завершается ошибкой, компонент Майкрософт отменяет предыдущие операции и завершает работу мини-порта. Например, если OID_WDI_TASK_CREATE_PORT завершается ошибкой, поток данных очищается, OID_WDI_TASK_CLOSE отправляется, и минипорт завершается ошибкой.

MiniportHaltEx

В родном Wi-Fi минипорте MiniportHaltEx используется для остановки операций и очистки экземпляра адаптера. В модели WDI компонент Майкрософт обрабатывает исходный вызов MiniportHaltEx и разделяет его на несколько вызовов интерфейса WDI.

  1. Вызов MiniportWdiStopOperation.

    Это необязательный обработчик мини-порта WDI внутри NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS, который драйвер IHV может использовать для отмены операций, которые он выполнял в MiniportWdiStartOperation.

  2. Несколько команд WDI с помощью MiniportOidRequest.

    После MiniportWdiStopOperationкомпонент Майкрософт отправляет задачи и свойства в минипорт IHV, чтобы очистить текущее состояние драйвера IHV. Эта очистка может включать в себя следующее.

    1. Вызовите OID_WDI_TASK_DISCONNECT/OID_WDI_TASK_STOP_AP, чтобы разорвать все существующие соединения.
    2. Вызовите OID_WDI_TASK_DELETE_PORT для удаления всех созданных портов.
    3. Вызовите MiniportWdiTalTxRxStop, чтобы остановить канал передачи данных.
    4. Вызовите MiniportWdiTalTxRxDeinitialize, чтобы деинициализировать путь к данным.
    5. Вызов для очистки состояния оборудования. Это отправляется в IHV с использованием MiniportWdiCloseAdapter, который был зарегистрирован драйвером IHV.

  3. После вызова всех указанных выше команд компонент Майкрософт вызывает MiniportWdiFreeAdapter, чтобы драйвер IHV удалил любое состояние программного обеспечения.

На схеме ниже показан поток MiniportHaltEx.

минипорт остановки потока wdi.

Обработка MiniportHaltEx не выполняется, если устройство неожиданно удалено или если система отключена. Для непредвиденного удаления посмотрите на поведение обработчика MiniportDevicePnPEventNotify. Для завершения работы системы ознакомьтесь с работой обработчика MiniportShutdownEx.

MiniportDriverUnload

MiniportDriverUnload — это обработчик, который вызывается перед выгрузкой мини-порта WDI IHV. Драйвер минипорта WDI IHV вызывает компонент Майкрософт для отмены регистрации. Компонент Майкрософт вызывает NdisMDeregisterMiniportDriver.

На схеме ниже показан поток MiniportDriverUnload.

поток выгрузки драйвера wdi miniport.

MiniportPause

Требования к NDIS MiniportPause обрабатываются компонентом Майкрософт. В рамках MiniportPause компонент Майкрософт останавливает передачу данных и ожидает, пока она очистится. Минипорт WDI IHV может зарегистрироваться на MiniportWdiPostAdapterPause обратный вызов, который вызывается компонентом Microsoft после завершения очистки пути данных.

На схеме ниже показан поток MiniportPause.

приостановка потока WDI мини-порта.

MiniportRestart

Требования NDIS MiniportRestart обрабатываются компонентом Майкрософт. В рамках MiniportRestart компонент Майкрософт снимает приостановку передачи данных, выполнившуюся в рамках MiniportPause. Минипорт WDI IHV может по желанию зарегистрироваться на вызов обратного вызова MiniportWdiPostAdapterRestart, который вызывается компонентом Microsoft после завершения перезапуска канала передачи данных.

На схеме ниже показан поток MiniportRestart.

перезапуск потока минипорта WDI.

MiniportResetEx

MiniportResetEx не обрабатывается компонентом Майкрософт. Минипорт WDI IHV может при необходимости зарегистрироваться для функции обратного вызова MiniportResetEx, которая вызывается компонентом Microsoft.

MiniportDevicePnPEventNotify

MiniportDevicePnPEventNotify используется для уведомления драйвера NDIS о событиях PNP, таких как неожиданное удаление устройства. Когда NDIS отправляет это уведомление, он сначала пересылается в мини-порт WDI IHV для обработки. После того как компонент IHV закончит обработку, компонент Майкрософт выполняет соответствующую обработку для этого события. Вызов, перенаправленный в компонент IHV, не сериализуется с другими задачами и обратными вызовами.

На схеме ниже показан поток MiniportDevicePnPEventNotify.

поток уведомлений для pnp-управления miniport-драйвером wdi.

MiniportShutdownEx

MiniportShutdownEx используется для уведомления драйвера NDIS о событиях завершения работы системы. Когда NDIS отправляет это уведомление, он сначала обрабатывается компонентом Майкрософт. После того как компонент Майкрософт завершит обработку, он передает событие в минипорт WDI IHV для обработки.

На схеме ниже показан поток MiniportShutdownEx.

процесс завершения работы WDI минипорта.

MiniportOidRequest

Обработчик MiniportOidRequest является обязательным обработчиком, который должен реализовать мини-порт WDI IHV. Он используется компонентом Майкрософт для отправки команд WDI в мини-порт IHV. Он также используется для пересылки OIDы, которые компонент Microsoft не обрабатывает, мини-порту IHV.

Вызов MiniportOidRequest в мини-порт WDI IHV следует рассматривать как сообщение M1 для команды WDI. Завершение OID (либо с помощью NdisMOidRequestComplete, либо через возврат состояния без ожидания от MiniportOidRequest) должно рассматриваться как сообщение M3 для команды или задачи WDI.

Для каждой команды WDI существует два потенциальных поля, в которых может быть возвращён код NDIS_STATUS для операции — код состояния из вызова MiniportOidRequest (или NdisMOidRequestComplete), и код состояния в поле WDI_MESSAGE_HEADER (либо при завершении OID, либо через NdisMIndicateStatusEx). Компонент Microsoft сначала проверяет NDIS_STATUS при завершении OID, а затем поле WDI_MESSAGE_HEADERStatus. Ожидания компонента IHV для обработки OID WDI приведены ниже.

  1. WDI OID отправляются в компонент IHV с помощью NDIS_OID_REQUESTRequestTypeNdisRequestMethod, а соответствующее сообщение и его длина находятся в полях DATA.METHOD_INFORMATION.InformationBuffer и DATA.METHOD_INFORMATION.InputBufferLength соответственно.
  2. Компонент IHV сообщает об ошибке на завершении OID, если при обработке команды возникает ошибка, и устанавливает поле "Состояние" в WDI_MESSAGE_HEADER на неудачный статус, если произошел сбой уровня Wi-Fi.
  3. Для задач и свойств номер порта для запроса находится в поле WDI_MESSAGE_HEADERPortId. Значение PortNumber в NDIS_OID_REQUEST всегда равно 0.
  4. Допустимо, чтобы MiniportOidRequest возвращал NDIS_STATUS_PENDING и завершал OID позже (синхронно или асинхронно) с помощью NdisMOidRequestComplete.
  5. Если компонент IHV завершает OID с NDIS_STATUS_SUCCESS, он должен заполнить поле BytesWritten запроса OID соответствующим числом байтов, включая место для WDI_MESSAGE_HEADER.
  6. Если компонент IHV не имеет достаточно места в поле DATA.METHOD_INFORMATION.OutputBufferLength для заполнения ответа, он завершает OID с NDIS_STATUS_BUFFER_TOO_SHORT и заполняет значение в поле DATA.METHOD_INFORMATION.BytesNeeded. Компонент Майкрософт может попытаться выделить буфер запрошенного размера и отправить новый запрос в IHV.
  7. Если это задача, то задача M4 (NdisMIndicateStatusEx) должна быть указана только в том случае, если задача была успешно запущена — завершение OID было успешным, а состояние в WDI_MESSAGE_HEADER в завершении OID было успешным.

На схеме ниже показан пример запроса NDIS OID, который сопоставляется с одной командой WDI. Когда запрос OID отправляется операционной системой, компонент Майкрософт преобразует его в запрос WDI OID и отправляет запрос WDI OID в мини-порт IHV. Когда минипорт IHV завершает OID, компонент Майкрософт соответствующим образом завершает исходный запрос OID.

последовательность запросов минипорта wdi для одной команды wdi.

Если OriginalOidRequest сопоставляется с несколькими WDI OidRequests и один из них завершается сбоем, то OriginalOidRequest также завершается сбоем. Если подмножество промежуточных операций уже завершено, компонент Майкрософт пытается отменить операции, поддерживающие очистку.

На приведенной ниже схеме показан пример запроса NDIS OID, который обрабатывается компонентом Майкрософт. Когда запрос OID отправляется операционной системой, компонент Майкрософт обрабатывает и завершает OID. Этот OID не передается в мини-порт WDI IHV.

последовательность запросов минипорта wdi для oid, обрабатываемых компонентом Майкрософт.

OIDы, которые не понимаются компонентом Майкрософт, перенаправляются непосредственно в компонент IHV для обработки.

последовательность запросов минипорта wdi для oids, не обрабатываемых компонентом Майкрософт.

Поведение MiniportOidRequest не изменилось для минипорт-драйвера WDI IHV (по сравнению с минипортом Native Wi-Fi). Вызовы сериализуются, а минипорт IHV может выполнять его синхронно или асинхронно с вызовом NdisMOidRequestComplete.

MiniportCancelOidRequest

Это необязательный обработчик, используемый мини-портом WDI IHV, который должен обрабатывать OID, которые не сопоставлены с сообщениями WDI. Этот обработчик не используется для каких-либо WDI OID. WDI OID должны выполняться быстро, и драйвер минипорта IHV не должен пытаться отменить ожидающий OID. Отмена задач WDI обрабатывается с помощью соответствующего запроса на отмену задачи OID. Для неопределённых OID ожидаемое поведение определяется NDIS.

NdisMIndicateStatusEx

NdisMIndicateStatusEx используется мини-портом WDI IHV для отправки указаний в компонент Майкрософт. Эти указания могут быть не запрашиваемыми, такими как сбои TKIP MIC, или запрашиваемыми указаниями для завершения задачи (M4).

Диаграмма ниже показывает пример индикации WDI, которая связана с индикацией NDIS/Native Wi-Fi. Когда указание отправляется мини-портом IHV в компонент Майкрософт, компонент Майкрософт преобразует его в существующее указание и пересылает его в операционную систему.

поток отображения состояния мини-порта wdi.

На приведенной ниже схеме показан пример индикации WDI, не имеющей соответствующей индикации NDIS/Native Wi-Fi. Это обрабатывается компонентом Майкрософт.

индикация состояния WDI без прямого сопоставления с NDIS.

На приведенной ниже схеме показаны признаки, которые не распознаны компонентом Майкрософт. Индикация перенаправлена as-is в операционную систему.

индикация статуса wdi, не распознанная компонентом Microsoft.

Поведение функции NdisMIndicateStatusEx не изменяется для минипорта драйвера WDI IHV (по сравнению с минипортом драйвера Native Wi-Fi).

MiniportDirectOidRequest

Это необязательный обработчик, регистрируемый минипортом драйвера WDI IHV, если необходимо обрабатывать непосредственные OID, которые не сопоставлены с сообщениями WDI. Все существующие локальные идентификаторы для Wi-Fi Direct сопоставляются с сообщениями WDI, поэтому этот обработчик не требуется для поддержки этих функций. Неподдерживаемые прямые OID не сериализуются компонентом компании Майкрософт.

MiniportCancelDirectOidRequest

Это необязательный обработчик, используемый мини-портом WDI IHV, который должен обрабатывать прямые OID, которые не сопоставлены с сообщениями WDI. Для неотображенных идентификаторов OID ожидаемое поведение определяется NDIS.

MiniportSendNetBufferLists

Этот обработчик не используется в минипорт-драйвере WDI IHV и не должен быть предоставлен. Компонент Майкрософт использует обработчики пути данных, зарегистрированные через NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS для отправки пакетов в мини-порт IHV.

MiniportCancelSend

Этот обработчик не используется в минипорте WDI IHV и не следует предоставлять.

MiniportReturnNetBufferLists

Этот обработчик не используется в драйвере Минипорта WDI IHV и не должен быть предоставлен. Компонент Майкрософт использует обработчики пути к данным, зарегистрированные через NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS для возврата полученных пакетов в мини-порт IHV.

Обработчик WDI: MiniportWdiOpenAdapter

Обработчик MiniportWdiOpenAdapter используется компонентом Майкрософт для запуска операции Open Task в драйвере IHV. Этот вызов должен завершиться быстро, и если открытая операция успешно запущена, IHV должен вернуть NDIS_STATUS_SUCCESS по этому вызову и вызвать обработчик OpenAdapterComplete, который передается в параметр NDIS_WDI_INIT_PARAMETERS miniportWdiAllocateAdapter.

Обработчик WDI: MiniportWdiCloseAdapter

Обработчик MiniportWdiCloseAdapter используется компонентом Microsoft для инициирования операции закрытия задачи на драйвере IHV. Этот вызов должен завершиться быстро и, если открытая операция успешно запущена, IHV должен вернуть NDIS_STATUS_SUCCESS по этому вызову и вызвать обработчик CloseAdapterComplete, который передается в параметр NDIS_WDI_INIT_PARAMETERSMiniportWdiAllocateAdapter.