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

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

  • Статья

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

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

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

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

  1. Сначала перейдите к свойствам конфигурации->параметрам драйвера->модели драйвера и убедитесь, что тип драйвера установлен как KMDF, и что версия KMDF старшая и версия KMDF младшая обе пустые.

  2. В свойствах проекта откройте параметры драйвера>драйвер сетевого адаптера и установите ссылку на расширение класса сетевого адаптера в значение Да.

    • Если преобразованный драйвер продолжает вызывать API NDIS, продолжите связываться с ndis.lib.

  3. Удалите макросы препроцессора NDIS, например NDIS650_MINIPORT=1.

  4. Добавьте следующие заголовки в каждый исходный файл (или в общий или предварительно скомпилированные заголовки):

    #include <ntddk.h>
#include <wdf.h>
#include <netadaptercx.h>

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

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

[Yourdriver.wdfsect]
KmdfLibraryVersion = <insert here>

  6. Добавьте новые необходимые ключевые слова сети в раздел NT в INF:

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

Удалите вызов 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, поэтому вам не нужно вносить глубокие изменения в логику. Основное различие заключается в том, что теперь можно запрашивать эти флаги во время последовательности выключения питания. См. последовательность выключения для драйвера клиента 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.