DEVICE_OBJECT
A device object represents a logical, virtual, or physical device for which a
loaded driver handles I/O requests. Every kernel-mode driver must call IoCreateDevice
one or more times from its DriverEntry routine when it initializes to create
its device object(s).
A device object is partially opaque. Driver writers must know about certain
fields and system-defined symbolic constants associated with device objects
because their drivers must access these fields through the device object
pointer returned by IoCreateDevice and passed to most standard driver
routines. The following fields in device objects are accessible to drivers.
Accessible Fields
-
PDRIVER_OBJECT DriverObject
-
Points to the driver object, representing the driver’s loaded image, that was
input to the DriverEntry routine.
-
PDEVICE_OBJECT NextDevice
-
Points to the next device object, if any, created by the same driver.The I/O
Manager updates this list at each successful call to IoCreateDevice. A
driver that is being unloaded must walk the list of its device objects and
delete them. A driver that re-creates its device objects dynamically also uses
this field.
-
PIRP CurrentIrp
-
Points to the current IRP if the driver has a StartIo routine whose entry
point was set in the driver object and if the driver is currently processing
IRP(s). Otherwise, this field is NULL.
-
ULONG Flags
-
Device drivers OR this field in their newly created device objects with either
of the following system-defined values: DO_BUFFERED_IO or DO_DIRECT_IO.
Higher-level drivers OR this field with the same value as the next-lower
driver, except possibly for highest-level drivers. While processing transfer
requests, removable-media device drivers also OR this field with
DO_VERIFY_VOLUME, as well as checking whether this field is already set with
DO_VERIFY_VOLUME in the target for a transfer request.
-
ULONG Characteristics
-
Set when a floppy, CD-ROM, WORM, or other removable-media device driver calls IoCreateDevice
with one of the following values, as appropriate: FILE_REMOVABLE_MEDIA,
FILE_READ_ONLY_DEVICE, FILE_FLOPPY_DISKETTE, FILE_WRITE_ONCE_MEDIA.
-
PVOID DeviceExtension
-
Points to the device extension. The structure and contents of the device
extension are driver-defined. The size is driver-determined, specified in the
driver’s call to IoCreateDevice. Most driver routines that process IRPs
are given a pointer to the device object so the device extension is usually
every driver’s primary global storage area and frequently a driver’s only
global storage area for objects, resources, and any state the driver maintains
about the I/O requests it handles.
-
DEVICE_TYPE DeviceType
-
Set when a driver calls IoCreateDevice as appropriate for the type of
underlying device. A driver writer can define a new FILE_DEVICE_XXX
with a value in the customer range 32768 to 65535 if none of the
system-defined values describes the type of the new device. For a list of the
system-defined values, see the FILE_DEVICE_XXX in Chapter
1 of Part II in this manual.
-
CCHAR StackSize
-
Specifies the minimum number of stack locations in IRPs to be sent to this
driver. IoCreateDevice sets this field to one in newly created device
objects; lowest-level drivers can therefore ignore this field. The I/O manager
automatically sets the StackSize field in a higher-level driver’s
device object to the appropriate value if the driver calls IoAttachDevice
or IoAttachDeviceToDeviceStack. Only a higher-level driver that chains
itself over another driver with IoGetDeviceObjectPointer must
explicitly set the value of StackSize in its own device object(s) to (1
+ the StackSize value of the next-lower driver’s device object).
-
ULONG AlignmentRequirement
-
Some higher-level drivers, such as a class driver layered over a corresponding
port driver, that call IoGetDeviceObjectPointer reset this field in
their device objects to the value of the next-lower driver’s device object.
Other higher-level drivers set this field at the discretion of the driver
designer or leave it as set by the I/O Manager. Each device driver sets this
field in its newly created device object(s) to the greater of (the alignment
requirement of the device - 1) or (the
initialized value of this field), which can be one of the following
system-defined values:
FILE_BYTE_ALIGNMENT
FILE_WORD_ALIGNMENT
FILE_LONG_ALIGNMENT
FILE_QUAD_ALIGNMENT
FILE_OCTA_ALIGNMENT
FILE_32_BYTE_ALIGNMENT
FILE_64_BYTE_ALIGNMENT
FILE_128_BYTE_ALIGNMENT
FILE_512_BYTE_ALIGNMENT
Comments
The DeviceType range 0 to 32767 is reserved for use by Microsoft.
Undocumented fields within a device object should be considered inaccessible.
Drivers with dependencies on object field locations or access to undocumented
fields might not remain portable and interoperable with other drivers over
time.
The system-supplied video port driver sets up the fields of the device objects
it creates on behalf of video miniport drivers. For more information about
these video drivers, see the Graphics Driver Design Guide and the Graphics
Driver Design Reference.
The system-supplied SCSI port driver sets up the fields of the device objects
it creates on behalf of HBA miniport drivers. For more information about these
SCSI drivers, see the Kernel-Mode Driver Design Guide and Part 3 of
this manual.
The system-supplied NDIS library sets up the fields of the device objects it
creates on behalf of netcard drivers. For more information about NDIS drivers,
see the Network Driver Design Guide.
See Also
DRIVER_OBJECT, IoAttachDevice,
IoAttachDeviceToDeviceStack,
IoCreateDevice, IoDeleteDevice,
IoGetDeviceObjectPointer