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

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

• Установка драйвера
• DriverEntry
• MiniportSetOptions
• MiniportInitializeEx
• MiniportHaltEx
• MiniportDriverUnload
• MiniportPause
• MiniportRestart
• MiniportResetEx
• MiniportDevicePnPEventNotify
• MiniportShutdownEx
• MiniportOidRequest
• MiniportCancelOidRequest
• NdisMIndicateStatusEx
• MiniportDirectOidRequest
• MiniportCancelDirectOidRequest
• MiniportSendNetBufferLists
• MiniportCancelSend
• MiniportReturnNetBufferLists
• Обработчик WDI: MiniportWdiOpenAdapter
• Обработчик WDI: MiniportWdiCloseAdapter

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

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

DriverEntry

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

Ниже приведены ключевые параметры NdisMRegisterWdiMiniportDriver.

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

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

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

Дополнительные сведения о DriverEntry см. в разделе DriverEntry of NDIS Miniport Drivers.

MiniportSetOptions

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

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

MiniportInitializeEx

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

1. Вызовите MiniportWdiAllocateAdapter.

   Когда операционная система находит экземпляр оборудования IHV, это первый вызов драйвера WDI IHV miniport. В этом вызове минипорт 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 компонент Майкрософт отправляет следующие задачи, свойства и вызовы в минипорт 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.

   

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

MiniportHaltEx

В мини-порту native 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.

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

MiniportDriverUnload

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

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

MiniportPause

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

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

MiniportRestart

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

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

MiniportResetEx

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

MiniportDevicePnPEventNotify

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

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

MiniportShutdownEx

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

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

MiniportOidRequest

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

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

Для каждой команды WDI есть два потенциальных поля, в которых может быть возвращен код NDIS_STATUS для операции: код состояния из вызова MiniportOidRequest (или NdisMOidRequestComplete) и код состояния в поле WDI_MESSAGE_HEADER (при завершении OID или через NdisMIndicateStatusEx). Компонент Майкрософт всегда просматривает 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. Для завершения OID допустимо, чтобы 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 и заполняет данные. METHOD_INFORMATION. Поле BytesNeeded . Компонент Майкрософт может попытаться выделить буфер запрошенного размера и отправить новый запрос в IHV.
7. Если это задача, M4 задачи (NdisMIndicateStatusEx) необходимо указывать только в том случае, если задача была зарегистрирована как успешно запущенная. OID завершен успешно и состояние в WDI_MESSAGE_HEADER в OID завершено успешно.

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

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

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

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

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

MiniportCancelOidRequest

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

NdisMIndicateStatusEx

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

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

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

На приведенной ниже схеме показано, что компонент Майкрософт не распознает его. Указание перенаправлено в операционную систему как есть.

Поведение NdisMIndicateStatusEx для драйвера мини-порта WDI IHV не изменяется (по сравнению с собственным Wi-Fi мини-портом).

MiniportDirectOidRequest

Это необязательный обработчик, который регистрируется драйвером мини-порта WDI IHV, если ему нужно обрабатывать прямые идентификаторы OID, которые не сопоставлены с сообщениями WDI. Все существующие OID Direct для 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 Miniport и не должен предоставляться. Компонент Майкрософт использует обработчики пути к данным, зарегистрированные с помощью NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS , для возврата полученных пакетов в мини-порт IHV.

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

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

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

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