Demand Paging APIs

Data Structures
struct	k_mem_paging_stats_t
	Paging Statistics. More...
struct	k_mem_paging_histogram_t
	Paging Statistics Histograms. More...

Functions
int	k_mem_page_out (void *addr, size_t size)
	Evict a page-aligned virtual memory region to the backing store.
void	k_mem_page_in (void *addr, size_t size)
	Load a virtual data region into memory.
void	k_mem_pin (void *addr, size_t size)
	Pin an aligned virtual data region, paging in as necessary.
void	k_mem_unpin (void *addr, size_t size)
	Un-pin an aligned virtual data region.
void	k_mem_paging_stats_get (struct k_mem_paging_stats_t *stats)
	Get the paging statistics since system startup.
void	k_mem_paging_thread_stats_get (struct k_thread *thread, struct k_mem_paging_stats_t *stats)
	Get the paging statistics since system startup for a thread.
void	k_mem_paging_histogram_eviction_get (struct k_mem_paging_histogram_t *hist)
	Get the eviction timing histogram.
void	k_mem_paging_histogram_backing_store_page_in_get (struct k_mem_paging_histogram_t *hist)
	Get the backing store page-in timing histogram.
void	k_mem_paging_histogram_backing_store_page_out_get (struct k_mem_paging_histogram_t *hist)
	Get the backing store page-out timing histogram.

Detailed Description

Function Documentation

k_mem_page_in()

void k_mem_page_in	(	void *	addr,
		size_t	size
	)

#include <zephyr/kernel/mm/demand_paging.h>

Load a virtual data region into memory.

After the function completes, all the page frames associated with this function will be paged in. However, they are not guaranteed to stay there. This is useful if the region is known to be used soon.

If CONFIG_DEMAND_PAGING_ALLOW_IRQ is enabled, this function may not be called by ISRs as the backing store may be in-use.

Parameters

addr	Base page-aligned virtual address
size	Page-aligned data region size

k_mem_page_out()

int k_mem_page_out	(	void *	addr,
		size_t	size
	)

#include <zephyr/kernel/mm/demand_paging.h>

Evict a page-aligned virtual memory region to the backing store.

Useful if it is known that a memory region will not be used for some time. All the data pages within the specified region will be evicted to the backing store if they weren't already, with their associated page frames marked as available for mappings or page-ins.

None of the associated page frames mapped to the provided region should be pinned.

Note that there are no guarantees how long these pages will be evicted, they could take page faults immediately.

If CONFIG_DEMAND_PAGING_ALLOW_IRQ is enabled, this function may not be called by ISRs as the backing store may be in-use.

Parameters

addr	Base page-aligned virtual address
size	Page-aligned data region size

Return values

0	Success
-ENOMEM	Insufficient space in backing store to satisfy request. The region may be partially paged out.

k_mem_paging_histogram_backing_store_page_in_get()

void k_mem_paging_histogram_backing_store_page_in_get

(

struct k_mem_paging_histogram_t *

hist

)

#include <zephyr/kernel/mm/demand_paging.h>

Get the backing store page-in timing histogram.

This populates the timing histogram struct being passed in as argument.

Parameters

[in,out]

hist

Timing histogram struct to be filled.

k_mem_paging_histogram_backing_store_page_out_get()

void k_mem_paging_histogram_backing_store_page_out_get

(

struct k_mem_paging_histogram_t *

hist

)

#include <zephyr/kernel/mm/demand_paging.h>

Get the backing store page-out timing histogram.

This populates the timing histogram struct being passed in as argument.

Parameters

[in,out]

hist

Timing histogram struct to be filled.

k_mem_paging_histogram_eviction_get()

void k_mem_paging_histogram_eviction_get

(

struct k_mem_paging_histogram_t *

hist

)

#include <zephyr/kernel/mm/demand_paging.h>

Get the eviction timing histogram.

This populates the timing histogram struct being passed in as argument.

Parameters

[in,out]

hist

Timing histogram struct to be filled.

k_mem_paging_stats_get()

void k_mem_paging_stats_get

(

struct k_mem_paging_stats_t *

stats

)

#include <zephyr/kernel/mm/demand_paging.h>

Get the paging statistics since system startup.

This populates the paging statistics struct being passed in as argument.

Parameters

[in,out]

stats

Paging statistics struct to be filled.

k_mem_paging_thread_stats_get()

void k_mem_paging_thread_stats_get	(	struct k_thread *	thread,
		struct k_mem_paging_stats_t *	stats
	)

#include <zephyr/kernel/mm/demand_paging.h>

Get the paging statistics since system startup for a thread.

This populates the paging statistics struct being passed in as argument for a particular thread.

Parameters

[in]	thread	Thread
[in,out]	stats	Paging statistics struct to be filled.

k_mem_pin()

void k_mem_pin	(	void *	addr,
		size_t	size
	)

#include <zephyr/kernel/mm/demand_paging.h>

Pin an aligned virtual data region, paging in as necessary.

After the function completes, all the page frames associated with this region will be resident in memory and pinned such that they stay that way. This is a stronger version of z_mem_page_in().

If CONFIG_DEMAND_PAGING_ALLOW_IRQ is enabled, this function may not be called by ISRs as the backing store may be in-use.

Parameters

addr	Base page-aligned virtual address
size	Page-aligned data region size

k_mem_unpin()

void k_mem_unpin	(	void *	addr,
		size_t	size
	)

#include <zephyr/kernel/mm/demand_paging.h>

Un-pin an aligned virtual data region.

After the function completes, all the page frames associated with this region will be no longer marked as pinned. This does not evict the region, follow this with z_mem_page_out() if you need that.

Parameters

addr	Base page-aligned virtual address
size	Page-aligned data region size