/kernel (Create Kernel Mode Binary)

  • Article

 

The latest version of this topic can be found at -kernel (Create Kernel Mode Binary).

Creates a binary that can be executed in the Windows kernel.

Syntax

/kernel[-]

Arguments

/kernel
The code in the current project is compiled and linked by using a set of C++ language rules that are specific to code that will run in kernel mode.

/kernel-
The code in the current project is compiled and linked without using the C++ language rules that are specific to code that will run in kernel mode.

Remarks

There is no #pragma equivalent to control this option.

Specifying the /kernel option tells the compiler and linker to arbitrate which language features are permissible in kernel mode and to make sure that that you have sufficient expressive power to avoid runtime instability that is unique to kernel mode C++. This is accomplished by prohibiting the use of C++ language features that are disruptive in kernel mode and by providing warnings for C++ language features that are potentially disruptive but cannot be disabled.

The /kernel option applies to both the compiler and linker phases of a build and is set at the project level. Pass the /kernel switch to indicate to the compiler that the resulting binary, after linking, should be loaded into the Windows kernel. The compiler will narrow the spectrum of C++ language features to a subset that is compatible with the kernel.

The following table lists changes in compiler behavior when /kernel is specified.

Behavior Type /kernel Behavior
C++ Exception Handling Disabled. All instances of the throw and try keywords emit a compiler error (except for the exception specification throw()). No /EH options are compatible with /kernel, except for /EH-.
RTTI Disabled. All instances of the dynamic_cast and typeid keywords emit a compiler error, unless dynamic_cast is used statically.
new and delete You must explicitly define the new() or delete() operator; neither the compiler nor the runtime will supply a default definition.

Custom calling conventions, the /GS build option, and all optimizations are permitted when you use the /kernel option. Inlining is largely not affected by /kernel, with the same semantics honored by the compiler. If you want to make sure that the __forceinline inlining qualifier is honored, you must make sure that warning C4714 is enabled so that you know when a particular __forceinline function is not inlined.

When the compiler is passed the /kernel switch, it predefines a preprocessor macro that's named _KERNEL_MODE and has the value 1. You can use this to conditionally compile code based on whether the execution environment is in user mode or kernel mode. For example, the following code specifies that the class should be in a non-pageable memory segment when it is compiled for kernel mode execution.

  
      #ifdef _KERNEL_MODE  
#define NONPAGESECTION __declspec(code_seg("$kerneltext$"))  
#else  
#define NONPAGESECTION  
#endif  
  
class NONPAGESECTION MyNonPagedClass  
{  
  
};

Some the following combinations of target architecture and the /arch option produce an error when they are used with /kernel:

  • /arch:{SSE|SSE2|AVX} are not supported on x86. Only /arch:IA32 is supported with /kernel on x86.

  • /arch:AVX is not supported with /kernel on x64.

Building with /kernel also passes /kernel to the linker. Her's how this affects linker behavior:

  • Incremental linking is disabled. If you add /incremental to the command line, the linker emits this fatal error:

    LINK : fatal error LNK1295: '/INCREMENTAL' not compatible with '/KERNEL' specification; link without '/INCREMENTAL'

  • The linker inspects each object file (or any included archive member from static libraries) to see whether it could have been compiled by using the /kernel option but was not. If any instances meet this criterion, the linker still successfully links but might issue a warning, as shown in the following table.

    /kernel obj /kernel- obj, MASM obj, or cvtresed Mix of /kernel and /kernel- objs
    link /kernel Yes Yes Yes with warning LNK4257
    link Yes Yes Yes

    LNK4257 linking object not compiled with /KERNEL ; image may not run

The /kernel option and the /driver option operate independently and neither affects the other.

To set the /kernel compiler option in Visual Studio

  1. Open the Property Pages dialog box for the project. For more information, see How to: Open Project Property Pages.

  2. Select the C/C++ folder.

  3. Select the Command Line property page.

  4. In the Additional options box, add /kernel or /kernel-.

See Also

Compiler Options
Setting Compiler Options