MINIPORT_INITIALIZE 콜백 함수(ndis.h)

아티클
02/29/2024

NDIS는 미니포트 드라이버의 MiniportInitializeEx 함수를 호출하여 네트워크 I/O 작업에 대한 미니포트 어댑터를 초기화합니다.

참고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 는 미니포트 어댑터를 구성하고 설정하고 드라이버가 네트워크 I/O 작업을 수행해야 하는 모든 리소스를 할당했습니다.
NDIS_STATUS_NOT_ACCEPTED	MiniportInitializeEx 는 MiniportInitializeEx 가 레지스트리에서 가져온 구성 매개 변수를 수락하는 미니포트 어댑터를 가져올 수 없습니다.
NDIS_STATUS_RESOURCES	MiniportInitializeEx 는 네트워크 I/O 작업을 수행하기 위해 리소스를 할당할 수 없습니다. MiniportInitializeEx 는 리소스 충돌을 식별하기 위해 NdisWriteErrorLogEntry 함수를 호출해야 합니다(예: I/O 포트 범위, 인터럽트 벡터, 디바이스 메모리 범위). 오류 로그 레코드를 제공하면 이러한 하드웨어 리소스 충돌을 방지하기 위해 컴퓨터를 다시 구성하는 데 사용할 수 있는 사용자 또는 시스템 관리자 정보를 제공합니다.
NDIS_STATUS_FAILURE	MiniportInitializeEx 는 이전 목록의 이유가 아닌 이유로 실패했습니다. 드라이버는 실패 이유를 지정하는 매개 변수를 사용하여 NdisWriteErrorLogEntry 를 호출해야 합니다.

설명

NDIS는 시스템 PnP 작업의 일부로 MiniportInitializeEx 를 호출합니다. 드라이버는 를 호출하여 MiniportInitializeEx 진입점을 지정합니다.DriverEntry 루틴 의 NdisMRegisterMiniportDriver 함수입니다. NDIS는 DriverEntry가 반환된 후 MiniportInitializeEx를 호출할 수 있습니다. 자세한 내용은 NDIS 미니포트 드라이버의 DriverEntry를 참조하세요.

NDIS 중간 드라이버의 경우 NDIS는 의 컨텍스트에서 MiniportInitializeEx 를 호출할 수 있습니다. NdisIMInitializeDeviceInstanceEx 함수 또는 반환 후 이러한 드라이버의 ProtocolBindAdapterEx 함수는 일반적으로 NdisIMInitializeDeviceInstanceEx를 호출합니다.

드라이버는 결합된 미니포트 드라이버 및 중간 드라이버로 등록할 수 있습니다( NdisMRegisterMiniportDriver 참조). 이러한 미니포트 중간 드라이버는 물리적 미니포트 드라이버 위에 계층화된 중간 드라이버와 유사하게 작동합니다. 미니포트 중간 드라이버의 각 가상 또는 물리적 디바이스 instance IMMiniport 레지스트리 키가 DWORD:0x0000001 설정된 경우 NDIS는 드라이버가 가상 디바이스에 등록한 MiniportInitializeEx 함수를 호출합니다. 그렇지 않으면 NDIS는 드라이버가 물리적 디바이스에 등록한 드라이버의 MiniportInitializeEx 함수를 호출합니다.

MiniportInitializeEx가 반환될 때까지 NDIS는 초기화되는 미니포트 어댑터에 대한 요청을 제출하지 않습니다. 미니포트 어댑터가 초기화 상태입니다.

미니포트 어댑터에 대한 구성 정보를 얻기 위해 드라이버는 NdisOpenConfigurationEx 및 NdisReadConfiguration 함수를 호출합니다. 드라이버는 NdisMGetBusData 함수를 호출하여 버스 관련 정보를 가져올 수 있습니다.

미니포트 드라이버는 다음을 호출해야 합니다. NdisMSetMiniportAttributes 함수 및 제공 다음 특성을 포함하는 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES 구조체:

드라이버 할당 컨텍스트 영역에 대한 핸들입니다.
적절한 특성 플래그입니다.
호출에 대한 시간 제한 간격입니다. MiniportCheckForHangEx 함수입니다.
인터페이스 형식입니다.

미니포트 드라이버는 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES MiniportAdapterContext 멤버에서 NdisMSetMiniportAttributes 핸들을 전달합니다. 드라이버는 이 컨텍스트 영역에서 지정된 미니포트 어댑터에 대한 상태 정보를 유지 관리합니다. NDIS는 이 핸들을 다른 MiniportXxx 함수에 입력 매개 변수로 전달합니다.

미니포트 드라이버는 에서 특성을 설정해야 합니다. NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES 구조에서 등록 특성을 설정한 후 추가 특성을 설정하기 전에 구조체를 NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES.

MiniportInitializeEx 는 다음과 같은 리소스를 할당할 수도 있습니다.

페이징이 아닌 풀 메모리
구조 풀 NET_BUFFER 및 NET_BUFFER_LIST
스핀 잠금
타이머
IO 포트
DMA
공유 메모리
인터럽트

드라이버가 를 사용하여 수신을 나타내는 경우 NdisMIndicateReceiveNetBufferLists 함수, MiniportInitializeEx 함수는 를 호출해야 합니다. NdisAllocateNetBufferListPool 및 NdisAllocateNetBufferPool 함수는 이러한 NDIS 함수에서 반환된 핸들을 저장합니다. 일반적으로 드라이버가 NdisMIndicateReceiveNetBufferLists 로 나타내는 네트워크 데이터는 에 할당된 구조를 참조합니다. NdisAllocateNetBufferAndNetBufferList 함수입니다. 드라이버는 NdisAllocateNetBuffer와 함께 할당된 구조를 사용할 수도 있습니다. NdisAllocateNetBufferList 함수.

MiniportInterrupt 함수 이외의 드라이버 함수가 리소스를 공유하는 경우 MiniportInitializeEx는 NdisAllocateSpinLock 함수를 호출하여 이러한 공유 리소스에 대한 액세스를 동기화하는 데 필요한 스핀 잠금을 설정해야 합니다. 다른 드라이버 함수가 MiniportInterrupt와 공유하는 리소스(예: NIC 레지스터)는 드라이버가 로 설정한 인터럽트 개체로 보호됩니다. NdisMRegisterInterruptEx 함수입니다. 드라이버 함수는 를 호출하여 이러한 리소스에 액세스합니다. NdisMSynchronizeWithInterruptEx 함수입니다.

MiniportInitializeEx는 드라이버 제공 NetTimerCallback 함수와 타이머 개체에 대한 드라이버 할당 메모리에 대한 포인터를 사용하여 NdisAllocateTimerObject 함수를 호출할 수 있습니다. 드라이버는 각각 자체 타이머 개체를 사용하여 여러 NetTimerCallback 함수를 설정할 수 있습니다. 드라이버는 NdisSetTimerObject 함수를 호출하여 주기적인 NetTimerCallback 함수를 사용하도록 설정할 수 있습니다. 드라이버는 NdisSetTimerObject 함수를 호출하여 일회성 NetTimerCallback 함수를 사용하도록 설정할 수도 있습니다.

MiniportInitializeEx는 다음을 호출해야 합니다. NdisMSetMiniportAttributes 함수는 미니포트 어댑터에 대한 하드웨어 리소스를 클레임하는 NdisMRegisterIoPortRange 또는 NdisMMapIoSpace 함수와 같은 NdisMXxx 함수를 호출하기 전에 함수입니다. MiniportInitializeEx 는 DMA 작업에 대한 리소스를 할당하기 전에 NdisMSetMiniportAttributes 를 호출해야 합니다.

디바이스가 버스 master DMA를 지원하는 경우 MiniportInitializeEx는 를 호출해야 합니다.NdisMSetMiniportAttributes를 호출한 후 및 를 호출하기 전에 NdisMRegisterScatterGatherDma 함수 NdisMAllocateSharedMemory 함수입니다. 디바이스가 하위 DMA를 지원하는 경우 MiniportInitializeEx 는 를 호출하기 전에 NdisMSetMiniportAttributes를 호출해야 합니다. NdisMRegisterDmaChannel 함수입니다.

MiniportInitializeEx가 를 호출한 후 NdisMRegisterInterruptEx 함수인 NDIS는 드라이버의 MiniportInterrupt 함수를 호출할 수 있습니다. NDIS는 NIC가 인터럽트를 생성하거나 NIC가 인터럽트를 공유하는 다른 디바이스가 인터럽트를 생성하는 경우 MiniportInterrupt 를 호출합니다. 미니포트 드라이버는 NdisMRegisterInterruptEx를 호출하는 즉시 인터럽트를 가져올 수 있으며 에 대한 호출까지 인터럽트를 계속 받을 수 있습니다. NdisMDeregisterInterruptEx 함수가 반환됩니다.

MiniportInitializeEx 는 하드웨어가 올바르게 구성되었는지 확인하기 위해 NIC를 테스트해야 합니다. 드라이버가 하드웨어에서 상태 변경이 발생할 때까지 기다려야 하는 경우 MiniportInitializeEx 는 NdisWaitEvent 함수 또는 NdisMSleep 함수를 사용할 수 있습니다.

MiniportInitializeEx가 성공적으로 반환되면 미니포트 어댑터가 일시 중지됨 상태입니다. NDIS는 MiniportRestart 함수를 호출하여 미니포트 어댑터를 실행 중 상태로 전환할 수 있습니다 .

MiniportInitializeEx가 NDIS_STATUS_SUCCESS 반환하는 경우 드라이버는 MiniportHaltEx 함수의 미니포트 어댑터에 대한 모든 리소스를 해제해야 합니다.

드라이버는 NdisMSetMiniportAttributes를 호출하고 NDIS_STATUS_SUCCESS 반환하는 경우 NDIS_MINIPORT_ADAPTER_ATTRIBUTES 구조체에서 GeneralAttributes를 설정해야 합니다.

MiniportInitializeEx가 실패한 경우 MiniportInitializeEx는 반환되기 전에 할당된 모든 리소스를 해제해야 하며 미니포트 어댑터는 중지됨 상태로 돌아갑니다.

NDIS는 IRQL = PASSIVE_LEVEL MiniportInitializeEx 를 호출합니다.

예

MiniportInitializeEx 함수를 정의하려면 먼저 정의할 함수의 형식을 식별하는 함수 선언을 제공해야 합니다. Windows는 드라이버에 대한 함수 형식 집합을 제공합니다. 함수 형식을 사용하여 함수를 선언하면 드라이버에 대한 코드 분석, SDV( 정적 드라이버 검증 도구 ) 및 기타 확인 도구에서 오류를 찾을 수 있으며 Windows 운영 체제용 드라이버를 작성하기 위한 요구 사항입니다.

예를 들어 " MyInitializeEx"라는 MiniportInitializeEx 함수를 정의하려면 다음 코드 예제와 같이 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
헤더	ndis.h(Ndis.h 포함)
IRQL	PASSIVE_LEVEL