reactos/ntoskrnl/ke/apc.c

   1 /*
   2  * COPYRIGHT:       See COPYING in the top level directory
   3  * PROJECT:         ReactOS kernel
   4  * FILE:            ntoskrnl/ke/apc.c
   5  * PURPOSE:         NT Implementation of APCs
   6  *
   7  * PROGRAMMERS:     Alex Ionescu (alex@relsoft.net)
   8  *                  Phillip Susi
   9  */
  10
  11 /* INCLUDES *****************************************************************/
  12
  13 #include <ntoskrnl.h>
  14 #define NDEBUG
  15 #include <internal/debug.h>
  16
  17 /* FUNCTIONS *****************************************************************/
  18
  19 /*++
  20  * KiKernelApcDeliveryCheck
  21  * @implemented NT 5.2
  22  *
  23  *     The KiKernelApcDeliveryCheck routine is called whenever APCs have just
  24  *     been re-enabled in Kernel Mode, such as after leaving a Critical or
  25  *     Guarded Region. It delivers APCs if the environment is right.
  26  *
  27  * Params:
  28  *     None.
  29  *
  30  * Returns:
  31  *     None.
  32  *
  33  * Remarks:
  34  *     This routine allows KeLeave/EnterCritical/GuardedRegion to be used as a
  35  *     macro from inside WIN32K or other Drivers, which will then only have to
  36  *     do an Import API call in the case where APCs are enabled again.
  37  *
  38  *--*/
  39 VOID
  40 STDCALL
  41 KiKernelApcDeliveryCheck(VOID)
  42 {
  43     /* We should only deliver at passive */
  44     if (KeGetCurrentIrql() == PASSIVE_LEVEL)
  45     {
  46         /* Raise to APC and Deliver APCs, then lower back to Passive */
  47         KfRaiseIrql(APC_LEVEL);
  48         KiDeliverApc(KernelMode, 0, 0);
  49         KfLowerIrql(PASSIVE_LEVEL);
  50     }
  51     else
  52     {
  53         /*
  54          * If we're not at passive level it means someone raised IRQL
  55          * to APC level before the a critical or guarded section was entered
  56          * (e.g) by a fast mutex). This implies that the APCs shouldn't
  57          * be delivered now, but after the IRQL is lowered to passive
  58          * level again.
  59          */
  60         HalRequestSoftwareInterrupt(APC_LEVEL);
  61     }
  62 }
  63
  64 /*++
  65  * KeEnterCriticalRegion
  66  * @implemented NT4
  67  *
  68  *     The KeEnterCriticalRegion routine temporarily disables the delivery of
  69  *     normal kernel APCs; special kernel-mode APCs are still delivered.
  70  *
  71  * Params:
  72  *     None.
  73  *
  74  * Returns:
  75  *     None.
  76  *
  77  * Remarks:
  78  *     Highest-level drivers can call this routine while running in the context
  79  *     of the thread that requested the current I/O operation. Any caller of
  80  *     this routine should call KeLeaveCriticalRegion as quickly as possible.
  81  *
  82  *     Callers of KeEnterCriticalRegion must be running at IRQL <= APC_LEVEL.
  83  *
  84  *--*/
  85 #undef KeEnterCriticalRegion
  86 VOID
  87 STDCALL
  88 KeEnterCriticalRegion(VOID)
  89 {
  90     /* Disable Kernel APCs */
  91     PKTHREAD Thread = KeGetCurrentThread();
  92     if (Thread) Thread->KernelApcDisable--;
  93 }
  94
  95 /*++
  96  * KeLeaveCriticalRegion
  97  * @implemented NT4
  98  *
  99  *     The KeLeaveCriticalRegion routine reenables the delivery of normal
 100  *     kernel-mode APCs that were disabled by a call to KeEnterCriticalRegion.
 101  *
 102  * Params:
 103  *     None.
 104  *
 105  * Returns:
 106  *     None.
 107  *
 108  * Remarks:
 109  *     Highest-level drivers can call this routine while running in the context
 110  *     of the thread that requested the current I/O operation.
 111  *
 112  *     Callers of KeLeaveCriticalRegion must be running at IRQL <= DISPATCH_LEVEL.
 113  *
 114  *--*/
 115 #undef KeLeaveCriticalRegion
 116 VOID
 117 STDCALL
 118 KeLeaveCriticalRegion (VOID)
 119 {
 120     PKTHREAD Thread = KeGetCurrentThread();
 121
 122     /* Check if Kernel APCs are now enabled */
 123     if((Thread) && (++Thread->KernelApcDisable == 0))
 124     {
 125         /* Check if we need to request an APC Delivery */
 126         if (!IsListEmpty(&Thread->ApcState.ApcListHead[KernelMode]))
 127         {
 128             /* Check for the right environment */
 129             KiKernelApcDeliveryCheck();
 130         }
 131     }
 132 }
 133
 134 /*++
 135  * KeInitializeApc
 136  * @implemented NT4
 137  *
 138  *     The The KeInitializeApc routine initializes an APC object, and registers
 139  *     the Kernel, Rundown and Normal routines for that object.
 140  *
 141  * Params:
 142  *     Apc - Pointer to a KAPC structure that represents the APC object to
 143  *           initialize. The caller must allocate storage for the structure
 144  *           from resident memory.
 145  *
 146  *     Thread - Thread to which to deliver the APC.
 147  *
 148  *     TargetEnvironment - APC Environment to be used.
 149  *
 150  *     KernelRoutine - Points to the KernelRoutine to associate with the APC.
 151  *                     This routine is executed for all APCs.
 152  *
 153  *     RundownRoutine - Points to the RundownRoutine to associate with the APC.
 154  *                      This routine is executed when the Thread exists with
 155  *                      the APC executing.
 156  *
 157  *     NormalRoutine - Points to the NormalRoutine to associate with the APC.
 158  *                     This routine is executed at PASSIVE_LEVEL. If this is
 159  *                     not specifed, the APC becomes a Special APC and the
 160  *                     Mode and Context parameters are ignored.
 161  *
 162  *     Mode - Specifies the processor mode at which to run the Normal Routine.
 163  *
 164  *     Context - Specifices the value to pass as Context parameter to the
 165  *               registered routines.
 166  *
 167  * Returns:
 168  *     None.
 169  *
 170  * Remarks:
 171  *     The caller can queue an initialized APC with KeInsertQueueApc.
 172  *
 173  *     Storage for the APC object must be resident, such as nonpaged pool
 174  *     allocated by the caller.
 175  *
 176  *     Callers of this routine must be running at IRQL = PASSIVE_LEVEL.
 177  *
 178  *--*/
 179 VOID
 180 STDCALL
 181 KeInitializeApc(IN PKAPC Apc,
 182                 IN PKTHREAD Thread,
 183                 IN KAPC_ENVIRONMENT TargetEnvironment,
 184                 IN PKKERNEL_ROUTINE KernelRoutine,
 185                 IN PKRUNDOWN_ROUTINE RundownRoutine OPTIONAL,
 186                 IN PKNORMAL_ROUTINE NormalRoutine,
 187                 IN KPROCESSOR_MODE Mode,
 188                 IN PVOID Context)
 189 {
 190     DPRINT("KeInitializeApc(Apc %x, Thread %x, Environment %d, "
 191            "KernelRoutine %x, RundownRoutine %x, NormalRoutine %x, Mode %d, "
 192            "Context %x)\n",Apc,Thread,TargetEnvironment,KernelRoutine,RundownRoutine,
 193             NormalRoutine,Mode,Context);
 194
 195     /* Set up the basic APC Structure Data */
 196     RtlZeroMemory(Apc, sizeof(KAPC));
 197     Apc->Type = ApcObject;
 198     Apc->Size = sizeof(KAPC);
 199
 200     /* Set the Environment */
 201     if (TargetEnvironment == CurrentApcEnvironment) {
 202
 203         Apc->ApcStateIndex = Thread->ApcStateIndex;
 204
 205     } else {
 206
 207         Apc->ApcStateIndex = TargetEnvironment;
 208     }
 209
 210     /* Set the Thread and Routines */
 211     Apc->Thread = Thread;
 212     Apc->KernelRoutine = KernelRoutine;
 213     Apc->RundownRoutine = RundownRoutine;
 214     Apc->NormalRoutine = NormalRoutine;
 215
 216     /* Check if this is a Special APC, in which case we use KernelMode and no Context */
 217     if (ARGUMENT_PRESENT(NormalRoutine)) {
 218
 219         Apc->ApcMode = Mode;
 220         Apc->NormalContext = Context;
 221
 222     } else {
 223
 224         Apc->ApcMode = KernelMode;
 225     }
 226 }
 227
 228 /*++
 229  * KiInsertQueueApc
 230  *
 231  *     The KiInsertQueueApc routine queues a APC for execution when the right
 232  *     scheduler environment exists.
 233  *
 234  * Params:
 235  *     Apc - Pointer to an initialized control object of type DPC for which the
 236  *           caller provides the storage.
 237  *
 238  *     PriorityBoost - Priority Boost to apply to the Thread.
 239  *
 240  * Returns:
 241  *     If the APC is already inserted or APC queueing is disabled, FALSE.
 242  *     Otherwise, TRUE.
 243  *
 244  * Remarks:
 245  *     The APC will execute at APC_LEVEL for the KernelRoutine registered, and
 246  *     at PASSIVE_LEVEL for the NormalRoutine registered.
 247  *
 248  *     Callers of this routine must be running at IRQL = PASSIVE_LEVEL.
 249  *
 250  *--*/
 251 BOOLEAN
 252 STDCALL
 253 KiInsertQueueApc(PKAPC Apc,
 254                  KPRIORITY PriorityBoost)
 255 {
 256     PKTHREAD Thread = Apc->Thread;
 257     PLIST_ENTRY ApcListEntry;
 258     PKAPC QueuedApc;
 259
 260     /* Don't do anything if the APC is already inserted */
 261     if (Apc->Inserted) {
 262
 263         return FALSE;
 264     }
 265
 266     /* Three scenarios:
 267        1) Kernel APC with Normal Routine or User APC = Put it at the end of the List
 268        2) User APC which is PsExitSpecialApc = Put it at the front of the List
 269        3) Kernel APC without Normal Routine = Put it at the end of the No-Normal Routine Kernel APC list
 270     */
 271     if ((Apc->ApcMode != KernelMode) && (Apc->KernelRoutine == (PKKERNEL_ROUTINE)PsExitSpecialApc)) {
 272
 273         DPRINT ("Inserting the Process Exit APC into the Queue\n");
 274         Thread->ApcStatePointer[(int)Apc->ApcStateIndex]->UserApcPending = TRUE;
 275         InsertHeadList(&Thread->ApcStatePointer[(int)Apc->ApcStateIndex]->ApcListHead[(int)Apc->ApcMode],
 276                        &Apc->ApcListEntry);
 277
 278     } else if (Apc->NormalRoutine == NULL) {
 279
 280         DPRINT ("Inserting Special APC %x into the Queue\n", Apc);
 281
 282         for (ApcListEntry = Thread->ApcStatePointer[(int)Apc->ApcStateIndex]->ApcListHead[(int)Apc->ApcMode].Flink;
 283              ApcListEntry != &Thread->ApcStatePointer[(int)Apc->ApcStateIndex]->ApcListHead[(int)Apc->ApcMode];
 284              ApcListEntry = ApcListEntry->Flink) {
 285
 286             QueuedApc = CONTAINING_RECORD(ApcListEntry, KAPC, ApcListEntry);
 287             if (Apc->NormalRoutine != NULL) break;
 288         }
 289
 290         /* We found the first "Normal" APC, so write right before it */
 291         ApcListEntry = ApcListEntry->Blink;
 292         InsertHeadList(ApcListEntry, &Apc->ApcListEntry);
 293
 294     } else {
 295
 296         DPRINT ("Inserting Normal APC %x into the %x Queue\n", Apc, Apc->ApcMode);
 297         InsertTailList(&Thread->ApcStatePointer[(int)Apc->ApcStateIndex]->ApcListHead[(int)Apc->ApcMode],
 298                        &Apc->ApcListEntry);
 299     }
 300
 301     /* Confirm Insertion */
 302     Apc->Inserted = TRUE;
 303
 304     /*
 305      * Three possibilites here again:
 306      *  1) Kernel APC, The thread is Running: Request an Interrupt
 307      *  2) Kernel APC, The Thread is Waiting at PASSIVE_LEVEL and APCs are enabled and not in progress: Unwait the Thread
 308      *  3) User APC, Unwait the Thread if it is alertable
 309      */
 310     if (Apc->ApcMode == KernelMode) {
 311
 312         /* Set Kernel APC pending */
 313         Thread->ApcState.KernelApcPending = TRUE;
 314
 315         /* Check the Thread State */
 316         if (Thread->State == Running) {
 317
 318 #ifdef CONFIG_SMP
 319             PKPRCB Prcb, CurrentPrcb;
 320             LONG i;
 321             KIRQL oldIrql;
 322 #endif
 323
 324             DPRINT ("Requesting APC Interrupt for Running Thread \n");
 325
 326 #ifdef CONFIG_SMP
 327             oldIrql = KeRaiseIrqlToDpcLevel();
 328             CurrentPrcb = KeGetCurrentPrcb();
 329             if (CurrentPrcb->CurrentThread == Thread)
 330             {
 331                HalRequestSoftwareInterrupt(APC_LEVEL);
 332             }
 333             else
 334             {
 335                for (i = 0; i < KeNumberProcessors; i++)
 336                {
 337                   Prcb = ((PKPCR)(KPCR_BASE + i * PAGE_SIZE))->Prcb;
 338                   if (Prcb->CurrentThread == Thread)
 339                   {
 340                      ASSERT (CurrentPrcb != Prcb);
 341                      KiIpiSendRequest(Prcb->SetMember, IPI_REQUEST_APC);
 342                      break;
 343                   }
 344                }
 345                ASSERT (i < KeNumberProcessors);
 346             }
 347             KeLowerIrql(oldIrql);
 348 #else
 349             HalRequestSoftwareInterrupt(APC_LEVEL);
 350 #endif
 351
 352         } else if ((Thread->State == Waiting) && (Thread->WaitIrql == PASSIVE_LEVEL) &&
 353                    ((Apc->NormalRoutine == NULL) ||
 354                    ((!Thread->KernelApcDisable) && (!Thread->ApcState.KernelApcInProgress)))) {
 355
 356             DPRINT("Waking up Thread for Kernel-Mode APC Delivery \n");
 357             KiAbortWaitThread(Thread, STATUS_KERNEL_APC, PriorityBoost);
 358         }
 359
 360    } else if ((Thread->State == Waiting) &&
 361               (Thread->WaitMode == UserMode) &&
 362               (Thread->Alertable)) {
 363
 364         DPRINT("Waking up Thread for User-Mode APC Delivery \n");
 365         Thread->ApcState.UserApcPending = TRUE;
 366         KiAbortWaitThread(Thread, STATUS_USER_APC, PriorityBoost);
 367     }
 368
 369     return TRUE;
 370 }
 371
 372 /*++
 373  * KeInsertQueueApc
 374  * @implemented NT4
 375  *
 376  *     The KeInsertQueueApc routine queues a APC for execution when the right
 377  *     scheduler environment exists.
 378  *
 379  * Params:
 380  *     Apc - Pointer to an initialized control object of type DPC for which the
 381  *           caller provides the storage.
 382  *
 383  *     SystemArgument[1,2] - Pointer to a set of two parameters that contain
 384  *                           untyped data.
 385  *
 386  *     PriorityBoost - Priority Boost to apply to the Thread.
 387  *
 388  * Returns:
 389  *     If the APC is already inserted or APC queueing is disabled, FALSE.
 390  *     Otherwise, TRUE.
 391  *
 392  * Remarks:
 393  *     The APC will execute at APC_LEVEL for the KernelRoutine registered, and
 394  *     at PASSIVE_LEVEL for the NormalRoutine registered.
 395  *
 396  *     Callers of this routine must be running at IRQL = PASSIVE_LEVEL.
 397  *
 398  *--*/
 399 BOOLEAN
 400 STDCALL
 401 KeInsertQueueApc(PKAPC Apc,
 402                  PVOID SystemArgument1,
 403                  PVOID SystemArgument2,
 404                  KPRIORITY PriorityBoost)
 405
 406 {
 407     KIRQL OldIrql;
 408     PKTHREAD Thread;
 409     BOOLEAN Inserted;
 410
 411     ASSERT_IRQL_LESS_OR_EQUAL(DISPATCH_LEVEL);
 412     DPRINT("KeInsertQueueApc(Apc %x, SystemArgument1 %x, "
 413            "SystemArgument2 %x)\n",Apc,SystemArgument1,
 414             SystemArgument2);
 415
 416     /* Lock the Dispatcher Database */
 417     OldIrql = KeAcquireDispatcherDatabaseLock();
 418
 419     /* Get the Thread specified in the APC */
 420     Thread = Apc->Thread;
 421
 422     /* Make sure the thread allows APC Queues.
 423     * The thread is not apc queueable, for instance, when it's (about to be) terminated.
 424     */
 425     if (Thread->ApcQueueable == FALSE) {
 426         DPRINT("Thread doesn't allow APC Queues\n");
 427         KeReleaseDispatcherDatabaseLock(OldIrql);
 428         return FALSE;
 429     }
 430
 431     /* Set the System Arguments */
 432     Apc->SystemArgument1 = SystemArgument1;
 433     Apc->SystemArgument2 = SystemArgument2;
 434
 435     /* Call the Internal Function */
 436     Inserted = KiInsertQueueApc(Apc, PriorityBoost);
 437
 438     /* Return Sucess if we are here */
 439     KeReleaseDispatcherDatabaseLock(OldIrql);
 440     return Inserted;
 441 }
 442
 443 /*++
 444  * KeRemoveQueueApc
 445  *
 446  *     The KeRemoveQueueApc routine removes a given APC object from the system
 447  *     APC queue.
 448  *
 449  * Params:
 450  *     APC - Pointer to an initialized APC object that was queued by calling
 451  *           KeInsertQueueApc.
 452  *
 453  * Returns:
 454  *     TRUE if the APC Object is in the APC Queue. If it isn't, no operation is
 455  *     performed and FALSE is returned.
 456  *
 457  * Remarks:
 458  *     If the given APC Object is currently queued, it is removed from the queue
 459  *     and any calls to the registered routines are cancelled.
 460  *
 461  *     Callers of KeLeaveCriticalRegion can be running at any IRQL.
 462  *
 463  *--*/
 464 BOOLEAN
 465 STDCALL
 466 KeRemoveQueueApc(PKAPC Apc)
 467 {
 468     KIRQL OldIrql;
 469     PKTHREAD Thread = Apc->Thread;
 470
 471     ASSERT_IRQL_LESS_OR_EQUAL(DISPATCH_LEVEL);
 472     DPRINT("KeRemoveQueueApc called for APC: %x \n", Apc);
 473
 474     OldIrql = KeAcquireDispatcherDatabaseLock();
 475     KeAcquireSpinLock(&Thread->ApcQueueLock, &OldIrql);
 476
 477     /* Check if it's inserted */
 478     if (Apc->Inserted) {
 479
 480         /* Remove it from the Queue*/
 481         RemoveEntryList(&Apc->ApcListEntry);
 482         Apc->Inserted = FALSE;
 483
 484         /* If the Queue is completely empty, then no more APCs are pending */
 485         if (IsListEmpty(&Thread->ApcStatePointer[(int)Apc->ApcStateIndex]->ApcListHead[(int)Apc->ApcMode])) {
 486
 487             /* Set the correct State based on the Apc Mode */
 488             if (Apc->ApcMode == KernelMode) {
 489
 490                 Thread->ApcStatePointer[(int)Apc->ApcStateIndex]->KernelApcPending = FALSE;
 491
 492             } else {
 493
 494                 Thread->ApcStatePointer[(int)Apc->ApcStateIndex]->UserApcPending = FALSE;
 495             }
 496         }
 497
 498     } else {
 499
 500         /* It's not inserted, fail */
 501         KeReleaseSpinLock(&Thread->ApcQueueLock, OldIrql);
 502         KeReleaseDispatcherDatabaseLock(OldIrql);
 503         return(FALSE);
 504     }
 505
 506     /* Restore IRQL and Return */
 507     KeReleaseSpinLock(&Thread->ApcQueueLock, OldIrql);
 508     KeReleaseDispatcherDatabaseLock(OldIrql);
 509     return(TRUE);
 510 }
 511
 512 /*++
 513  * KiDeliverApc
 514  * @implemented @NT4
 515  *
 516  *     The KiDeliverApc routine is called from IRQL switching code if the
 517  *     thread is returning from an IRQL >= APC_LEVEL and Kernel-Mode APCs are
 518  *     pending.
 519  *
 520  * Params:
 521  *     DeliveryMode - Specifies the current processor mode.
 522  *
 523  *     Reserved - Pointer to the Exception Frame on non-i386 builds.
 524  *
 525  *     TrapFrame - Pointer to the Trap Frame.
 526  *
 527  * Returns:
 528  *     None.
 529  *
 530  * Remarks:
 531  *     First, Special APCs are delivered, followed by Kernel-Mode APCs and
 532  *     User-Mode APCs. Note that the TrapFrame is only valid if the previous
 533  *     mode is User.
 534  *
 535  *     Upon entry, this routine executes at APC_LEVEL.
 536  *
 537  *--*/
 538 VOID
 539 STDCALL
 540 KiDeliverApc(KPROCESSOR_MODE DeliveryMode,
 541              PVOID Reserved,
 542              PKTRAP_FRAME TrapFrame)
 543 {
 544     PKTHREAD Thread = KeGetCurrentThread();
 545     PLIST_ENTRY ApcListEntry;
 546     PKAPC Apc;
 547     KIRQL OldIrql;
 548     PKKERNEL_ROUTINE KernelRoutine;
 549     PVOID NormalContext;
 550     PKNORMAL_ROUTINE NormalRoutine;
 551     PVOID SystemArgument1;
 552     PVOID SystemArgument2;
 553
 554     ASSERT_IRQL_EQUAL(APC_LEVEL);
 555
 556     /* Lock the APC Queue and Raise IRQL to Synch */
 557     KeAcquireSpinLock(&Thread->ApcQueueLock, &OldIrql);
 558
 559     /* Clear APC Pending */
 560     Thread->ApcState.KernelApcPending = FALSE;
 561
 562     /* Do the Kernel APCs first */
 563     while (!IsListEmpty(&Thread->ApcState.ApcListHead[KernelMode])) {
 564
 565         /* Get the next Entry */
 566         ApcListEntry = Thread->ApcState.ApcListHead[KernelMode].Flink;
 567         Apc = CONTAINING_RECORD(ApcListEntry, KAPC, ApcListEntry);
 568
 569         /* Save Parameters so that it's safe to free the Object in Kernel Routine*/
 570         NormalRoutine = Apc->NormalRoutine;
 571         KernelRoutine = Apc->KernelRoutine;
 572         NormalContext = Apc->NormalContext;
 573         SystemArgument1 = Apc->SystemArgument1;
 574         SystemArgument2 = Apc->SystemArgument2;
 575
 576         /* Special APC */
 577        if (NormalRoutine == NULL) {
 578
 579             /* Remove the APC from the list */
 580             RemoveEntryList(ApcListEntry);
 581             Apc->Inserted = FALSE;
 582
 583             /* Go back to APC_LEVEL */
 584             KeReleaseSpinLock(&Thread->ApcQueueLock, OldIrql);
 585
 586             /* Call the Special APC */
 587             DPRINT("Delivering a Special APC: %x\n", Apc);
 588             KernelRoutine(Apc,
 589                           &NormalRoutine,
 590                           &NormalContext,
 591                           &SystemArgument1,
 592                           &SystemArgument2);
 593
 594             /* Raise IRQL and Lock again */
 595             KeAcquireSpinLock(&Thread->ApcQueueLock, &OldIrql);
 596
 597         } else {
 598
 599              /* Normal Kernel APC */
 600             if (Thread->ApcState.KernelApcInProgress || Thread->KernelApcDisable) {
 601
 602                 /*
 603                  * DeliveryMode must be KernelMode in this case, since one may not
 604                  * return to umode while being inside a critical section or while
 605                  * a regular kmode apc is running (the latter should be impossible btw).
 606                  * -Gunnar
 607                  */
 608                 ASSERT(DeliveryMode == KernelMode);
 609
 610                 KeReleaseSpinLock(&Thread->ApcQueueLock, OldIrql);
 611                 return;
 612             }
 613
 614             /* Dequeue the APC */
 615             Apc->Inserted = FALSE;
 616             RemoveEntryList(ApcListEntry);
 617
 618             /* Go back to APC_LEVEL */
 619             KeReleaseSpinLock(&Thread->ApcQueueLock, OldIrql);
 620
 621             /* Call the Kernel APC */
 622             DPRINT("Delivering a Normal APC: %x\n", Apc);
 623             KernelRoutine(Apc,
 624                           &NormalRoutine,
 625                           &NormalContext,
 626                           &SystemArgument1,
 627                           &SystemArgument2);
 628
 629             /* If There still is a Normal Routine, then we need to call this at PASSIVE_LEVEL */
 630             if (NormalRoutine != NULL) {
 631
 632                 /* At Passive Level, this APC can be prempted by a Special APC */
 633                 Thread->ApcState.KernelApcInProgress = TRUE;
 634                 KeLowerIrql(PASSIVE_LEVEL);
 635
 636                 /* Call and Raise IRQ back to APC_LEVEL */
 637                 DPRINT("Calling the Normal Routine for a Normal APC: %x\n", Apc);
 638                 NormalRoutine(NormalContext, SystemArgument1, SystemArgument2);
 639                 KeRaiseIrql(APC_LEVEL, &OldIrql);
 640             }
 641
 642             /* Raise IRQL and Lock again */
 643             KeAcquireSpinLock(&Thread->ApcQueueLock, &OldIrql);
 644             Thread->ApcState.KernelApcInProgress = FALSE;
 645         }
 646     }
 647
 648     /* Now we do the User APCs */
 649     if ((!IsListEmpty(&Thread->ApcState.ApcListHead[UserMode])) &&
 650         (DeliveryMode == UserMode) && (Thread->ApcState.UserApcPending == TRUE)) {
 651
 652         /* It's not pending anymore */
 653         Thread->ApcState.UserApcPending = FALSE;
 654
 655         /* Get the APC Object */
 656         ApcListEntry = Thread->ApcState.ApcListHead[UserMode].Flink;
 657         Apc = CONTAINING_RECORD(ApcListEntry, KAPC, ApcListEntry);
 658
 659         /* Save Parameters so that it's safe to free the Object in Kernel Routine*/
 660         NormalRoutine = Apc->NormalRoutine;
 661         KernelRoutine = Apc->KernelRoutine;
 662         NormalContext = Apc->NormalContext;
 663         SystemArgument1 = Apc->SystemArgument1;
 664         SystemArgument2 = Apc->SystemArgument2;
 665
 666         /* Remove the APC from Queue, restore IRQL and call the APC */
 667         RemoveEntryList(ApcListEntry);
 668         Apc->Inserted = FALSE;
 669         KeReleaseSpinLock(&Thread->ApcQueueLock, OldIrql);
 670
 671         DPRINT("Calling the Kernel Routine for for a User APC: %x\n", Apc);
 672         KernelRoutine(Apc,
 673                       &NormalRoutine,
 674                       &NormalContext,
 675                       &SystemArgument1,
 676                       &SystemArgument2);
 677
 678         if (NormalRoutine == NULL) {
 679
 680             /* Check if more User APCs are Pending */
 681             KeTestAlertThread(UserMode);
 682
 683         } else {
 684
 685             /* Set up the Trap Frame and prepare for Execution in NTDLL.DLL */
 686             DPRINT("Delivering a User APC: %x\n", Apc);
 687             KiInitializeUserApc(Reserved,
 688                                 TrapFrame,
 689                                 NormalRoutine,
 690                                 NormalContext,
 691                                 SystemArgument1,
 692                                 SystemArgument2);
 693         }
 694
 695     } else {
 696
 697         /* Go back to APC_LEVEL */
 698         KeReleaseSpinLock(&Thread->ApcQueueLock, OldIrql);
 699     }
 700 }
 701
 702 VOID
 703 STDCALL
 704 KiFreeApcRoutine(PKAPC Apc,
 705                  PKNORMAL_ROUTINE* NormalRoutine,
 706                  PVOID* NormalContext,
 707                  PVOID* SystemArgument1,
 708                  PVOID* SystemArgument2)
 709 {
 710     /* Free the APC and do nothing else */
 711     ExFreePool(Apc);
 712 }
 713
 714 /*++
 715  * KiInitializeUserApc
 716  *
 717  *     Prepares the Context for a User-Mode APC called through NTDLL.DLL
 718  *
 719  * Params:
 720  *     Reserved - Pointer to the Exception Frame on non-i386 builds.
 721  *
 722  *     TrapFrame - Pointer to the Trap Frame.
 723  *
 724  *     NormalRoutine - Pointer to the NormalRoutine to call.
 725  *
 726  *     NormalContext - Pointer to the context to send to the Normal Routine.
 727  *
 728  *     SystemArgument[1-2] - Pointer to a set of two parameters that contain
 729  *                           untyped data.
 730  *
 731  * Returns:
 732  *     None.
 733  *
 734  * Remarks:
 735  *     None.
 736  *
 737  *--*/
 738 VOID
 739 STDCALL
 740 KiInitializeUserApc(IN PVOID Reserved,
 741                     IN PKTRAP_FRAME TrapFrame,
 742                     IN PKNORMAL_ROUTINE NormalRoutine,
 743                     IN PVOID NormalContext,
 744                     IN PVOID SystemArgument1,
 745                     IN PVOID SystemArgument2)
 746 {
 747     PCONTEXT Context;
 748     PULONG Esp;
 749
 750     DPRINT("KiInitializeUserApc(TrapFrame %x/%x)\n", TrapFrame, KeGetCurrentThread()->TrapFrame);
 751
 752     /*
 753      * Save the thread's current context (in other words the registers
 754      * that will be restored when it returns to user mode) so the
 755      * APC dispatcher can restore them later
 756      */
 757     Context = (PCONTEXT)(((PUCHAR)TrapFrame->Esp) - sizeof(CONTEXT));
 758     RtlZeroMemory(Context, sizeof(CONTEXT));
 759     Context->ContextFlags = CONTEXT_FULL;
 760     Context->SegGs = TrapFrame->Gs;
 761     Context->SegFs = TrapFrame->Fs;
 762     Context->SegEs = TrapFrame->Es;
 763     Context->SegDs = TrapFrame->Ds;
 764     Context->Edi = TrapFrame->Edi;
 765     Context->Esi = TrapFrame->Esi;
 766     Context->Ebx = TrapFrame->Ebx;
 767     Context->Edx = TrapFrame->Edx;
 768     Context->Ecx = TrapFrame->Ecx;
 769     Context->Eax = TrapFrame->Eax;
 770     Context->Ebp = TrapFrame->Ebp;
 771     Context->Eip = TrapFrame->Eip;
 772     Context->SegCs = TrapFrame->Cs;
 773     Context->EFlags = TrapFrame->Eflags;
 774     Context->Esp = TrapFrame->Esp;
 775     Context->SegSs = TrapFrame->Ss;
 776
 777     /*
 778      * Setup the trap frame so the thread will start executing at the
 779      * APC Dispatcher when it returns to user-mode
 780      */
 781     Esp = (PULONG)(((PUCHAR)TrapFrame->Esp) - (sizeof(CONTEXT) + (6 * sizeof(ULONG))));
 782     Esp[0] = 0xdeadbeef;
 783     Esp[1] = (ULONG)NormalRoutine;
 784     Esp[2] = (ULONG)NormalContext;
 785     Esp[3] = (ULONG)SystemArgument1;
 786     Esp[4] = (ULONG)SystemArgument2;
 787     Esp[5] = (ULONG)Context;
 788     TrapFrame->Eip = (ULONG)LdrpGetSystemDllApcDispatcher();
 789     DPRINT("TrapFrame->Eip: %x\n", TrapFrame->Eip);
 790     TrapFrame->Esp = (ULONG)Esp;
 791 }
 792
 793 /*++
 794  * KeAreApcsDisabled
 795  * @implemented NT4
 796  *
 797  *     Prepares the Context for a User-Mode APC called through NTDLL.DLL
 798  *
 799  * Params:
 800  *     None.
 801  *
 802  * Returns:
 803  *     KeAreApcsDisabled returns TRUE if the thread is within a critical region
 804  *     or a guarded region, and FALSE otherwise.
 805  *
 806  * Remarks:
 807  *     A thread running at IRQL = PASSIVE_LEVEL can use KeAreApcsDisabled to
 808  *     determine if normal kernel APCs are disabled. A thread that is inside a
 809  *     critical region has both user APCs and normal kernel APCs disabled, but
 810  *     not special kernel APCs. A thread that is inside a guarded region has
 811  *     all APCs disabled, including special kernel APCs.
 812  *
 813  *     Callers of this routine must be running at IRQL <= APC_LEVEL.
 814  *
 815  *--*/
 816 BOOLEAN
 817 STDCALL
 818 KeAreApcsDisabled(VOID)
 819 {
 820     /* Return the Kernel APC State */
 821     return KeGetCurrentThread()->KernelApcDisable ? TRUE : FALSE;
 822 }
 823
 824 /*++
 825  * NtQueueApcThread
 826  * NT4
 827  *
 828  *    This routine is used to queue an APC from user-mode for the specified
 829  *    thread.
 830  *
 831  * Params:
 832  *     Thread Handle - Handle to the Thread. This handle must have THREAD_SET_CONTEXT privileges.
 833  *
 834  *     ApcRoutine - Pointer to the APC Routine to call when the APC executes.
 835  *
 836  *     NormalContext - Pointer to the context to send to the Normal Routine.
 837  *
 838  *     SystemArgument[1-2] - Pointer to a set of two parameters that contain
 839  *                           untyped data.
 840  *
 841  * Returns:
 842  *     STATUS_SUCCESS or failure cute from associated calls.
 843  *
 844  * Remarks:
 845  *      The thread must enter an alertable wait before the APC will be
 846  *      delivered.
 847  *
 848  *--*/
 849 NTSTATUS
 850 STDCALL
 851 NtQueueApcThread(HANDLE ThreadHandle,
 852          PKNORMAL_ROUTINE ApcRoutine,
 853          PVOID NormalContext,
 854          PVOID SystemArgument1,
 855          PVOID SystemArgument2)
 856 {
 857     PKAPC Apc;
 858     PETHREAD Thread;
 859     KPROCESSOR_MODE PreviousMode = ExGetPreviousMode();
 860     NTSTATUS Status;
 861
 862     /* Get ETHREAD from Handle */
 863     Status = ObReferenceObjectByHandle(ThreadHandle,
 864                        THREAD_SET_CONTEXT,
 865                        PsThreadType,
 866                        PreviousMode,
 867                        (PVOID)&Thread,
 868                        NULL);
 869
 870     /* Fail if the Handle is invalid for some reason */
 871     if (!NT_SUCCESS(Status)) {
 872
 873         return(Status);
 874     }
 875
 876     /* If this is a Kernel or System Thread, then fail */
 877     if (Thread->Tcb.Teb == NULL) {
 878
 879         ObDereferenceObject(Thread);
 880         return STATUS_INVALID_HANDLE;
 881     }
 882
 883     /* Allocate an APC */
 884     Apc = ExAllocatePoolWithTag(NonPagedPool, sizeof(KAPC), TAG('P', 's', 'a', 'p'));
 885     if (Apc == NULL) {
 886
 887         ObDereferenceObject(Thread);
 888         return(STATUS_NO_MEMORY);
 889     }
 890
 891     /* Initialize and Queue a user mode apc (always!) */
 892     KeInitializeApc(Apc,
 893                     &Thread->Tcb,
 894                     OriginalApcEnvironment,
 895                     KiFreeApcRoutine,
 896                     NULL,
 897                     ApcRoutine,
 898                     UserMode,
 899                     NormalContext);
 900
 901     if (!KeInsertQueueApc(Apc, SystemArgument1, SystemArgument2, IO_NO_INCREMENT)) {
 902
 903         Status = STATUS_UNSUCCESSFUL;
 904
 905     } else {
 906
 907         Status = STATUS_SUCCESS;
 908     }
 909
 910     /* Dereference Thread and Return */
 911     ObDereferenceObject(Thread);
 912     return Status;
 913 }
 914
 915 static inline
 916 VOID RepairList(PLIST_ENTRY Original,
 917                 PLIST_ENTRY Copy,
 918                 KPROCESSOR_MODE Mode)
 919 {
 920     /* Copy Source to Desination */
 921     if (IsListEmpty(&Original[(int)Mode])) {
 922
 923         InitializeListHead(&Copy[(int)Mode]);
 924
 925     } else {
 926
 927         Copy[(int)Mode].Flink = Original[(int)Mode].Flink;
 928         Copy[(int)Mode].Blink = Original[(int)Mode].Blink;
 929         Original[(int)Mode].Flink->Blink = &Copy[(int)Mode];
 930         Original[(int)Mode].Blink->Flink = &Copy[(int)Mode];
 931     }
 932 }
 933
 934 VOID
 935 STDCALL
 936 KiMoveApcState(PKAPC_STATE OldState,
 937                PKAPC_STATE NewState)
 938 {
 939     /* Restore backup of Original Environment */
 940     *NewState = *OldState;
 941
 942     /* Repair Lists */
 943     RepairList(NewState->ApcListHead, OldState->ApcListHead, KernelMode);
 944     RepairList(NewState->ApcListHead, OldState->ApcListHead, UserMode);
 945 }
 946