SerCx2SystemDmaTransmitCreate 함수(sercx.h)

아티클
02/29/2024

SerCx2SystemDmaTransmitCreate 메서드는 SerCx2 시스템-DMA-전송 개체를 만듭니다. 이 개체는 SerCx2(직렬 프레임워크 확장) 버전 2가 시스템 DMA 전송 트랜잭션을 수행하는 데 사용합니다.

구문

NTSTATUS SerCx2SystemDmaTransmitCreate(
  [in]           WDFDEVICE                          Device,
  [in]           PSERCX2_SYSTEM_DMA_TRANSMIT_CONFIG SystemDmaTransmitConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES             Attributes,
  [out]          SERCX2SYSTEMDMATRANSMIT            *SystemDmaTransmit
);

매개 변수

[in] Device

직렬 컨트롤러를 나타내는 프레임워크 디바이스 개체에 대한 WDFDEVICE 핸들입니다. 직렬 컨트롤러 드라이버는 EvtDriverDeviceAdd 콜백 함수에서 이 개체를 만들었습니다. 자세한 내용은 SerCx2InitializeDevice를 참조하세요.

[in] SystemDmaTransmitConfig

SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG 구조체에 대한 포인터입니다. 이 메서드를 호출하기 전에 호출자는 SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT 함수를 호출하여 구조를 초기화해야 합니다. 이 구조체에는 직렬 컨트롤러 드라이버에서 구현하는 이벤트 콜백 루틴 집합에 대한 포인터가 포함되어 있습니다. SerCx2는 이러한 함수를 호출하여 시스템 DMA 전송 트랜잭션을 수행합니다.

[in, optional] Attributes

새 시스템 DMA 전송 개체에 할당할 특성을 설명하는 WDF_OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. 이 메서드를 호출하기 전에 호출자는 WDF_OBJECT_ATTRIBUTES_INIT 함수를 호출하여 구조를 초기화해야 합니다. 이 매개 변수는 선택 사항이며 직렬 컨트롤러 드라이버가 개체에 특성을 할당할 필요가 없는 경우 WDF_NO_OBJECT_ATTRIBUTES 지정할 수 있습니다. 자세한 내용은 설명 부분을 참조하세요.

[out] SystemDmaTransmit

이 메서드가 새로 만든 시스템 DMA 전송 개체에 SERCX2SYSTEMDMATRANSMIT 핸들을 쓰는 위치에 대한 포인터입니다. SerCx2 및 직렬 컨트롤러 드라이버는 이 개체를 참조하기 위해 후속 호출에서 이 핸들을 사용합니다.

반환 값

이 메서드는 호출에 성공하면 STATUS_SUCCESS 반환합니다. 가능한 오류 반환 값에는 다음 상태 코드가 포함됩니다.

반환 코드	설명
STATUS_INVALID_DEVICE_REQUEST	이전 SerCx2SystemDmaTransmitCreate 호출에서 시스템 DMA 전송 개체가 이미 존재합니다. 또는 사용자 지정 전송 개체가 SerCx2CustomTransmitCreate 메서드에 대한 이전 호출에서 존재합니다. 또는 사용자 지정 수신 개체가 SerCx2CustomReceiveCreate 메서드에 대한 이전 호출에서 존재합니다. 또는 SerCx2PioTransmitCreate 는 PIO 전송 개체를 만들기 위해 아직 호출되지 않았습니다.
STATUS_INFO_LENGTH_MISMATCH	구성->크기 값이 sizeof(SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG)와 같지 않습니다.
STATUS_INVALID_PARAMETER	매개 변수 값이 잘못되었습니다.
STATUS_INSUFFICIENT_RESOURCES	시스템 DMA 전송 개체를 만드는 데 사용할 수 있는 리소스가 부족합니다.

설명

직렬 컨트롤러 드라이버는 이 메서드를 사용하여 시스템 DMA 전송 개체를 만들 수 있습니다. SerCx2는 이 개체를 사용하여 시스템 DMA 전송 트랜잭션을 수행합니다. 이 트랜잭션은 시스템 DMA 컨트롤러를 사용하여 전송할 직렬 컨트롤러에 데이터를 쓰는 트랜잭션입니다.

일반적으로 직렬 컨트롤러 드라이버는 EvtDevicePrepareHardware 콜백 함수에서 SerCx2SystemDmaTransmitCreate를 호출합니다. 이 함수는 시스템 DMA 채널을 포함할 수 있는 하드웨어 리소스 목록을 받습니다.

직렬 컨트롤러 드라이버는 SerCx2SystemDmaTransmitCreate를 호출하기 전에 SerCx2InitializeDevice 및 SerCx2PioTransmitCreate 메서드 를 성공적으로 호출해야 합니다.

SerCx2SystemDmaTransmitCreate를 호출하기 전에 직렬 컨트롤러 드라이버는 SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT 함수를 호출하여 SystemDmaTransmitConfig가 가리키는 SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG 구조를 초기화해야 합니다. 이 함수는 구조체의 다음 멤버를 0으로 설정합니다.

MaximumScatterGatherFragments
MinimumTransferUnitOverride
DmaAlignment
MinimumTransactionLength
전용

필요한 경우 직렬 컨트롤러 드라이버는 초기화 함수가 반환된 후 이러한 멤버를 0이 아닌 값으로 설정할 수 있습니다. 그러나 편의상 SerCx2SystemDmaTransmitCreate 는 이러한 멤버가 0인 경우 다음 기본값을 사용합니다.

MaximumScatterGatherFragments가 0이면 SerCx2는 분산/수집 목록의 최대 요소 수를 ((ULONG)-1)로 설정합니다.
MinimumTransferUnitOverride가 0이면 SerCx2는 최소 전송 단위를 시스템 DMA 컨트롤러의 DMA_ADAPTER 구조에 지정된 기본값으로 설정합니다. 이 구조체에 대한 자세한 내용은 WdfDmaEnablerWdmGetDmaAdapter를 참조하세요.
DmaAlignment가 0이면 SerCx2는 맞춤 값을 최소 전송 단위로 설정합니다. MinimumTransferUnitOverride가 0이면 기본 최소 전송 단위가 사용됩니다.
MinimumTransactionLength가 0이면 SerCx2는 최소 트랜잭션 길이를 1바이트로 설정합니다.
Exclusive이 0(FALSE)이면 배타적 모드가 비활성화됩니다.

호출 드라이버가 Exclusive 를 TRUE로 설정하면 MinimumTransferUnitOverride, DmaAlignment 및 MinimumTransactionLength 멤버는 0이어야 합니다. 자세한 내용은 SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG 참조하세요.

구현된 콜백 함수의 지정된 조합이 유효하지 않으면 SerCx2SystemDmaTransmitCreate 가 실패하고 STATUS_INVALID_PARAMETER 반환합니다. 드라이버는 EvtSerCx2SystemDmaTransmitDrainFifo, EvtSerCx2SystemDmaTransmitCancelDrainFifo 및 EvtSerCx2SystemDmaTransmitPurgeFifo 함수를 모두 구현해야 합니다.

옵션으로 직렬 컨트롤러 드라이버는 Attributes 매개 변수를 사용하여 시스템 DMA 전송 개체에 대한 컨텍스트를 만들고 삭제할 개체를 준비하기 위해 호출되는 EvtCleanupCallback 및 EvtDestroyCallback 함수에 대한 포인터를 제공할 수 있습니다. 자세한 내용은 WDF_OBJECT_ATTRIBUTES.

Attributes 매개 변수가 WDF_OBJECT_ATTRIBUTES 구조를 가리키는 경우 호출자는 WDF_OBJECT_ATTRIBUTES_INIT 초기화 함수가 이 구조체의 ParentObject, ExecutionLevel 및 SynchronizationScope 멤버에 쓰는 값을 덮어써서는 안 됩니다.

시스템 DMA 전송 개체를 만드는 방법에 대한 자세한 내용은 SERCX2SYSTEMDMATRANSMIT. 시스템 DMA 전송 트랜잭션에 대한 자세한 내용은 SerCx2 System-DMA-Transmit Transactions를 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 8.1 시작해서 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	sercx.h
IRQL	PASSIVE_LEVEL