функция обратного вызова MINIPORT_INITIALIZE (ndis.h)
NDIS вызывает функцию MiniportInitializeEx драйвера мини-порта для инициализации адаптера мини-порта для операций сетевого ввода-вывода.
Синтаксис
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 может возвращать одно из следующих значений состояния:
| Код возврата | Описание |
|---|---|
|
MiniportInitializeEx настроили и настроили адаптер мини-порта и выделили все ресурсы, необходимые драйверу для выполнения сетевых операций ввода-вывода. |
|
MiniportInitializeEx не удалось получить адаптер miniport для принятия параметров конфигурации, полученных miniportInitializeEx из реестра. |
|
MiniportInitializeEx не удалось выделить ресурсы для выполнения операций сетевого ввода-вывода. MiniportInitializeEx должен вызывать функцию NdisWriteErrorLogEntry , чтобы определить конфликт ресурсов (например, диапазон портов ввода-вывода, вектор прерывания, диапазон памяти устройства, если это необходимо). Предоставление записи журнала ошибок предоставляет пользователю или системным администраторам сведения, которые можно использовать для перенастройки компьютера во избежание конфликтов аппаратных ресурсов. |
|
Сбой 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.
- Тип интерфейса.
Драйверы мини-порта должны задавать атрибуты в NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES структуру после задания атрибутов регистрации в структуре NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES и до установки дополнительных атрибутов.
MiniportInitializeEx также может выделять следующие ресурсы:
- Память нестраничного пула
- Спин-блокировки
- Таймеры
- Порты ввода-вывода
- DMA
- Общая память
- Прерывания
Если функции драйвера, отличные от функции 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 |