Перенос драйверов минипорта NDIS в NetAdapterCx

Статья
05/03/2024

На этой странице описывается преобразование мини-драйвера NDIS 6.x в драйвер клиента NetAdapterCx.

Общие сведения о WDF см. в руководстве по разработке драйверов WDF.

Параметры компиляции

Откройте существующий проект драйвера мини-порта NDIS в Visual Studio и выполните следующие действия, чтобы преобразовать его в проект KMDF.

Во-первых, перейдите к модели "Свойства драйвера конфигурации" Параметры-Driver> и убедитесь, что для параметра "Тип драйвера" задано значение KMDF, а для основнойверсии KMDF и kmDF - значение "Дополнительный".>
В свойствах проекта откройте драйвер Параметры-сетевой> адаптер и установите для параметра Link to the Network Adapter Class Extension to Yes.
- Если преобразованный драйвер по-прежнему вызовет API NDIS, перейдите по ссылке на ndis.lib.
Удалите макросы препроцессора NDIS, например NDIS650_MINIPORT=1.
Добавьте следующие заголовки в каждый исходный файл (или в общий или предварительно скомпилированные заголовки):
```
#include <ntddk.h>
#include <wdf.h>
#include <netadaptercx.h>
```

Добавьте стандартные украшения WDF в INF:

[Yourdriver.Wdf]
KmdfService = Yourdriverservice, Yourdriver.wdfsect

[Yourdriver.wdfsect]
KmdfLibraryVersion = <insert here>

Добавьте новые необходимые сетевые ключевое слово в раздел NT inf:
- *If Подключение orPresent
- *Подключение ionType
- *DirectionType
- *AccessType
- *HardwareLoopback
  
  Дополнительные сведения об этих ключевое слово и примере см. в разделе INF-файлы для клиентских драйверов NetAdapterCx.

Инициализация драйвера

Удалите вызов NdisMRegisterMiniportDriver из DriverEntry и добавьте следующее:

WDF_DRIVER_CONFIG_INIT(&config, EvtDriverDeviceAdd);
status = WdfDriverCreate(. . . );
if (!NT_SUCCESS(status)) {
  return status;
}

Если он задан, удалите флаг WdfDriverInitNoDispatchOverride из вызова WdfDriverCreate.

DriverUnload — это необязательная подпрограмма для сетевого драйвера WDF, поэтому ее можно удалить, если вы хотите. Не вызывайте NdisMDeregisterMiniportDriver из DriverUnload.

Инициализация устройства

Затем вы распределите код из MiniportInitializeEx в соответствующие обработчики обратных вызовов событий WDF, некоторые из которых являются необязательными. Дополнительные сведения о последовательности обратного вызова см. в разделе "Последовательность power Up" для драйвера клиента WDF сетевого адаптера.

Вы вызовете методы, эквивалентные NdisMSetMiniportAttributes при запуске сетевого адаптера, но перед вызовом NetAdapterStart. Однако вместо вызова одной подпрограммы с универсальной структурой NDIS_MINIPORT_ADAPTER_ATTRIBUTES драйвер клиента вызывает различные функции, чтобы задать различные типы возможностей.

Сведения о обратных вызовах необходимо указать и когда запустить сетевой адаптер, см. в разделе инициализация устройства и адаптера.

Чтение конфигурации из реестра

Затем замените вызовы NdisOpenConfigurationEx и связанные функции методами NetConfiguration* . Методы NetConfiguration* похожи на Ndis*Configuration* функции, и вам не нужно реструктурировать код.

Дополнительные сведения см. в разделе "Доступ к сведениям о конфигурации".

Получение кодов управления ввода-вывода (IOCTLs) из пользовательского режима

Прочитайте этот раздел, если драйвер NDIS вызывает NdisRegisterDeviceEx, подпрограмму, используемую для создания объекта устройства управления (CDO) для получения ioCTLs из пользовательского режима.

Это можно сделать двумя способами в сетевом драйвере WDF.

Самый простой порт — создать объект устройства управления путем вызова WdfControlDeviceInitAllocate из EVT_WDF_DRIVER_DEVICE_ADD обратного вызова клиента. Дополнительные сведения см. в разделе "Использование объектов устройств управления".

Однако рекомендуется создать интерфейс устройства, как описано в разделе "Использование интерфейсов устройств".

Завершение инициализации устройства

На этом этапе в EVT_WDF_DRIVER_DEVICE_ADD вы можете сделать что-либо другое, что вы хотите инициализировать устройство, например выделение прерываний.

Обработка уведомлений об изменении состояния питания

Драйвер клиента WDF не получает OID_PNP_SET_POWER для изменений состояния питания.

Вместо этого клиент WDF регистрирует необязательные функции обратного вызова для получения уведомлений об изменении состояния питания. Общие сведения см. в статье о поддержке PnP и управления питанием в драйверах функций.

Как правило, код в обработчике OID_PNP_SET_POWER перемещается в EVT_WDF_DEVICE_D0_EXIT и EVT_WDF_DEVICE_D0_ENTRY.

Так как виртуальная машина состояния WDF немного отличается, может потребоваться внести незначительные изменения в код.

В частности, в функции обратного вызова MiniportInitializeEx драйвер минипорта NDIS выполняет задачи однократной инициализации, а также работает над переносом устройства в состояние D0. Затем он повторяет работу, чтобы перейти к D0 в своем обработчике OID_PNP_SET_POWER.

В отличие от этого, клиент WDF выполняет однократные задачи инициализации в обратных вызовах событий до EVT_WDF_DEVICE_D0_ENTRY, во время которого устройство находится в состоянии низкой мощности. Затем это делает работу, чтобы перейти в D0 в EVT_WDF_DEVICE_D0_ENTRY.

Чтобы подвести итог, в WDF вы помещаете код "перейти к D0" в одном месте вместо двух.

Дополнительные сведения о последовательности обратных вызовов см. в разделе "Последовательность Power Up" для драйвера клиента NetAdapterCx.

Запросы и настройка возможностей управления питанием

Аналогичным образом драйвер клиента WDF не получает OID_PM_PARAMETERS для запроса или настройки возможностей оборудования управления питанием сетевого адаптера.

Вместо этого драйвер запрашивает необходимую конфигурацию пробуждения по локальной сети (WoL) из объекта NETPOWERSETTINGS. Дополнительные сведения см. в разделе "Настройка управления питанием".

Фактические флаги, которые вы получаете обратно, имеют ту же семантику, что и для минипорта NDIS 6, поэтому вам не нужно вносить глубокие изменения в логику. Основное различие заключается в том, что теперь можно запрашивать эти флаги во время последовательности выключения питания. См . последовательность power down для драйвера клиента NetAdapterCx.

После перемещения этого кода можно удалить обработчики OID для OID_PNP_SET_POWER и OID_PM_PARAMETERS.

Так как платформа NetAdapter хранит устройство в D0, а узел использует сетевой интерфейс, клиент обычно не реализует логику питания; Поведение питания NetAdapter по умолчанию достаточно.

Путь к данным

Модель программирования пути к данным значительно изменилась. Ниже приведены некоторые ключевые отличия.

В модели NetAdapter сетевой трафик больше не является адаптером, как и в NDIS, а вместо очереди WDF. См. статью "Создание очередей ввода-вывода".
Вместо NET_BUFFER_LIST и пулов NET_BUFFER NetAdapterCx представляет кольцевой буфер, состоящий из чистых пакетов, которые сопоставляют с NDIS следующим образом:
- NET_PACKET похож на NET_BUFFER_LIST + NET_BUFFER.
- NET_PACKET_FRAGMENT аналогичен списку дескрипторов памяти (MDL). Каждый NET_PACKET имеет один или несколько из них.
- Дополнительные сведения о структурах замены и их использовании см . в дескрипторах пакетов и расширениях.
В NDIS 6.x минипорт должен обрабатывать семантику запуска и приостановки. В модели NetAdapterCx это больше не так.
Обратный вызов EVT_RXQUEUE_ADVANCE аналогичен MINIPORT_RETURN_NET_BUFFER_LISTS в NDIS 6.x.
Обратный вызов EVT_TXQUEUE_ADVANCE аналогичен MINIPORT_SEND_NET_BUFFER_LISTS в NDIS 6.x.

Удаление устройства

Удаление устройства для драйвера сетевого адаптера WDF совпадает с любым другим драйвером устройств WDF, без необходимости обработки сети. Путь к сетевым данным сначала завершает работу, а затем устройство WDF. Дополнительные сведения о завершении работы WDF см. в разделе "Пользователь отключает устройство".

Обработчик MiniportHaltEx, скорее всего, будет распределен между EVT_WDF_DEVICE_D0_EXIT и EVT_WDF_DEVICE_RELEASE_HARDWARE.

Клиент WDF не должен удалять NetAdapter или какие-либо очереди datapath, созданные им. WDF автоматически удаляет эти объекты.

Можно удалить MiniportShutdownEx, MiniportResetEx и MiniportCheckForHangEx. Эти обратные вызовы больше не поддерживаются.

Эквиваленты функций NDIS-WDF

Большинство NdisXxx функций можно заменить эквивалентом WDF. Как правило, необходимо найти, что вам нужны очень мало функций, импортируемых из NDIS.SYS.

Список эквивалентов функций см . в эквивалентах функций NDIS-WDF.

Отладка

См . сведения об отладке драйвера клиента NetAdapterCx.

Расширение отладчика !ndiskd.netadapter показывает аналогичные результаты тому, что показывает !ndiskd.miniport для драйвера NDIS 6.

Заключение

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

Примечание. NetAdapterCx в настоящее время не поддерживает загрузку iSCSI.

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