# tbKMode Package
{: .no_toc }

**Author:** fafalone. **Version:** 0.3.0.5. **On GitHub:** [fafalone/tbKMode](https://github.com/fafalone/tbKMode).

Declarations for writing a Windows kernel-mode driver in twinBASIC.

The **tbKMode** contributed package declares types, routines, constants and macros of the Windows Driver Kit (WDK), from its headers `wdm.h`, `ntddk.h`, `ntifs.h`, `fltkernel.h`, `ntdddisk.h`, `mountmgr.h` and `ntimage.h`, for a driver built as a `.sys` file. It covers a part of the WDK: its author describes it as a start, to be extended by each project that uses it.

> [!WARNING] 0.3.0.5
> The package compiles, and a driver can be built with it, but many of the declarations of [modWDM](/tB/Packages/Contributed/tbKMode/modWDM.md) do not match the WDK, and most of them fail with no error: the driver reads or writes other memory than it means to, or a call never returns. The main ones:
>
> - Declarations of routines whose parameters or result do not match the routine: see [modWDM](/tB/Packages/Contributed/tbKMode/modWDM.md#declares).
> - Structures with another layout than the C structure, so that a field holds other data: see [modWDM](/tB/Packages/Contributed/tbKMode/modWDM.md#types).
> - Values that are not the WDK's: [**POOL_TYPE**](/tB/Packages/Contributed/tbKMode/modWDM.md#POOL_TYPE) and the mount device types of [modWDM](/tB/Packages/Contributed/tbKMode/modWDM.md#constants) with the two I/O control codes made from them.
> - In a 32-bit driver, routines declared in another calling convention than the kernel's, most of them routines that the kernel exports as `__fastcall`, receive other values than their arguments: see [modWDM](/tB/Packages/Contributed/tbKMode/modWDM.md#declares).
> - Procedures of modWDM that write over memory or never return: the list procedures, such as [**InsertHeadList**](/tB/Packages/Contributed/tbKMode/modWDM.md#InsertHeadList), the stack-location procedures, such as [**IoSetCompletionRoutine**](/tB/Packages/Contributed/tbKMode/modWDM.md#IoSetCompletionRoutine), and in a 64-bit driver [**InterlockedIncrement**](/tB/Packages/Contributed/tbKMode/modWDM.md#InterlockedIncrement) and [**InterlockedAdd64**](/tB/Packages/Contributed/tbKMode/modWDM.md#InterlockedAdd64). [**NT_ERROR**](/tB/Packages/Contributed/tbKMode/modWDM.md#NT_ERROR), [**InStr**](/tB/Packages/Contributed/tbKMode/modWDM.md#InStr), [**MsgBox**](/tB/Packages/Contributed/tbKMode/modWDM.md#MsgBox) and [**ExInitializeFastMutex**](/tB/Packages/Contributed/tbKMode/modWDM.md#ExInitializeFastMutex) give wrong results.
>
> Each page states the defects of its own declarations, in a warning or a note below its table or in the section of the procedure.

* TOC
{:toc}

## Building a driver

A driver is a project whose [Build Type](/tB/IDE/Project-Settings.md#build-type) is **Standard EXE**, with these [project settings](/tB/IDE/Project-Settings.md):

- [**Native Subsystem**](/tB/IDE/Project-Settings.md#native-subsystem): **Yes**, which marks the built file as a native-subsystem image, as a driver is.
- [**Override Entry Point**](/tB/IDE/Project-Settings.md#override-entry-point): `DriverEntry`, the name of the driver's entry point. It is a **Public Function** of a module that receives the driver's **DRIVER_OBJECT** and the path of its registry key, as in the [example of modWDM](/tB/Packages/Contributed/tbKMode/modWDM.md#example).
- [**Runtime Binding Of DLL Declares**](/tB/IDE/Project-Settings.md#runtime-binding-of-dll-declares): **No**, which puts the routines that the driver calls into the import table of the built file, for the kernel to resolve when it loads the driver. Only the routines that the driver calls are imported.
- [**Strip PE File Relocation Symbols**](/tB/IDE/Project-Settings.md#strip-pe-symbols): **NO**, which keeps the relocation data in the built file. Its default, **AUTO**, leaves it out of an EXE. With the relocations kept, [**Enable Address Space Layout Randomization (ASLR)**](/tB/IDE/Project-Settings.md#enable-aslr), **Yes** by default, also marks the file as one that can be loaded at any address.

> [!WARNING] 0.3.0.5
> The package's own procedures are compiled with the package's settings, not the driver's, and the package sets none of the settings above. A driver that calls one of them imports routines from `USER32.dll`, `OLEAUT32.dll` and `KERNEL32.dll`, which the kernel does not load for a driver, so the driver does not load. Among them are [**IoGetNextIrpStackLocation**](/tB/Packages/Contributed/tbKMode/modWDM.md#IoGetNextIrpStackLocation) and [**IoSkipCurrentIrpStackLocation**](/tB/Packages/Contributed/tbKMode/modWDM.md#IoSkipCurrentIrpStackLocation), and in a 64-bit driver [**InterlockedIncrement**](/tB/Packages/Contributed/tbKMode/modWDM.md#InterlockedIncrement), which is a declaration of a kernel routine in a 32-bit one. A driver that uses only the package's declarations of kernel routines, its types and its constants is not affected. A procedure copied into the driver's own code, under another name, is compiled with the driver's settings.

The [Build Output Path](/tB/IDE/Project-Settings.md#build-output-path) ends in `.sys` in place of `.${FileExtension}`. A driver is built for the architecture of the Windows it runs on: the kernel runs no 32-bit code on 64-bit Windows. [Project Types](/Features/Project-Configuration/Project-Types.md#kernel-mode-drivers) says more about kernel-mode projects.

## Names shared with VBA

**modWDM** has procedures named [**LCase**](/tB/Packages/Contributed/tbKMode/modWDM.md#LCase), [**UCase**](/tB/Packages/Contributed/tbKMode/modWDM.md#UCase), [**InStr**](/tB/Packages/Contributed/tbKMode/modWDM.md#InStr) and [**MsgBox**](/tB/Packages/Contributed/tbKMode/modWDM.md#MsgBox), as VBA's functions are. They take the addresses of null-terminated strings, since a driver works on the kernel's strings, and the package's changelog calls them overrides of VBA's.

> [!WARNING] 0.3.0.5
> A call of one of these names without a module name calls VBA's function, not the package's. `LCase(StrPtr(s))` and `UCase(StrPtr(s))` leave the string as it was, `InStr(StrPtr(a), StrPtr(b))` returns 0 when *a* holds *b*, and `MsgBox "text"` compiles as VBA's **MsgBox**. A driver writes the module name to call the package's procedures: `modWDM.LCase`, `modWDM.UCase`, `modWDM.InStr` and `modWDM.MsgBox`.

## Modules

- [**modWDM**](/tB/Packages/Contributed/tbKMode/modWDM.md) -- the Windows Driver Model: driver and device objects, IRPs, memory, synchronization, the registry, processes and threads, strings and callbacks; the types the other modules share
- [**modFltMgr**](/tB/Packages/Contributed/tbKMode/modFltMgr.md) -- the Filter Manager, for a file-system minifilter driver
- [**modSysInfo**](/tB/Packages/Contributed/tbKMode/modSysInfo.md) -- the information classes and structures of the `Zw` query and set routines
- [**modDisk**](/tB/Packages/Contributed/tbKMode/modDisk.md) -- disk geometry, partitions and the structures of a driver that presents a disk
- [**modImage**](/tB/Packages/Contributed/tbKMode/modImage.md) -- the headers, sections and tables of an executable image in the PE format
- [**modKmOpaque**](/tB/Packages/Contributed/tbKMode/modKmOpaque.md) -- offsets of fields in opaque kernel structures

## See Also

- [tbKMode Verifier](/tB/Packages/Contributed/tbKMode/Verifier.md) -- checks the package's declarations, and a built driver's imports, against the Windows kernel
- [tbKMode Writer](/tB/Packages/Contributed/tbKMode/Writer.md) -- writes the module pages of this section
- [Project Settings](/tB/IDE/Project-Settings.md) -- the settings of a driver project
- [Project Types](/Features/Project-Configuration/Project-Types.md#kernel-mode-drivers) -- kernel-mode drivers in twinBASIC
- [Experimental Packages](/tB/Packages/Experimental/index.md) -- the packages from TWINSERV that are not yet ready for use in a program

## Test cases

The notes and warnings of this section are checked by the test cases in [tbKMode-tests.twinproj](tbKMode-tests.twinproj), a twinBASIC project. It uses tbKMode as a [linked package](/Features/Packages/Linked.md#manual-management): put the package's `.twinpack` in `%APPDATA%\twinBASIC\packages`, then run the project, and each case prints whether it passes. The [tbKMode Verifier](/tB/Packages/Contributed/tbKMode/Verifier.md), a Node.js program, checks the package's Declares against what the Windows kernel exports, and a built driver's imports.
