mem_manage.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020 Intel Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_SYS_MEM_MANAGE_H
#define ZEPHYR_INCLUDE_SYS_MEM_MANAGE_H
 
#include <zephyr/sys/util.h>
#include <zephyr/toolchain.h>
#if defined(CONFIG_ARM_MMU) && defined(CONFIG_ARM64)
#include <zephyr/arch/arm64/arm_mem.h>
#endif
 
/*
 * Caching mode definitions. These are mutually exclusive.
 */
 
#define K_MEM_CACHE_NONE        2
 
#define K_MEM_CACHE_WT          1
 
#define K_MEM_CACHE_WB          0
 
/*
 * ARM64 Specific flags are defined in arch/arm64/arm_mem.h,
 * pay attention to be not conflicted when updating these flags.
 */
 
#define K_MEM_CACHE_MASK        (BIT(3) - 1)
 
/*
 * Region permission attributes. Default is read-only, no user, no exec
 */
 
#define K_MEM_PERM_RW           BIT(3)
 
#define K_MEM_PERM_EXEC         BIT(4)
 
#define K_MEM_PERM_USER         BIT(5)
 
/*
 * Region mapping behaviour attributes
 */
 
#define K_MEM_DIRECT_MAP        BIT(6)
 
/*
 * This is the offset to subtract from a virtual address mapped in the
 * kernel's permanent mapping of RAM, to obtain its physical address.
 *
 *     virt_addr = phys_addr + Z_MEM_VM_OFFSET
 *
 * This only works for virtual addresses within the interval
 * [CONFIG_KERNEL_VM_BASE, CONFIG_KERNEL_VM_BASE + (CONFIG_SRAM_SIZE * 1024)).
 *
 * These macros are intended for assembly, linker code, and static initializers.
 * Use with care.
 *
 * Note that when demand paging is active, these will only work with page
 * frames that are pinned to their virtual mapping at boot.
 *
 * TODO: This will likely need to move to an arch API or need additional
 * constraints defined.
 */
#ifdef CONFIG_MMU
#define Z_MEM_VM_OFFSET ((CONFIG_KERNEL_VM_BASE + CONFIG_KERNEL_VM_OFFSET) - \
                         (CONFIG_SRAM_BASE_ADDRESS + CONFIG_SRAM_OFFSET))
#else
#define Z_MEM_VM_OFFSET 0
#endif
 
#define Z_MEM_PHYS_ADDR(virt)   ((virt) - Z_MEM_VM_OFFSET)
#define Z_MEM_VIRT_ADDR(phys)   ((phys) + Z_MEM_VM_OFFSET)
 
#if Z_MEM_VM_OFFSET != 0
#define Z_VM_KERNEL 1
#ifdef CONFIG_XIP
#error "XIP and a virtual memory kernel are not allowed"
#endif
#endif
 
#ifndef _ASMLANGUAGE
#include <stdint.h>
#include <stddef.h>
#include <inttypes.h>
#include <zephyr/sys/__assert.h>
 
struct k_mem_paging_stats_t {
#ifdef CONFIG_DEMAND_PAGING_STATS
        struct {
                unsigned long                   cnt;
 
                unsigned long                   irq_locked;
 
                unsigned long                   irq_unlocked;
 
#ifndef CONFIG_DEMAND_PAGING_ALLOW_IRQ
                unsigned long                   in_isr;
#endif
        } pagefaults;
 
        struct {
                unsigned long                   clean;
 
                unsigned long                   dirty;
        } eviction;
#endif /* CONFIG_DEMAND_PAGING_STATS */
};
 
struct k_mem_paging_histogram_t {
#ifdef CONFIG_DEMAND_PAGING_TIMING_HISTOGRAM
        /* Counts for each bin in timing histogram */
        unsigned long   counts[CONFIG_DEMAND_PAGING_TIMING_HISTOGRAM_NUM_BINS];
 
        /* Bounds for the bins in timing histogram,
         * excluding the first and last (hence, NUM_SLOTS - 1).
         */
        unsigned long   bounds[CONFIG_DEMAND_PAGING_TIMING_HISTOGRAM_NUM_BINS];
#endif /* CONFIG_DEMAND_PAGING_TIMING_HISTOGRAM */
};
 
/* Just like Z_MEM_PHYS_ADDR() but with type safety and assertions */
static inline uintptr_t z_mem_phys_addr(void *virt)
{
        uintptr_t addr = (uintptr_t)virt;
 
#ifdef CONFIG_MMU
        __ASSERT(
#if CONFIG_KERNEL_VM_BASE != 0
                 (addr >= CONFIG_KERNEL_VM_BASE) &&
#endif
#if (CONFIG_KERNEL_VM_BASE + CONFIG_KERNEL_VM_SIZE) != 0
                 (addr < (CONFIG_KERNEL_VM_BASE +
                          (CONFIG_KERNEL_VM_SIZE))),
#else
                 false,
#endif
                 "address %p not in permanent mappings", virt);
#else
        /* Should be identity-mapped */
        __ASSERT(
#if CONFIG_SRAM_BASE_ADDRESS != 0
                 (addr >= CONFIG_SRAM_BASE_ADDRESS) &&
#endif
#if (CONFIG_SRAM_BASE_ADDRESS + (CONFIG_SRAM_SIZE * 1024UL)) != 0
                 (addr < (CONFIG_SRAM_BASE_ADDRESS +
                          (CONFIG_SRAM_SIZE * 1024UL))),
#else
                 false,
#endif
                 "physical address 0x%lx not in RAM",
                 (unsigned long)addr);
#endif /* CONFIG_MMU */
 
        /* TODO add assertion that this page is pinned to boot mapping,
         * the above checks won't be sufficient with demand paging
         */
 
        return Z_MEM_PHYS_ADDR(addr);
}
 
/* Just like Z_MEM_VIRT_ADDR() but with type safety and assertions */
static inline void *z_mem_virt_addr(uintptr_t phys)
{
        __ASSERT(
#if CONFIG_SRAM_BASE_ADDRESS != 0
                 (phys >= CONFIG_SRAM_BASE_ADDRESS) &&
#endif
#if (CONFIG_SRAM_BASE_ADDRESS + (CONFIG_SRAM_SIZE * 1024UL)) != 0
                 (phys < (CONFIG_SRAM_BASE_ADDRESS +
                          (CONFIG_SRAM_SIZE * 1024UL))),
#else
                 false,
#endif
                 "physical address 0x%lx not in RAM", (unsigned long)phys);
 
        /* TODO add assertion that this page frame is pinned to boot mapping,
         * the above check won't be sufficient with demand paging
         */
 
        return (void *)Z_MEM_VIRT_ADDR(phys);
}
 
#ifdef __cplusplus
extern "C" {
#endif
 
void z_phys_map(uint8_t **virt_ptr, uintptr_t phys, size_t size,
                uint32_t flags);
 
void z_phys_unmap(uint8_t *virt, size_t size);
 
/*
 * k_mem_map() control flags
 */
 
#define K_MEM_MAP_UNINIT        BIT(16)
 
#define K_MEM_MAP_LOCK          BIT(17)
 
size_t k_mem_free_get(void);
 
void *k_mem_map(size_t size, uint32_t flags);
 
void k_mem_unmap(void *addr, size_t size);
 
size_t k_mem_region_align(uintptr_t *aligned_addr, size_t *aligned_size,
                          uintptr_t addr, size_t size, size_t align);
 
int k_mem_page_out(void *addr, size_t size);
 
void k_mem_page_in(void *addr, size_t size);
 
void k_mem_pin(void *addr, size_t size);
 
void k_mem_unpin(void *addr, size_t size);
 
__syscall void k_mem_paging_stats_get(struct k_mem_paging_stats_t *stats);
 
struct k_thread;
__syscall
void k_mem_paging_thread_stats_get(struct k_thread *thread,
                                   struct k_mem_paging_stats_t *stats);
 
__syscall void k_mem_paging_histogram_eviction_get(
        struct k_mem_paging_histogram_t *hist);
 
__syscall void k_mem_paging_histogram_backing_store_page_in_get(
        struct k_mem_paging_histogram_t *hist);
 
__syscall void k_mem_paging_histogram_backing_store_page_out_get(
        struct k_mem_paging_histogram_t *hist);
 
#include <syscalls/mem_manage.h>
 
struct z_page_frame *k_mem_paging_eviction_select(bool *dirty);
 
void k_mem_paging_eviction_init(void);
 
int k_mem_paging_backing_store_location_get(struct z_page_frame *pf,
                                            uintptr_t *location,
                                            bool page_fault);
 
void k_mem_paging_backing_store_location_free(uintptr_t location);
 
void k_mem_paging_backing_store_page_out(uintptr_t location);
 
void k_mem_paging_backing_store_page_in(uintptr_t location);
 
void k_mem_paging_backing_store_page_finalize(struct z_page_frame *pf,
                                              uintptr_t location);
 
void k_mem_paging_backing_store_init(void);
 
#ifdef __cplusplus
}
#endif
 
#endif /* !_ASMLANGUAGE */
#endif /* ZEPHYR_INCLUDE_SYS_MEM_MANAGE_H */