HW_BUILDIO 콜백 함수(storport.h)

아티클
05/23/2024

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

구문

HW_BUILDIO HwBuildio;

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

매개 변수

DeviceExtension

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

Srb

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

반환 값

HwStorBuildIo 는 TRUE 를 반환하여 StorPort가 LUN이 I/O를 받을 준비가 된 것으로 간주하는 경우 StorPort가 HwStorStartIo 루틴을 호출해야 한다고 호출자에게 알릴 수 있습니다. HwStorBuildIo 는 SRB 를 HwStorStartIo에 전달해서는 안 됨을 호출자에게 알리기 위해 FALSE를 반환합니다. 이러한 경우 미니포트 드라이버는 RequestComplete 알림 유형으로 StorPortNotification을 호출하여 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 instance 활성 상태인 경우 경합 중일 수 있습니다.

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 대한 자세한 내용은 함수 동작 주석 지정을 참조하세요.