class Pool

Default-construction uses the identity mapping for a

BookkeepingAddressToPointer.

Initializes a Pool from a variable number of memory ranges, performing an

internal allocation for its internal bookkeeping among the free RAM

encoded in the provided ranges. `default_min_addr` and `default_max_addr`

prescribe default bounds on the addresses Pool is allowed to allocate; the

placement of the internal bookkeeping must respect these.

The provided ranges cannot feature overlap among different allocated

types, or between an allocated type with one of kReserved or kPeripheral;

otherwise, arbitrary overlap is permitted.

fit::failed is returned if there is insufficient free RAM to use for

Pool's initial bookkeeping.

Initializes a Pool from a variable number of memory ranges, performing an

internal allocation for its internal bookkeeping among the free RAM

encoded in the provided ranges. `default_min_addr` and `default_max_addr`

prescribe default bounds on the addresses Pool is allowed to allocate; the

placement of the internal bookkeeping must respect these.

The provided ranges cannot feature overlap among different allocated

types, or between an allocated type with one of kReserved or kPeripheral;

otherwise, arbitrary overlap is permitted.

fit::failed is returned if there is insufficient free RAM to use for

Pool's initial bookkeeping.

Initializes a Pool from a variable number of memory ranges, performing an

internal allocation for its internal bookkeeping among the free RAM

encoded in the provided ranges. `default_min_addr` and `default_max_addr`

prescribe default bounds on the addresses Pool is allowed to allocate; the

placement of the internal bookkeeping must respect these.

The provided ranges cannot feature overlap among different allocated

types, or between an allocated type with one of kReserved or kPeripheral;

otherwise, arbitrary overlap is permitted.

fit::failed is returned if there is insufficient free RAM to use for

Pool's initial bookkeeping.

Initializes a Pool from a variable number of memory ranges, performing an

internal allocation for its internal bookkeeping among the free RAM

encoded in the provided ranges. `default_min_addr` and `default_max_addr`

prescribe default bounds on the addresses Pool is allowed to allocate; the

placement of the internal bookkeeping must respect these.

The provided ranges cannot feature overlap among different allocated

types, or between an allocated type with one of kReserved or kPeripheral;

otherwise, arbitrary overlap is permitted.

fit::failed is returned if there is insufficient free RAM to use for

Pool's initial bookkeeping.

Returns the number of tracked, normalized ranges.

Sets an allocation callback (see AccessCallback for more details). This

may be called before Init().

Sets an allocation callback (see AccessCallback for more details). This

may be called before Init().

Sets an allocation callback (see AccessCallback for more details). This

may be called before Init().

Sets an allocation callback (see AccessCallback for more details). This

may be called before Init().

Attempts to allocate memory out of free RAM of the prescribed type, size,

and alignment. An optional upper address bound may be passed: if

unspecified the default upper bound passed to Init() will be respected.

`type` must be an allocated type. `size` must be positive and the following

must hold:

`min_addr.value_or(default_min_addr)

<

= max_addr.value_or(default_max_addr)`

Any returned address is guaranteed to be nonzero.

fit::failed is returned if there is insufficient free RAM to track any

new ranges or if there is no free RAM that meets the given constraints.

Attempts to allocate memory out of free RAM of the prescribed type, size,

and alignment. An optional upper address bound may be passed: if

unspecified the default upper bound passed to Init() will be respected.

`type` must be an allocated type. `size` must be positive and the following

must hold:

`min_addr.value_or(default_min_addr)

<

= max_addr.value_or(default_max_addr)`

Any returned address is guaranteed to be nonzero.

fit::failed is returned if there is insufficient free RAM to track any

new ranges or if there is no free RAM that meets the given constraints.

Attempts to allocate memory out of free RAM of the prescribed type, size,

and alignment. An optional upper address bound may be passed: if

unspecified the default upper bound passed to Init() will be respected.

`type` must be an allocated type. `size` must be positive and the following

must hold:

`min_addr.value_or(default_min_addr)

<

= max_addr.value_or(default_max_addr)`

Any returned address is guaranteed to be nonzero.

fit::failed is returned if there is insufficient free RAM to track any

new ranges or if there is no free RAM that meets the given constraints.

Returns an iterator pointing to the tracked, normalized range containing

the provided address if one exists, or else end().

Returns an iterator pointing to the tracked, normalized range containing

the provided address if one exists, or else end().

Returns `fit::success` if the provided range was succesully marked as peripheral. This requires

that `range.type` is `memalloc::Type::kPeripheral` and that there are no ranges of type

`memalloc::Type::kFreeRam` or allocated types overlapping in the range, otherwise `fit::failed`

is returned.

Pretty-prints the memory ranges contained in the pool.

Pretty-prints the memory ranges contained in the pool.

Destructively reallocates all RAM types within the given range to the

provided allocated type.

`addr + size` cannot exceed UINT64_MAX.

The utility of this method lies in situations where there is a special

range that we ultimately want to reserve for another booting context that

we are handing pool bookkeeping off to. For example, when loading a

fixed-address kernel image, we would want to prevent page tables - which

must persist across the boot - from being allocated out of that load range.

fit::failed is returned if there is insufficient bookkeeping to track any

new ranges of memory.

Destructively reallocates all RAM types within the given range to the

provided allocated type.

`addr + size` cannot exceed UINT64_MAX.

The utility of this method lies in situations where there is a special

range that we ultimately want to reserve for another booting context that

we are handing pool bookkeeping off to. For example, when loading a

fixed-address kernel image, we would want to prevent page tables - which

must persist across the boot - from being allocated out of that load range.

fit::failed is returned if there is insufficient bookkeeping to track any

new ranges of memory.

Attempts to free a subrange of a previously allocated range or one of

an allocated type that had previously been passed to Init(). This subrange

is updated to have type kFreeRam.

Freeing a range already tracked as kFreeRam is a no-op.

fit::failed is returned if there is insufficient memory to track the new

(subdivided) ranges of memory that would result from freeing.

Attempts to free a subrange of a previously allocated range or one of

an allocated type that had previously been passed to Init(). This subrange

is updated to have type kFreeRam.

Freeing a range already tracked as kFreeRam is a no-op.

fit::failed is returned if there is insufficient memory to track the new

(subdivided) ranges of memory that would result from freeing.

Attempts to resize a previously allocated range or one of the ranges of

allocated type originally passed to Init(). The resizing occurs only at

the level of bookkeeping; the start of the resized region is returned and,

if it differs from the one originally supplied, it is the responsibility

of the caller to actually std::memmove the old contents to the new region

before another allocation is performed. If the new size is smaller than

the original, then this method effectively just frees the range's tail.

The original range - as opposed to just its root address - is required to

be passed in as testimony; since the original allocation or

initialization, the pool may have coalesced neighbouring regions into it

or freed subregions of it, this method asserts that the associated tracked

range does at least still have `original` as a subrange with the

appropriate type. The provided range must also be of allocated type.

`new_size` must be positive; this method is not a backdoor `Free()`. The

original range must already be `min_alignment`-aligned.

fit::failed is returned if there is insufficient memory to track the new

(subdivided) ranges of memory that would result from resizing, or if the

range is untracked. No failure mode will leave the original range freed.

Attempts to resize a previously allocated range or one of the ranges of

allocated type originally passed to Init(). The resizing occurs only at

the level of bookkeeping; the start of the resized region is returned and,

if it differs from the one originally supplied, it is the responsibility

of the caller to actually std::memmove the old contents to the new region

before another allocation is performed. If the new size is smaller than

the original, then this method effectively just frees the range's tail.

The original range - as opposed to just its root address - is required to

be passed in as testimony; since the original allocation or

initialization, the pool may have coalesced neighbouring regions into it

or freed subregions of it, this method asserts that the associated tracked

range does at least still have `original` as a subrange with the

appropriate type. The provided range must also be of allocated type.

`new_size` must be positive; this method is not a backdoor `Free()`. The

original range must already be `min_alignment`-aligned.

fit::failed is returned if there is insufficient memory to track the new

(subdivided) ranges of memory that would result from resizing, or if the

range is untracked. No failure mode will leave the original range freed.

Effectively truncates all of RAM (free or allocated) by allocating all of

it past the provided capacity as type kTruncatedRam. This is used to

simulate physical memory constraints of smaller devices. Any allocations

(including pool bookkeeping) past the cut-off are destructively

reallocated (via UpdateRamSubranges()).

kNvram is excluded from this truncation, as such ranges are special and

are of diagnostic value even when simulating physical memory constraints.

Effectively truncates all of RAM (free or allocated) by allocating all of

it past the provided capacity as type kTruncatedRam. This is used to

simulate physical memory constraints of smaller devices. Any allocations

(including pool bookkeeping) past the cut-off are destructively

reallocated (via UpdateRamSubranges()).

kNvram is excluded from this truncation, as such ranges are special and

are of diagnostic value even when simulating physical memory constraints.

This method will generate one peripheral range for every run of consecutive peripheral ranges

the pool knows of. This peripheral range will be aligned to oen of the provided alignments.

Each of the provided alignments is tried, and the first one not to generate invalid ranges,

such as overlapping with free ram ranges, is selected.

`alignments` is a collection of power of two alignments, that is the mask for alignment is

equivalent to `(1

<

<

alignments[n]) - 1`.

This method will generate one peripheral range for every run of consecutive peripheral ranges

the pool knows of. This peripheral range will be aligned to oen of the provided alignments.

Each of the provided alignments is tried, and the first one not to generate invalid ranges,

such as overlapping with free ram ranges, is selected.

`alignments` is a collection of power of two alignments, that is the mask for alignment is

equivalent to `(1

<

<

alignments[n]) - 1`.

This method will generate one peripheral range for every run of consecutive peripheral ranges

the pool knows of. This peripheral range will be aligned to oen of the provided alignments.

Each of the provided alignments is tried, and the first one not to generate invalid ranges,

such as overlapping with free ram ranges, is selected.

`alignments` is a collection of power of two alignments, that is the mask for alignment is

equivalent to `(1

<

<

alignments[n]) - 1`.

This method will generate one peripheral range for every run of consecutive peripheral ranges

the pool knows of. This peripheral range will be aligned to oen of the provided alignments.

Each of the provided alignments is tried, and the first one not to generate invalid ranges,

such as overlapping with free ram ranges, is selected.

`alignments` is a collection of power of two alignments, that is the mask for alignment is

equivalent to `(1

<

<

alignments[n]) - 1`.