class PmmNode

We disable thread safety analysis here, since this function is only called

during early boot before threading exists.

This constructor may be called early in the boot sequence so make sure it does not do any "real

work" or depend on any globals.

See pmm_end_handoff().

We don't need to hold the arena lock while executing this, since it is

only accesses values that are set once during system initialization.

Returns compressed representation a page_t*, with the following characteristics:

- zeros in the last kIndexZeroBits bits, used by clients to store metadata.

- The value 0 is never returned, it can be used as "no page" marker.

Note: This method needs to traverse (up to) all the memory pools so it's cost is

low but not trivial.

Converts the number returned by PageToIndex() back to a page_t* pointer.

It does not check for invalid indexes such as 0.

Note: This method is faster than PageToIndex(), about the cost of some basic math

and bit manipulation.

Converts the number returned by PageToIndex() back to a paddr_t.

It does not check for invalid indexes such as 0 or kIndexReserved0.

Note: This method is faster than IndexToPage()->paddr() as the vm_page_t itself does not have

to be de-referenced, saving a memory load.

main allocator routines

Allocates a single page from the loaned pages list. The allocated page will always have

is_loaned() being true, and must be returned by either FreeLoanedPage or FreeLoanedList. If

there are not loaned pages available ZX_ERR_UNAVAILABLE is returned, as an absence of loaned

pages does not constitute an out of memory scenario.

The provided callback must transition the page into a state such that it has a valid backlink,

i.e. it is in the OBJECT state with an owner set, prior to returning.

During the execution of the callback the page contents must *not* be modified.

Begins freeing a loaned page that was previously allocated by AllocLoanPage by moving into a

holding object. It is an error to attempt to free a non loaned page. When this method is called

the |page| must have a valid backlink (i.e. be in the OBJECT state with an owner set). This

backlink should be removed by the |release_page| callback, which is invoked under the loaned

pages lock, prior to transition the page into the holding state. The caller *must*, at some

point in the future, complete the page freeing process by passing the provided |flph| into a

|FinishFreeLoanedPages| call.

Completes the freeing of any loaned pages in |flph|, after which |flph| is allowed to be

destructed. Once this method is called on a given |flph| that object is effectively 'dead' and

is not allowed to be passed to any PmmNode methods.

Begins freeing multiple pages that were allocated by AllocLoanedPage by moving into a holding

object. It is an error to attempt to free any non loaned pages. When this method is called all

pages in the array must have a valid backlink (i.e. be in the OBJECT state with an owner set),

and the |release_list| method must remove the backlink from all pages, and place them in the

provided list in the same order.

The caller *must*, at some point in the future, complete the page freeing process by passing

the provided |flph| into a |FinishFreeLoanedPages| call.

Waits the system to exit low memory state and then attempts to allocate.

To prevent herding problem, and because allocation compete for the `PmmNode::lock_` anyway,

only one thread is woken up a time, only if the previous thread successfully allocated.

In normal conditions, when the system is in low memory state, this method will return

`ZX_ERR_TIMED_OUT` if the system didn't transition fast enough. If we run into a TOC to TOU,

for the system race `ZX_ERR_SHOULD_WAIT` will be returned, that is the system transitioned

out and back into low memory state before we managed to perform the allocation.

If `BootOptions::Get()->pmm_alloc_random_wait` is true, then the system

may return spurious `ZX_ERR_SHOULD_WAIT`, in such cases, if the system is

not in a low memory state, a thread is woken up anyway, so forward

progress can be made.

If |suspendable| is true, the wait will terminate early with

`ZX_ERR_INTERNAL_INTR_RETRY` if the thread is suspended. If false, suspension is ignored and

the wait continues.

Not actually used and cancelled is still not free, since the page can't be allocated in that

state.

printf free and overall state of the internal arenas

NOTE: both functions skip mutexes and can be called inside timer or crash context

though the data they return may be questionable

Copies |count| pmm_arena_info_t objects into |buffer| starting with the |i|-th arena ordered by

base address. For example, passing an |i| of 1 would skip the 1st arena.

The objects will be sorted in ascending order by arena base address.

Returns ZX_ERR_OUT_OF_RANGE if |count| is 0 or |i| and |count| specificy an invalid range.

Returns ZX_ERR_BUFFER_TOO_SMALL if the buffer is too small.

Fill all free pages (both non-loaned and loaned) with a pattern and arm the checker. See

|PmmChecker|.

This is a no-op if the checker is not enabled. See |EnableFreePageFilling|

Synchronously walk the PMM's free list (and free loaned list) and validate each page. This is

an incredibly expensive operation and should only be used for debugging purposes.

Enable the free fill checker with the specified fill size and action, and begin filling freed

pages (including freed loaned pages) going forward. See |PmmChecker| for definition of fill

size.

Note, pages freed piror to calling this method will remain unfilled. To fill them, call

|FillFreePagesAndArm|.

Returns true if the checker was enabled with the requested fill_size, or |false| otherwise.

Returns the number of active arenas.

Retrieve any page compression instance. If this returns non-null then it's return value will

not change and the result can be cached.

Return a pointer to this object's free fill checker.

For test and diagnostic purposes.

If randomly waiting on allocations is enabled, this re-seeds from the global prng, otherwise it

does nothing.