vystem/docs/shelter/memory/heap.md

Kernel heap manager

Introduction

In order to allocate small-sized object or medium-sized buffers (approximately between one and one hundred pages), the lower half have been designed for hosting the heap of the kernel. This is an early design subject to changes for perfomances and/or robustess in the coming updates. It's defined inside shelter/lib/include/memory/heap.h and implemented inside shelter/lib/src/memory/heap.c.

Overview

The kernel heap manager is based on a dual allocation strategy:

• small objects, less or equal to 1024 bytes goes into slab allocators
• medium buffers, greater than 1024 bytes, are allocated using the Pez allocator for physical and virtual planes management

The heap metadatas are stored inside the sh_heap_KERNEL_HEAP structure. The alloc_size_tree field is a radix tree mapping virtual pages offset of any pages mapping with their size in pages. This allow for quick retrieval of any pages allocations on the heap.

Slab allocators

These are described into generic slab allocator documentation. Each one is setted up with a PBA containing 12 terabytes of virtual memory

Here are a table describing the virtual pages ranges of all allocators:

Object size range (bytes)	Allocator level	Virtual pages range start address
1-8	0	0x0000200000000000
9-16	1	0x00002C0000000000
17-32	2	0x0000380000000000
33-64	3	0x0000440000000000
65-128	4	0x0000500000000000
129-256	5	0x00005C0000000000
257-512	6	0x0000680000000000
513-1024	7	0x0000740000000000

Pages allocations

If the needed amount of bytes is greater than 1024 bytes, pages are allocated on the heap. The number of pages allocated is the nearest amount that can satisfy the demand. The pages are allocated inside a virtual pages range starting at 0x0000100000000000 and contain 16 terabytes of virtual memory.

API

The heap manager provide the following API, that should only be called by the abstraction provided by sh_malloc, except the first three one:

• sh_heap_KERNEL_HEAP *sh_heap_get_default_heap(): return a pointer to the kernel heap structure
• void sh_heap_load_default_heap(sh_heap_KERNEL_HEAP *heap): set the pointer to the kernel heap structure
• SH_STATUS sh_heap_init_heap(sh_pez_PHYSICAL_PLANE *phys_plane,sh_pez_VIRTUAL_PLANE *virt_plane,sh_page_PAGE_TABLE_POOL *kernel_ptp,sh_heap_KERNEL_HEAP *kernel_heap): initialize the heap structure, the calling entity need to setup and place the generic slab allocators pointers manually inside the returned structure
• SH_STATUS sh_heap_allocate_pages(sh_uint32 pages_count,sh_page_VIRTUAL_ADDRESS *address): allocate a certain amount of pages, provided by the Pez physical backend and mapped on the heap pages allocation range
• SH_STATUS sh_heap_free_pages(sh_page_VIRTUAL_ADDRESS va): free an allocated region of pages from the heap. Return the pages to Pez physical backend
• SH_STATUS sh_heap_allocate_object(sh_uint32 size_bytes,sh_page_VIRTUAL_ADDRESS *address): allocate a certain object based on his size, automatically uses the most adapted generic slab allocator. Will refuse any size superior to 1024 bytes
• SH_STATUS sh_heap_free_object(sh_page_VIRTUAL_ADDRESS va): free a certain object by providing his VA. Automatically free from the previously used slab allocator. Will refuse any VA not in the range of the object allocation range