memrange: Add support for stealing required memory from given ranges

This change adds memranges_steal() which allows the user
to steal memory from the list of available ranges by providing a set
of constraints (limit, size, alignment, tag). It tries to find the
first big enough range that can satisfy the constraints, creates a
hole as per the request and returns base of the stolen memory.

BUG=b:149186922

Signed-off-by: Furquan Shaikh <furquan@google.com>
Change-Id: Ibe9cfae18fc6101ab2e7e27233e45324c8117708
Reviewed-on: https://review.coreboot.org/c/coreboot/+/39484
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Patrick Georgi <pgeorgi@google.com>

src/include/memrange.h

@@ -16,6 +16,7 @@
 #define MEMRANGE_H_
 
 #include <device/resource.h>
+#include <stdbool.h>
 
 /* A memranges structure consists of a list of range_entry(s). The structure
  * is exposed so that a memranges can be used on the stack if needed. */
@@ -166,4 +167,18 @@ void memranges_update_tag(struct memranges *ranges, unsigned long old_tag,
 /* Returns next entry after the provided entry. NULL if r is last. */
 struct range_entry *memranges_next_entry(struct memranges *ranges,
 					 const struct range_entry *r);
+
+/* Steals memory from the available list in given ranges as per the constraints:
+ * limit = Upper bound for the memory range to steal.
+ * size  = Requested size for the stolen memory.
+ * align = Alignment requirements for the starting address of the stolen memory.
+ *         (Alignment must be a power of 2).
+ * tag   = Use a range that matches the given tag.
+ *
+ * If the constraints can be satisfied, this function creates a hole in the memrange,
+ * writes the base address of that hole to stolen_base and returns true. Otherwise it returns
+ * false. */
+bool memranges_steal(struct memranges *ranges, resource_t limit, resource_t size, size_t align,
+		     unsigned long tag, resource_t *stolen_base);
+
 #endif /* MEMRANGE_H_ */