MiniportQueryInformation
NDIS_STATUS
MiniportQueryInformation(
IN NDIS_HANDLE MiniportAdapterContext,
IN NDIS_OID Oid,
IN PVOID InformationBuffer,
IN ULONG InformationBufferLength,
OUT PULONG BytesWritten,
OUT PULONG BytesNeeded
);
|
MiniportQueryInformation은 드라이버의 혹은 그 NIC의 능력과 상태에 대한 정보를 리턴하는 요구된 함수이다.
매개변수
- MiniportAdapterContext
- 드라이버가 MiniportInitialize에서 설정된 NIC에 대한 상태를 유지하는 미니포트 할당 컨텍스트 영역에 대한
핸들을 지정한다.
- Oid
- 드라이버가 실행해야 할 글로벌 쿼리 연산을 지정하는 (designating) 시스템 정의 OID_XXX 코드를 지정한다.
- InformationBuffer
- MiniportQueryInformation은 OID 특정 정보를 리턴해야 하는 버퍼를 가리킨다.
- InformationBufferLength
- InformationBuffer에 대한 바이트 수를 지정한다.
- BytesWritten
- MiniportQueryInformation은 InformationBuffer에서 리턴하는 바이트 수를 설정하는 변수를 가리킨다.
- BytesNeeded
- MiniportQueryInformation은 만약 InformationBufferLength가 Oid가 요구한 것보다 작다면은 요구를
만족하는데 필요한 추가적인 바이트 수를 설정하는 변수를 가리킨다.
리턴값
MiniportQueryInformation은 다음 중 하나를 리턴할 수 있다.
- NDIS_STATUS_SUCCESS
- MiniportQueryInformation은 InformationBuffer에서 요구된 정보를 리턴하고 리턴된 정보 양에
대해 BytesWritten 변수를 설정한다.
- NDIS_STATUS_PENDING
- 드라이버는 요구된 정보를 모을 때 NdisMQueryInformationComplete에 대한 호출로 비동적인 요구를 완성할
것이다.
- NDIS_STATUS_INVALID_OID
- MiniportQueryInformation은 Oid를 인식하지 않는다.
- NDIS_STATUS_INVLAID_LENGTH
- InformationBufferLength는 주어진 Oid에 의해 필요한 길이와 매치하지 않는다.
MiniportQueryInformation은 버퍼가 BytesNeeded에서 얼마나 많은 바이트 수가 되는지를 리턴한다.
- NDIS_STATUS_NOT_ACCEPTED
- MiniportQueryInformation은 NIC으로부터 요구된 정보를 모으려고 했지만은 성공하지 못했다.
- NDIS_STATUS_NOT_SUPPORTED
- MiniportQueryInformation은 Oid를 지원하지 않는다. 선택적이다.
- NDIS_STATUS_RESOURCES
- MiniportQueryInformation은 요구된 정보를 리턴하기 위한 충분한 자원들을 할당할 수 없다. 이 리턴 값은
반드시 나중에 제출된 같은 요구가 같은 이유로 실패한다고는 의미하지 않는다.
주석
NDIS는 자기 자신을 위해서 MiniportQueryInformation을 호출한다.
드라이버가 지원하는 옵션들이 무엇인지 결정하기 위해 혹은 미니포트를 위해 바인딩 특정 정보를 관리하기 위해
바인딩 프로토콜 드라이버가 NdisRequest를 호출할 때.
NDIS는 드라이버의 MiniportInitialize 함수가 NDIS_STATUS_SUCCESS를 리턴한 후, 단지 MiniportQueryInformation에
대한 하나나 그 이상의 호출들을 한다.
NDIS는 드라이버의 MiniportQueryInformation 함수에 대한 초기화 시 호출에서 다음과 같은 OID들을 제공한다:
- OID_GEN_MAXIMUM_LOOKAHEAD
- MiniportQuertInformation은 NIC이 제공할 수 있는 lookahead 데이터의 바이트 수를 리턴해야 하고 즉 NIC의
초기 전송 능력을 리턴한다.
드라이버가 멀티패킷 리시브들을 지원하는 것처럼 그러므로 패킷 들을 설정하기 위해 배열 포인터를 지시해야
한다면은 MiniportQueryInformation은 이 정보를 제공해야 한다. 그러한 드라이버는 그것이 지시할 수 있는
최대 패킷 크기를 리턴해야 한다.
- OID_GEN_MAC_OPTIONS
- MiniportQueryInformation은 드라이버가 제공하는 (혹은 NIC이 제공하는) 옵션들이 어느 것인지를 지시하는
적당한 NDIS_MAC_OPTION_XXX 플래그들로 설정된 비트마스크를 리턴해야 한다. 혹은
이러한 플래그들로 할당된 선택들의 어떠한 것도 지원하지 않는다면은 InformationBuffer에 0을 리턴해야 한다.
예를 들어, NIC 드라이버는 항상 만약 NIC이 루프백을 위한 내부 하드웨어 지원을 가지지 않는다면은
NDIS_MAC_OPTION_NO_LOOKBACK 플래그를 설정한다. 이것은 NDIS가 드라이버를 위해 루프백을 관리하기 위해 NDIS
에게 말한다. 그것은 NDIS가 미니포트를 위해 모든 바인딩 특정 정보를 관리하기 때문에 NDIS 라이브러리보다
더 효율적인 소프트웨어 루프백 코드를 제공할 수 없다.
소프트웨어 루프백을 지원하려고 시도하는 어떤 미니포트는 모든 보내는 패킷의 목적지 주소를 체크해야 한다.
각 패킷의 루프백이 어떤것인지를 결정하기 위한 현재 설정된 필터 주소들에 대응하여.
만약 NIC 드라이버가 NDIS_MAC_OPTION_FULL_DUPLEX 플래그를 설정한다면은, NDIS 라이브러리는 SMP 컴퓨터에서
다른 MiniportXxx 함수들에 대한 직렬화된 호출로부터 다르게 MiniportSendPackets 혹은 Miniport(Wan)Send
함수에 대한 호출들을 직렬화한다.
그러나, NDIS는 그러한 드라이버의 MiniportReset 함수가 실행되는 동안, 프로토콜들에 대한 들어오는 보내기
패킷들을 리턴한다.: 즉, NDIS 가 결코 리셋 연산이 완성되기 전까지 패킷을 전송하기 위해 full-duplex
미니포트를 호출하지 않는다.
어떤 full-duplex 드라이버의 디자인너는 그러한 드라이버가 SMP 컴퓨터들에서 매우 높은 퍼포먼스를 성취하도록
그러한 드라이버를 기대할 수 있지만은 드라이버는 레이스 조건들 혹은 데드락들이 발생하는 것을 막기 위해
주의깊게 공유된 자원들의 대한 접근들을 동기화해야한다.
NDIS는 모든 인터미디엇 드라이버들은 full-duplex 드라이버들이라고 생각한다.
MiniportInitialize가 선택한 NdisMediumXxx에 의존하여, NDIS는 추가적인 다음과 같은 MiniportQueryInformation에
대한 초기화시 요구들을 제출한다:
- OID_XXX_CURRENT_ADDRESS
- 만약 드라이버의 MiniportInitialize 함수가 시스템이 필터를 제공한 것을 위한 NdisMediumXxx를 선택한다면은
NDIS는 미디엄 특정 포맷에서 NIC의 현 주소를 리턴하기 위해 MiniportQueryInformation를 호출한다.
FDDI 드라이버들을 위해, NDIS는 길고 짧은 현재 주소들을 요구한다.
- OID_802_3_MAXIMUM_LIST_SIZE
- Ethernet 드라이버들을 위해, NDIS는 멀티캐스트 리스트 크기를 요구한다.
- OID_FDDI_LONG/SHORT_MAX_LIST_SIZE
- FDDI 드라이버들을 위해서, NDIS는 멀티캐스트 리스트 크기들을 요구한다.
만약 가능하다면은, MiniportQueryInformation은 초기화시 요구들을 위해 NDIS_STATUS_PENDING를 리턴하지 말아야 한다.
NDIS가 미니포트에 대한 바인딩들을 설정하기 위해 충분한 정보를 가질 때까지, 그러한 요구들은 동기적으로
다루어져야 한다.
결과적으로 NDIS 라이브러리는 다음과 같은 어떤 OID들에 대한 모든 프로토콜 초기화 쿼리들을 가로챈다:
- OID_GEN_CURRENT_PACKET_FILTER
- OID_GEN_PROTOCOL_OPTIONS
- OID_802_5_CURRENT_FUNCTIONAL
- OID_802_3_MULTICAST_LIST
- OID_FDDI_LONG_MULTICAST_LIST
- OID_FDDI_SHORT_MULTICAST_LIST
시스템 정의 OID들에 대한 더 많은 정보에 대하여 Part 2를 봐라.
만약 MiniportQueryInformation은 동기적으로 요구들을 완성하지 않는다면은 그리고 NDIS_STATUS_PENDING을
리턴한다면은, 드라이버는 NdisMQueryInformationComplete에 대한 호출로 나중에 요구를 완성해야 한다.
어떤 그러한 요구들을 완성할 때까지, 미니포트는 안전하게 InformationBuffer, BytesWritten, BytesNeeded에
대한 메모리에 접근할 수 있다.
미니포트가 어떤 쿼리를 완성한 후에, 이러한 변수들과 버퍼에 대한 소유가 NDIS로 바뀌고 혹은 NdisRequest의
호출자로 바뀐다. 그것이 메모리를 할당했든지간에.
MiniportQueryInformation에 대한 호출 후, NDIS는 현재 요구가 완성될 때까지 드라이버에 대한 다른 요구들을
제출할 수 없다. 동기적으로 혹은 비동기적으로.
그 대신에 NDIS는 현재 쿼리가 완성될 때까지 큐에 저장된 요구들을 유지할 수 있다.
MiniportQueryInformation은 인터럽트에 으해 선점당할 수 있다.
디폴트로 MiniportQueryInformation은 IRQL DISPATCH_LEVEL에서 실행한다.
|