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

Статья
08/07/2023

Предупреждение

Функции обратного вызова MiniportResetEx и MiniportCheckForHangEx не рекомендуется использовать для всех драйверов NDIS 6.83 и более поздних версий. Дополнительные сведения см. в разделе Операции проверки зависания и сброса в NDIS 6.83 и более поздних версиях.

NDIS вызывает функцию MiniportResetEx драйвера NDIS miniport, чтобы инициировать сброс сетевого интерфейса карта (NIC). Дополнительные сведения см. в разделах Miniport Adapter Check-for-Hang and Reset Operations и Miniport Driver Hardware Reset.

Примечание Драйвер мини-порта NDIS может объявить эту функцию с помощью типа MINIPORT_RESET .

Синтаксис

MINIPORT_RESET MiniportReset;

NDIS_STATUS MiniportReset(
  [in]  NDIS_HANDLE MiniportAdapterContext,
  [out] PBOOLEAN AddressingReset
)
{...}

Параметры

[in] MiniportAdapterContext

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

[out] AddressingReset

Указатель на логическую переменную. Драйвер мини-порта устанавливает для этой переменной значение TRUE , если NDIS должен вызывать функцию MiniportOidRequest для восстановления адресации и других параметров конфигурации для текущих значений. Дополнительные сведения см. в разделе Сброс оборудования.

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

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

Код возврата	Описание
NDIS_STATUS_SUCCESS	MiniportResetEx успешно сбрасывает адаптер мини-порта в рабочее состояние.
NDIS_STATUS_PENDING	Драйвер завершит операцию сброса асинхронно, вызвав функцию NdisMResetComplete по завершении операции.
NDIS_STATUS_RESET_IN_PROGRESS	MiniportResetEx определил, что адаптер мини-порта в настоящее время сбрасывается, поэтому этот вызов является лишним.
NDIS_STATUS_SOFT_ERRORS	MiniportResetEx успешно сбросил адаптер мини-порта, но во время операции произошла ошибка с возможностью восстановления. MiniportResetEx должен был вызвать функцию NdisWriteErrorLogEntry с дополнительными сведениями об ошибке.
NDIS_STATUS_HARD_ERRORS	MiniportResetEx попыталась сбросить адаптер мини-порта, но во время операции произошла неустранимая ошибка. MiniportResetEx должен вызывать NdisWriteErrorLogEntry с дополнительными сведениями об ошибке.

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

Если операция сброса изменяет другие сведения, например сведения о многоадресной рассылке или функциональной адресации, MiniportResetEx должен задать для переменной в AddressingResetзначение TRUE , прежде чем она возвращается. Это приводит к тому, что NDIS вызывает функцию MiniportOidRequest для восстановления сведений. NDIS также восстанавливает список шаблонов Пробуждение по локальной сети (WoL), вызывая OID_PNP_ADD_WAKE_UP_PATTERN. Драйвер должен освободить список шаблонов WoL из контекста адаптера, так как список оборудования уже сброшен.

NDIS не прервет ожидающие запросы OID или отправку запросов. Если драйвер может безопасно завершить ожидающий OID или отправить запросы после сброса, драйвер может хранить ожидающий OID или отправлять запросы до завершения операции сброса. В противном случае драйвер должен завершить ожидающий OID или отправить запросы, вызвав NdisMOidRequestComplete илиФункции NdisMSendNetBufferListsComplete соответственно до возврата MiniportResetEx.

Примечание Начиная с версии NDIS 6.30 драйвер мини-порта не должен хранить ожидающий OID или отправлять запросы до завершения операции сброса. Вместо этого драйвер должен завершить эти ожидающие запросы, вызвав соответственно функции NdisMOidRequestComplete или NdisMSendNetBufferListsComplete , прежде чем операция сброса будет завершена. Если драйвер завершает операцию сброса асинхронно, он должен завершить ожидающий OID и отправить запросы, прежде чем драйвер вызовет NdisMResetComplete.

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

Если miniportResetEx должен ждать изменения состояния в адаптере минипорта во время операций сброса, он может вызвать функцию NdisStallExecution . Тем не менее,
Функция MiniportResetEx не должна вызывать NdisStallExecution с интервалом времени более 50 микросекунд. Если драйвер должен ждать более 50 микросекунд (или опрос), он должен установить таймер и вернуть NDIS_STATUS_PENDING.

Если MiniportResetEx возвращает NDIS_STATUS_PENDING, драйвер должен завершить сброс, вызвав функцию NdisMResetComplete .

Если адаптер мини-порта находится в состоянии MediaConnectStateConnected и его состояние меняется из-за сброса, включая изменение состояния MediaConnectStateUnknown , драйвер мини-порта должен сообщить об изменении состояния с указанием состояния NDIS_STATUS_LINK_STATE . Драйвер мини-порта также должен указывать состояние MediaConnectStateConnected , когда ссылка будет восстановлена после сброса.

MiniportResetEx может быть вытеснено прерыванием.

NDIS периодически вызывает функцию MiniportCheckForHangEx , чтобы определить, следует ли вызывать MiniportResetEx. Время ожидания по умолчанию для вызова MiniportCheckForHangEx составляет 2 секунды. Если значение по умолчанию слишком короткое, драйвер мини-порта может задать большее значение CheckForHangTimeInSeconds при вызове
Функция NdisMSetMiniportAttributes во время инициализации. Дополнительные сведения см. в разделе Miniport Adapter Check-for-Hang and Reset Operations.

NDIS не может определить, перестала ли сетевой адаптер отвечать на операции получения. Для обработки такого типа сбоя функция MiniportCheckForHangEx может отслеживать операции получения и при необходимости возвращать значение TRUE для принудительного сброса. Мини-порт также может запросить сброс, вызвав NdisMResetMiniport.

NDIS вызывает MiniportResetEx по адресу IRQL <= DISPATCH_LEVEL.

Примеры

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

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

MINIPORT_RESET MyResetEx;

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

_Use_decl_annotations_
NDIS_STATUS
 MyResetEx(
    NDIS_HANDLE  MiniportAdapterContext,
    PBOOLEAN  AddressingReset
    )
  {...}

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

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

Требования

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