Funzione SerCx2SystemDmaReceiveCreate (sercx.h)

Articolo
08/07/2023

Il metodo SerCx2SystemDmaReceiveCreate crea un oggetto SerCx2 system-DMA-receive, che la versione 2 dell'estensione del framework seriale (SerCx2) usa per eseguire transazioni di ricezione system-DMA.

Sintassi

NTSTATUS SerCx2SystemDmaReceiveCreate(
  [in]           WDFDEVICE                         Device,
  [in]           PSERCX2_SYSTEM_DMA_RECEIVE_CONFIG SystemDmaReceiveConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES            Attributes,
  [out]          SERCX2SYSTEMDMARECEIVE            *SystemDmaReceive
);

Parametri

[in] Device

Handle WDFDEVICE per l'oggetto dispositivo framework che rappresenta il controller seriale. Il driver del controller seriale ha creato questo oggetto nella relativa funzione EvtDriverDeviceAdd callback. Per altre informazioni, vedere SerCx2InitializeDevice.

[in] SystemDmaReceiveConfig

Puntatore a una struttura SERCX2_SYSTEM_DMA_RECEIVE_CONFIG . Prima di chiamare questo metodo, il chiamante deve chiamare la funzione SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT o SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION per inizializzare la struttura. Questa struttura contiene puntatori a un set di routine di callback eventi implementate dal driver del controller seriale. SerCx2 chiama queste funzioni per eseguire transazioni di ricezione DMA di sistema.

[in, optional] Attributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES che descrive gli attributi da assegnare al nuovo oggetto system-DMA-receive. Prima di chiamare questo metodo, il chiamante deve chiamare la funzione WDF_OBJECT_ATTRIBUTES_INIT per inizializzare la struttura. Questo parametro è facoltativo e può essere specificato come WDF_NO_OBJECT_ATTRIBUTES se il driver del controller seriale non deve assegnare attributi all'oggetto. Per altre informazioni, vedere la sezione Osservazioni.

[out] SystemDmaReceive

Puntatore a un percorso in cui questo metodo scrive un handle SERCX2SYSTEMDMARECEIVE nell'oggetto system-DMA-receive appena creato. SerCx2 e il driver del controller seriale usano questo handle nelle chiamate successive per fare riferimento a questo oggetto.

Valore restituito

Questo metodo restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti degli errori possibili includono i codici di stato seguenti.

Codice restituito	Descrizione
STATUS_INVALID_DEVICE_REQUEST	Esiste già un oggetto system-DMA-receive da una chiamata SerCx2SystemDmaReceiveCreate ; o un oggetto di ricezione personalizzato esiste già da una chiamata precedente al metodo SerCx2CustomReceiveCreate ; o un oggetto di trasmissione personalizzato esiste da una chiamata precedente al metodo SerCx2CustomTransmitCreate ; o SerCx2PioReceiveCreate non è ancora stato chiamato per creare un oggetto di ricezione PIO.
STATUS_INFO_LENGTH_MISMATCH	Il valore Config->Size non è uguale a sizeof(SERCX2_SYSTEM_DMA_RECEIVE_CONFIG).
STATUS_INVALID_PARAMETER	Un valore di parametro non è valido.
STATUS_INSUFFICIENT_RESOURCES	Sono disponibili risorse insufficienti per eseguire l'operazione richiesta.

Commenti

Questo metodo viene chiamato dal driver del controller seriale per creare un oggetto system-DMA-receive. SerCx2 usa questo oggetto per eseguire transazioni di ricezione DMA di sistema, ovvero transazioni di I/O che usano il controller DMA di sistema per leggere i dati ricevuti dal controller seriale.

In genere, un driver del controller seriale chiama SerCx2SystemDmaReceiveCreate dalla sua funzione di callback EvtDevicePrepareHardware . Questa funzione riceve un elenco di risorse hardware, che possono includere canali DMA di sistema.

Un driver del controller seriale deve chiamare correttamente i metodi SerCx2InitializeDevice e SerCx2PioReceiveCreate prima di chiamare SerCx2SystemDmaReceiveCreate.

Prima di chiamare SerCx2SystemDmaReceiveCreate, il driver del controller seriale deve chiamare la funzione SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT o SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION per inizializzare la struttura SERCX2_SYSTEM_DMA_RECEIVE_CONFIG puntata da SystemDmaReceiveConfig. Queste funzioni impostano i membri seguenti della struttura su zero:

MaximumScatterGatherFragments
MinimumTransferUnitOverride
DmaAlignment
MinimumTransactionLength
Exclusive

Se necessario, il driver del controller seriale può impostare uno di questi membri su valori non zero dopo che la funzione di inizializzazione restituisce. Tuttavia, per praticità , SerCx2SystemDmaReceiveCreate usa i valori predefiniti seguenti se questi membri sono zero:

Se MaximumScatterGatherFragments è zero, SerCx2 imposta il numero massimo di elementi in un elenco di dispersione/raccolta su ((ULONG)-1).
Se MinimumTransferUnitOverride è zero, SerCx2 imposta l'unità di trasferimento minima sul valore predefinito, specificato nella struttura di DMA_ADAPTER per il controller DMA di sistema. Per altre informazioni su questa struttura, vedere WdfDmaEnablerWdmGetDmaAdapter.
Se DmaAlignment è zero, SerCx2 imposta il valore di allineamento sull'unità di trasferimento minima. Se MinimumTransferUnitOverride è zero, viene usata l'unità di trasferimento minima predefinita.
Se MinimumTransactionLength è zero, SerCx2 imposta la lunghezza minima della transazione su un byte.
Se Exclusive è zero (FALSE), la modalità esclusiva è disabilitata.

Se il driver chiamante imposta Exclusive su TRUE, i membri MinimumTransferUnitOverride, DmaAlignment e MinimumTransactionLength devono essere zero. Per altre informazioni, vedere SERCX2_SYSTEM_DMA_RECEIVE_CONFIG.

Se la combinazione specificata di funzioni di callback implementate non è valida, SerCx2SystemDmaReceiveCreate ha esito negativo e restituisce STATUS_INVALID_PARAMETER. Il driver deve implementare entrambe le funzioni EvtSerCx2SystemDmaReceiveEnableNewDataNotification e EvtSerCx2SystemDmaReceiveCancelNewDataNotification .

Come opzione, un driver del controller seriale può usare il parametro Attributes per creare un contesto per l'oggetto system-DMA-receive e fornire puntatori alle funzioni EvtCleanupCallback e EvtDestroyCallback che vengono chiamate per preparare l'oggetto per l'eliminazione. Per altre informazioni, vedere WDF_OBJECT_ATTRIBUTES.

Se il parametro Attributes punta a una struttura WDF_OBJECT_ATTRIBUTES , il chiamante non deve sovrascrivere i valori scritti dalla funzione di inizializzazione WDF_OBJECT_ATTRIBUTES_INIT ai membri ParentObject, ExecutionLevel e SyncScope di questa struttura.

Per altre informazioni sulla creazione di oggetti system-DMA-receive, vedere SERCX2SYSTEMDMARECEIVE. Per altre informazioni sulle transazioni system-DMA-receive, vedere SerCx2 System-DMA-Receive Transactions.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 8.1.
Piattaforma di destinazione	Universale
Intestazione	sercx.h
IRQL	PASSIVE_LEVEL