class ProtectedRanges

If the SecureMem driver cleanly disconnects, we know that all protected ranges are gone. This

allows ~ProtectedRanges to run without asserting.

This method attempts to add an additional range to the set of requested protected ranges. The

requested protected ranges are the ranges that need to all be continuously covered by a limited

number of HW-supported ranges.

If this returns true, the added range is now usable as a protected range. If this returns

false, the range was not added and no attempt should be made to use the range as a protected

range. Do not use ranges that happen to be protected due to being in the set of HW-backed

protected ranges at any given moment, as HW-backed protected ranges may be adjusted at any

time, and the implementation is free to cause DMA glitches in ranges that are not in the set

of required protected ranges.

This method typically will succeed even if there are more ranges added via AddRange() than the

number of HW-backed ranges. In this case, at least one of the HW-backed ranges is used to

cover more than one required range. This can lead to "extra" pages in between required ranges

which are HW-protected despite not being used as protected ranges. These pages are still

considered "used" in terms of ProtectedRangesControl.UseRange() and UnUseRange(), but must not

be used for protected DMA, as the implementation is free to disrupt protected DMA to/from any

such protected gap.

During this call, outgoing callbacks to ranges_control _may_ be made to effect the change. The

outgoing calls can in some cases be more numerous and change other ranges, as the HW-backed

ranges are being re-optimized to some extent during this call.

To finish optimizing ranges, the caller should call StepTowardOptimalRanges() until it returns

true, typically with a timer delay in between calls to avoid churning loaned pages too fast.

range - the range to add to the raw set of ranges that must be protected.

This method removes a range from the set of required protected ranges. See also AddRange().

This method can't fail. If the system is too broken to delete a required range, this method

will ZX_PANIC() instead of returning. A hard reboot will result.

During this call, outgoing callbacks to ranges_control _may_ be made to effect the change. The

outgoing calls can in some cases be more numerous and change other ranges, as the HW-backed

ranges are being re-optimized to some extent during this call.

To finish optimizing ranges, the caller should call StepTowardOptimalRanges() until it returns

true, typically with a timer delay in between calls to avoid churning loaned pages too fast.

range - the range to remove from the raw set of ranges that must be protected.

requested ranges

requested_ranges() processed to align to block boundaries

required_ranges() processed to merge overlaps and barely-touching ranges

coalesced_required_ranges() gaps

interior_unused_ranges() processed to keep only the largest gaps

largest_interior_unused_ranges() gaps plus the left-most and right-most ranges needed to cover

the rest of colesced_required_ranges()

current ranges; when called within a ProtectedRangesControl method, this will reutnr the

"before" ranges.

When AddRange() or DeleteRange() is called, we don't instantly try to fix the ranges to be

completely optimal immediately, because optimizing can involve some reclaiming of pages and

loaning of different pages. If we do all of that too quickly, the opportunistic borrowing

during PageQueues rotation / GC will not necessarily have enough time to soak up the

newly-loaned pages before an OOM is triggered. We basically want to incrementally step toward

optimal instead of slamming the whole set of ranges into place all at once, especially when

the optimal set of ranges is changing to a quite different configuration.

As we incrementally optimize, it's possible we'll end up triggering a PageQueues rotation / GC

sooner than would have happened otherwise, and that's fine/good, but we do want to give

PageQueues rotation enough time to borrow (or "re-borrow" if you like, from the point of view

of an offset of a pager-backed VMO) some pages before we perform another step toward optimal

ranges.

Despite the delayed optimization of ranges in steps with some delay in between steps, a

a successful call to AddRange() is guaranteed to make the added range usable for protected DMA.

Calling this "extra" times after this has returned true and before any more AddRange() or

DeleteRange() is permitted, but is also not necessary, and won't achieve any further

optimization (until called after the next AddRange() or DeleteRange() when there may be more

optimizing to do).

This method guarantees that it'll eventually return true if called repeatedly without any more

calls to AddRange() or DeleteRange(), _if_ memory pressure is low enough to allow optimizing

ranges. If memory pressure is too high to make progress for a while, this method will keep

returning true during that while.

true - known done optimizing, until the next call to AddRange() or DeleteRange().

false - call again later to try to do more optimizing.

only for dumping the small ranges in unit tests

Requirement: Either ranges must not contain any self-overlaps (all Ranges available via this

class except required_ranges()), or ranges must be required_ranges(). The required_ranges()

can have a limited degree of self-overlap, which this method does accommodate.

The returned iterators are a begin, end pair. If there is no range in "ranges" that overlaps

"range", then both iterators will be ranges.end(). If there are any ranges in "ranges" that

overlap "range", then [begin, end) is exactly those ranges in "ranges" which overlap "range".

un-covered pages / un-used pages

un-covered pages / total pages

un-covered bytes