MiniportInitialize

NDIS_STATUS MiniportInitialize( OUT PNDIS_STATUS OpenErrorStatus, OUT PUINT SelectedMediumIndex, IN PNDIS_MEDIUM MediumArray, IN UINT MediumArraySize, IN NDIS_HANDLE MiniportAdapterHandle, IN NDIS_HANDLE WrapperConfigurationContext );

MiniportInitialize는 네트워크 I/O 연산들을 위한 NIC(혹은 가상 NIC)을 설정하고 레지스트리에 NIC에 필요한 모든 하드웨어 자원들을 요구하고 드라이버가 네크워트 I/O 연산들을 실행하는 데 필요한 자원들을 할당하는데 필요한 함수이다.

매개변수

OpenErrorStatus

만약 MiniportInitialize가 NDIS_STATUS_OPEN_ERROR을 리턴한다면은 에러에 대한 더 추가적 정보을 지정하는 NDIS_STATUS_XXX 코드를 설정하는 변수를 가리킨다.

SelectedMediumIndex

MiniportInitialize는 드라이버나 NIC이 사용하는 미디엄 타입을 지정하는 MediumArray 요소의 인덱스를 설정하는 변수를 가리킨다.

MediumArraySize

MediumArray에서 요소 수를 지정한다.

MiniportAdapterHandle

NDIS 라이브러리에 의해 할당되는 미니포트 NIC을 지정하는 핸들을 지정한다. MiniportInitialize는 이 핸들을 저장해야 한다. NdisXxx 함수들의 계속적인 호출에서 요구되는 매개변수이다.

WrapperConfigurationContext

NdisXxx 구성과 초기화 함수들에 대한 호출을 위해 초기화하는 동안 단지 사용된 핸들을 지정한다. 예를 들어, 이 핸들은 NdisOpenConfiguration과 NdisImmediateReadXxx와 NdisImmediateReadXxx와 NdisImmediateWriteXxx 함수들에 대해 필요한 매개변수이다.

리턴값

MiniportInitialize는 다음과 같은 값중에 하나를 리턴할 수 있다.

NDIS_STATUS_SUCCESS

MiniportInitialize은 NIC을 구성하고 설정하고 드라이버가 네트워크 I/O 연산들을 실행하는 데 필요한 모든 자원들을 할당한다.

NDIS_STATUS_FAILURE

MiniportInitialize는 연산적인 상태에 대해 NIC이 설정할 수 없고 혹은 필요한 자원들도 할당할 수 없다. MiniportInitialize는 구성과 자원 할당에 대한 실패을 지정하는 매개변수를 가지고 NdisWriteErrorLogEntry을 호출한다.

NDIS_STATUS_FAILURE에 대한 대용으로 MiniportInitialize는 다음과 같은 값들중 적당한 값을 초기화가 실패할 때 리턴한다:

NDIS_STATUS_UNSUPPORTED_MEDIA

MediumArray의 값들이 드라이버가(혹은 NIC이) 지원할 수 있는 미디엄을 포함하지 않는다.

NDIS_STATUS_ADAPTER_NOT_FOUND

MiniportInitialize가 NdisOpenConfiguration과 NdisReadConfiguration을 사용하여 혹은 특정 I/O 버스로 NIC을 감지함으로써 NdisImmediateXxx 혹은 버스 타입 특정 NdisXxx 구성 함수들을 사용함으로써 레지스트리내에서 디스크립션으로부터 NIC을 인지하지 못한다. 이 리턴은 NdisOpenConfiguration과 같은 미니포트의 어떤 특정 NdisXxx 함수들에 대한 호출로부터 전달되어질 수 있다.

NDIS_STATUS_OPEN_ERROR

MiniportInitialize가 NIC을 설정하려고 시도했지만은 성공하지 못했다.

NDIS_STATUS_NOT_ACCEPTED

MiniportInitialize는 NIC이 레지스트로부터 혹은 버스 타입 특정 NdisXxx 구성 함수로부터 얻는 구성 매개변수들을 허락 받지 못할 수 있다.

NDIS_STATUS_RESOURCES

MiniportInitialize가 네트워크 I/O 연산들을 실행하기 위한 충분한 자원들을 할당받지 못하고 NIC을 위해 레지스트리내에 버스 관련 하드웨어 자원들을 요구하느 시도가 실패했다. 이러한 리턴은 NdisXxx 함수에 대한 미니포트의 호출로부터 전달 되어질 수 있다.

만약 또 하나의 장치가 이미 NIC이 필요한 레지스트리내에 자원을 요구한다면은 MiniportInitialize는 또한 특정 자원 충돌(I/O 포트 범위, 인터럽트 벡터, 장치 메모리 범위, 등등)를 기록하기 위해 NdisWriteErrorLogEntry를 호출해야 한다. 에러 로그 기록을 제공하는 것은 사용자와 혹은 시스템 관리자에게 그러한 하드웨어 자원 충돌들을 피하기 위해 기계를 재구성하도록 할 수 있는 정보를 제공한다.

주석

NDIS는 초기화가 완성될 때까지 드라이버에 대한 어떠한 요구도 하지 않는다.

DriverEntry 함수들로부터 NdisMRegisterMiniport를 호출하는 NIC이나 인터미디엇 드라이버들에서 NDIS는 NdisMRegisterMiniport 함수의 컨텍스트에서 MiniportInitialize을 호출한다. 하위 레벨 드라이버는 그러한 장치에 의존하는 인터미디엇 드라이버가 NdisMRegisterMiniport를 호출하기 전에 초기화를 해야 한다.

ProtocolXxx 함수와 MiniportXxx 함수들을 익스포트하고 DriverEntry 함수들에서 NdisImRegisterLayeredMiniport를 호출하는 NDIS 인터미디엇 드라이버들을 위해서 NDIS는 NdisIMInitializeDeviceInstance 컨텍스트내에서 MiniportInitialize을 호출한다. 그러한 드라이버의 ProtocolBindAdapter 함수는 항상 NdisIMInitializeDeviceInstance에 대한 호출을 한다.

NIC 드라이버에 대하여, NDIS는 적어도 NIC의 I/O 버스 인터페이스 타입을 발견해야 하고, 만약 ISA 버스가 아니면은 버스 넘버는 이미 드라이버의 인스톨 스크립트에 의해서 레지스트리내에 설치된다. 윈도우즈 2000 드라이버을 인스톨하는 것에 대한 더 많은 정보는 Driver Writer's Guide을 봐라.

NIC 드라이버는 NdisOpenConfiguration과 NdisReadConfiguration을 호출함으로써 NIC을 위한 구성 정보를 얻는다. NIC 드라이버는 적당한 버스 특정 함수을 호출함으로써 버스 특정 정보를 얻는다:

버스	버스 특정 정보를 얻기위한 함수
EISA	NdisReadEisaSlotInformation or NdisReadEisaSlotInformationEx
PCI	NdisReadPciSlotInformation
PC Card	NdisReadPcmciaAttributeMemory

EISA NIC에 대한 NIC 드라이버는 NdisReadEisaSlotInformation와 NdisReadEisaSlotInformationEx을 호출함으로써 NIC을 위한 하드웨어 자원에 대한 정보를 얻는다. PCI NIC과 PC Card NIC들을 위한 NIC 드라이버들은 NdisMQueryAdapterResources을 호출함으로써 그러한 정보를 얻는다.

MiniportInitialize을 호출할 때, NDIS 라이브러리는 시스템 정의 NdisMediumXxx 값들로서 지정된 지원되는 미디어 타입들의 배열을 제공한다. MiniportInitialize은 배열 요소들을 읽고 NDIS가 NIC을 위해 드라이버가 사용해야 하는미디엄 타입의 인덱스를 제공한다. 만약 미니포트가 미디엄 타입을 에뮬레이트한다면은 에뮬레이션은 NDIS에게는 투명해야 한다.

NIC 드라이버의 MiniportInitialize 함수는 NIC을 위해 레지스트리내에 하드웨어 자원들을 요구하는 NdisRegisterIoPortRange 혹은 NdisMMapIoSpace와 같은 어떤 NdisXxx 함수을 호출하기 전에 NdisMSetAttributes 혹은 NdisMSetAttributesEx을 호출해야 한다. MiniportInitialize는 DMA 연산들을 위한 자원들에 대한 할당을 시도하기 전에 NdisMSetAttributes(Ex)를 호출해야 한다. 만약 NIC이 버스마스터이면은 MiniportInitialize는 NdisMSetAttributesEx 호출한 다음 NdisMAllocateSharedMemory 호출하기 전에 NdisMAllocateMapRegisters를 호출해야 한다. 만약 NIC이 슬레이브면은(slave), MiniportInitialize는 NdisMRegisterDmaChannel을 호출하기 전에 NdisMSetAttributes(Ex)를 호출해야 한다.

인터미디엇 드라이버 MiniportInitialize 함수들은 AttributeFlags 매개변수를 NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER로 설정해서 NdisMSetAttributesEx를 호출해야 한다. 이 플래그를 설정하는 것은 NDIS가 모든 인터미디엇 드라이버를 full-duplex로 다루도록 한다. 그래서 드물지만은 동시에 보내고 받는 이벤트가 일어날 때 intermittant 데드락들을 막아준다. 결과적으로 모든 인터미디엇 드라이버는 동시에 보내고 받기를 다룰 수 있는 능력을 가진 full-duplex 드라이버로서 쓰여진다.

만약 NDIS 라이브러리의 디폴트의 두드러진 보내기 요구에 대한 4초의 타임아웃 시간 간격은 드라이버의 NIC에게는 너무 짧다면은 MiniportInitialize는 시간간격을 확장하기 위해 NdisMSetAttributesEx를 호출할 수 있다. 모든 인터미디엇 드라이버는 또한 NDIS가 인터미디엇 드라이버에 큐로 저장되어서 유지하고 있는 보내기와 요구들이 타임 아웃을 시도하지 않도록 AttributeFlags에 NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT과 NDIS_ATTRIBUTE_IGNORE_TIMEOUT 으로 설정해서 NdisMSetAttributesEx를 호출해야 한다.

NdisMSetAttributes 혹은 NdisMSetAttributesEx 에 대한 호출은 미니포트가 실행 시간 상태 정보를 유지하는 점에서 드라이버 할당 컨텍스트 지역에 대한 MiniportAdapterContext를 포함한다. NDIS 계속해서 다른 MiniportXxx 함수들에 대한 입력 매개변수로서 제공된 MiniportAdapterContext 핸들을 전달한다.

결과적으로 인터미디엇 드라이버의 MiniportInitialize 함수는 가상 NIC 당 드라이버 할당 컨텍스트 지역을 위한 MiniportAdapterContext을 설정하기 위한 NdisMSetAttributesEx를 호출해야 한다. 그렇지 않으면, NDIS는 인터미디엇 드라이버의 다른 MiniportXxx 함수들에 대한 계속적인 호출에서 NULL MiniportAdapterContext 핸들을 전달해야 한다.

NdisMRegisterIoPortRange에 대한 호출 후, 미니포트는 NIC과 통신하기 위해 NdisMRegisterIoPortRange에 의해 리턴된 PortOffset 값으로 NdisRawXxx 함수들을 호출해야 한다. NIC 드라이버는 더이상 NdisImmediateRead/WritePortXxx 함수들을 호출할 수 없다. 유사하게,

NdisMMapIoSpace에 대한 호출 후에 NIC 드라이버는 더이상 NdisImmediateRead/WriteSharedMemory을 호출할 수 없다. 레지스트리내에 NIC을 위해 어떤 버스 관련 하드웨어 자원들을 요구한 후에, 미니포트는 더이상 버스 타입 특정 NdisReadXxx 함수를 호출할 수 없다.

MiniportInitialize 함수는 NdisMRegisterInterrupt 함수 호출 후에, 드라이버의 MiniportISR 함수는 만약 드라이버의 NIC이 인터럽트를 발생하거나 혹은 NIC이 어떤 다른 장치와 함계 IRQ 인터럽트들을 공유한다면은 호출되어진다. NDIS는 만약 초기화하는 동안 드라이버가 그들을 제공한다면은 NIC이 발생한 어떤 인터럽트를 인지하거나 클리어시키는 것에 대한 미니포트의 책임을 위해 MiniportDisableInterrupt와 MiniportEnableInterrupt 함수들을 호출하지 않는다. 만약 NIC이 IRQ을 공유한다면은, 드라이버는 처음 NIC이 인터럽트를 발생할 것인지 결정해야 하고 그렇지 않는다면은 미니포트는 가능한 한 빨리 FALSE를 리턴해야 한다. 미니포트는 NdisMRegisterInterrupt를 호출하자 마자 인터럽트을 얻을 수 있고 NdisMDeregisterInterrupt에 대한 호출이 리턴할 때까지 얻은 인터럽트들을 유지할 수 있다는 것을 주의하라.

만약 NIC이 인터럽트들을 발생하지 않는다면은, MiniportInitialize는 드라이버 제공 폴링 MiniportTimer 함수와 타이머 객체를 위한 드라이버 할당 메모리에 대한 포인터로 NdisMInitializeTimer를 호출해야 한다. 인터럽트를 방생하는 NIC 드라이버들과 인터미디엇 드라이버들은 또한 각각 자신의 타이머 객체를 가지는 하나나 그 이상의 MiniportTimer을 설정할 수 있다. MiniportInitialize는 항상 NdisMSetPeriodicTimer를 호출해서 폴링 MiniportTimer 함수를 인에블한다. 드라이버는 드라이버의 비폴링 MiniportTimer 함수가 실행해야 하기 위해 조건들이 일어날 때 계속해서 NdisMSetTimer 를 호출한다.

만약 드라이버가 계속해서 NdisMIndicateReceivePacket로 수신들을 인디케이트한다면은, MiniportInitialize 함수는 이러한 NDIS 함수들에 의해 리턴된 해들을 저장하기 위해 NdisAllocateBufferPool과 NdisAllocatePacketPool을 호출해야 한다. 드라이버가 계속해서 NdisMIndicateReceivePacket로 인디케이트한 패킷들은 NdisAllocatePacket과 NdisAllocateBuffer로 할당된 디스크립터들을 참조해야 한다.

MiniportISR과 MiniportDisableInterrupt와 다른 드라이버 함수들이 자원들을 공유한다면은, MiniportInitialize 함수는 그러한 공유 자원들에 대한 특히, 풀 듀풀렉스 드라이버내에서 혹은 ISR보다는 폴링 MiniportTimer 함수를 가진 드라이버에서 접근을 동기화히기 위해 필요한 스핀 락을 설정하기 위해 NdisAllocateSpinLock을 호출해야 한다. NIC 레지스터와 같은 MiniportISR 혹은 MiniportDisableInterrupt와 함께 다른 드라이버 함수들에 의해 공유된 자원들은 MiniportInitialize가 NdisMRegisterInterrupt 함수를 호출할 때 설정된 인터럽트 개체에 의해 보호되어지고 계속해서 NdisMSynchronizeWithInterrupt를 호출함으로써 접근되어진다.

어떤 NIC 드라이버의 MiniportInitialize 함수는 하드웨어가 계속적인 네트워크 I/O 연산들을 실행하기 위해 올바로 구성되어졌는지를 확실히 하기 위해 테스트 해야 한다. 만약 하드웨어에서 상태 변화가 일어나는 것을 기다려야 한다면은 MiniportInitialize 함수는 드라이버 초기화된 이벤트 객체에 대한 포인터를 가지고 NdisWaitEvent를 호출할 수 있고 혹은 NdisMSleep를 호출할 수 있다.

만약 NIC의 MiniportInitialize 함수가 에러 상태를 리턴하지 않는다면은 드라이버 제공 MiniportShutdown 함수로 NdisMRegisterAdapterShutdownHandler를 호출해야 한다.

만약 MiniportInitialize가 초기화가 실패한다면은, 제어를 리턴하기 전에 이미 할당된 모든 자원을 해제해야 한다.

만약 MiniportInitialize가 NDIS_STATUS_OPEN_ERROR을 리턴한다면은, NDIS는 에러에 대한 더 많은 정보를 얻기 위해 OpenErrorStatus로 리턴된 값을 조사할 수 있다.

MiniportInitialize가 NDIS_STATUS_SUCCESS르리턴할 때, NDIS 라이브러리는 드라이버의 MiniportQueryInformation 함수를 다음에 호출한다.

디폴트로 MiniportInitialize는 IRQL PASSIVE_LEVEL로 실행한다. 그리고 시스템 컨텍스트내에서 실행한다.