Sdílet prostřednictvím

Rozhraní ovladačů WDI IHV

  • Článek

Miniport WDI IHV je jako jakýkoli jiný ovladač miniportu NDIS a postupoval by podle vývojových postupů a dokumentace pro jakýkoli miniport NDIS. Odpovědnosti nativního ovladače WLAN Miniport pro obslužné rutiny NDIS jsou rozděleny mezi komponentu MS a ovladač WDI IHV. Komponenta Microsoft WLAN se stará o požadavky NDIS, které platí pro všechny Wi-Fi miniporty, aby každý IHV nemusel znovu provádět veškerou práci. Mapování a změny chování pro obslužné rutiny NDIS pro miniport Native WLAN IHV při použití na miniport WDI IHV jsou popsány níže.

Instalace ovladače

Neexistují žádné změny způsobu, jakým je ovladač miniportu WDI IHV načten a nainstalován v systému. Proces INF a instalace je podobný procesu u miniportového ovladače IHV Native WLAN. Stejně jako existující ovladače NDIS, když je třeba načíst ovladač IHV pro práci s adaptérem WLAN IHV, operační systém volá rutinu DriverEntry ovladače IHV miniportu.

DriverEntry

Operační systém volá přímo rutinu DriverEntry ovladače miniportu WDI IHV. Miniport IHV se řídí podle většiny obecných pokynů pro rutinu DriverEntry běžného miniportu NDIS. Jedinou výjimkou je, že místo volání NdisMRegisterMiniportDriver, miniport IHV volá NdisMRegisterWdiMiniportDriver, aby operační systém povolil komponentu Microsoft WLAN.

Níže jsou uvedené klíčové parametry NdisMRegisterWdiMiniportDriver.

  • NDIS_MINIPORT_DRIVER_CHARACTERISTICS: Jedná se o původní strukturu NDIS, kterou nativní miniport Wi-Fi používá k registraci v NDIS. U modelu WDI je většina parametrů obslužné rutiny volitelná. Jediné požadované obslužné rutiny jsou MINIPORT_OID_REQUEST_HANDLER a MINIPORT_DRIVER_UNLOAD. MINIPORT_OID_REQUEST_HANDLER slouží k předávání zpráv WDI ovladači IHV. Pokud je zadána jakákoli jiná obslužná rutina, komponenta Microsoft WLAN obvykle volá obslužnou rutinu po provedení vlastního zpracování obslužné rutiny.
  • NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS: Jedná se o novou sadu obslužných rutin, které musí implementovat ovladač miniportu WDI. Ovladač IHV se používá k registraci dalších obslužných rutin pro kontrolní cestu a úplné sady obslužných rutin pro cestu k datům.

Když miniport IHV volá NdisMRegisterWdiMiniportDriver, součást Microsoft WLAN aktualizuje obslužné rutiny NDIS_MINIPORT_DRIVER_CHARACTERISTICS a volá funkci NDIS NdisMRegisterMiniportDriver. Aktualizace se provádějí tak, aby komponenta Microsoft WLAN mohla zachytit obslužné rutiny, pro které může miniportovému ovladači WDI IHV poskytnout pomoc nebo zjednodušení.

Níže je typický tok procesu DriverEntry pro ovladač miniportu WDI IHV.

tok ovladače wdi.

Další informace o DriverEntry naleznete v tématu DriverEntry ovladačů NDIS Miniport.

MiniportSetOptions

Jak je znázorněno ve výše uvedeném diagramu DriverEntry, pokud miniport WDI IHV zaregistroval obslužnou rutinu MiniportSetOptions, operační systém volá tuto funkci v kontextu, kdy ovladač miniport volá NdisMRegisterWdiMiniportDriver.

Pokud ovladač miniportu IHV zaregistruje jakékoli obslužné rutiny možností pomocí NdisSetOptionalHandlers, nemusí být tyto obslužné rutiny serializovány přes vrstvu WDI komponentou od Microsoftu. Komponenta IHV proto zodpovídá za zpracování všech požadavků na synchronizaci těchto obslužných rutin.

MiniportInitializeEx

Model WDI rozdělí chování MiniportInitializeEx na více volání rozhraní WDI.

  1. Volání na MiniportWdiAllocateAdapter.

    Když operační systém najde instanci hardwaru IHV, jedná se o první volání ovladače miniportu WDI IHV. V tomto volání miniport WDI provádí akce potřebné k vytvoření softwarové reprezentace (MiniportAdapterContext) zařízení. Také určuje informace o zařízení potřebné k vyplnění struktury NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES. Skutečná inicializace zařízení a zásobníku Wi-Fi se provede později, když komponenta Microsoftu odešle příkazy WDI k provedení specifických inicializací.

    Pomocí dat získaných z ovladače miniportu WDI IHV volá komponenta Microsoft NdisMSetMiniportAttributes a nastaví NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES na NDIS. Většina polí NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES je vyplněna výchozími hodnotami součástí Microsoftu. Ovladač IHV musí vyplnit pole MiniportAdapterContext a InterfaceType.

    Jakmile se toto volání vrátí z ovladače miniportu IHV, začne přijímat příkazy WDI prostřednictvím obslužné rutiny MiniportOidRequest. Během tohoto hovoru nemusí být komponenta Microsoftu schopná provádět operace resetování/obnovení, takže jakákoli aktivita, kterou zde provedete, by měla být rychlá a spolehlivá.

  2. Volání MiniportWdiOpenAdapter.

    Po MiniportWdiAllocateAdaptervolá komponenta Microsoft MiniportWdiOpenAdapter k načtení firmwaru a inicializaci hardwaru.

  3. Více příkazů WDI pomocí MiniportOidRequest.

    Jakmile MiniportWdiOpenAdapter, komponenta Microsoft odešle do miniportu IHV následující úlohy/ vlastnosti/volání.

    1. Zavolejte MiniportWdiTalTxRxInitialize k inicializaci cesty k datům a obslužných rutin výměny.
    2. Zavolejte OID_WDI_GET_ADAPTER_CAPABILITIES, abyste získali možnosti adaptéru.
    3. Voláním OID_WDI_SET_ADAPTER_CONFIGURATION nakonfigurujte adaptér.
    4. Proveďte volání OID_WDI_TASK_SET_RADIO_STATE, abyste nastavili počáteční stav rádia, pokud ještě není v očekávaném stavu.
    5. Zavolejte MiniportWdiTalTxRxStart pro nastavení cesty k datům.
    6. Voláním OID_WDI_TASK_CREATE_PORT vytvořte počáteční port.

    Další příkazy mohou být také odeslány do součásti IHV jako součást zpracování MiniportInitializeEx součásti Microsoft. Dokud však není volána funkce MiniportWdiStartOperation, komponenta Microsoftu neodesílá žádné úkoly, které potřebují komunikaci přes bezdrátové připojení. S výjimkou OID_WDI_TASK_OPEN, které se vždy odesílají jako první, se může změnit pořadí ostatních příkazů nebo volání.

    Pomocí dat získaných z ovladače miniportu WDI IHV volá komponenta Microsoft NdisMSetMiniportAttributes a nastavuje NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES a NDIS_MINIPORT_ADAPTER_NATIVE_802_11_ATTRIBUTES na NDIS.

  4. Zavolejte MiniportWdiStartOperation.

    Jedná se o volitelnou obslužnou rutinu miniportu WDI uvnitř NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS, kterou může ovladač IHV použít k provádění dalších úloh MiniportInitializeEx. IHV miniport může také použít jako indikaci, že komponenta od Microsoftu dokončila inicializaci miniportu, a miniport může zahájit všechny potřebné aktivity na pozadí.

    Následující diagram znázorňuje tok MiniportInitializeEx.

    inicializační tok miniportu WDI.

    Pokud se zprostředkující operace nezdaří, komponenta Microsoftu vrátí zpět předchozí operace a nezdaří se nástup miniportu. Pokud například OID_WDI_TASK_CREATE_PORT selže, cesta k datům se vyčistí, OID_WDI_TASK_CLOSE se odešle a miniport selže.

MiniportHaltEx

V nativním miniportu Wi-Fi se MiniportHaltEx používá k tomu, aby miniport zastavil operace a vyčistil instanci adaptéru. V modelu WDI Microsoft komponenta zpracovává původní volání MiniportHaltEx a následně ho rozdělí na více volání rozhraní WDI.

  1. Volejte MiniportWdiStopOperation.

    Jedná se o volitelnou funkci obslužné rutiny miniportu WDI v rámci NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS, kterou může ovladač IHV využít k vrácení operací provedených v MiniportWdiStartOperation.

  2. Více příkazů WDI pomocí MiniportOidRequest.

    Po MiniportWdiStopOperationodešle komponenta Microsoft úkoly/vlastnosti miniportu IHV k vyčištění aktuálního stavu ovladače IHV. Toto vyčištění může zahrnovat následující:

    1. Volejte OID_WDI_TASK_DISCONNECT/OID_WDI_TASK_STOP_AP, aby byla zrušena všechna existující připojení.
    2. Voláním OID_WDI_TASK_DELETE_PORT odstraňte všechny vytvořené porty.
    3. Voláním MiniportWdiTalTxRxStop zastavte cestu k datům.
    4. Volání MiniportWdiTalTxRxDeinitialize pro deinicializaci datové cesty.
    5. Volání pro vyčištění stavu hardwaru To se odešle do IHV pomocí MiniportWdiCloseAdapter, který byl registrován ovladačem IHV.

  3. Jakmile jsou volány všechny výše uvedené příkazy, komponenta Microsoft zavolá MiniportWdiFreeAdapter, aby požádala ovladač IHV o odstranění jakéhokoli stavu softwaru, který může mít.

Následující diagram znázorňuje tok miniportHaltEx.

zastavení wdi miniportu.

Zpracování MiniportHaltEx se neprovádí, pokud je zařízení neočekávaně odebráno nebo je-li systém vypínán. Pokud chcete odebrat překvapení, projděte si chování obslužné rutiny MiniportDevicePnPEventNotify. Informace o vypnutí systému naleznete v chování obslužné rutiny MiniportShutdownEx.

MiniportDriverUnload

MiniportDriverUnload je obslužný program, který se volá před tím, než je uvolněn miniport WDI IHV. Ovladač miniportu WDI IHV volá komponentu Microsoftu, aby se odregistrovala sama. Komponenta Microsoft volá NdisMDeregisterMiniportDriver.

Následující diagram znázorňuje tok MiniportDriverUnload.

tok odstranění ovladače wdi miniport.

MiniportPause

Požadavky NDIS MiniportPause jsou zpracovávány komponentou Microsoftu. V rámci MiniportPause komponenta Microsoft zastaví cestu k datům a počká, až se vyčistí. Miniport WDI IHV se může volitelně zaregistrovat pro zpětné volání MiniportWdiPostAdapterPause, které je voláno komponentou společnosti Microsoft po dokončení vyčištění datové cesty.

Následující diagram znázorňuje tok MiniportPause.

tok pozastavení miniportu wdi.

MiniportRestart

Požadavky na NDIS MiniportRestart jsou zpracovávány komponentou Microsoft. V rámci MiniportRestartu komponenta Microsoftu zruší pozastavení cesty dat, které bylo provedené jako součást MiniportPause. Miniport WDI IHV se může volitelně zaregistrovat k MiniportWdiPostAdapterRestart zpětnému volání, které je voláno komponentou od Microsoftu po dokončení restartu datové cesty.

Následující diagram znázorňuje tok MiniportRestartu.

tok restartování miniportu wdi.

MiniportResetEx

MiniportResetEx nezpracovává komponenta Microsoftu. Miniport WDI IHV se může volitelně zaregistrovat pro MiniportResetEx callback, který je volán komponentou Microsoftu.

MiniportDevicePnPEventNotify

MiniportDevicePnPEventNotify slouží k upozornění ovladače NDIS na události PNP, jako je neočekávané odstranění zařízení. Když NDIS toto oznámení odešle, je nejprve předáno miniportu WDI IHV ke zpracování. Jakmile komponenta IHV dokončí zpracování, komponenta Microsoftu provede příslušné zpracování pro tuto událost. Volání přesměrované do komponenty IHV není serializováno s jinými úlohami a zpětnými voláními.

Následující diagram znázorňuje tok MiniportDevicePnPEventNotify.

tok oznámení pnp pro ovladač disku miniport wdi.

MiniportShutdownEx

MiniportShutdownEx slouží k oznámení ovladače NDIS o událostech vypnutí systému. Když NDIS toto oznámení odešle, zpracovává ho nejprve komponenta Microsoftu. Jakmile komponenta Microsoftu dokončí zpracování, předá událost miniportu WDI IHV ke zpracování.

Následující diagram znázorňuje tok MiniportShutdownEx.

tok vypnutí miniportu wdi.

MiniportOidRequest

Obslužná rutina MiniportOidRequest je požadovaná obslužná rutina, kterou musí implementovat miniport WDI IHV. Komponenta Microsoftu ji používá k odesílání příkazů WDI do miniportu IHV. Používá se také k předávání identifikátorů OID, které komponenta Microsoft nezpracuje s miniportem IHV.

MiniportOidRequest volání do miniportu WDI IHV by mělo být považováno za zprávu M1 pro příkaz WDI. Dokončení identifikátoru OID (buď prostřednictvím NdisMOidRequestComplete, nebo vrácením, který není čekající od MiniportOidRequest) by se měl považovat za zprávu M3 pro úkol nebo příkaz WDI.

Pro každý příkaz WDI existují dvě potenciální pole, kde může být vrácen kód NDIS_STATUS pro operaci – stavový kód z volání MiniportOidRequest (nebo NdisMOidRequestComplete) a stavový kód v poli WDI_MESSAGE_HEADER (buď při dokončení identifikátoru OID, nebo prostřednictvím NdisMIndicateStatusEx). Komponenta Microsoftu se vždy podívá na NDIS_STATUS z dokončení identifikátoru OID, než se podívá na pole WDI_MESSAGE_HEADERStatus. Očekávání komponenty IHV pro zpracování WDI OID jsou následující.

  1. Identifikátory OID WDI se odesílají do komponenty IHV pomocí NDIS_OID_REQUESTRequestTypeNdisRequestMethoda odpovídající zpráva a délka zprávy jsou v polích DATA.METHOD_INFORMATION.InformationBuffer a DATA.METHOD_INFORMATION.InputBufferLength.
  2. Komponenta IHV hlásí chybu v dokončení OID, pokud při zpracování příkazu dojde k chybě, a nastaví pole Status v WDI_MESSAGE_HEADER na neúspěšné, pokud dojde k selhání na úrovni Wi-Fi.
  3. U úkolů a vlastností je číslo portu požadavku v poli WDI_MESSAGE_HEADERPortId. Hodnota PortNumber v NDIS_OID_REQUEST je vždy nastavená na 0.
  4. Pro dokončení identifikátoru OID je přijatelné, aby MiniportOidRequest vrátit NDIS_STATUS_PENDING a dokončit OID později (synchronně nebo asynchronně) pomocí NdisMOidRequestComplete.
  5. Pokud komponenta IHV dokončí OID s NDIS_STATUS_SUCCESS, musí vyplnit pole BytesWritten požadavku OID odpovídajícím počtem bajtů, včetně prostoru pro WDI_MESSAGE_HEADER.
  6. Pokud komponenta IHV nemá dostatek místa v poli DATA.METHOD_INFORMATION.OutputBufferLength k vyplnění odpovědi, dokončí OID s NDIS_STATUS_BUFFER_TOO_SHORT a naplní pole DATA.METHOD_INFORMATION.BytesNeeded. Komponenta Microsoftu se může pokusit přidělit vyrovnávací paměť požadované velikosti a odeslat novou žádost k IHV.
  7. Pokud se jedná o úkol, úkol M4 (NdisMIndicateStatusEx) musí být indikováno pouze v případě, že byl úkol nahlášen jako úspěšně zahájen – dokončení OID bylo úspěšné a Status v WDI_MESSAGE_HEADER v dokončení OID bylo úspěšné.

Následující diagram znázorňuje příklad požadavku NDIS OID, který se mapuje na jeden příkaz WDI. Když operační systém odešle požadavek OID, komponenta Microsoftu ji převede na požadavek WDI OID a odešle požadavek WDI OID do miniportu IHV. Jakmile miniport IHV dokončí identifikátor OID, komponenta Microsoft odpovídajícím způsobem dokončí původní požadavek OID.

pořadí požadavků wdi miniport oid pro jeden příkaz wdi.

Pokud OriginalOidRequest mapuje na více WDI OidRequests a některý z těchto WDI požadavků selže, OriginalOidRequest také selže. Pokud už je dokončena podmnožina zprostředkujících operací, pokusí se komponenta Microsoftu vrátit zpět operace, které podporují vyčištění.

Následující diagram znázorňuje příklad požadavku NDIS OID, který je zpracován komponentou Microsoftu. Když operační systém odešle požadavek OID, komponenta Microsoft zpracuje a dokončí identifikátor OID. Tento identifikátor OID není předán miniportu WDI IHV.

pořadí požadavků OID pro WDI miniport zpracovávané komponentou Microsoft.

Identifikátory OID, kterým komponenta Microsoftu nerozumí, se předávají přímo komponentě IHV ke zpracování.

sekvence žádosti miniportu WDI OID pro OIDy, které nejsou spravovány komponentou společnosti Microsoft.

Chování MiniportOidRequest zůstává nezměněné u WDI IHV miniportu (ve srovnání s nativním miniportem Wi-Fi). Volání jsou serializována a miniport IHV je může dokončit buď synchronně, nebo asynchronně pomocí volání NdisMOidRequestComplete.

MiniportCancelOidRequest

Jedná se o volitelnou obslužnou rutinu, kterou používá miniport WDI IHV, který potřebuje zpracovat identifikátory OID, které nejsou namapované na zprávy WDI. Tato obslužná rutina se nepoužívá pro žádné WDI OID. Identifikátory OID WDI musí být dokončeny rychle a není nutné, aby se ovladač miniportu IHV pokusil zrušit čekající identifikátor OID. Zrušení úkolů WDI se provádí prostřednictvím požadavku na zrušení úkolu OID. U nemapovaných identifikátorů OID je očekávané chování definované rozhraním NDIS.

NdisMIndicateStatusEx

NdisMIndicateStatusEx používá miniport WDI IHV k odesílání indikací komponentě Microsoftu. Můžou to být nežádoucí indikace, jako jsou selhání MIC TKIP, nebo vyžádané indikace pro dokončení úkolu (M4).

Následující diagram znázorňuje příklad indikace WDI, která má odpovídající indikaci NDIS/Native Wi-Fi. Pokud je indikace odeslána miniportem IHV do komponenty Microsoftu, převede ji na existující indikaci a předá ji operačnímu systému.

tok indikace stavu WDI miniportu.

Následující diagram znázorňuje příklad indikace WDI, která neobsahuje žádnou odpovídající indikaci NDIS/Native Wi-Fi. To zpracovává komponenta Microsoftu.

indikace stavu WDI bez přímého mapování na NDIS.

Následující diagram znázorňuje označení, které komponenta Microsoftu nerozpozná. Indikace se předá as-is operačnímu systému.

označení stavu wdi nerozpoznané komponentou Microsoft.

Chování NdisMIndicateStatusEx se u ovladače miniportu WDI IHV nemění (ve srovnání s nativním Wi-Fi miniportem).

MiniportDirectOidRequest

Toto je volitelná obslužná rutina, kterou registruje ovladač miniportu WDI IHV, pokud potřebuje zpracovat přímé OID, které nejsou namapovány na zprávy WDI. Všechny existující přímé OIDy pro Wi-Fi Direct jsou mapovány na zprávy WDI, takže není třeba, aby tato obslužná rutina podporovala tuto funkci. Nepodporované přímé identifikátory OID nejsou serializovány komponentou Microsoftu.

MiniportCancelDirectOidRequest

Jedná se o volitelnou obslužnou rutinu, kterou používá miniport WDI IHV, který potřebuje zpracovávat přímé identifikátory OID, které nejsou namapované na zprávy WDI. U nemapovaných OID je očekávané chování definováno NDIS.

MiniportSendNetBufferLists

Tato obslužná rutina se nepoužívá v ovladači miniportu WDI IHV a neměla by být poskytována. Komponenta Microsoftu používá obslužné rutiny cesty k datům registrovaným prostřednictvím NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS k odesílání paketů do miniportu IHV.

MiniportCancelSend

Tato obslužná rutina se nepoužívá v ovladači miniportu WDI IHV a neměla by se poskytovat.

MiniportReturnNetBufferLists

Tato obslužná rutina se nepoužívá v ovladači miniportu WDI IHV a neměla by být zadána. Komponenta Microsoftu používá obslužné rutiny datové cesty registrované prostřednictvím NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS pro vrácení paketů přijatých do miniportu IHV.

Obslužná rutina WDI: MiniportWdiOpenAdapter

Obslužnou rutinu MiniportWdiOpenAdapter používá komponenta Microsoftu k zahájení operace Otevření úlohy na ovladači IHV. Toto volání musí být rychle dokončeno a pokud byla operace otevření úspěšně spuštěna, musí IHV vrátit NDIS_STATUS_SUCCESS pro toto volání a volat obslužnou rutinu OpenAdapterComplete, která je předána do parametru NDIS_WDI_INIT_PARAMETERSMiniportWdiAllocateAdapter.

Obslužná rutina WDI: MiniportWdiCloseAdapter

Obslužnou rutinu MiniportWdiCloseAdapter používá komponenta Microsoftu k zahájení operace Zavřít úlohu na ovladači IHV. Toto volání musí být dokončeno rychle, a pokud byla operace otevření úspěšně spuštěna, musí IHV vrátit NDIS_STATUS_SUCCESS pro toto volání a zavolat obslužnou rutinu CloseAdapterComplete, která je předána do parametru NDIS_WDI_INIT_PARAMETERS v rámci MiniportWdiAllocateAdapter.