Allocator Parameters
include/mem/alloc_param.h View source View on GitHubTL;DR:
FLAGS: TELL THE ALLOCATOR WHAT KIND OF MEMORY YOU WANT
BEHAVIORS: TELL THE ALLOCATOR WHAT IT IS ALLOWED TO DO TO GET THAT MEMORY
PRIORITIES: TELL THE ALLOCATOR HOW MUCH YOU WANT YOUR ALLOCATION TO SUCCEED
─────────────────────────── ALLOC FLAGS ───────────────────────────
Structs
Section titled “Structs”alloc_flag_ex_desc
Section titled “alloc_flag_ex_desc” struct alloc_flag_ex_desc (3 fields) source
alloc_params
Section titled “alloc_params” struct alloc_params (3 fields) source
alloc_capabilities
Section titled “alloc_capabilities” struct alloc_capabilities (4 fields) source
§
enum alloc_flags flags A bitmask
§
enum alloc_behavior behaviors Bitmask 1 << base
§
enum alloc_behavior behavior_flags Bitmask for remaining flags
§
enum alloc_priority priorities Supported priorities, 1 << base bitmap
alloc_flags
Section titled “alloc_flags” enum alloc_flags : uint32_t (13 variants) source
Flags define properties regarding the memory the allocator will return
Cache alignment
§
ALLOC_FLAG_PREFER_CACHE_ALIGNED = (1 << 0) §
ALLOC_FLAG_NO_CACHE_ALIGN = 0 Flexible locality
§
ALLOC_FLAG_FLEXIBLE_LOCALITY = (1 << 1) §
ALLOC_FLAG_STRICT_LOCALITY = 0 Pageable
§
ALLOC_FLAG_PAGEABLE = (1 << 2) §
ALLOC_FLAG_NONPAGEABLE = 0 Movable
§
ALLOC_FLAG_MOVABLE = (1 << 3) §
ALLOC_FLAG_NONMOVABLE = 0 Zero on alloc
§
ALLOC_FLAG_ZERO_ON_ALLOC = (1 << 4) §
ALLOC_FLAG_NON_ZERO = 0 Allocation classes
§
ALLOC_FLAG_CLASS_DEFAULT = (1 << ALLOC_CLASS_SHIFT) §
ALLOC_FLAG_CLASS_INTERLEAVED = (2 << ALLOC_CLASS_SHIFT) §
ALLOC_FLAG_CLASS_HIGH_BANDWIDTH = (3 << ALLOC_CLASS_SHIFT) alloc_behavior
Section titled “alloc_behavior” enum alloc_behavior : uint16_t (9 variants) source
Allocation behavior restricts flags. If non-faulting behaviors are selected, then the allocator cannot allocate pageable memory
§
ALLOC_BEHAVIOR_NORMAL §
ALLOC_BEHAVIOR_NMI_SAFE §
ALLOC_BEHAVIOR_IRQ_SAFE §
ALLOC_BEHAVIOR_FAULT_SAFE §
ALLOC_BEHAVIOR_NO_BLOCK §
ALLOC_BEHAVIOR_NO_APC §
ALLOC_BEHAVIOR_MAX §
ALLOC_BEHAVIOR_FLAG_FAST = 1 << ALLOC_BEHAVIOR_FLAG_SHIFT §
ALLOC_BEHAVIOR_FLAG_MINIMAL = 1 << (ALLOC_BEHAVIOR_FLAG_SHIFT + 1) Used by various allocators to prevent recursion in things they interact with
alloc_priority
Section titled “alloc_priority” enum alloc_priority : uint16_t (6 variants) source
alloc_priority: 16 bit bitflags
Do note that with allocation priorities, the default ones given are in increments of 8. This gives allocators room to interpret the priorities as a continuous curve instead of discrete steps.
┌──────────────────────────┐Bits │ 15..12 11..8 7..4 3..0 │Use │ AAAA AAAA %%%% %%%% │ └──────────────────────────┘%%%% - Priority A - Unused (available) * - Unused (unavailable)
§
ALLOC_PRIORITY_MIN = 0 §
ALLOC_PRIORITY_LOW = 8 §
ALLOC_PRIORITY_NORMAL = 16 §
ALLOC_PRIORITY_HIGH = 24 §
ALLOC_PRIORITY_CRITICAL = 32 §
ALLOC_PRIORITY_MAX = ALLOC_PRIORITY_CRITICAL Functions
Section titled “Functions”alloc_flags_valid
Section titled “alloc_flags_valid”bool alloc_flags_valid(enum alloc_flags flags)alloc_flag_ex_get_desc
Section titled “alloc_flag_ex_get_desc”size_t alloc_flag_ex_get_desc(
enum alloc_flags flag,
struct alloc_flag_ex_desc out[ALLOC_FLAG_EX_DESC_MAX]
)alloc_behavior_base
Section titled “alloc_behavior_base”enum alloc_behavior alloc_behavior_base(enum alloc_behavior raw)alloc_behavior_may_fault
Section titled “alloc_behavior_may_fault”bool alloc_behavior_may_fault(enum alloc_behavior raw)alloc_behavior_may_block
Section titled “alloc_behavior_may_block”bool alloc_behavior_may_block(enum alloc_behavior raw)alloc_behavior_is_isr_safe
Section titled “alloc_behavior_is_isr_safe”bool alloc_behavior_is_isr_safe(enum alloc_behavior raw)alloc_behavior_is_fast
Section titled “alloc_behavior_is_fast”bool alloc_behavior_is_fast(enum alloc_behavior raw)Fast hint: should this allocation prefer short paths?
alloc_flag_behavior_verify
Section titled “alloc_flag_behavior_verify”bool alloc_flag_behavior_verify(struct alloc_params params)alloc_request_sanitize
Section titled “alloc_request_sanitize”void alloc_request_sanitize(struct alloc_params *params) TODO
Rework these into capabilities
Macros
Section titled “Macros”ALLOC_LOCALITY_SHIFT
Section titled “ALLOC_LOCALITY_SHIFT”#define ALLOC_LOCALITY_SHIFT 25ALLOC_CLASS_SHIFT
Section titled “ALLOC_CLASS_SHIFT”#define ALLOC_CLASS_SHIFT 28ALLOC_CLASS_MASK
Section titled “ALLOC_CLASS_MASK”#define ALLOC_CLASS_MASK 0xFALLOC_LOCALITY_MAX
Section titled “ALLOC_LOCALITY_MAX”#define ALLOC_LOCALITY_MAX 7The larger the locality, the closer it must be
ALLOC_LOCALITY_MIN
Section titled “ALLOC_LOCALITY_MIN”#define ALLOC_LOCALITY_MIN 0ALLOC_LOCALITY_MASK
Section titled “ALLOC_LOCALITY_MASK”#define ALLOC_LOCALITY_MASK 0x7ALLOC_LOCALITY_FROM_FLAGS
Section titled “ALLOC_LOCALITY_FROM_FLAGS”#define ALLOC_LOCALITY_FROM_FLAGS(flags)Expansion
#define ALLOC_LOCALITY_FROM_FLAGS(flags) \
(((flags) >> ALLOC_LOCALITY_SHIFT) & ALLOC_LOCALITY_MASK)ALLOC_LOCALITY_TO_FLAGS
Section titled “ALLOC_LOCALITY_TO_FLAGS”#define ALLOC_LOCALITY_TO_FLAGS(locality)Expansion
#define ALLOC_LOCALITY_TO_FLAGS(locality) \
(((locality) & ALLOC_LOCALITY_MASK) << ALLOC_LOCALITY_SHIFT)ALLOC_FLAG_TEST
Section titled “ALLOC_FLAG_TEST”#define ALLOC_FLAG_TEST(flags, mask)Expansion
#define ALLOC_FLAG_TEST(flags, mask) (flags & mask)ALLOC_FLAG_CLASS
Section titled “ALLOC_FLAG_CLASS”#define ALLOC_FLAG_CLASS(flags)Expansion
#define ALLOC_FLAG_CLASS(flags) \
((flags >> ALLOC_CLASS_SHIFT) & ALLOC_CLASS_MASK)ALLOC_FLAG_EX_JOIN
Section titled “ALLOC_FLAG_EX_JOIN”#define ALLOC_FLAG_EX_JOIN(subsys, flag)Expansion
#define ALLOC_FLAG_EX_JOIN(subsys, flag) ALLOC_FLAG_EX_##subsys##_##flagALLOC_FLAG_EX
Section titled “ALLOC_FLAG_EX”#define ALLOC_FLAG_EX(subsys, flag)Expansion
#define ALLOC_FLAG_EX(subsys, flag) ALLOC_FLAG_EX_JOIN(subsys, flag)ALLOC_FLAG_AVAIL_BIT
Section titled “ALLOC_FLAG_AVAIL_BIT”#define ALLOC_FLAG_AVAIL_BIT(n)Expansion
#define ALLOC_FLAG_AVAIL_BIT(n) BITFLAG_AVAIL_BIT(ALLOC_FLAG, n)ALLOC_FLAG_EX_REGISTER
Section titled “ALLOC_FLAG_EX_REGISTER”#define ALLOC_FLAG_EX_REGISTER(subsys, name)Expansion
#define ALLOC_FLAG_EX_REGISTER(subsys, name) \
static LINKER_SECTION_OBJECT(struct alloc_flag_ex_desc, \
alloc_flag_ex_descs) \
__alloc_flag_desc_##subsys##_##name = { \
.subsystem = #subsys, \
.flag_name = #name, \
.flag = ALLOC_FLAG_EX(subsys, name)}ALLOC_FLAG_EX_REGISTER
Section titled “ALLOC_FLAG_EX_REGISTER”#define ALLOC_FLAG_EX_REGISTER(subsys, name)Expansion
#define ALLOC_FLAG_EX_REGISTER(subsys, name)ALLOC_FLAGS_NONE
Section titled “ALLOC_FLAGS_NONE”#define ALLOC_FLAGS_NONE 0ALLOC_FLAGS_UNAVAILABLE_BITS
Section titled “ALLOC_FLAGS_UNAVAILABLE_BITS”#define ALLOC_FLAGS_UNAVAILABLE_BITS ((1 << 24) | (0x3FFU << 6))Bits 6..15 and 24
ALLOC_FLAGS_DEFAULT
Section titled “ALLOC_FLAGS_DEFAULT”#define ALLOC_FLAGS_DEFAULTALLOC_FLAGS_ZERO
Section titled “ALLOC_FLAGS_ZERO”#define ALLOC_FLAGS_ZERO (ALLOC_FLAGS_DEFAULT | ALLOC_FLAG_ZERO_ON_ALLOC)ALLOC_ZERO
Section titled “ALLOC_ZERO”#define ALLOC_ZERO .flags = ALLOC_FLAGS_ZEROALLOC_FLAGS_PAGEABLE
Section titled “ALLOC_FLAGS_PAGEABLE”#define ALLOC_FLAGS_PAGEABLEExpansion
#define ALLOC_FLAGS_PAGEABLE \
ALLOC_FLAG_PAGEABLE | ALLOC_FLAG_CLASS_DEFAULT | \
ALLOC_FLAG_FLEXIBLE_LOCALITYALLOC_FLAGS_VALID
Section titled “ALLOC_FLAGS_VALID”#define ALLOC_FLAGS_VALID(flags)Expansion
#define ALLOC_FLAGS_VALID(flags) (((flags) & ALLOC_FLAGS_UNAVAILABLE_BITS) == 0)ALLOC_BEHAVIOR_FLAG_SHIFT
Section titled “ALLOC_BEHAVIOR_FLAG_SHIFT”#define ALLOC_BEHAVIOR_FLAG_SHIFT 4ALLOC_BEHAVIOR_MASK
Section titled “ALLOC_BEHAVIOR_MASK”#define ALLOC_BEHAVIOR_MASK (0xF)ALLOC_BEHAVIOR_AVAILABLE_SHIFT
Section titled “ALLOC_BEHAVIOR_AVAILABLE_SHIFT”#define ALLOC_BEHAVIOR_AVAILABLE_SHIFT 12ALLOC_BEHAVIOR_AVAIL_BIT
Section titled “ALLOC_BEHAVIOR_AVAIL_BIT”#define ALLOC_BEHAVIOR_AVAIL_BIT(n)Bits 12..15 are available, this gives the 0-indexed Nth available bit
Expansion
#define ALLOC_BEHAVIOR_AVAIL_BIT(n) (1 << (ALLOC_BEHAVIOR_AVAILABLE_SHIFT + n))ALLOC_BEHAVIOR_DEFAULT
Section titled “ALLOC_BEHAVIOR_DEFAULT”#define ALLOC_BEHAVIOR_DEFAULT ALLOC_BEHAVIOR_NORMALALLOC_PRIORITY_STEP
Section titled “ALLOC_PRIORITY_STEP”#define ALLOC_PRIORITY_STEP 8ALLOC_PRIORITY_HALFSTEP
Section titled “ALLOC_PRIORITY_HALFSTEP”#define ALLOC_PRIORITY_HALFSTEP (ALLOC_PRIORITY_STEP / 2)ALLOC_PRIORITY_ABOVE
Section titled “ALLOC_PRIORITY_ABOVE”#define ALLOC_PRIORITY_ABOVE(p)Expansion
#define ALLOC_PRIORITY_ABOVE(p) ((p) + ALLOC_PRIORITY_HALFSTEP)ALLOC_PRIORITY_BELOW
Section titled “ALLOC_PRIORITY_BELOW”#define ALLOC_PRIORITY_BELOW(p)Expansion
#define ALLOC_PRIORITY_BELOW(p) ((p) - ALLOC_PRIORITY_HALFSTEP)ALLOC_PRIORITY_BITMAP_DECLARE
Section titled “ALLOC_PRIORITY_BITMAP_DECLARE”#define ALLOC_PRIORITY_BITMAP_DECLARE(name)Expansion
#define ALLOC_PRIORITY_BITMAP_DECLARE(name) \
BITMAP_DECLARE(name, ALLOC_PRIORITY_MAX)ALLOC_PRIORITY_DEFAULT
Section titled “ALLOC_PRIORITY_DEFAULT”#define ALLOC_PRIORITY_DEFAULT ALLOC_PRIORITY_MINALLOC_FLAG_EX_DESC_MAX
Section titled “ALLOC_FLAG_EX_DESC_MAX”#define ALLOC_FLAG_EX_DESC_MAX 8ALLOC_BEHAVIOR_BASE
Section titled “ALLOC_BEHAVIOR_BASE”#define ALLOC_BEHAVIOR_BASE(raw)Expansion
#define ALLOC_BEHAVIOR_BASE(raw) ((raw) & ALLOC_BEHAVIOR_MASK)ALLOC_BEHAVIOR_MAY_FAULT
Section titled “ALLOC_BEHAVIOR_MAY_FAULT”#define ALLOC_BEHAVIOR_MAY_FAULT(raw)Expansion
#define ALLOC_BEHAVIOR_MAY_FAULT(raw) \
(ALLOC_BEHAVIOR_BASE(raw) != ALLOC_BEHAVIOR_IRQ_SAFE && \
ALLOC_BEHAVIOR_BASE(raw) != ALLOC_BEHAVIOR_FAULT_SAFE)ALLOC_BEHAVIOR_MAY_BLOCK
Section titled “ALLOC_BEHAVIOR_MAY_BLOCK”#define ALLOC_BEHAVIOR_MAY_BLOCK(raw)Expansion
#define ALLOC_BEHAVIOR_MAY_BLOCK(raw) \
(ALLOC_BEHAVIOR_BASE(raw) != ALLOC_BEHAVIOR_IRQ_SAFE && \
ALLOC_BEHAVIOR_BASE(raw) != ALLOC_BEHAVIOR_NO_BLOCK)ALLOC_BEHAVIOR_IS_ISR_SAFE
Section titled “ALLOC_BEHAVIOR_IS_ISR_SAFE”#define ALLOC_BEHAVIOR_IS_ISR_SAFE(raw)Expansion
#define ALLOC_BEHAVIOR_IS_ISR_SAFE(raw) \
(ALLOC_BEHAVIOR_BASE(raw) == ALLOC_BEHAVIOR_IRQ_SAFE || \
ALLOC_BEHAVIOR_BASE(raw) == ALLOC_BEHAVIOR_NMI_SAFE)ALLOC_FLAGS_CAN_FAULT
Section titled “ALLOC_FLAGS_CAN_FAULT”#define ALLOC_FLAGS_CAN_FAULT(flags)Expansion
#define ALLOC_FLAGS_CAN_FAULT(flags) \
(((flags) & (ALLOC_FLAG_PAGEABLE | ALLOC_FLAG_MOVABLE)) != 0)ALLOC_FLAGS_BEHAVIOR_VALID
Section titled “ALLOC_FLAGS_BEHAVIOR_VALID”#define ALLOC_FLAGS_BEHAVIOR_VALID(flags, behavior)Check that flags and behavior are in agreement
Expansion
#define ALLOC_FLAGS_BEHAVIOR_VALID(flags, behavior) \
(!(!ALLOC_BEHAVIOR_MAY_FAULT(behavior) && ALLOC_FLAGS_CAN_FAULT(flags)) && \
!(ALLOC_BEHAVIOR_IS_ISR_SAFE(behavior) && \
((flags) & ALLOC_FLAG_PAGEABLE) != 0))