SerCx2SystemDmaTransmitCreate, fonction (sercx.h)

Article
08/07/2023

La méthode SerCx2SystemDmaTransmitCreate crée un objet system-DMA-transmit SerCx2, que la version 2 de l’extension d’infrastructure série (SerCx2) utilise pour effectuer des transactions de transmission système DMA.

Syntaxe

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

Paramètres

[in] Device

Un handle WDFDEVICE pour l’objet d’appareil framework qui représente le contrôleur série. Le pilote du contrôleur série a créé cet objet dans sa fonction de rappel EvtDriverDeviceAdd . Pour plus d’informations, consultez SerCx2InitializeDevice.

[in] SystemDmaTransmitConfig

Pointeur vers une structure SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG . Avant d’appeler cette méthode, l’appelant doit appeler la fonction SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT pour initialiser la structure. Cette structure contient des pointeurs vers un ensemble de routines de rappel d’événements implémentées par le pilote de contrôleur série. SerCx2 appelle ces fonctions pour effectuer des transactions de transmission DMA système.

[in, optional] Attributes

Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES qui décrit les attributs à affecter au nouvel objet system-DMA-transmit. Avant d’appeler cette méthode, l’appelant doit appeler la fonction WDF_OBJECT_ATTRIBUTES_INIT pour initialiser la structure. Ce paramètre est facultatif et peut être spécifié en tant que WDF_NO_OBJECT_ATTRIBUTES si le pilote de contrôleur série n’a pas besoin d’affecter des attributs à l’objet. Pour plus d'informations, consultez la section Notes.

[out] SystemDmaTransmit

Pointeur vers un emplacement dans lequel cette méthode écrit un handle de SERCX2SYSTEMDMATRANSMIT dans l’objet system-DMA-transmit nouvellement créé. SerCx2 et le pilote de contrôleur série utilisent ce handle dans les appels suivants pour faire référence à cet objet.

Valeur retournée

Cette méthode retourne STATUS_SUCCESS si l’appel réussit. Les valeurs de retour d’erreur possibles incluent les codes status suivants.

Code de retour	Description
STATUS_INVALID_DEVICE_REQUEST	Un objet system-DMA-transmit existe déjà à partir d’un appel SerCx2SystemDmaTransmitCreate précédent ; ou un objet de transmission personnalisée existe à partir d’un appel précédent à la méthode SerCx2CustomTransmitCreate ; ou un objet custom-receive existe à partir d’un appel précédent à la méthode SerCx2CustomReceiveCreate ; ou SerCx2PioTransmitCreate n’a pas encore été appelé pour créer un objet de transmission PIO.
STATUS_INFO_LENGTH_MISMATCH	La valeurTaille de la configuration-> n’est pas égale à sizeof(SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG).
STATUS_INVALID_PARAMETER	Une valeur de paramètre n’est pas valide.
STATUS_INSUFFICIENT_RESOURCES	Les ressources disponibles sont insuffisantes pour créer l’objet system-DMA-transmit.

Remarques

Votre pilote de contrôleur série peut utiliser cette méthode pour créer un objet de transmission DMA système. SerCx2 utilise cet objet pour effectuer des transactions de transmission système DMA, qui sont des transactions qui utilisent le contrôleur DMA système pour écrire des données dans le contrôleur série à transmettre.

En règle générale, un pilote de contrôleur série appelle SerCx2SystemDmaTransmitCreate à partir de sa fonction de rappel EvtDevicePrepareHardware . Cette fonction reçoit une liste de ressources matérielles, qui peuvent inclure des canaux DMA système.

Le pilote du contrôleur série doit appeler correctement les méthodes SerCx2InitializeDevice et SerCx2PioTransmitCreate avant d’appeler SerCx2SystemDmaTransmitCreate.

Avant d’appeler SerCx2SystemDmaTransmitCreate, le pilote de contrôleur série doit appeler la fonction SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT pour initialiser la structure SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG pointée par SystemDmaTransmitConfig. Cette fonction définit les membres suivants de la structure sur zéro :

MaximumScatterGatherFragments
MinimumTransferUnitOverride
DmaAlignment
MinimumTransactionLength
Exclusif

Si nécessaire, le pilote du contrôleur série peut définir l’un de ces membres sur des valeurs différentes de zéro après le retour de la fonction d’initialisation. Toutefois, pour des raisons pratiques, SerCx2SystemDmaTransmitCreate utilise les valeurs par défaut suivantes si ces membres sont zéro :

Si MaximumScatterGatherFragments est égal à zéro, SerCx2 définit le nombre maximal d’éléments dans une liste de points/regroupements sur ((ULONG)-1).
Si MinimumTransferUnitOverride est égal à zéro, SerCx2 définit l’unité de transfert minimale sur sa valeur par défaut, qui est spécifiée dans la structure DMA_ADAPTER pour le contrôleur DMA système. Pour plus d’informations sur cette structure, consultez WdfDmaEnablerWdmGetDmaAdapter.
Si DmaAlignment est égal à zéro, SerCx2 définit la valeur d’alignement sur l’unité de transfert minimale. Si MinimumTransferUnitOverride est égal à zéro, l’unité de transfert minimale par défaut est utilisée.
Si MinimumTransactionLength est égal à zéro, SerCx2 définit la longueur minimale de transaction sur un octet.
Si Exclusive a la valeur zéro (FALSE), le mode exclusif est désactivé.

Si le pilote appelant définit Exclusive sur TRUE, les membres MinimumTransferUnitOverride, DmaAlignment et MinimumTransactionLength doivent être zéro. Pour plus d’informations, consultez SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG.

Si la combinaison spécifiée de fonctions de rappel implémentées n’est pas valide, SerCx2SystemDmaTransmitCreate échoue et retourne STATUS_INVALID_PARAMETER. Le pilote doit implémenter les trois fonctions EvtSerCx2SystemDmaTransmitDrainFifo, EvtSerCx2SystemDmaTransmitCancelDrainFifo et EvtSerCx2SystemDmaTransmitPurgeFifo .

En option, un pilote de contrôleur série peut utiliser le paramètre Attributes pour créer un contexte pour l’objet system-DMA-transmit et pour fournir des pointeurs vers les fonctions EvtCleanupCallback et EvtDestroyCallback appelées pour préparer l’objet à la suppression. Pour plus d’informations, consultez WDF_OBJECT_ATTRIBUTES.

Si le paramètre Attributes pointe vers une structure WDF_OBJECT_ATTRIBUTES , l’appelant ne doit pas remplacer les valeurs que la fonction d’initialisation WDF_OBJECT_ATTRIBUTES_INIT écrit sur les membres ParentObject, ExecutionLevel et SynchronizationScope de cette structure.

Pour plus d’informations sur la création d’objets de transmission système-DMA, consultez SERCX2SYSTEMDMATRANSMIT. Pour plus d’informations sur les transactions de transmission système-DMA, consultez SerCx2 System-DMA-Transmit Transactions.