HW_STARTIO 콜백 함수(storport.h)

아티클
02/26/2024

Storport 드라이버는 들어오는 각 I/O 요청에 대해 HwStorStartIo 루틴을 한 번 호출합니다.

구문

HW_STARTIO HwStartio;

BOOLEAN HwStartio(
  PVOID DeviceExtension,
  PSCSI_REQUEST_BLOCK Srb
)
{...}

매개 변수

DeviceExtension

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

Srb

시작할 SCSI 요청 블록에 대한 포인터입니다.

반환 값

요청이 성공적으로 시작된 경우 HwStorStartIo는 TRUE를 반환합니다. 그렇지 않으면 FALSE를 반환합니다.

설명

HwStorStartIo 는 I/O 작업을 시작합니다. StorPort는 HwStorBuildIo에서 준비되고 DeviceExtension 또는 Srb-SrbExtension>에 저장된 미니포트의 프라이빗 데이터를 사용하도록 설계되었습니다. HwStorBuildIo는 스핀 잠금 없이 호출되므로 HwStorBuildIo에서 가능한 한 많은 데이터를 준비하여 최상의 드라이버 성능을 달성할 수 있습니다.

Storport는 다음과 같은 방법으로 HwStorStartIo 를 호출합니다.

스토리지 비 가상 미니포트 드라이버의 경우 PORT_CONFIGURATION_INFORMATION 설정된 SynchronizationModel 값에 따라 Storport는 항상 동일한 IRQL에서 HwStorStartIo를 호출하고 내부 스핀 잠금을 사용하여 I/O 요청이 순차적으로 시작되도록 합니다. IRQL은 DISPATCH_LEVEL(전체 이중 모드) 또는 DIRQL(반이중 모드)입니다.

반이중 모드에서 I/O를 처리할 때 HwStorStartIo 루틴은 자체 스핀 잠금을 획득할 필요가 없습니다. 또한 StorPortAllocatePool 을 사용한 메모리 할당 및 StorPortAcquireSpinLock 을 통한 상호 제외는 HwStorStartIo 루틴에서 허용되지 않습니다. 전체 이중 모드에서는 StorPortAllocatePool 및 StorPortAcquireSpinLock 을 HwStorStartIo 루틴에서 사용할 수 있습니다.

가상이 아닌 미니포트가 동시 채널 최적화( StorPortInitializePerfOpts에서 설정한 STOR_PERF_CONCURRENT_CHANNELS)를 지원하는 경우 HwStorStartIo에 대한 여러 호출이 동시에 가능합니다. 이 경우 미니포트는 공유 리소스가 잠금으로 보호되도록 해야 합니다. 이 성능 최적화를 사용하면 Storport는 HwStorStartIo 를 호출하기 전에 StartIo 잠금을 획득하지 않으며 미니포트는 필요한 경우 자체 잠금을 제공해야 합니다.
스토리지 가상 미니포트 드라이버의 경우 Storport는 IRQL <= DISPATCH_LEVEL HwStorStartIo를 호출하며 내부 스핀 잠금을 사용하지 않습니다. HwStorStartIo 루틴은 StorPortAcquireSpinLock을 호출하여 자체 스핀 잠금을 획득할 수 있습니다. 또한 StorPortAllocatePool 에 대한 호출은 스토리지 가상 미니포트 드라이버의 HwStorStartIo 루틴에서 허용됩니다.

SRB는 SCSI 상태 수신될 때 완료될 것으로 예상됩니다. Storport 드라이버가 RequestComplete의 NotificationType을 사용하여 StorPortNotification을 호출하여 SRB를 완료하면 SRB는 Srb의 SrbStatus 필드에 다음 값 중 하나를 반환해야 합니다.

SRB_STATUS_SUCCESS
- Srb가 전송되었고 SCSI 상태(데이터 포함)가 반환되었음을 나타냅니다.
- Storport는 데이터를 반환하고 호출자에게 상태.
- 미니포트 작업은 HwStorDpcRoutine에서 StorPortNotification for RequestComplete를 사용하여 요청을 완료하는 것 외에는 아무 것도 없습니다.
SRB_STATUS_BUSY
- Srb를 보내는 데 일시적인 문제가 있음을 나타냅니다(예: 어댑터 레지스터 또는 버퍼가 사용 중임).
- Storport는 Srb-SrbExtension>이 가리키고 새 Srb 확장을 발급하는 원래 Srb 확장을 삭제합니다. Storport는 HwStorBuildIo 및 HwStorStartIo에 대한 후속 호출에서 새로 발급된 Srb 확장을 사용하여 원래 Srb를 보냅니다. 원래 Srb 확장의 모든 데이터가 손실됩니다.
- 미니포트는 Srb의 DataTransferLength를 업데이트해서는 안 됩니다.
- 새 Srb 확장이 실행되기 때문에 미니포트는 SCSI 트랜잭션 중간에 SRB_STATUS_BUSY 발급하지 않도록 해야 합니다. 트랜잭션이 시작된 후에는 트랜잭션을 완료하거나 취소해야 합니다. 트랜잭션 중 하드웨어 사용 중 상태는 미니포트 드라이버에서 처리해야 합니다.

HwStorStartIo라는 이름은 HW_INITIALIZATION_DATA 구조체의 HwStartIo 멤버에 설정된 미니포트 루틴을 설명하는 자리 표시자입니다. 이 구조체는 StorPortInitialize의 HwInitializationData 매개 변수에 전달됩니다. 이 루틴의 실제 프로토타입은 다음과 같이 Storport.h에 정의됩니다.

typedef
BOOLEAN
(*PHW_STARTIO) (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

Windows 8 Srb 매개 변수는 SCSI_REQUEST_BLOCK 또는 STORAGE_REQUEST_BLOCK 가리킬 수 있습니다. Srb의 함수 필드에 있는 함수 식별자가 SRB_FUNCTION_STORAGE_REQUEST_BLOCK 경우 SRB는 STORAGE_REQUEST_BLOCK 요청 구조입니다.

예제

HwStorStartIo 콜백 루틴을 정의하려면 먼저 다음 코드 예제와 같이 SDV(정적 드라이버 검증 도구) 및 기타 확인 도구에 필요한 함수 선언을 제공해야 합니다.

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

예를 들어 MyHwStartIo라는 HwStorStartIo 콜백 루틴을 정의하려면 HW_STARTIO 형식을 사용하고 다음과 같이 콜백 루틴을 구현합니다.

HW_STARTIO MyHwStartIo

BOOLEAN
MyHwStartIo (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );
  {
      ...
  }

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