Backing Store APIs

Backing store APIs. More...

Functions
int	k_mem_paging_backing_store_location_get (struct k_mem_page_frame *pf, uintptr_t *location, bool page_fault)
	Reserve or fetch a storage location for a data page loaded into a page frame.
void	k_mem_paging_backing_store_location_free (uintptr_t location)
	Free a backing store location.
int	k_mem_paging_backing_store_location_query (void *addr, uintptr_t *location)
	Obtain persistent location token for on-demand content.
void	k_mem_paging_backing_store_page_out (uintptr_t location)
	Copy a data page from K_MEM_SCRATCH_PAGE to the specified location.
void	k_mem_paging_backing_store_page_in (uintptr_t location)
	Copy a data page from the provided location to K_MEM_SCRATCH_PAGE.
void	k_mem_paging_backing_store_page_finalize (struct k_mem_page_frame *pf, uintptr_t location)
	Update internal accounting after a page-in.
void	k_mem_paging_backing_store_init (void)
	Backing store initialization function.

Detailed Description

Backing store APIs.

Function Documentation

k_mem_paging_backing_store_init()

void k_mem_paging_backing_store_init

(

void

)

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

Backing store initialization function.

The implementation may expect to receive page in/out calls as soon as this returns, but not before that. Called at POST_KERNEL.

This function is expected to do two things:

• Initialize any internal data structures and accounting for the backing store.
• If the backing store already contains all or some loaded kernel data pages at boot time, K_MEM_PAGE_FRAME_BACKED should be appropriately set for their associated page frames, and any internal accounting set up appropriately.

k_mem_paging_backing_store_location_free()

void k_mem_paging_backing_store_location_free

(

uintptr_t

location

)

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

Free a backing store location.

Any stored data may be discarded, and the location token associated with this address may be re-used for some other data page.

This function is invoked with interrupts locked.

Parameters

location

Location token to free

k_mem_paging_backing_store_location_get()

int k_mem_paging_backing_store_location_get	(	struct k_mem_page_frame *	pf,
		uintptr_t *	location,
		bool	page_fault )

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

Reserve or fetch a storage location for a data page loaded into a page frame.

The returned location token must be unique to the mapped virtual address. This location will be used in the backing store to page out data page contents for later retrieval. The location value must be page-aligned.

This function may be called multiple times on the same data page. If its page frame has its K_MEM_PAGE_FRAME_BACKED bit set, it is expected to return the previous backing store location for the data page containing a cached clean copy. This clean copy may be updated on page-out, or used to discard clean pages without needing to write out their contents.

If the backing store is full, some other backing store location which caches a loaded data page may be selected, in which case its associated page frame will have the K_MEM_PAGE_FRAME_BACKED bit cleared (as it is no longer cached).

k_mem_page_frame_to_virt(pf) will indicate the virtual address the page is currently mapped to. Large, sparse backing stores which can contain the entire address space may simply generate location tokens purely as a function of that virtual address with no other management necessary.

This function distinguishes whether it was called on behalf of a page fault. A free backing store location must always be reserved in order for page faults to succeed. If the page_fault parameter is not set, this function should return -ENOMEM even if one location is available.

This function is invoked with interrupts locked.

Parameters

	pf	Virtual address to obtain a storage location
[out]	location	storage location token
	page_fault	Whether this request was for a page fault

Returns

0 Success

-ENOMEM Backing store is full

k_mem_paging_backing_store_location_query()

int k_mem_paging_backing_store_location_query	(	void *	addr,
		uintptr_t *	location )

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

Obtain persistent location token for on-demand content.

Unlike k_mem_paging_backing_store_location_get() this does not allocate any backing store space. Instead, it returns a location token corresponding to some fixed storage content to be paged in on demand. This is expected to be used in conjonction with CONFIG_LINKER_USE_ONDEMAND_SECTION and the K_MEM_MAP_UNPAGED flag to create demand mappings at boot time. This may also be used e.g. to implement file-based mmap().

Parameters

	addr	Virtual address to obtain a location token for
[out]	location	storage location token

Returns

0 for success or negative error code

k_mem_paging_backing_store_page_finalize()

void k_mem_paging_backing_store_page_finalize	(	struct k_mem_page_frame *	pf,
		uintptr_t	location )

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

Update internal accounting after a page-in.

This is invoked after k_mem_paging_backing_store_page_in() and interrupts have been* re-locked, making it safe to access the k_mem_page_frame data. The location value will be the same passed to k_mem_paging_backing_store_page_in().

The primary use-case for this is to update custom fields for the backing store in the page frame, to reflect where the data should be evicted to if it is paged out again. This may be a no-op in some implementations.

If the backing store caches paged-in data pages, this is the appropriate time to set the K_MEM_PAGE_FRAME_BACKED bit. The kernel only skips paging out clean data pages if they are noted as clean in the page tables and the K_MEM_PAGE_FRAME_BACKED bit is set in their associated page frame.

Parameters

pf	Page frame that was loaded in
location	Location of where the loaded data page was retrieved

k_mem_paging_backing_store_page_in()

void k_mem_paging_backing_store_page_in

(

uintptr_t

location

)

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

Copy a data page from the provided location to K_MEM_SCRATCH_PAGE.

Immediately before this is called, K_MEM_SCRATCH_PAGE will be mapped read-write to the intended destination page frame for the calling context.

Calls to this and k_mem_paging_backing_store_page_out() will always be serialized, but interrupts may be enabled.

Parameters

location

Location token for the data page

k_mem_paging_backing_store_page_out()

void k_mem_paging_backing_store_page_out

(

uintptr_t

location

)

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

Copy a data page from K_MEM_SCRATCH_PAGE to the specified location.

Immediately before this is called, K_MEM_SCRATCH_PAGE will be mapped read-write to the intended source page frame for the calling context.

Calls to this and k_mem_paging_backing_store_page_in() will always be serialized, but interrupts may be enabled.

Parameters

location

Location token for the data page, for later retrieval