SerCx2SystemDmaReceiveCreate, fonction (sercx.h)
La méthode SerCx2SystemDmaReceiveCreate crée un objet system-DMA-receive SerCx2, que la version 2 de l’extension d’infrastructure série (SerCx2) utilise pour effectuer des transactions system-DMA-receive.
Syntaxe
NTSTATUS SerCx2SystemDmaReceiveCreate(
[in] WDFDEVICE Device,
[in] PSERCX2_SYSTEM_DMA_RECEIVE_CONFIG SystemDmaReceiveConfig,
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[out] SERCX2SYSTEMDMARECEIVE *SystemDmaReceive
);
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] SystemDmaReceiveConfig
Pointeur vers une structure SERCX2_SYSTEM_DMA_RECEIVE_CONFIG . Avant d’appeler cette méthode, l’appelant doit appeler la fonction SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT ou SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION 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 système-DMA-receive.
[in, optional] Attributes
Pointeur vers une structure WDF_OBJECT_ATTRIBUTES qui décrit les attributs à affecter au nouvel objet system-DMA-receive. 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] SystemDmaReceive
Pointeur vers un emplacement dans lequel cette méthode écrit un handle SERCX2SYSTEMDMARECEIVE dans l’objet system-DMA-receive 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 |
---|---|
|
Un objet system-DMA-receive existe déjà à partir d’un appel SerCx2SystemDmaReceiveCreate précédent ; ou un objet custom-receive existe déjà à partir d’un appel précédent à la méthode SerCx2CustomReceiveCreate ; ou un objet de transmission personnalisée existe à partir d’un appel précédent à la méthode SerCx2CustomTransmitCreate ; ou SerCx2PioReceiveCreate n’a pas encore été appelé pour créer un objet PIO-receive. |
|
->La valeurTaille de configuration n’est pas égale àsizeof(SERCX2_SYSTEM_DMA_RECEIVE_CONFIG). |
|
Une valeur de paramètre n’est pas valide. |
|
Les ressources disponibles sont insuffisantes pour effectuer l’opération demandée. |
Remarques
Cette méthode est appelée par le pilote de contrôleur série pour créer un objet system-DMA-receive. SerCx2 utilise cet objet pour effectuer des transactions system-DMA-receive, qui sont des transactions d’E/S qui utilisent le contrôleur DMA système pour lire les données reçues par le contrôleur série.
En règle générale, un pilote de contrôleur série appelle SerCx2SystemDmaReceiveCreate à 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.
Un pilote de contrôleur série doit appeler correctement les méthodes SerCx2InitializeDevice et SerCx2PioReceiveCreate avant d’appeler SerCx2SystemDmaReceiveCreate.
Avant d’appeler SerCx2SystemDmaReceiveCreate, le pilote du contrôleur série doit appeler la fonction SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT ou SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION pour initialiser la structure SERCX2_SYSTEM_DMA_RECEIVE_CONFIG pointée par SystemDmaReceiveConfig. Ces fonctions définissent les membres suivants de la structure sur zéro :
- MaximumScatterGatherFragments
- MinimumTransferUnitOverride
- DmaAlignment
- MinimumTransactionLength
- Exclusif
- 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 la combinaison spécifiée de fonctions de rappel implémentées n’est pas valide, SerCx2SystemDmaReceiveCreate échoue et retourne STATUS_INVALID_PARAMETER. Le pilote doit implémenter les fonctions EvtSerCx2SystemDmaReceiveEnableNewDataNotification et EvtSerCx2SystemDmaReceiveCancelNewDataNotification .
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-receive et pour fournir des pointeurs vers les fonctions EvtCleanupCallback et EvtDestroyCallback appelées pour préparer l’objet pour 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 system-DMA-receive, consultez SERCX2SYSTEMDMARECEIVE. Pour plus d’informations sur les transactions system-DMA-receive, consultez SerCx2 System-DMA-Receive Transactions.
Configuration requise
Condition requise | Valeur |
---|---|
Client minimal pris en charge | Disponible à partir de Windows 8.1. |
Plateforme cible | Universal |
En-tête | sercx.h |
IRQL | PASSIVE_LEVEL |
Voir aussi
EvtSerCx2SystemDmaReceiveCancelNewDataNotification
EvtSerCx2SystemDmaReceiveCleanupTransaction
EvtSerCx2SystemDmaReceiveEnableNewDataNotification
EvtSerCx2SystemDmaReceiveInitializeTransaction
SERCX2_SYSTEM_DMA_RECEIVE_CONFIG
SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT
Commentaires
https://aka.ms/ContentUserFeedback.
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultezEnvoyer et afficher des commentaires pour