HW_ADAPTER_CONTROL 콜백 함수(storport.h)

아티클
02/07/2025

미니포트 드라이버의 HwStorAdapterControl 루틴은 전원 관리를 위해 HBA(호스트 버스 어댑터)를 중지하거나 다시 시작하는 등 어댑터의 상태 또는 동작을 제어하는 동기 작업을 수행하기 위해 호출됩니다.

통사론

HW_ADAPTER_CONTROL HwAdapterControl;

SCSI_ADAPTER_CONTROL_STATUS HwAdapterControl(
  [in] PVOID DeviceExtension,
  [in] SCSI_ADAPTER_CONTROL_TYPE ControlType,
  [in] PVOID Parameters
)
{...}

매개 변수

[in] DeviceExtension

미니포트 드라이버의 HBA별 스토리지 영역에 대한 포인터입니다.

[in] ControlType

각 컨트롤 형식이 미니포트 드라이버에서 작업을 시작하는 어댑터 컨트롤 작업을 지정하는 SCSI_ADAPTER_CONTROL_TYPE 값입니다. 자세한 내용은 SCSI_ADAPTER_CONTROL_TYPE 참조하세요.

[in] Parameters

ControlType관련된 정보를 포함하는 구조체 또는 값에 대한 포인터이거나, 컨트롤 형식이 구조를 사용하지 않는 경우 NULL입니다. 모든 구조체는 호출자가 할당됩니다. 자세한 내용은 SCSI_ADAPTER_CONTROL_TYPE 참조하세요.

반환 값

컨트롤 형식에 따라 HwStorAdapterControl 다음 SCSI_ADAPTER_CONTROL_STATUS 값 중 하나를 반환합니다.

반환 코드	묘사
ScsiAdapterControlSuccess	미니포트 드라이버가 요청된 작업을 성공적으로 완료했습니다. 현재 HwStorAdapterControl 모든 컨트롤 형식에 대해 이 값을 반환해야 합니다.
ScsiAdapterControlUnsuccessful	어댑터 컨트롤 작업이 실패했습니다.

발언

HwStorAdapterControl 필수 함수입니다.

Storport는 HBA가 초기화된 후 첫 번째 I/O 전에 ScsiQuerySupportedControlTypes 컨트롤 형식으로 미니포트의 HwStorAdapterControl 호출합니다. 미니포트 드라이버는 매개 변수SCSI_SUPPORTED_CONTROL_TYPE_LIST 구조체를 지원하는 작업으로 채웁니다. HwStorAdapterControl 이 호출에서 반환되면 Storport 드라이버는 미니포트에서 지원하는 작업에 대해서만 미니포트 드라이버의 HwStorAdapterControl 콜백을 호출합니다.

Storport 드라이버와 함께 작동하는 미니포트 드라이버는 PnP(플러그 앤 플레이)를 지원해야 하므로 미니포트는 ScsiStopAdapter 지원해야 하며 컨트롤 형식을 ScsiRestartAdapter를.

다음 표에서는 현재 IRQL 및 컨트롤 형식이 발급될 때 획득한 스핀 잠금을 나열합니다.

컨트롤 형식	IRQL	스핀 잠금
ScsiQuerySupportedControlTypes	PASSIVE_LEVEL	없음
ScsiStopAdapter	DIRQL	InterruptLock
ScsiRestartAdapter	DIRQL	InterruptLock
ScsiSetBootConfig	PASSIVE_LEVEL	없음
ScsiSetRunningConfig	PASSIVE_LEVEL	없음
ScsiPowerSettingNotification	PASSIVE_LEVEL	없음
ScsiAdapterPower	<= DISPATCH_LEVEL	없음
ScsiAdapterPoFxPowerRequired	<= DISPATCH_LEVEL	없음
ScsiAdapterPoFxPowerActive	<= DISPATCH_LEVEL	없음
ScsiAdapterPoFxPowerSetFState	<= DISPATCH_LEVEL	없음
ScsiAdapterPoFxPowerControl	<= DISPATCH_LEVEL	없음
ScsiAdapterPrepareForBusReScan	PASSIVE_LEVEL	없음
ScsiAdapterSystemPowerHints	PASSIVE_LEVEL	없음
ScsiAdapterFilterResourceRequirements	< DISPATCH_LEVEL	없음
ScsiAdapterPoFxMaxOperationalPower	PASSIVE_LEVEL	없음
ScsiAdapterPoFxSetPerfState	<= DISPATCH_LEVEL	없음
ScsiAdapterSurpriseRemoval	< DISPATCH_LEVEL	없음
ScsiAdapterSerialNumber	< DISPATCH_LEVEL	없음
ScsiAdapterCryptoOperation	PASSIVE_LEVEL	없음
ScsiAdapterQueryFruId	PASSIVE_LEVEL	없음
ScsiAdapterSetEventLogging	PASSIVE_LEVEL	없음

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

typedef
SCSI_ADAPTER_CONTROL_STATUS
HW_ADAPTER_CONTROL (
  _In_ PVOID  DeviceExtension,
  _In_ SCSI_ADAPTER_CONTROL_TYPE  ControlType,
  _In_ PVOID  Parameters
  );

예제

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

예를 들어 myHwAdapterControl 이름이HwStorAdapterControl 콜백 루틴을 정의하려면 다음 코드 예제와 같이 HW_ADAPTER_CONTROL 형식을 사용합니다.

HW_ADAPTER_CONTROL MyHwAdapterControl;

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

_Use_decl_annotations_
SCSI_ADAPTER_CONTROL_STATUS
MyHwAdapterControl (
  _In_ PVOID  DeviceExtension,
  _In_ SCSI_ADAPTER_CONTROL_TYPE  ControlType,
  _In_ PVOID  Parameters
  );
  {
      ...
  }

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