HW_FIND_ADAPTER 콜백 함수(storport.h)

아티클
08/07/2023

HwStorFindAdapter 루틴은 제공된 구성을 사용하여 특정 HBA가 지원되는지 여부를 확인하고, 지원되는 경우 해당 어댑터에 대한 구성 정보를 반환합니다.

구문

HW_FIND_ADAPTER HwFindAdapter;

ULONG HwFindAdapter(
           PVOID DeviceExtension,
  [in]     PVOID HwContext,
  [in]     PVOID BusInformation,
  [in]     PCHAR ArgumentString,
  [in/out] PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  [in]     PBOOLEAN Reserved3
)
{...}

매개 변수

DeviceExtension

어댑터당 스토리지 영역을 제공합니다.

[in] HwContext

NULL로 설정됨.

[in] BusInformation

NULL로 설정됨.

[in] ArgumentString

드라이버에 대한 컨텍스트 정보가 포함된 NULL로 종료된 문자열을 제공합니다.

[in/out] ConfigInfo

미니포트 드라이버가 초기화하는 동안 사용하는 초기화된 PORT_CONFIGURATION_INFORMATION 구조를 제공합니다.

[in] Reserved3

시스템에서 사용하도록 예약되었습니다.

반환 값

HwStorFindAdapter는 다음 상태 값 중 하나를 반환해야 합니다.

반환 코드	설명
SP_RETURN_FOUND	지원되는 HBA가 발견되었고 HBA 관련 구성 정보가 성공적으로 결정되고 PORT_CONFIGURATION_INFORMATION 구조에서 설정되었음을 나타냅니다.
SP_RETURN_ERROR	HBA가 발견되었지만 구성 정보를 가져오는 동안 오류가 발생했음을 나타냅니다. 가능하면 StorPortLogError를 사용하여 이러한 오류를 기록해야 합니다.
SP_RETURN_BAD_CONFIG	제공된 구성 정보가 어댑터에 유효하지 않음을 나타냅니다.
SP_RETURN_NOT_FOUND	제공된 구성 정보에 대해 지원되는 HBA가 없음을 나타냅니다.

설명

Storport 드라이버는 PnP(플러그 앤 플레이) 디바이스만 지원하므로 HwStorFindAdapter에 대한 HwContext 및 BusInformation 매개 변수는 가상이 아닌 미니포트 드라이버에 제공되지 않습니다.

HwStorFindAdapter는 ConfigInfo 구조체에서 MaximumTransferLength 및 NumberOfPhysicalBreaks 필드를 설정해야 합니다. 이러한 필드 외에도 PORT_CONFIGURATION_INFORMATION 구조는 어댑터를 시작하는 데 필요한 모든 어댑터 리소스를 항상 완전히 지정합니다.

HwStorFindAdapter 이름은 자리 표시자일 뿐입니다. 이 루틴의 실제 프로토타입은 다음과 같이 Storport.h 에 정의됩니다.

typedef
ULONG
HW_FIND_ADAPTER (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );

대부분의 경우 StorPort는 스핀 잠금을 획득하지 않고 IRQL == PASSIVE_LEVEL HwStorFindAdapter 루틴을 호출합니다. 예외 사례는 미니포트가 ScsiRestartAdapter 컨트롤 형식으로 HwStorAdaptorControl 호출을 지원하지 않는 경우입니다. 이 경우 StorPort는 HwStorFindAdapter 및 HwStorInitialize를 모두 호출하여 어댑터를 다시 초기화합니다. 이 경우 HwStorFindAdapter 는 IRQL == DISPATCH_LEVEL 호출됩니다. 또한 덤프 모드에서 HwStorFindAdapter 는 IRQL == HIGH_LEVEL 호출됩니다.

예제

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

예를 들어 MyHwFindAdapter라는 HwStorFindAdapter 콜백 루틴을 정의하려면 이 코드 예제와 같이 HW_FIND_ADAPTER 형식을 사용합니다.

HW_FIND_ADAPTER MyHwFindAdapter;

그런 다음 다음과 같이 콜백 루틴을 구현합니다.

_Use_decl_annotations_
ULONG
MyHwFindAdapter (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );
  {
      ...
  }

HW_FIND_ADAPTER 함수 형식은 Storport.h 헤더 파일에 정의되어 있습니다. 코드 분석 도구를 실행할 때 오류를 보다 정확하게 식별하려면 함수 정의에 Use_decl_annotations 주석을 추가해야 합니다. Use_decl_annotations 주석은 헤더 파일의 HW_FIND_ADAPTER 함수 형식에 적용되는 주석이 사용되도록 합니다. 함수 선언에 대한 요구 사항에 대한 자세한 내용은 Storport 드라이버에 함수 역할 형식을 사용하여 함수 선언을 참조하세요. Use_decl_annotations 대한 자세한 내용은 함수 동작에 주석을 추가를 참조하세요.