Policy Interfaces (_ops)

A detailed technical reference for the usm_alloc_policy_ops and usm_swap_policy_ops structures that form the core of any USM policy.

The _ops structures are the heart of the USM programming interface. They are collections of function pointers that you implement in your policy file. The USM framework then calls your functions through these pointers at the appropriate times.

Allocation Policies (usm_alloc_policy_ops)

This structure, defined in APIv/include/policies/alloc/alloc.h, defines the interface for all allocation-related policies.

struct usm_alloc_policy_ops {
    int (*usm_init) (unsigned int pagesNumber);
    int (*usm_alloc) (struct usm_event *event);
    int (*usm_free) (struct usm_event *event);
    int (*usm_accessed) (struct usm_event *event);
    int (*usm_virt_address_space_change) (struct usm_event *event);
    int (*usm_permissions_change) (struct usm_event *event);
    int (*usm_task_state_change) (struct usm_event *event);
    int (*usm_new_process) (struct usm_event *event);
    int (*usm_new_task) (struct usm_event *event);
    int (*get_pages) (struct list_head *placeHolder, int nr);
    void (*put_pages) (struct list_head *pages);
    void (*get_used_pages)(struct list_head *placeHolder , int nr);
    void (*put_used_pages)(struct list_head *page);
    int (*usm_policy_free)() ;
    int (*usm_oom)();
};
Function PointerSignatureDescription
usm_initint (*)(unsigned int pagesNumber)An optional initialization function for your policy. Called once when the policy is first registered.
usm_allocint (*)(struct usm_event *event)(Mandatory) The core allocation function. Called on a page fault. Your implementation must select a free physical page, set event->paddr to its physical address, and call usmSubmitAllocEvent(event). Returns 0 on success, non-zero on failure.
usm_freeint (*)(struct usm_event *event)An alternative page free function that is triggered by a vaddr instead of a paddr. It is less efficient than usm_pindex_free as it may require searching your list of used pages to find the correct one.
usm_accessedint (*)(struct usm_event *event)(Mandatory) The primary, high-performance page free function. Called when the kernel frees a page (e.g., on process exit), reporting its paddr via /proc/usmPgs. Your implementation should use this to find the corresponding struct page and return it to your free list.
usm_virt_address_space_changeint (*)(struct usm_event *event)Intended to be called when a VMA (Virtual Memory Area) of a managed process changes (e.g., via mremap). Not fully implemented in the current version.
usm_permissions_changeint (*)(struct usm_event *event)Intended to be called when memory permissions change (e.g., via mprotect). Not fully implemented.
usm_task_state_changeint (*)(struct usm_event *event)Intended to be called when a process`s state changes (e.g., sleeping, running), which could influence policy decisions. Not fully implemented.
usm_new_processint (*)(struct usm_event *event)Intended to be called when a new process is assigned to this policy. Used in complex policies to track metadata when a new PID is attached to the policy.
usm_new_taskint (*)(struct usm_event *event)An Optional hook triggered when a new task (thread) is created within a managed process. Can be used to initialize task-level memory tracking or adapt heuristics for multithreaded workloads.
get_pagesint (*)(struct list_head *placeHolder, int nr)(Mandatory) The policy selects the pages from its free pool and returns them as a list. Used by the swap module for page restoration or prefetching.
put_pagesint (*)(struct list_head *pages)(Mandatory) Returns a list of free pages back to the policy. Used when an allocation, restoration, or prefetching attempt fails, or when pages are evicted and become reusable.
get_used_pageint (*)(struct list_head *placeHolder , int nr)(Mandatory) THe policy requests the used paged according to the eviction heuristics (e.g least recently used) and are returned reordered as needed vy the swap module.
put_used_pageint (*)(struct list_head *page)(Mandatory) Returns a list of previously allocated pages back to the used-page pool. Called on eviction failure, concurrent page faults, swap cache hits, or successful page restorations.
usm_policy_freeint (*)(void)(Mandatory) Frees all internal structures of the policy. Called when the associated InstanceUSM shuts down. May optionally preserve metadata in USM-provided memory for planned restarts of the same instance.
usm_oomint (*)(void)Intended to be applied the decision to the OOMs of the policy. Very costly and limited optimizations given its “ultimate” nature.

Swapping & Eviction Policies (usm_swap_policy_ops)

This structure, defined in APIv/include/policies/evict/swap.h, defines the interface for handling page swaps and proactive eviction.

struct usm_swap_policy_ops {
    char *usm_swap_policy_name;
    int (*usm_policy_init) ();
    int (*usm_swap) (struct usm_event *event);
    void (*cond_swap_out) (struct usm_event *event);
    int (*cond_swap_in) (struct usm_event *event);
    int (*usm_free) (struct usm_event *event);
    int (*usm_new_process) (struct usm_event *event);
    int (*usm_new_task)(struct usm_event *event);
    int (*usm_virt_address_space_change) (struct usm_event *event);
    int (*usm_permissions_change) (struct usm_event *event);
    int (*usm_process_state_change) (struct usm_event *event);
};
Function PointerSignatureDescription
usm_policy_initint (*)(void)An optional initialization function for your swap policy. For instance, this is where you would open your swap file or initialize your swap device nodes.
usm_swapint (*)(struct usm_event *event)(Mandatory for Swap) The swap-in function. Called on a page fault for a page that has been swapped out. The event->offst field contains the swap entry information. Your implementation must find the data on the swap device, get a new physical page, read the data into it, and submit the new mapping.
cond_swap_outvoid (*)(struct usm_event *event)A proactive eviction hook. This function is called by the USM framework after certain events (like a successful allocation). You can use this hook to check for memory pressure (e.g., usedMemory > threshold) and trigger a swap-out of victim pages.
cond_swap_inint (*)(struct usm_event *event)Allows the policy to proactively restore pages before faults occur (e.g., based on access patterns, hints, or task state). Can also be used to cancel or delay swap-out decisions when memory pressure subsides.
usm_freeint (*)(struct usm_event *event)Called to free resources associated with swapping when a process exits. This could involve cleaning up entries in your swap metadata tables or freeing swap file space.
usm_new_processint (*)(struct usm_event *event)Optional hook called when a new process is attached to the swap policy. Used to initialize per-process swap metadata, assign preferred swap devices, or establish swap quotas and eviction priorities.
usm_new_taskint (*)(struct usm_event *event)An optional hook for receiving application-specific hints that could guide eviction decisions (e.g., a hint to "never swap this memory region").
usm_virt_address_space_changeint (*)(struct usm_event *event)Optional notification of a virtual address space change (e.g., mremap). Enables the policy to update swap metadata associated with VMAs, invalidate swap entries, or adapt eviction logic to changed layouts.
usm_permissions_changeint (*)(struct usm_event *event)Optional hook called when VMA access permissions change. Can be used to protect pages from eviction (e.g., executable or critical regions) or to deprioritize others. Not fully exploited in current USM versions.
usm_process_state_changeint (*)(struct usm_event *event)Optional hook notified on process state transitions (running, sleeping, blocked, etc.). Enables state-aware swapping strategies, such as aggressive eviction for sleeping processes or swap-in prioritization for waking ones.

Note:

The USM framework also exposes a global function pointer, usm_evict_fallback, which can be set by your swap policy. This function serves as a synchronous, emergency eviction path that your allocation policy can call directly when it runs out of memory.

Edit this page on GitHub