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

Статья
08/07/2023

Функция MiniportPnpIrp позволяет драйверу мини-порта при необходимости управлять своими ресурсами Plug and Play (PnP). Сам miniportPnpIrp никогда не определяется драйверами минипорта напрямую. Вместо этого он определяется как MiniportFilterResourceRequirements или MiniportStartDevice.

Если она определена как MiniportFilterResourceRequirements, эта функция позволяет драйверу мини-порта изменять требования к ресурсам для устройства. Если он определен как MiniportStartDevice, эта функция позволяет драйверу мини-порта удалять ресурсы, добавленные вФункция MiniportFilterResourceRequirements.

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

Синтаксис

MINIPORT_PNP_IRP MiniportPnpIrp;

NDIS_STATUS MiniportPnpIrp(
  [in] NDIS_HANDLE MiniportAddDeviceContext,
  [in] PIRP Irp
)
{...}

Параметры

[in] MiniportAddDeviceContext

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

[in] Irp

Если эта функция определена как MiniportFilterResourceRequirements, этот параметр является указателем на IRP_MN_FILTER_RESOURCE_REQUIREMENTS для обработки драйвером.

Если эта функция определена как MiniportStartDevice, этот параметр является указателем на IRP_MN_START_DEVICE IRP.

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

MiniportPnpIrp возвращает одно из следующих значений:

Код возврата	Описание
NDIS_STATUS_SUCCESS	Драйвер мини-порта успешно обработал запрос на запуск устройства.
NDIS_STATUS_RESOURCES	Драйверу мини-порта не удалось обработать запрос на запуск устройства из-за нехватки ресурсов.
NDIS_STATUS_FAILURE	Сбой MiniportFilterResourceRequirements по другим причинам, кроме нехватки ресурсов.

Функция MiniportFilterResourceRequirements является необязательной. Драйверы miniport должны зарегистрировать эту функцию, если они поддерживают MSI-X, и верно хотя бы одно из следующих значений:

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

Чтобы зарегистрировать MiniportFilterResourceRequirements, укажите точку входа в структура NDIS_MINIPORT_PNP_CHARACTERISTICS .

NDIS вызывает функцию MiniportFilterResourceRequirements после получения NDIS IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP для сетевого интерфейса карта (NIC). NDIS вызывает MiniportFilterResourceRequirements после того, как базовые драйверы функций в стеке устройств завершили обработку IRP.

Драйвер мини-порта должен быть подготовлен к обработке IRP_MN_FILTER_RESOURCE_REQUIREMENTS из MiniportFilterResourceRequirements сразу после того, как функция MiniportAddDevice возвращает NDIS_STATUS_SUCCESS.

Драйвер мини-порта может задать политику сходства для каждого ресурса типа CmResourceTypeInterrupt , описывающего сообщение MSI-X. Если политика сходства запрашивает нацеливание на определенный набор процессоров, драйвер мини-порта также устанавливает маску KAFFINITY в члене Interrupt.TargetedProcessors в структуре IO_RESOURCE_DESCRIPTOR .

Если драйверу NDIS 6.1 или более поздней версии требуется больше ресурсов прерывания сообщений, он может добавить дополнительные ресурсы прерывания сообщений в список ресурсов. Если операционная система может предоставить больше ресурсов прерывания сообщений, адаптер мини-порта получает добавленные ресурсы прерывания сообщений при запуске.

Каждому ресурсу прерывания сообщения в списке назначается номер сообщения, соответствующий порядку в списке ресурсов. Сообщения нумеруются от 0 до общего числа ресурсов прерывания сообщений минус один.

Чтобы назначить запись таблицы MSI-X ЦП во время выполнения, драйвер мини-порта может вызвать Функция NdisMConfigMSIXTableEntry .

Драйвер мини-порта может удалить все ресурсы типа CmResourceTypeInterrupt , которые являются ресурсами прерывания сообщений. Затем драйвер может зарегистрироваться для прерываний на основе строк в функции MiniportInitializeEx . Если драйвер мини-порта не удаляет эти ресурсы прерываний сообщений, операционная система завершится сбоем, если драйвер попытается зарегистрировать прерывание на основе строки в MiniportInitializeEx.

Чтобы выделить память для нового списка требований к ресурсам, используйтеФункция NdisAllocateMemoryWithTagPriority. Драйвер мини-порта может освободить память для старого списка требований к ресурсам с помощью функции NdisFreeMemory . Диспетчер PnP освобождает любую память, выделенную драйвером, после завершения связанного IRP.

Драйверы мини-портов не должны изменять другие ресурсы, такие как ресурсы CmResourceTypeMemory и CmResourceTypePort . Драйверы мини-портов не должны добавлять новый ресурс в список ресурсов. Однако драйверы мини-портов могут добавлять дополнительные ресурсы прерывания сообщений. Если драйвер мини-порта добавляет дополнительные ресурсы прерывания сообщений, драйвер не должен удалять их из функции MiniportStartDevice .

Если драйвер мини-порта возвращает NDIS_STATUS_RESOURCES или NDIS_STATUS_FAILURE из MiniportFilterResourceRequirements, NDIS будет использовать требования к ресурсам, указанные родительским драйвером автобуса.

NDIS может вызывать MiniportFilterResourceRequirements несколько раз, прежде чем NDIS вызовет функцию MiniportRemoveDevice . Но NDIS вызывает MiniportFilterResourceRequirements , только если устройство находится в остановленном состоянии.

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

Пример MiniportFilterResourceRequirements

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

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

MINIPORT_FILTER_RESOURCE_REQUIREMENTS MyFilterResourceRequirements;

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

_Use_decl_annotations_
NDIS_STATUS
 MyFilterResourceRequirements(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

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

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

Примечания к miniportStartDevice

MiniportStartDevice — это необязательная функция. Драйверы miniport, поддерживающие MSI-X, могут указывать точку входа для этой функции в структура NDIS_MINIPORT_PNP_CHARACTERISTICS . Когда NDIS получает запрос от диспетчера Plug and Play (PnP) на запуск устройства, NDIS вызывает функцию MiniportStartDevice, если она есть. Если драйвер мини-порта добавляет новые ресурсы в Функция MiniportFilterResourceRequirements должна предоставлять функцию MiniportStartDevice для удаления ресурсов.

Если драйвер мини-порта изменяет ресурсы таким образом, что базовый драйвер автобуса не может распознать ресурсы, драйвер должен предоставить функцию MiniportStartDevice для удаления ресурсов. Базовый драйвер автобуса может не выполнить запрос на запуск устройства, если он не распознает ресурсы, добавленные драйвером мини-порта в MiniportFilterRequirements. Если драйвер мини-порта добавляет ресурсы прерывания сообщений, он не должен удалять их из MiniportStartDevice.

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

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

Пример MiniportStartDevice

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

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

MINIPORT_START_DEVICE MyStartDevice;

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

_Use_decl_annotations_
NDIS_STATUS
 MyStartDevice(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

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

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

Требования

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