reactos/include/ddk/iofuncs.h

   1 /* IO MANAGER ***************************************************************/
   2
   3 /*
   4  * FUNCTION: Registers the driver with WMI
   5  * ARGUMENTS:
   6  *          DeviceObject = Device to register
   7  *          Action = Action to take
   8  * RETURNS: Status (?)
   9  */
  10 //NTSTATUS IoWMIRegistrationControl(DeviceObject, WMIREGACTION Action);
  11
  12 /*
  13  * FUNCTION: Synchronizes cancelable-state transistions for IRPs in a
  14  * multiprocessor-safe way
  15  * ARGUMENTS:
  16  *          Irpl = Variable to store the current IRQ level
  17  */
  18 VOID IoAcquireCancelSpinLock(PKIRQL Irpl);
  19
  20 typedef IO_ALLOCATION_ACTION (*PDRIVER_CONTROL)(PDEVICE_OBJECT DeviceObject,
  21                                         PIRP irp,
  22                                         PVOID MapRegisterBase,
  23                                         PVOID Context);
  24
  25 /*
  26  * FUNCTION: Allocates an adaptor object for a DMA operation on the target
  27  * device
  28  * ARGUMENTS:
  29  *         Adaptor = Adapter channel or busmaster adapter to be allocated
  30  *         DeviceObject = Target device for DMA
  31  *         NumberOfMapRegisters = Number of map registers
  32  *         ExecutionRoutine = Routine to be called when the adaptor is
  33  *                            available
  34  *         Context = driver defined contex that will be passed to the
  35  *                   execution routine
  36  * RETURNS: Success or failure code
  37  */
  38 NTSTATUS IoAllocateAdapterChannel(PADAPTER_OBJECT AdaperObject,
  39                                   PDEVICE_OBJECT DeviceObject,
  40                                   ULONG NumberOfMapRegisters,
  41                                   PDRIVER_CONTROL ExecutionRoutine,
  42                                   PVOID Context);
  43
  44 /*
  45  * FUNCTION: Sets up a call to a driver supplied controller object as
  46  * soon as it is available
  47  * ARGUMENTS:
  48  *        ControllerObject = Driver created controller object
  49  *        DeviceObject = target device
  50  *        ExecutionObject = Routine to be called
  51  *        Context = Driver determined context to be based to the routine
  52  */
  53 VOID IoAllocateController(PCONTROLLER_OBJECT ControllerObject,
  54                           PDEVICE_OBJECT DeviceObject,
  55                           PDRIVER_CONTROL ExecutionRoutine,
  56                           PVOID Context);
  57
  58 /*
  59  * FUNCTION: Allocates an error log packet
  60  * ARGUMENTS:
  61  *         IoObject = Object which found the error
  62  *         EntrySize = Size in bytes of the packet to be allocated
  63  * RETURNS: On success a pointer to the allocated packet
  64  *          On failure returns NULL
  65  */
  66 PVOID IoAllocateErrorLogEntry(PVOID IoObject, UCHAR EntrySize);
  67
  68 /*
  69  * FUNCTION: Allocates an IRP
  70  * ARGUMENTS:
  71  *        StackSize = number of stack locations to allocate
  72  *        ChargeQuota = Who knows
  73  * RETURNS: On success the allocated IRP
  74  *          On failure NULL
  75  */
  76 PIRP IoAllocateIrp(CCHAR StackSize, BOOLEAN ChargeQuota);
  77
  78 /*
  79  * FUNCTION: Allocates an MDL large enough to map the supplied buffer
  80  * ARGUMENTS:
  81  *        VirtualAddress = base virtual address of the buffer to be mapped
  82  *        Length = length of the buffer to be mapped
  83  *        SecondaryBuffer = Whether the buffer is primary or secondary
  84  *        ChargeQuota = Charge non-paged pool quota to current thread
  85  *        Irp = Optional irp to be associated with the MDL
  86  * RETURNS: On the success the allocated MDL
  87  *          On failure NULL
  88  */
  89 PMDL IoAllocateMdl(PVOID VirtualAddress, ULONG Length,
  90                    BOOLEAN SecondaryBuffer, BOOLEAN ChargeQuota,
  91                    PIRP Irp);
  92
  93 /*
  94  * FUNCTION: Creates a symbolic link between the ARC name of a physical
  95  * device and the name of the corresponding device object
  96  * ARGUMENTS:
  97  *        ArcName = ARC name of the device
  98  *        DeviceName = Name of the device object
  99  */
 100 VOID IoAssignArcName(PUNICODE_STRING ArcName, PUNICODE_STRING DeviceName);
 101
 102 enum
 103 {
 104    IO_NO_INCREMENT,
 105 };
 106
 107 /*
 108  * FUNCTION: Takes a list of requested hardware resources and allocates them
 109  * ARGUMENTS:
 110  *        RegisterPath =
 111  *        DriverClassName =
 112  *        DriverObject = Driver object passed to the DriverEntry routine
 113  *        DeviceObject =
 114  *        RequestedResources = List of resources
 115  * RETURNS:
 116  */
 117 NTSTATUS IoAssignResources(PUNICODE_STRING RegistryPath,
 118                            PUNICODE_STRING DriverClassName,
 119                            PDRIVER_OBJECT DriverObject,
 120                            PDEVICE_OBJECT DeviceObject,
 121                            PIO_RESOURCE_REQUIREMENTS_LIST RequestedResources,
 122                            PCM_RESOURCE_LIST* AllocatedResources);
 123
 124 /*
 125  * FUNCTION: Attaches the callers device object to a named target device
 126  * ARGUMENTS:
 127  *        SourceDevice = caller's device
 128  *        TargetDevice = Name of the target device
 129  *        AttachedDevice = Caller allocated storage. On return contains
 130  *                         a pointer to the target device
 131  * RETURNS: Success or failure code
 132  */
 133 NTSTATUS IoAttachDevice(PDEVICE_OBJECT SourceDevice,
 134                         PUNICODE_STRING TargetDevice,
 135                         PDEVICE_OBJECT* AttachedDevice);
 136
 137 /*
 138  * FUNCTION: Obsolete
 139  * ARGUMENTS:
 140  *       SourceDevice = device to attach
 141  *       TargetDevice = device to be attached to
 142  * RETURNS: Success or failure code
 143  */
 144 NTSTATUS IoAttachDeviceByPointer(PDEVICE_OBJECT SourceDevice,
 145                                  PDEVICE_OBJECT TargetDevice);
 146
 147 /*
 148  * FUNCTION: Attaches the callers device to the highest device in the chain
 149  * ARGUMENTS:
 150  *       SourceDevice = caller's device
 151  *       TargetDevice = Device to attach
 152  * RETURNS: On success the previously highest device
 153  *          On failure NULL
 154  */
 155 PDEVICE_OBJECT IoAttachDeviceToDeviceStack(PDEVICE_OBJECT SourceDevice,
 156                                            PDEVICE_OBJECT TargetDevice);
 157
 158 /*
 159  * FUNCTION: Builds a irp to be sent to lower level drivers
 160  * ARGUMENTS:
 161  *       MajorFunction = Major function code to be set in the IRP
 162  *       DeviceObject = Next lower device object
 163  *       Buffer = Buffer (only required for some major function codes)
 164  *       Length = Length in bytes of the buffer
 165  *       StartingOffset = Starting offset on the target device
 166  *       IoStatusBlock = Storage for status about the operation (optional)
 167  * RETURNS: On success the IRP allocated
 168  *          On failure NULL
 169  */
 170 PIRP IoBuildAsynchronousFsdRequest(ULONG MajorFunction,
 171                                    PDEVICE_OBJECT DeviceObject,
 172                                    PVOID Buffer,
 173                                    ULONG Length,
 174                                    PLARGE_INTEGER StartingOffset,
 175                                    PIO_STATUS_BLOCK IoStatusBlock);
 176
 177 /*
 178  * FUNCTION: Allocates and sets up an IRP for a device control request
 179  * ARGUMENTS:
 180  *        IoControlCode = Type of request
 181  *        DeviceObject = Target device
 182  *        InputBuffer = Optional input buffer to the driver
 183  *        InputBufferLength = Length of the input buffer
 184  *        OutputBuffer = Optional output buffer
 185  *        OutputBufferLength = Length of the output buffer
 186  *        InternalDeviceIoControl = TRUE if the request is internal
 187  *        Event = Initialized event for the caller to wait for the request
 188  *                to be completed
 189  *        IoStatusBlock = I/O status block to be set when the request is
 190  *                        completed
 191  * RETURNS: Returns the IRP created
 192  */
 193 PIRP IoBuildDeviceIoControlRequest(ULONG IoControlCode,
 194                                    PDEVICE_OBJECT DeviceObject,
 195                                    PVOID InputBuffer,
 196                                    ULONG InputBufferLength,
 197                                    PVOID OutputBuffer,
 198                                    ULONG OutputBufferLength,
 199                                    BOOLEAN InternalDeviceIoControl,
 200                                    PKEVENT Event,
 201                                    PIO_STATUS_BLOCK IoStatusBlock);
 202
 203
 204 VOID IoBuildPartialMdl(PMDL SourceMdl,
 205                        PMDL TargetMdl,
 206                        PVOID VirtualAddress,
 207                        ULONG Length);
 208
 209 PIRP IoBuildSynchronousFsdRequest(ULONG MajorFunction,
 210                                   PDEVICE_OBJECT DeviceObject,
 211                                   PVOID Buffer,
 212                                   ULONG Length,
 213                                   PLARGE_INTEGER StartingOffset,
 214                                   PKEVENT Event,
 215                                   PIO_STATUS_BLOCK IoStatusBlock);
 216
 217 /*
 218  * FUNCTION: Sends an irp to the next lower driver
 219  */
 220 NTSTATUS IoCallDriver(PDEVICE_OBJECT DeviceObject, PIRP irp);
 221
 222 BOOLEAN IoCancelIrp(PIRP Irp);
 223
 224 NTSTATUS IoCheckShareAccess(ACCESS_MASK DesiredAccess,
 225                             ULONG DesiredShareAccess,
 226                             PFILE_OBJECT FileObject,
 227                             PSHARE_ACCESS ShareAccess,
 228                             BOOLEAN Update);
 229
 230 /*
 231  * FUNCTION: Indicates the caller has finished all processing for a given
 232  * I/O request and is returning the given IRP to the I/O manager
 233  * ARGUMENTS:
 234  *         Irp = Irp to be cancelled
 235  *         PriorityBoost = Increment by which to boost the priority of the
 236  *                         thread making the request
 237  */
 238 VOID IoCompleteRequest(PIRP Irp, CCHAR PriorityBoost);
 239
 240 NTSTATUS IoConnectInterrupt(PKINTERRUPT* InterruptObject,
 241                             PKSERVICE_ROUTINE ServiceRoutine,
 242                             PVOID ServiceContext,
 243                             PKSPIN_LOCK SpinLock,
 244                             ULONG Vector,
 245                             KIRQL Irql,
 246                             KIRQL SynchronizeIrql,
 247                             KINTERRUPT_MODE InterruptMode,
 248                             BOOLEAN ShareVector,
 249                             KAFFINITY ProcessorEnableMask,
 250                             BOOLEAN FloatingSave);
 251
 252 PCONTROLLER_OBJECT IoCreateController(ULONG Size);
 253
 254 /*
 255  * FUNCTION: Allocates memory for and intializes a device object for use for
 256  * a driver
 257  * ARGUMENTS:
 258  *         DriverObject : Driver object passed by iomgr when the driver was
 259  *                        loaded
 260  *         DeviceExtensionSize : Number of bytes for the device extension
 261  *         DeviceName : Unicode name of device
 262  *         DeviceType : Device type
 263  *         DeviceCharacteristics : Bit mask of device characteristics
 264  *         Exclusive : True if only one thread can access the device at a
 265  *                     time
 266  * RETURNS:
 267  *         Success or failure
 268  *         DeviceObject : Contains a pointer to allocated device object
 269  *                        if the call succeeded
 270  * NOTES: See the DDK documentation for more information
 271  */
 272 NTSTATUS IoCreateDevice(PDRIVER_OBJECT DriverObject,
 273                         ULONG DeviceExtensionSize,
 274                         PUNICODE_STRING DeviceName,
 275                         DEVICE_TYPE DeviceType,
 276                         ULONG DeviceCharacteristics,
 277                         BOOLEAN Exclusive,
 278                         PDEVICE_OBJECT* DeviceObject);
 279
 280
 281 PKEVENT IoCreateNotificationEvent(PUNICODE_STRING EventName,
 282                                   PHANDLE EventHandle);
 283
 284 NTSTATUS IoCreateSymbolicLink(PUNICODE_STRING SymbolicLinkName,
 285                               PUNICODE_STRING DeviceName);
 286
 287 PKEVENT IoCreateSynchronizationEvent(PUNICODE_STRING EventName,
 288                                      PHANDLE EventHandle);
 289
 290 NTSTATUS IoCreateUnprotectedSymbolicLink(PUNICODE_STRING SymbolicLinkName,
 291                                          PUNICODE_STRING DeviceName);
 292
 293
 294 VOID IoDeassignArcName(PUNICODE_STRING ArcName);
 295
 296 VOID IoDeleteController(PCONTROLLER_OBJECT ControllerObject);
 297
 298 VOID IoDeleteDevice(PDEVICE_OBJECT DeviceObject);
 299
 300 NTSTATUS IoDeleteSymbolicLink(PUNICODE_STRING SymbolicLinkName);
 301
 302 VOID IoDetachDevice(PDEVICE_OBJECT TargetDevice);
 303
 304 VOID IoDisconnectInterrupt(PKINTERRUPT InterruptObject);
 305
 306 BOOLEAN IoFlushAdapterBuffers(PADAPTER_OBJECT AdapterObject,
 307                               PMDL Mdl,
 308                               PVOID MapRegisterBase,
 309                               PVOID CurrentVa,
 310                               ULONG Length,
 311                               BOOLEAN WriteToDevice);
 312
 313 VOID IoFreeAdapterChannel(PADAPTER_OBJECT AdapterObject);
 314 VOID IoFreeController(PCONTROLLER_OBJECT ControllerObject);
 315 VOID IoFreeIrp(PIRP Irp);
 316 VOID IoFreeMapRegisters(PADAPTER_OBJECT AdapterObject,
 317                         PVOID MapRegisterBase,
 318                         ULONG NumberOfMapRegisters);
 319 VOID IoFreeMdl(PMDL Mdl);
 320 PCONFIGURATION_INFORMATION IoGetConfigurationInformation(VOID);
 321
 322
 323 /*
 324  * FUNCTION: Returns a pointer to the callers stack location in the irp
 325  */
 326 PIO_STACK_LOCATION IoGetCurrentIrpStackLocation(IRP* irp);
 327
 328 struct _EPROCESS* IoGetCurrentProcess(VOID);
 329
 330 NTSTATUS IoGetDeviceObjectPointer(PUNICODE_STRING ObjectName,
 331                                   ACCESS_MASK DesiredAccess,
 332                                   PFILE_OBJECT* FileObject,
 333                                   PDEVICE_OBJECT* DeviceObject);
 334
 335 PDEVICE_OBJECT IoGetDeviceToVerify(PETHREAD Thread);
 336
 337 PGENERIC_MAPPING IoGetFileObjectGenericMapping(VOID);
 338
 339 ULONG IoGetFunctionCodeFromCtlCode(ULONG ControlCode);
 340
 341 PVOID IoGetInitialStack(VOID);
 342
 343 /*
 344  * FUNCTION:
 345  */
 346 PIO_STACK_LOCATION IoGetNextIrpStackLocation(IRP* irp);
 347
 348 PDEVICE_OBJECT IoGetRelatedDeviceObject(PFILE_OBJECT FileObject);
 349
 350 VOID IoInitializeDpcRequest(PDEVICE_OBJECT DeviceObject,
 351                             PIO_DPC_ROUTINE DpcRoutine);
 352
 353 /*
 354  * FUNCTION: Initalizes an irp allocated by the caller
 355  * ARGUMENTS:
 356  *          Irp = IRP to initalize
 357  *          PacketSize = Size in bytes of the IRP
 358  *          StackSize = Number of stack locations in the IRP
 359  */
 360 VOID IoInitializeIrp(PIRP Irp, USHORT PacketSize, CCHAR StackSize);
 361
 362 NTSTATUS IoInitializeTimer(PDEVICE_OBJECT DeviceObject,
 363                            PIO_TIMER_ROUTINE TimerRoutine,
 364                            PVOID Context);
 365
 366 BOOLEAN IoIsErrorUserInduced(NTSTATUS Status);
 367
 368 BOOLEAN IoIsTotalDeviceFailure(NTSTATUS Status);
 369
 370 PIRP IoMakeAssociatedIrp(PIRP Irp, CCHAR StackSize);
 371
 372 PHYSICAL_ADDRESS IoMapTransfer(PADAPTER_OBJECT AdapterObject,
 373                                PMDL Mdl,
 374                                PVOID MapRegisterBase,
 375                                PVOID CurrentVa,
 376                                PULONG Length,
 377                                BOOLEAN WriteToDevice);
 378
 379 /*
 380  * FUNCTION: Marks an IRP as pending
 381  * ARGUMENTS:
 382  *         Irp = Irp to mark
 383  * NOTE: If a driver doesn't complete the irp in its dispatch routine it
 384  * must mark it pending otherwise the I/O manager will complete it on
 385  * return from the dispatch routine.
 386  */
 387 VOID IoMarkIrpPending(PIRP Irp);
 388
 389 NTSTATUS IoQueryDeviceDescription(PINTERFACE_TYPE BusType,
 390                                   PULONG BusNumber,
 391                                   PCONFIGURATION_TYPE ControllerType,
 392                                   PULONG ControllerNumber,
 393                                   PCONFIGURATION_TYPE PeripheralType,
 394                                   PULONG PeripheralNumber,
 395                                   PIO_QUERY_DEVICE_ROUTINE CalloutRoutine,
 396                                   PVOID Context);
 397
 398 VOID IoRaiseHardError(PIRP Irp, PVPB Vpb, PDEVICE_OBJECT RealDeviceObject);
 399
 400 BOOLEAN IoRaiseHardInformationalError(NTSTATUS ErrorStatus,
 401                                       PUNICODE_STRING String,
 402                                       PKTHREAD Thread);
 403
 404 NTSTATUS IoReadPartitionTable(PDEVICE_OBJECT DeviceObject,
 405                               ULONG SectorSize,
 406                               BOOLEAN ReturnedRecognizedPartitions,
 407                               struct _DRIVE_LAYOUT_INFORMATION** PBuffer);
 408
 409 VOID IoRegisterDriverReinitialization(PDRIVER_OBJECT DriverObject,
 410                                       PDRIVER_REINITIALIZE ReinitRoutine,
 411                                       PVOID Context);
 412
 413 NTSTATUS IoRegisterShutdownNotification(PDEVICE_OBJECT DeviceObject);
 414
 415 VOID IoReleaseCancelSpinLock(KIRQL Irql);
 416
 417 VOID IoRemoveShareAccess(PFILE_OBJECT FileObject,
 418                          PSHARE_ACCESS ShareAccess);
 419
 420 NTSTATUS IoReportResourceUsage(PUNICODE_STRING DriverClassName,
 421                                PDRIVER_OBJECT DriverObject,
 422                                PCM_RESOURCE_LIST DriverList,
 423                                ULONG DriverListSize,
 424                                PDEVICE_OBJECT DeviceObject,
 425                                PCM_RESOURCE_LIST DeviceList,
 426                                ULONG DeviceListSize,
 427                                BOOLEAN OverrideConflict,
 428                                PBOOLEAN ConflictDetected);
 429
 430 VOID IoRequestDpc(PDEVICE_OBJECT DeviceObject,
 431                   PIRP Irp,
 432                   PVOID Context);
 433
 434 PDRIVER_CANCEL IoSetCancelRoutine(PIRP Irp, PDRIVER_CANCEL CancelRoutine);
 435
 436 VOID IoSetCompletionRoutine(PIRP Irp,
 437                             PIO_COMPLETION_ROUTINE CompletionRoutine,
 438                             PVOID Context,
 439                             BOOLEAN InvokeOnSuccess,
 440                             BOOLEAN InvokeOnError,
 441                             BOOLEAN InvokeOnCancel);
 442
 443 VOID IoSetHardErrorOrVerifyDevice(PIRP Irp, PDEVICE_OBJECT DeviceObject);
 444
 445 VOID IoSetNextIrpStackLocation(PIRP Irp);
 446
 447 NTSTATUS IoSetPartitionInformation(PDEVICE_OBJECT DeviceObject,
 448                                    ULONG SectorSize,
 449                                    ULONG PartitionNumber,
 450                                    ULONG PartitionType);
 451
 452 VOID IoSetShareAccess(ACCESS_MASK DesiredAccess,
 453                       ULONG DesiredShareAccess,
 454                       PFILE_OBJECT FileObject,
 455                       PSHARE_ACCESS ShareAccess);
 456
 457 /*
 458  * FUNCTION:  Determines the size of an IRP
 459  * ARGUMENTS:
 460  *           StackSize = number of stack locations in the IRP
 461  * RETURNS: The size of the IRP in bytes
 462  */
 463 USHORT IoSizeOfIrp(CCHAR StackSize);
 464
 465 /*
 466  * FUNCTION: Dequeues the next IRP from the device's associated queue and
 467  * calls its StartIo routine
 468  * ARGUMENTS:
 469  *          DeviceObject = Device object
 470  *          Cancelable = True if IRPs in the queue can be cancelled
 471  */
 472 VOID IoStartNextPacket(PDEVICE_OBJECT DeviceObject, BOOLEAN Cancelable);
 473
 474 VOID IoStartNextPacketByKey(PDEVICE_OBJECT DeviceObject,
 475                             BOOLEAN Cancelable,
 476                             ULONG Key);
 477
 478 /*
 479  * FUNCTION: Calls the drivers StartIO routine with the IRP or queues it if
 480  * the device is busy
 481  * ARGUMENTS:
 482  *         DeviceObject = Device to pass the IRP to
 483  *         Irp = Irp to be processed
 484  *         Key = Optional value for where to insert the IRP
 485  *         CancelFunction = Entry point for a driver supplied cancel function
 486  */
 487 VOID IoStartPacket(PDEVICE_OBJECT DeviceObject, PIRP Irp, PULONG Key,
 488                    PDRIVER_CANCEL CancelFunction);
 489
 490 VOID IoStartTimer(PDEVICE_OBJECT DeviceObject);
 491
 492 VOID IoStopTimer(PDEVICE_OBJECT DeviceObject);
 493
 494 VOID IoUnregisterShutdownNotification(PDEVICE_OBJECT DeviceObject);
 495
 496 VOID IoUpdateShareAccess(PFILE_OBJECT FileObject, PSHARE_ACCESS ShareAccess);
 497
 498 VOID IoWriteErrorLogEntry(PVOID ElEntry);
 499
 500 NTSTATUS IoWritePartitionTable(PDEVICE_OBJECT DeviceObject,
 501                                ULONG SectorSize,
 502                                ULONG SectorsPerTrack,
 503                                ULONG NumberOfHeads,
 504                                struct _DRIVE_LAYOUT_INFORMATION* PBuffer);
 505
 506 typedef ULONG FS_INFORMATION_CLASS;
 507
 508 // Preliminary guess
 509 NTKERNELAPI NTSTATUS IoQueryFileVolumeInformation(IN PFILE_OBJECT FileObject,
 510                                   IN FS_INFORMATION_CLASS FsInformationClass,
 511                                                   IN ULONG Length,
 512                                                   OUT PVOID FsInformation,
 513                                                   OUT PULONG ReturnedLength);
 514
 515 NTKERNELAPI // confirmed - Undocumented because it does not require a valid file handle
 516 NTSTATUS
 517 IoQueryFileInformation(
 518 IN PFILE_OBJECT FileObject,
 519 IN FILE_INFORMATION_CLASS FileInformationClass,
 520 IN ULONG Length,
 521 OUT PVOID FileInformation,
 522 OUT PULONG ReturnedLength
 523 );