HW_BUILDIO 콜백 함수(storport.h)

아티클
02/07/2025

HwStorBuildIo 루틴은 공유 시스템 데이터 구조에 대한 비동기 액세스 권한으로 SRB를 처리한 후 HwStorStartIo전달합니다.

통사론

HW_BUILDIO HwBuildio;

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

매개 변수

DeviceExtension

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

Srb

처리할 SRB(SCSI 요청 블록)에 대한 포인터입니다.

반환 값

HwStorBuildIoTRUE 반환하여 StorPort가 LUN이 I/O를 받을 준비가 된 것으로 간주하는 경우 storPort가 HwStorStartIo 루틴을 호출해야 한다고 호출자에게 알릴 수 있습니다. HwStorBuildIoFALSE 반환하여 SRB를 HwStorStartIo전달해서는 안 됨을 호출자에게 알릴 수 있습니다. 이러한 경우 미니포트 드라이버는 알림 유형이 RequestCompleteStorPortNotification 호출하여 SRB를 완료해야 합니다. SRB 구조의 TimeOutValue 필드에 지정된 시간 제한 전에 SRB가 완료되는 한 HwStorBuildIo 또는 미니포트 드라이버의 다른 위치에서 이 작업을 수행할 수 있습니다.

발언

HwStorBuildIo 이름은 HW_INITIALIZATION_DATA 구조에서 HwBuildIo 멤버가 가리키는 미니포트 함수의 자리 표시자일 뿐입니다. 이 루틴의 실제 프로토타입은 다음과 같이 storport.h 정의됩니다.

typedef
BOOLEAN
HW_BUILDIO (
  _In_ PVOID DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

포트 드라이버는 스핀 잠금을 유지하지 않고 DISPATCH IRQL에서 HwStorBuildIo 루틴을 호출합니다. 이 때문에 StorPortAllocatePool 사용한 메모리 할당 및 StorPortAcquireSpinLock 통한 상호 제외는 HwStorBuildIo허용됩니다. 다중 프로세서 환경에서는 한 번에 둘 이상의 HwStorBuildIo 활성화할 수 있으므로 미니포트 드라이버는 시스템 리소스에 대한 액세스를 동기화해야 하며, 이는 지정된 시간에 둘 이상의 HwStorBuildIo 인스턴스가 활성화된 경우 경합이 발생할 수 있습니다.

HwStorStartIo대신 HwStorBuildIo 시간 소모 I/O 설정 작업을 완료하면 미니포트 드라이버는 더 큰 I/O 동시성을 가능하게 하므로 I/O 처리량을 향상시킵니다. 최고 성능을 위해 미니포트 드라이버는 가능한 한 짧은 시간 안에 HwStorStartIo 통해 HBA에 요청을 보낼 수 있도록 HwStorBuildIo 최대한 많은 전처리를 수행해야 합니다. 전처리된 데이터 및 상태는 DeviceExtension 또는 SrbExtension 구조에 저장할 수 있습니다. 잠금이 유지되지 않으므로 DeviceExtension 고유한 부분에 대한 수정만 이뤄져야 합니다. HwStorBuildIo 및 HwStorStartIo는 다음 Srb 함수 형식을 받을 있습니다.

SRB_FUNCTION_EXECUTE_SCSI: 지정된 버스/대상/lun에 CDB를 보냅니다.
- Srb->DataTransferLength는 모든 Cdbs에 유효합니다.
- Srb->DataBuffer는 읽기 및 쓰기 요청에 대해 NULL . 연결된 데이터에 액세스하려면 StorPortGetScatterGatherList 사용하거나(Dma 전송의 경우) StorPortGetSystemAddress(프로그램 제어 I/O의 경우)를 사용하여 분산 수집 목록 또는 버퍼의 가상 주소를 가져옵니다. 다른 요청의 경우 Srb->Databuffer는 Srb와 연결된 데이터를 가리킵니다.
- Srb->PathId는 유효하며 StorPortNotification(BusChange)에서 Storport에 지정된 pathid를 나타냅니다. 미니포트 드라이버 작성자는 미니포트 내의 버스 테이블에 pathid를 인덱스로 사용해야 합니다.
- Srb->TargetId 및 Srb->Lun은 유효합니다.
SRB_FUNCTION_IO_CONTROL: 미니포트가 정의되었습니다.
- Srb->DataTransferLength 및 Srb->DataBuffer는 요청자가 설정한 경우 유효합니다.
- Srb->PathId, Srb->TargetId 및 Srb->Lun은 모두 유효합니다.
SRB_FUNCTION_RESET_LOGICAL_UNIT: 지정된 논리 단위를 다시 설정합니다(디바이스가 가능한 경우).
- Srb->DataTransferLength 및 Srb->DataBuffer가 잘못되었습니다.
- Srb->PathId, Srb->TargetId 및 Srb->Lun은 모두 유효합니다.
SRB_FUNCTION_RESET_DEVICE: 지정된 Scsi 대상을 다시 설정합니다.
- Srb->DataTransferLength 및 Srb->DataBuffer, Srb->Lun이 잘못되었습니다.
- Srb->PathId 및 Srb->TargetId는 유효합니다.
SRB_FUNCTION_RESET_BUS: 지정된 SCSI 버스의 모든 대상을 다시 설정합니다.
- Srb->PathId만 유효합니다.
SRB_FUNCTION_FLUSH: 미니포트 드라이버에 캐시된 모든 데이터를 플러시하도록 지시합니다.
- PORT_CONFIGURATION_INFORMATION 구조에서 CachesData == TRUE 설정하는 경우에만 미니포트 드라이버에서 수행합니다.
- Srb->PathId, Srb->TargetId 및 Srb->Lun은 모두 유효합니다.
SRB_FUNCTION_SHUTDOWN: 미니포트 드라이버에 캐시된 모든 데이터 준비를 플러시하여 종료하도록 지시합니다.
- PORT_CONFIGURATION_INFORMATION 구조에서 CachesData == TRUE 설정하는 경우에만 미니포트 드라이버에서 수행합니다.
- Srb->PathId, Srb->TargetId 및 Srb->Lun은 모두 유효합니다.
SRB_FUNCTION_DUMP_POINTERS: 미니포트 드라이버가 크래시 덤프 및 최대 절전 모드를 지원하는 데 필요한 정보를 제공합니다.
- 이 요청은 크래시 덤프 데이터를 보유하는 디스크를 제어하는 데 사용되는 Storport 가상 미니포트 드라이버로 전송됩니다. Windows 8부터 가상이 아닌 미니포트 드라이버는 필요에 따라 이 요청을 받을 수 있습니다.
- Srb->PathId, Srb->TargetId 및 Srb->Lun은 모두 유효합니다.
SRB_FUNCTION_FREE_DUMP_POINTERS: Windows 8부터 이 요청은 미니포트로 전송되어 SRB_FUNCTION_DUMP_POINTERS 요청 중에 할당된 리소스를 해제합니다.
- Srb->PathId, Srb->TargetId 및 Srb->Lun은 모두 유효합니다.

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

이 미니포트 드라이버 루틴에서 안전하게 수행할 수 있는 작업과 수행할 수 없는 작업에 대한 자세한 내용은 비동기 HwStorBuildIo 루틴참조하세요.

예제

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

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

HW_BUILDIO MyHwBuildIo;

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

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

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