NTSTATUS WaitForKeyBeingPressed( IN BYTE bKeyScanCode, IN ULONG ulElapseInHundredthsOfSec )
{
      LARGE_INTEGER                 liWaitElapse;
      ULONG                         i;
      BYTE                          bKeybPortByte;
 
      // Wait and Read the Keyboard Port.
 
      liWaitElapse = RtlConvertLongToLargeInteger( - 100000 ); // Ten Milliseconds.
 
      for ( i=0; i<ulElapseInHundredthsOfSec; i++ )
      {
            // Read from the Keyboard Port.
 
            __asm
            {
                  in          al, 0x64
                  test      al, 1
                  mov         al, 0
                  jz          _SkipKeybInputPortRead
 
                  in          al, 0x60
 
_SkipKeybInputPortRead:
 
                  mov         bKeybPortByte, al
            }
 
            // Check if we have to Exit.
 
            if ( bKeybPortByte == bKeyScanCode )
                  return STATUS_SUCCESS;
 
            // Wait.
 
            KeDelayExecutionThread( UserMode, FALSE, & liWaitElapse );
      }
 
      // Return to the Caller.
 
      return STATUS_UNSUCCESSFUL;
}

Here we poll the keyboard i/o port comparing the read byte with the passed key scancode. This is a simplistic approach to this problem but it is the one that has less hassles and is more appropriate in this case: we need a safe way to read from the keyboard, we need a method that will not create any problem on the user computers. In BugChecker, for example, the keyboard is read in a far more complex dedicated Interrupt Service Routine, avoiding the problem of the polling.

The "OutputTextString" writes in the text video memory exactly as we were used to do in the old times of DOS. A more interesting function is the one that allows us to get a virtual memory pointer to the text video memory:

NTSTATUS InitializeTextVideoBufferPtr( VOID )
{
      PDEVICE_EXTENSION       extension = g_pDeviceObject->DeviceExtension;
      PVOID                         pvTextVideoBuffer;
      ULONG                         ulOutBufferSize;
 
      // Initialize the Pointer.
 
      if ( extension->pvTextVideoBuffer == NULL )
      {
#ifdef USE_PAGETABLE_TO_OBTAIN_TEXTMODE_VIDEOADDRESS
            if ( PhysAddressToLinearAddresses( & pvTextVideoBuffer, 1, & ulOutBufferSize, 0xB8000 ) == STATUS_SUCCESS &&
                  ulOutBufferSize == 1 )
            {
                  extension->pvTextVideoBuffer = pvTextVideoBuffer;
 
                  return STATUS_SUCCESS;
            }
            else
            {
                  return STATUS_UNSUCCESSFUL;
            }
#else
            PHYSICAL_ADDRESS        paPhysAddr;
            paPhysAddr.QuadPart = 0xB8000;
            extension->pvTextVideoBuffer = MmMapIoSpace( paPhysAddr, 1, MmNonCached );
#endif
      }
 
      // Return to the Caller.
 
      return STATUS_SUCCESS;
}

In this snippet, two different approaches are presented: the first one uses the "PhysAddressToLinearAddress" function for searching in the page directory and in the page tables for an already mapped reference to the 0xB8000 physical address. The second approach, that is more "correct" in many ways, uses the NT "MmMapIoSpace" function for doing the same job: this function does not search in the page tables for the specified address (thus not relying on its presence and mapping for returning a valid, non-null pointer) but forces the system to map this address and to return the corresponding virtual pointer.

It is important to note that for using this code for displaying messages to the user in text video mode, it is necessary that the "/NOGUIBOOT" option was specified in the boot.ini file for the currently running system installation. On the contrary the system will boot up with the graphical splash screen and perhaps our message will end up on the screen as a little mess of pixels in the upper portion of the screen...

So, if the user doesn't stroke the hotkey, the "PsSetLoadImageNotifyRoutine" is called and the hook mechanism is activated. Now, at each system-wide image mapping operation our "VPCIceVideoImageCallback" is called. Here we do nothing special: we check whether the name of the display driver was already read from the registry (it is read only once and then the name is cached for future reference), check whether the image being mapped is our display driver and then it will check whether the "EnforceWriteProtection" setting is set to 0 in the registry thus allowing the writing in the read-only code sections of kernel images (this is required for setting our detour code; without it the system - at the write attempt - will immediately bugcheck).

Following the logic of the display driver initialization, the next step is to intercept the call that the system is going to make to the entry point of the driver module itself (remember that the module entry point refers actually to the display driver "DrvEnableDriver" function). We need to know the virtual address (in the just mapped module) of its entry point, calling this simple function:

PVOID GePeImageEntryPoint( PVOID pvPeImageStart )
{
      IMAGE_DOS_HEADER*             pidhImageDosHeader;
      IMAGE_NT_HEADERS*             pinhPeNtHdrs;
 
      __try
      {
            // Do the Requested Operation.
 
            pidhImageDosHeader = (IMAGE_DOS_HEADER*) pvPeImageStart;
 
            if ( pidhImageDosHeader->e_magic != IMAGE_DOS_SIGNATURE )
                  return NULL;
            if ( pidhImageDosHeader->e_lfarlc < 0x40 )
                  return NULL;
 
            pinhPeNtHdrs = (IMAGE_NT_HEADERS*) ( (BYTE*) pvPeImageStart + pidhImageDosHeader->e_lfanew );
 
            if ( pinhPeNtHdrs->Signature != IMAGE_NT_SIGNATURE )
                  return NULL;
 
            // Return the Information to the Caller.
 
            return (PVOID) ( (BYTE*) pvPeImageStart + pinhPeNtHdrs->OptionalHeader.AddressOfEntryPoint );
      }
      __except ( EXCEPTION_EXECUTE_HANDLER )
      {
            return NULL;
      }
}

As you can guess, we will allow the system to call the "DrvEnableDriver" function, as expected, but, using the detours hooking library from Microsoft Research, we will insert ourselves in the execution flow just after the "DrvEnableDriver" function's exit and just before the control is returned to GDI. This can be done successfully because the image callback mechanism that is provided by the NT image loader and exposed to the programmer through the "PsSetLoadImageNotifyRoutine" API takes place in a moment during the module load sequence where the DLL entry point function is not called yet.

The MS Research Detours Library (http://research.microsoft.com/sn/detours/) is a C++ library that allows to "detour" the normal execution of system or user functions to programmer-defined hook code. Later, at the programmer's whim, the execution can be resumed to the original function: this can be accomplished at any point in the execution of the hook procedure. In our case, we are interested in intercepting the function call to the aforementioned "DrvEnableDriver", calling the original display driver implementation as the first step in our hook function and then replacing the function pointer to the "DrvGetDirectDrawInfo" procedure in the display driver returned "pdrvfn" pointer array. The job of the Detours library (in our case) is pretty simple (I have used it in this project and proposed it here in this example for cutting my own development time and effort with BugChecker in this preliminary stage of the project and to simplify the code of this example: for inexplicable problems of its licensing conditions, the Detours library cannot be used in commercial applications - I plan to replace it with ease in this code with my own similar solution in the immediate future). Basically what Detours does is to disassemble the entry point of the given function, recursively disassembling instructions until it gets the finite number of bytes that need to be removed in order to make room for the detour itself, that actually is a IA-32 FAR JMP instruction, that specifically takes 5 bytes of memory. The overwritten code memory that will be taken by the JMP instruction is simply MEMCPYed in a structure named "trampoline". Just next to this code, the Detours library inserts in the trampoline an other JMP instruction that will point to the original detoured function memory plus the size of the first JMP instruction plus the size of an offset, thus allowing the resuming of the execution to the original implementation. This has to be done through a disassembler because the Detours implementation cannot take the risk to move in the trampoline a number of bytes that refer to incomplete IA-32 instructions, that actually can be a very destructive thing if the processor control happens to go to crippled code like this. So, I have removed from the original Detours library several references to Win32 functions, I have introduced some syntax changes to the macros and converted the various C++ source files to a handy single C file that can be used in kernel code (you can get this file downloading the zip archive of this example at the bottom of this page).

So at file scope you define the trampoline (note that the "DETOUR_TRAMPOLINE_GLOBVAR" is a my personal customization to the standard macro provided by the Detours library):

static PVOID            g_pfnDrvEnableDriver = NULL;
DETOUR_TRAMPOLINE_GLOBVAR( BOOL APIENTRY Trampoline_DrvEnableDriver( ULONG iEngineVersion, ULONG cj, DRVENABLEDATA *pded ), g_pfnDrvEnableDriver ) 

and then you can hook the function:

NTSTATUS HookDisplayDriverEntryPoint( PVOID pvDrvEnableDriverFnPtr )
{
      NTSTATUS          nsRetVal = STATUS_UNSUCCESSFUL;
      BOOLEAN                 bHookRes;
 
      // Do the Requested Operation.
 
      __try
      {
            g_pfnDrvEnableDriver = pvDrvEnableDriverFnPtr;
            bHookRes = DetourFunctionWithTrampoline( (PBYTE) Trampoline_DrvEnableDriver, (PBYTE) Hooked_DrvEnableDriver, NULL );
 
            if ( bHookRes )
                  nsRetVal = STATUS_SUCCESS;
            else
                  nsRetVal = STATUS_UNSUCCESSFUL;
      }
      __except ( EXCEPTION_EXECUTE_HANDLER )
      {
            nsRetVal = STATUS_UNSUCCESSFUL;
      }
 
      // Return to the Caller.
 
      return nsRetVal;
}

Note that the __try/__except clause is required because I have removed from the original Detours code the calls to the Win32 APIs that in user mode contexts can be made to check whether the specified input addresses are valid for reading or writing. Now the execution will be detoured from the original "DrvEnableDriver" function to our hook function:

BOOL APIENTRY Hooked_DrvEnableDriver(
    ULONG          iEngineVersion,
    ULONG          cj,
    DRVENABLEDATA *pded )
{
      // Call the Original Function.
 
      bOriginalFnRetVal = Trampoline_DrvEnableDriver( iEngineVersion, cj, pded );
 
      // ### ### ### HERE it can do whatever it wants with the filled pded->pdrvfn pointers array... ### ### ###
}

Now in the remaining part of the function, we will iterate in the returned "pded->pdrvfn" pointers array searching for the reference to the display driver DrvGetDirectDrawInfo function (each returned function pointer is identified by an ordinal: in this case the identifier of the function we are searching for is INDEX_DrvGetDirectDrawInfo). When that reference is found, we simply replace its function pointer in the pdrvfn array with a pointer to our hook function of DrvGetDirectDrawInfo, holding the old pointer so we are able to call the original implementation when finished with our grabbing and client notification job of the VIDEOMEMORYINFO data structure.

SAMPLE APPLICATION

Along with the source code of the BugCheckerVideo example, I have included also a MFC application that must be used in order to install the device driver the first time. From this point on the driver will be loaded at OS boot-up time. You can use this same application for testing the driver features, sending an IOCTL to the driver requesting the current VIDEOMEMORYINFO structure.


This is the text that the application will show when the "ioctl" button is clicked:

fpPrimary = 0x0
dwFlags = 0x0
dwDisplayWidth = 0x400
dwDisplayHeight = 0x300
lDisplayPitch = 0x1000
ddpfDisplay.dwSize = 0x20
ddpfDisplay.dwFlags = 0x40
ddpfDisplay.dwFourCC = 0x0
ddpfDisplay.dwRGBBitCount = 0x20
ddpfDisplay.dwRBitMask = 0xFF0000
ddpfDisplay.dwGBitMask = 0xFF00
ddpfDisplay.dwBBitMask = 0xFF
ddpfDisplay.dwRGBAlphaBitMask = 0x0
dwOffscreenAlign = 0x40
dwOverlayAlign = 0x40
dwTextureAlign = 0x40
dwZBufferAlign = 0x40
dwAlphaAlign = 0x40
pvPrimary = 0xBCA3B000

DOWNLOAD

You can download the binaries and the source code from here (133KB).