функция обратного вызова MINIPORT_INITIALIZE (ndis.h)

Статья
02/29/2024

NDIS вызывает функцию MiniportInitializeEx драйвера мини-порта для инициализации адаптера мини-порта для операций сетевого ввода-вывода.

Примечание Функцию необходимо объявить с помощью типа MINIPORT_INITIALIZE . Дополнительные сведения см. в следующем разделе Примеры.

Синтаксис

MINIPORT_INITIALIZE MiniportInitialize;

NDIS_STATUS MiniportInitialize(
  [in] NDIS_HANDLE NdisMiniportHandle,
  [in] NDIS_HANDLE MiniportDriverContext,
  [in] PNDIS_MINIPORT_INIT_PARAMETERS MiniportInitParameters
)
{...}

Параметры

[in] NdisMiniportHandle

Дескриптор, предоставляемый NDIS, который идентифицирует адаптер мини-порта, который должен инициализировать драйвер мини-порта.

[in] MiniportDriverContext

Дескриптор выделенной драйвером контекстной области, в которой драйвер хранит сведения о состоянии и конфигурации. Драйвер мини-порта передал эту область контекста вФункция NdisMRegisterMiniportDriver.

[in] MiniportInitParameters

Указатель на NDIS_MINIPORT_INIT_PARAMETERS структуры, определяющей параметры инициализации адаптера мини-порта.

Возвращаемое значение

MiniportInitializeEx может возвращать одно из следующих значений состояния:

Код возврата	Описание
NDIS_STATUS_SUCCESS	MiniportInitializeEx настроили и настроили адаптер мини-порта и выделили все ресурсы, необходимые драйверу для выполнения сетевых операций ввода-вывода.
NDIS_STATUS_NOT_ACCEPTED	MiniportInitializeEx не удалось получить адаптер miniport для принятия параметров конфигурации, полученных miniportInitializeEx из реестра.
NDIS_STATUS_RESOURCES	MiniportInitializeEx не удалось выделить ресурсы для выполнения операций сетевого ввода-вывода. MiniportInitializeEx должен вызывать функцию NdisWriteErrorLogEntry , чтобы определить конфликт ресурсов (например, диапазон портов ввода-вывода, вектор прерывания, диапазон памяти устройства, если это необходимо). Предоставление записи журнала ошибок предоставляет пользователю или системным администраторам сведения, которые можно использовать для перенастройки компьютера во избежание конфликтов аппаратных ресурсов.
NDIS_STATUS_FAILURE	Сбой MiniportInitializeEx по причинам, не указанным в предыдущем списке. Драйвер должен вызвать NdisWriteErrorLogEntry с параметрами, указывающими причину сбоя.

NDIS вызывает MiniportInitializeEx как часть системной операции PnP. Драйверы указывают точку входа MiniportInitializeEx путем вызоваФункция NdisMRegisterMiniportDriver из подпрограммы DriverEntry. NDIS может вызывать MiniportInitializeEx после возврата DriverEntry . Дополнительные сведения см. в разделе DriverEntry of NDIS Miniport Drivers.

Для промежуточных драйверов NDIS NDIS может вызывать MiniportInitializeEx в контекстеФункция NdisIMInitializeDeviceInstanceEx или после ее возврата. Функция ProtocolBindAdapterEx такого драйвера обычно вызывает NdisIMInitializeDeviceInstanceEx.

Драйверы могут регистрироваться в качестве объединенного драйвера мини-порта и промежуточного драйвера (см. раздел NdisMRegisterMiniportDriver). Такой промежуточный драйвер минипорта работает аналогично промежуточному драйверу, наложенном на физический драйвер минипорта. Для каждого экземпляра виртуального или физического устройства драйвера miniport-intermediate, если для раздела реестра IMMiniport задано значение DWORD:0x0000001, NDIS вызывает функцию MiniportInitializeEx , зарегистрированную драйвером для виртуального устройства. В противном случае NDIS вызывает функцию MiniportInitializeEx драйвера, зарегистрированную драйвером для физического устройства.

Пока miniportInitializeEx не возвращается, NDIS не отправляет запросы на инициализацию адаптера мини-порта. Адаптер мини-порта находится в состоянии инициализации .

Чтобы получить сведения о конфигурации адаптера мини-порта, драйвер вызывает функции NdisOpenConfigurationEx и NdisReadConfiguration . Драйвер может вызвать функцию NdisMGetBusData для получения сведений о шине.

Водители мини-порта должны вызывать Функция NdisMSetMiniportAttributes и предоставление NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES структура, содержащая следующие атрибуты:

Дескриптор области контекста, выделенной драйвером.
Соответствующие флаги атрибутов.
Интервал времени ожидания для вызоваФункция MiniportCheckForHangEx.
Тип интерфейса.

Драйвер мини-порта передает NdisMSetMiniportAttributes маркер на член MiniportAdapterContext NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES. Драйвер сохраняет сведения о состоянии для указанного адаптера мини-порта в этой области контекста. NDIS передает этот дескриптор в качестве входного параметра другим функциям MiniportXxx .

Драйверы мини-порта должны задавать атрибуты в NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES структуру после задания атрибутов регистрации в структуре NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES и до установки дополнительных атрибутов.

MiniportInitializeEx также может выделять следующие ресурсы:

Память нестраничного пула
пулы структур NET_BUFFER и NET_BUFFER_LIST
Спин-блокировки
Таймеры
Порты ввода-вывода
DMA
Общая память
Прерывания

Если драйвер указывает, что получает с Функция NdisMIndicateReceiveNetBufferLists , функция MiniportInitializeEx должна вызывать NdisAllocateNetBufferListPool иФункции NdisAllocateNetBufferPool и сохранение дескрипторов, возвращаемых этими функциями NDIS. Как правило, сетевые данные, которые драйвер впоследствии указывает с помощью NdisMIndicateReceiveNetBufferLists ссылается на структуры, выделенные с помощьюФункция NdisAllocateNetBufferAndNetBufferList. Драйвер также может использовать структуры, выделенные с помощью NdisAllocateNetBuffer, иФункции NdisAllocateNetBufferList.

Если функции драйвера, отличные от функции MiniportInterrupt , совместно используют ресурсы, MiniportInitializeEx должен вызвать функцию NdisAllocateSpinLock , чтобы настроить все блокировки спина, необходимые для синхронизации доступа к таким общим ресурсам. Ресурсы, совместно используемые другими функциями драйвера в MiniportInterrupt, такие как регистры сетевого адаптера, защищены объектом прерывания, настроенным драйвером с помощьюФункция NdisMRegisterInterruptEx. Функции драйвера получают доступ к этим ресурсам путем вызоваФункция NdisMSynchronizeWithInterruptEx.

MiniportInitializeEx может вызывать функцию NdisAllocateTimerObject с предоставленной драйвером функции NetTimerCallback и указателем на память, выделенную драйвером для объекта таймера. Драйверы могут настроить несколько функций NetTimerCallback , каждая из которых имеет собственный объект таймера. Драйвер может вызвать функцию NdisSetTimerObject для включения периодической функции NetTimerCallback . Драйвер также может вызвать функцию NdisSetTimerObject , чтобы включить одноразовую функцию NetTimerCallback .

MiniportInitializeEx должен вызывать Функция NdisMSetMiniportAttributes перед вызовом любой функции NdisMXxx , например NdisMRegisterIoPortRange или NdisMMapIoSpace , которая запрашивает аппаратные ресурсы для адаптера мини-порта. MiniportInitializeEx должен вызвать NdisMSetMiniportAttributes , прежде чем пытаться выделить ресурсы для операций DMA.

Если устройство поддерживает шину master DMA, MiniportInitializeEx должен вызвать Функция NdisMRegisterScatterGatherDma после вызова NdisMSetMiniportAttributes и перед вызовомФункция NdisMAllocateSharedMemory. Если устройство поддерживает подчиненное DMA, MiniportInitializeEx должен вызвать NdisMSetMiniportAttributes перед вызовомФункция NdisMRegisterDmaChannel.

После вызова MiniportInitializeExФункция NdisMRegisterInterruptEx, NDIS может вызывать функцию MiniportInterrupt драйвера. NDIS вызывает MiniportInterrupt , если сетевой адаптер создает прерывание или если любое другое устройство, с которым сетевой адаптер использует прерывание, создает прерывание. Обратите внимание, что драйвер мини-порта может получить прерывание сразу после вызова NdisMRegisterInterruptEx и продолжает получать прерывания до вызоваФункция NdisMDeregisterInterruptEx возвращает.

MiniportInitializeEx должен протестировать сетевой адаптер, чтобы убедиться, что оборудование настроено правильно. Если драйвер должен ждать изменения состояния в оборудовании, MiniportInitializeEx может использовать функцию NdisWaitEvent или NdisMSleep .

После успешного возврата MiniportInitializeEx адаптер мини-порта находится в состоянии Приостановлено . NDIS может вызвать функцию MiniportRestart , чтобы перевести адаптер минипорта в состояние Выполняется .

Если MiniportInitializeEx возвращает NDIS_STATUS_SUCCESS, драйвер должен освободить все ресурсы для адаптера мини-порта в функции MiniportHaltEx .

Драйвер должен вызвать NdisMSetMiniportAttributes и задать GeneralAttributes в структуре NDIS_MINIPORT_ADAPTER_ATTRIBUTES , если он возвращает NDIS_STATUS_SUCCESS.

Если miniportInitializeEx завершился сбоем, MiniportInitializeEx должен освободить все выделенные ресурсы перед возвратом, а адаптер мини-порта возвращается в состояние Остановлено .

NDIS вызывает MiniportInitializeEx по адресу IRQL = PASSIVE_LEVEL.

Примеры

Чтобы определить функцию MiniportInitializeEx , необходимо сначала предоставить объявление функции, определяющее тип определяемой функции. Windows предоставляет набор типов функций для драйверов. Объявление функции с помощью типов функций помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить функцию MiniportInitializeEx с именем MyInitializeEx, используйте тип MINIPORT_INITIALIZE , как показано в следующем примере кода:

MINIPORT_INITIALIZE MyInitializeEx;

Затем реализуйте функцию следующим образом:

_Use_decl_annotations_
NDIS_STATUS
 MyInitializeEx(
    NDIS_HANDLE  NdisMiniportHandle,
    NDIS_HANDLE  MiniportDriverContext,
    PNDIS_MINIPORT_INIT_PARAMETERS  MiniportInitParameters
    )
  {...}

Тип функции MINIPORT_INITIALIZE определен в файле заголовка Ndis.h. Чтобы более точно определить ошибки при запуске средств анализа кода, не забудьте добавить заметку Use_decl_annotations в определение функции. Заметка Use_decl_annotations гарантирует, что будут использоваться заметки, которые применяются к типу функции MINIPORT_INITIALIZE в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в статье Объявление функций с помощью типов ролей функций для драйверов NDIS.

Сведения о Use_decl_annotations см. в статье Поведение функции с заметками.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается в NDIS 6.0 и более поздних версиях.
Целевая платформа	Windows
Header	ndis.h (включая Ndis.h)
IRQL	PASSIVE_LEVEL