Data Structures
A technical reference for the key C structs used in USM policy development, including usm_event, page, and to_swap.
Understanding the data structures passed between the USM framework and your policy is critical for correct implementation. This page details the most important structs.
struct usm_event
This is the primary communication struct, passed to nearly all policy functions. It carries information about the memory event that occurred. Defined in APIv/include/com/event.h.
| Field | Type | Description |
|---|---|---|
type | enum evt_type | The type of event. Can be ALLOC, FREE, NEW_PROC, etc. |
vaddr | unsigned long | The virtual address that triggered the event, typically a page fault. |
paddr | unsigned long | The physical address (PFN). For usm_alloc, this is an output field you must set. For usm_pindex_free, this is an input field. |
length | unsigned long | For batch operations. In an allocation event, it indicates how many additional contiguous pages the application is likely to fault on soon. |
offst | unsigned long | For swap-in (UFFD_PAGEFAULT_FLAG_SWAP) faults, this contains the encoded swap entry information (device number and offset). |
flags | unsigned long | Kernel flags from the fault, such as UFFD_PAGEFAULT_FLAG_WRITE or UFFD_PAGEFAULT_FLAG_SHARED. |
origin | unsigned int | The unique ID (a userfaultfd file descriptor) for the process that generated the event. |
usmmem | char * | For the high-performance uThread path, this is a pointer to the shared memory communication page for the faulting thread. |
procName | char * | The name of the process, available for NEW_PROC events. |
struct page
This struct is USM's internal representation of a physical page within your managed memory pool. Defined in APIv/include/usm/usm.h.
| Field | Type | Description |
|---|---|---|
data | intptr_t | The virtual address of the page's content within the InstanceUSM process. Allows your policy to directly read or write page data (e.g., before swapping out). |
virtualAddress | unsigned long | The virtual address this page is mapped to within the managed application's address space. 0 if the page is free. |
physicalAddress | unsigned long | The physical address (Page Frame Number, or PFN) of this page. This is the value you pass back in event->paddr. |
process | int | The origin ID of the process that currently owns this page. 0 if the page is free. |
usedListPositionPointer | void * | Crucial Link: A generic pointer for you to store a reference back to your policy's wrapper struct (e.g., a pointer to the optEludeList that contains this page). This enables O(1) lookups. |
struct to_swap
This is a helper struct used by eviction and swapping policies to bundle all necessary information for a swap operation. Defined in APIv/include/policies/evict/swap.h.
| Field | Type | Description |
|---|---|---|
swapDevice | struct usm_swap_dev * | A pointer to the target swap device where the page will be written. |
page | struct page * | A pointer to the USM struct page that is the victim for this swap-out operation. |
swapped_address | unsigned long | The virtual address within the application that is being unmapped and swapped out. |
snode | struct swap_node * | A pointer to a node representing a free slot on the swap device. |
proc | int | The ID of the process owning the page. |
globlist | struct list_head | A list head for linking this struct into a global list of all swapped-out pages. |
iulist | struct list_head | A list head for linking this struct into a per-process list of swapped-out pages. |
Performance Insight: Why these structures matter:
The combination of usedListPositionPointer in the page struct and the paddr index in usm_event allows USM to bypass the standard kernel's expensive list-scanning (LRU) overhead.
By using the physical address as a direct index and maintaining a direct link to your policy's wrapper structures, you achieve O(1) complexity for critical path operations. This architecture is precisely why USM can outperform the standard Linux Memory Manager (LMM) in memory-intensive workloads like Redis or PageRank.