DEVICE_OBJECT

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.