Crate win_lookaside

source ·
Expand description

This crate provides an experimental Rust allocator for the Windows Kernel based on Lookaside Lists.

Given the nature of Lookaside Lists (fixed-size buffers) this Allocator is not meant to be used as the Global Allocator for this reason this crate does not implement the GlobalAlloc trait, on the other hand it does implement the Allocator trait (no grow nor shrink) so it can be used as the allocator in xxx_in methods.

The default implementation of grow/grow_zeroed & shrink of the Allocator API has been overridden to throw a panic. This is done just to make the user aware that calling these methods on this allocator is a misuse of the Lookaside API.

Obviously, this crate requires the allocator_apifeature is enabled (hence this being an experimental/unstable crate).

Alternatively, this can be used directly by initializing the allocator and using allocate & deallocate methods to get an entry from the list as a *mut u8 and return an entry to the list respectively.

Since this is meant to be used in the kernel, this Allocator can return NULL and doesn’t trigger the alloc_error_handler if an OOM condition happens. This requires using fallible APIs such as Box::try_new_in or crates such as fallible_vec.

Usage

If working on a Driver fully written in Rust, the following example shows how we can make use of the Allocator.

All in one function just for the sake of the example, usually we would store the Lookaside Allocator in some structure or global variable initialized in the DriverEntry and destroy it in the DriverUnload.

#![no_std]
#![feature(allocator_api)]
#[macro_use] extern crate win_lookaside;

extern crate alloc;

use alloc::boxed::Box;
use win_lookaside::LookasideAlloc;
use windows_sys::Wdk::Foundation::NonPagedPool;

fn example() {
    // Init Lookaside List allocator with default values//!
    let mut allocator = LookasideAlloc::default();

    // Init Lookaside List with fixed-size to hold a u32
    // Properly handle possible InitError;
    allocator.init(core::mem::size_of::<u32>(), NonPagedPool as i32, None, None, None).unwrap();

    // Allocate from Lookaside & Free to it on Drop
    {
        let Ok(ctx) = Box::try_new_in(10, &allocator) else {
            return; // AllocError
        };
    }

    // Destroy Lookaside List Allocator
    allocator.destroy();
}

Another option is if we are working with a Driver written in C++ and we want to work on a extensions/component in Rust. We can write a thin FFI layer on top of this crate to expose the functionality to the Driver.

A very simple implementation of how this FFI layer could look like is the following:

#![no_std]
#![feature(allocator_api)]
#[macro_use] extern crate win_lookaside;

extern crate alloc;

use alloc::boxed::Box;
use windows_sys::Wdk::Foundation::PagedPool;
use windows_sys::Win32::Foundation::{NTSTATUS, STATUS_INSUFFICIENT_RESOURCES, STATUS_SUCCESS};
use win_lookaside::LookasideAlloc;

// Interior mutability due to the way the Lookaside API works
static mut LOOKASIDE: LookasideAlloc = LookasideAlloc::default();

struct Context{};

#[no_mangle]
pub unsafe extern "C" fn init_lookaside(tag: u32) -> NTSTATUS {
    LOOKASIDE.init(core::mem::size_of::<Context>(), PagedPool, Some(tag), None, None )?;
    STATUS_SUCCESS
}

#[no_mangle]
pub extern "C" fn create_context(context: *mut *mut Context) -> FfiResult<()> {
    let Ok(ctx) = unsafe { Box::try_new_in(Context {}, &LOOKASIDE) } else {
        return STATUS_INSUFFICIENT_RESOURCES;
    };

    unsafe {
        *context = Box::into_raw(ctx);
    }

    STATUS_SUCCESS
}

#[no_mangle]
pub extern "C" fn remove_context(context: *mut Context) {
    let _ctx = unsafe { Box::from_raw_in(context, &LOOKASIDE) };
}

#[no_mangle]
pub unsafe extern "C" fn free_lookaside() {
    LOOKASIDE.destroy();
}

Here the Context is just an empty struct, but it could be something more complex that could offer more functionality and the C++ driver would just need to store those as an opaque pointer.

Remarks

This crate has been developed under the 22H2 WDK meaning certain Lookaside API methods are exported instead of inlined. The crate is yet to be tested in an older WDK, behavior when trying to build might be different.

At the moment the crate uses spin as the synchronization mechanism. Even thou this does the job, ideally at some point it should use synchronization primitives native to the OS.

Structs

Enums

  • LookasideError
    Possible Errors returned by the Lookaside List Allocator

Constants

  • DEFAULT_POOL_TAG
    Default PoolTag used by the Lookaside Allocator if none passed when initializing it

Functions

Type Definitions

  • AllocateFunctionEx
    The LookasideListAllocateEx routine allocates the storage for a new lookaside-list entry when a client requests an entry from a lookaside list that is empty.
  • FreeFunctionEx
    The LookasideListFreeEx routine frees the storage for a lookaside-list entry when a client tries to insert the entry into a lookaside list that is full.
  • LookasideResult
    Lookaside List Allocator Result