Routine DriverEntry pour les pilotes WDF
[S’applique à KMDF et UMDF]
DriverEntry est la première routine fournie par le pilote appelée après le chargement d’un pilote. Il est responsable de l’initialisation du pilote.
Syntaxe
NTSTATUS DriverEntry(
_In_ PDRIVER_OBJECT DriverObject,
_In_ PUNICODE_STRING RegistryPath
);
Paramètres
DriverObject [in]
Pointeur vers une structure DRIVER_OBJECT qui représente l’objet de pilote WDM du pilote.
RegistryPath [in]
Pointeur vers une structure de UNICODE_STRING qui spécifie le chemin d’accès à la clé Paramètres du pilote dans le Registre.
Valeur retournée
Si la routine réussit, elle doit retourner STATUS_SUCCESS. Sinon, il doit retourner l’une des valeurs d’erreur status définies dans ntstatus.h.
Remarques
Comme tous les pilotes WDM, les pilotes basés sur l’infrastructure doivent avoir une routine DriverEntry , appelée après le chargement du pilote. La routine DriverEntry d’un pilote basé sur l’infrastructure doit :
Activez le suivi logiciel WPP.
DriverEntry doit inclure une macro WPP_INIT_TRACING pour activer le suivi logiciel.
Appelez WdfDriverCreate.
L’appel à WdfDriverCreate permet au pilote d’utiliser des interfaces Windows Driver Framework. (Le pilote ne peut pas appeler d’autres routines d’infrastructure avant d’appeler WdfDriverCreate.)
Allouez toutes les ressources système non spécifiques à l’appareil et les variables globales dont il peut avoir besoin.
En règle générale, les pilotes associent des ressources système à des appareils individuels. Par conséquent, les pilotes basés sur l’infrastructure allouent la plupart des ressources dans un rappel EvtDriverDeviceAdd , qui est appelé lorsque des appareils individuels sont détectés.
Étant donné que plusieurs instances d’un pilote UMDF peuvent être hébergées par des instances distinctes de Wudfhost, une variable globale peut ne pas être disponible sur toutes les instances d’un pilote UMDF.
Obtenez des paramètres spécifiques au pilote à partir du Registre.
Certains pilotes obtiennent des paramètres à partir du Registre. Ces pilotes peuvent appeler WdfDriverOpenParametersRegistryKey pour ouvrir la clé de Registre qui contient ces paramètres.
Fournissez une valeur de retour DriverEntry.
Note Un pilote UMDF s’exécute dans un processus hôte en mode utilisateur, tandis qu’un pilote KMDF s’exécute en mode noyau dans un processus système. L’infrastructure peut charger plusieurs instances d’un pilote UMDF dans des instances distinctes du processus hôte. Par conséquent :
- L’infrastructure peut appeler la routine DriverEntry d’un pilote UMDF plusieurs fois s’il charge des instances du pilote dans différents processus hôtes. En revanche, l’infrastructure appelle une seule fois la routine DriverEntry d’un pilote KMDF.
- Si un pilote UMDF crée une variable globale dans sa routine DriverEntry, la variable peut ne pas être disponible pour toutes les instances du pilote. Toutefois, une variable globale créée par un pilote KMDF dans sa routine DriverEntry est disponible pour toutes les instances du pilote.
Pour plus d’informations sur l’appel de la routine DriverEntry d’un pilote basé sur l’infrastructure, consultez Génération et chargement d’un pilote WDF.
La routine DriverEntry n’est pas déclarée dans les en-têtes WDK. Le vérificateur de pilotes statique (SDV) et d’autres outils de vérification peuvent nécessiter une déclaration telle que :
DRIVER_INITIALIZE MyDriverEntry;
NTSTATUS
DriverEntry(
IN PDRIVER_OBJECT DriverObject,
IN PUNICODE_STRING RegistryPath
)
{
// Function body
}
Exemples
L’exemple de code suivant montre la routine DriverEntry de l’exemple de pilote série (KMDF).
NTSTATUS
DriverEntry(
IN PDRIVER_OBJECT DriverObject,
IN PUNICODE_STRING RegistryPath
)
{
WDF_DRIVER_CONFIG config;
WDFDRIVER hDriver;
NTSTATUS status;
WDF_OBJECT_ATTRIBUTES attributes;
SERIAL_FIRMWARE_DATA driverDefaults;
//
// Initialize WPP tracing.
//
WPP_INIT_TRACING(
DriverObject,
RegistryPath
);
SerialDbgPrintEx(
TRACE_LEVEL_INFORMATION,
DBG_INIT,
"Serial Sample (WDF Version) - Built %s %s\n",
__DATE__, __TIME__
);
//
// Register a cleanup callback function (which calls WPP_CLEANUP)
// for the framework driver object. The framework will call
// the cleanup callback function when it deletes the driver object,
// before the driver is unloaded.
//
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.EvtCleanupCallback = SerialEvtDriverContextCleanup;
WDF_DRIVER_CONFIG_INIT(
&config,
SerialEvtDeviceAdd
);
status = WdfDriverCreate(
DriverObject,
RegistryPath,
&attributes,
&config,
&hDriver
);
if (!NT_SUCCESS(status)) {
SerialDbgPrintEx(
TRACE_LEVEL_ERROR,
DBG_INIT,
"WdfDriverCreate failed with status 0x%x\n",
status
);
//
// Clean up tracing here because WdfDriverCreate failed.
//
WPP_CLEANUP(DriverObject);
return status;
}
//
// Call an internal routine to obtain registry values
// to use for all the devices that the driver
// controls, including whether or not to break on entry.
//
SerialGetConfigDefaults(
&driverDefaults,
hDriver
);
//
// Break on entry if requested bt registry value.
//
if (driverDefaults.ShouldBreakOnEntry) {
DbgBreakPoint();
}
return status;
}