vystem/docs/shelter/memory/pba.md

Pages block allocator

Introduction

The pages block allocator is a simple configurable bumb allocator designed to be the pages source of slabs allocator inside the kernel. It's defined inside shelter/lib/include/memory/pba.h and implemented inside shelter/lib/src/memory/pba.c.

Overview

A pages block allocator is conifigurable with various parameters.

Firstly, it need to know the size of each block that are allocated. This is specified inside the block_pages field of the PBA structure, under the sh_uint64 type.

The start_va field, a sh_page_VIRTUAL_ADDRESS, specify the starting VA of the virtual pages ranges dedicated to the allocator. It need to be aligned on a boundary of a region block_pages pages. The total_pages field, a sh_uint64, specify the size of the decicated virtual pages range, in pages. It need to be a multiple of block_pages.

Finally, the block_count field, a sh_uint64, store the amount of blocks already allocated. The max_blocks field, a sh_uint64, is computed at initialization and allow to know instantly if the PBA is full, which happen when the dedicated virtual pages range is fully mapped.

All those fields are stored inside the sh_pba_PAGE_BLOCK_ALLOCATOR structure. This structure can be manipulated by the following functions:

• SH_STATUS sh_pba_init(sh_pba_PAGE_BLOCK_ALLOCATOR *pba,sh_page_VIRTUAL_ADDRESS start_va,sh_uint64 area_pages_amount,sh_uint64 block_pages): initialize a PBA, using provided parameters. It ensure the previously specified constraints are met with the provided parameters
• SH_STATUS sh_pba_alloc(sh_pba_PAGE_BLOCK_ALLOCATOR *pba,sh_page_PAGE_TABLE_POOL *ptp,sh_page_VIRTUAL_ADDRESS *ptr): allocate a block from the PBA. Take care of the physical region search (using Page subsystem or Pez if it's initialized), VA computation (using provided virtual pages range) and pages mapping, as well as physical pages bitmap update if Pez isn't initialized.