tests/list-test.cc - 3p/cheriot-rtos - Git at Google

 // Copyright Microsoft and CHERIoT Contributors.
 // SPDX-License-Identifier: MIT

 #define TEST_NAME "List"
 #include "tests.hh"
 #include <ds/linked_list.h>

 using CHERI::Capability;

 namespace
 {
 	/**
 	 * Example class we want to link into a doubly linked list.
 	 *
 	 * The class contains a single integer for the purposes of the test.
 	 *
 	 * `ds::linked_list` is an intrusive list: we embed the list node into
 	 * the class we want to link.  There are various implementations of the
 	 * list nodes. Here we use the most simple one
 	 * (`ds::linked_list::cell::Pointer`) which relies on two pointers
 	 * `next` and `prev`.
 	 */
 	struct LinkedObject
 	{
 		using ObjectRing = ds::linked_list::cell::Pointer;

 		int data;
 		/**
 		 * List node: links objects into the doubly-linked list.
 		 */
 		ObjectRing ring __attribute__((__cheri_no_subobject_bounds__)) = {};
 		/**
 		 * Container-of for the above field. This is used to retrieve the
 		 * corresponding object from a list element.
 		 */
 		__always_inline static struct LinkedObject *from_ring(ObjectRing *c)
 		{
 			return reinterpret_cast<struct LinkedObject *>(
 			  reinterpret_cast<uintptr_t>(c) -
 			  offsetof(struct LinkedObject, ring));
 		}
 	};
 } // namespace

 /**
  * `ds::linked_list`s are circular, doubly-linked collections. While they can
  * stand on their own as rings of objects, it is sometimes convenient to create
  * a designated 'sentinel' node that participates in the collection without
  * being part of the collection:
  *
  * - a sentinel node provides pointers to the effective head and tail of the
  *   collection (the successor and predecessor of the sentinel, respectively)
  *
  * - a sentinel allows not having to special-case 'the collection is empty' in
  *   as many places as some other representations (that is, collections with
  *   sentinels need fewer NULL pointer checks)
  *
  * - a sentinel provides many handy functions to operate on the list
  *
  * Note: do not allocate the sentinel (or any list cell) on the stack, because
  * it would lead some list nodes to hold a pointer to a stack value, i.e., to
  * an invalid capability. This would manifest as a crash while using the list.
  */
 ds::linked_list::Sentinel<LinkedObject::ObjectRing> objects = {};

 int test_list()
 {
 	debug_log("Testing the list implementation.");

 	// Number of elements we will add to the list in the test. Must be
 	// divisible by two.
 	static constexpr int NumberOfListElements = 30;

 	auto heapAtStart = heap_quota_remaining(MALLOC_CAPABILITY);

 	TEST(objects.is_empty(), "Newly created list is not empty");

 	// Create heap-allocated objects, and link them into the linked list.
 	for (int i = 0; i < NumberOfListElements; i++)
 	{
 		Timeout       t{UnlimitedTimeout};
 		LinkedObject *o = static_cast<LinkedObject *>(
 		  heap_allocate(&t, MALLOC_CAPABILITY, sizeof(LinkedObject)));
 		TEST(Capability{o}.is_valid(), "Cannot allocate linked object");

 		// Use the object integer as an index.
 		o->data = i;
 		// The list node has not yet been initialized.
 		o->ring.cell_reset();

 		// Test that we can retrieve the object from the link node and
 		// that this results in a capability which is identical to what
 		// we got from the allocator.
 		TEST(Capability{o} == Capability{LinkedObject::from_ring(&(o->ring))},
 		     "The container of method does not return the right object");
 		TEST(Capability{LinkedObject::from_ring(&(o->ring))}.is_valid(),
 		     "Capability retrieved from `from_ring` is invalid");

 		// Add the new object to the list through the sentinel node.
 		objects.append(&(o->ring));
 	}

 	TEST(!objects.is_empty(), "The list is empty after adding objects");

 	// Test that the sentinel can be used to retrieve the first and last
 	// elements of the list as expected.
 	TEST(LinkedObject::from_ring(objects.last())->data ==
 	       NumberOfListElements - 1,
 	     "Last element of the list is incorrect, expected {}, got {}",
 	     NumberOfListElements - 1,
 	     LinkedObject::from_ring(objects.last())->data);
 	TEST(objects.last()->cell_next() == &objects.sentinel,
 	     "Last element in not followed by the sentinel");
 	TEST(objects.last() == objects.sentinel.cell_prev(),
 	     "Sentinel is not preceeded by the last element");

 	TEST(LinkedObject::from_ring(objects.first())->data == 0,
 	     "First element of the list is incorrect, expected {}, got {}",
 	     0,
 	     LinkedObject::from_ring(objects.last())->data);
 	TEST(objects.first()->cell_prev() == &objects.sentinel,
 	     "First element in not preceeded by the sentinel");
 	TEST(objects.first() == objects.sentinel.cell_next(),
 	     "Sentinel is not followed by the first element");

 	// Test that we can go through the list by following `cell_next`
 	// pointers as expected.
 	int counter = 0;
 	// While at it, retrieve a pointer to the middle element which we will
 	// use to cleave the list later.
 	LinkedObject::ObjectRing *middle = nullptr;
 	// We reach the sentinel when we have gone through all elements of the
 	// list.
 	for (auto *cell = objects.first(); cell != &objects.sentinel;
 	     cell       = cell->cell_next())
 	{
 		struct LinkedObject *o = LinkedObject::from_ring(cell);
 		TEST(
 		  o->data == counter,
 		  "Ordering of elements in the list is incorrect, expected {}, got {}",
 		  o->data,
 		  counter);
 		if (counter == NumberOfListElements / 2)
 		{
 			middle = cell;
 		}
 		counter++;
 	}

 	TEST(middle != nullptr, "Could not find middle element of the list");

 	// Cut the list in the middle. `middle` is now a handle to the (valid)
 	// collection of objects [middle, last] that have become detached from
 	// the sentinel.
 	ds::linked_list::remove(middle, objects.last());

 	// This should leave us with a list of size `NumberOfListElements / 2`.
 	counter = 0;
 	for (auto *cell = objects.first(); cell != &objects.sentinel;
 	     cell       = cell->cell_next())
 	{
 		counter++;
 	}
 	TEST(counter == NumberOfListElements / 2,
 	     "Cleaving didn't leave a list with the right number of elements");

 	// Now remove (and free) a single element from the list.
 	TEST(LinkedObject::from_ring(objects.first())->data == 0,
 	     "First element of the list is incorrect, expected {}, got {}",
 	     0,
 	     LinkedObject::from_ring(objects.first())->data);
 	// We must keep a reference to the removed object to free it, as
 	// `remove` returns a pointer to the residual list (return value which
 	// we do not use here), not to the removed element.
 	LinkedObject::ObjectRing *removedCell = objects.first();
 	ds::linked_list::remove(objects.first());
 	heap_free(MALLOC_CAPABILITY, LinkedObject::from_ring(removedCell));
 	TEST(LinkedObject::from_ring(objects.first())->data == 1,
 	     "First element of the list is incorrect after removing the first "
 	     "element, expected {}, got {}",
 	     1,
 	     LinkedObject::from_ring(objects.first())->data);
 	TEST(objects.first()->cell_prev() == &objects.sentinel,
 	     "First element in not preceeded by the sentinel after removing the "
 	     "first object");

 	// We are done with the list, free it.
 	counter                        = 0;
 	LinkedObject::ObjectRing *cell = objects.first();
 	while (cell != &objects.sentinel)
 	{
 		struct LinkedObject *o = LinkedObject::from_ring(cell);
 		cell                   = cell->cell_next();
 		heap_free(MALLOC_CAPABILITY, o);
 		counter++;
 	}

 	TEST(counter == (NumberOfListElements / 2) - 1,
 	     "Incorrect number of elements freed, expected {}, got {}",
 	     (NumberOfListElements / 2) - 1,
 	     counter);

 	// Now that the list is freed, reset the sentinel.
 	objects.reset();

 	TEST(objects.is_empty(), "Reset-ed list is not empty");

 	// We must also free the span of the list which we removed earlier.
 	// This time use the `::search` method to go through the collection.
 	ds::linked_list::search(
 	  middle, [&counter](LinkedObject::ObjectRing *&cell) {
 		  // `unsafe_remove` does not update the node pointers of the
 		  // removed cell. This is great here because we will free the
 		  // object anyways. We could also use `remove` here.
 		  auto l = ds::linked_list::unsafe_remove(cell);
 		  heap_free(MALLOC_CAPABILITY, LinkedObject::from_ring(cell));
 		  // `l` is the predecessor of `cell` in the residual ring, so
 		  // this does exactly what we want when `::search` iterates.
 		  cell = l;
 		  counter++;
 		  return false;
 	  });
 	// `::search` does not visit the element passed (`middle`)
 	heap_free(MALLOC_CAPABILITY, LinkedObject::from_ring(middle));
 	counter++;

 	TEST(counter == NumberOfListElements - 1,
 	     "Incorrect number of elements freed, expected {}, got {}",
 	     NumberOfListElements - 1,
 	     counter);

 	// Check that we didn't leak anything in the process
 	auto heapAtEnd = heap_quota_remaining(MALLOC_CAPABILITY);
 	TEST(heapAtStart == heapAtEnd,
 	     "The list leaked {} bytes ({} vs. {})",
 	     heapAtEnd - heapAtStart,
 	     heapAtStart,
 	     heapAtEnd);

 	debug_log("Done testing the list.");
 	return 0;
 }
	// Copyright Microsoft and CHERIoT Contributors.
	// SPDX-License-Identifier: MIT

	#define TEST_NAME "List"
	#include "tests.hh"
	#include <ds/linked_list.h>

	using CHERI::Capability;

	namespace
	{
	/**
	* Example class we want to link into a doubly linked list.
	*
	* The class contains a single integer for the purposes of the test.
	*
	* `ds::linked_list` is an intrusive list: we embed the list node into
	* the class we want to link. There are various implementations of the
	* list nodes. Here we use the most simple one
	* (`ds::linked_list::cell::Pointer`) which relies on two pointers
	* `next` and `prev`.
	*/
	struct LinkedObject
	{
	using ObjectRing = ds::linked_list::cell::Pointer;

	int data;
	/**
	* List node: links objects into the doubly-linked list.
	*/
	ObjectRing ring __attribute__((__cheri_no_subobject_bounds__)) = {};
	/**
	* Container-of for the above field. This is used to retrieve the
	* corresponding object from a list element.
	*/
	__always_inline static struct LinkedObject from_ring(ObjectRing c)
	{
	return reinterpret_cast<struct LinkedObject *>(
	reinterpret_cast<uintptr_t>(c) -
	offsetof(struct LinkedObject, ring));
	}
	};
	} // namespace

	/**
	* `ds::linked_list`s are circular, doubly-linked collections. While they can
	* stand on their own as rings of objects, it is sometimes convenient to create
	* a designated 'sentinel' node that participates in the collection without
	* being part of the collection:
	*
	* - a sentinel node provides pointers to the effective head and tail of the
	* collection (the successor and predecessor of the sentinel, respectively)
	*
	* - a sentinel allows not having to special-case 'the collection is empty' in
	* as many places as some other representations (that is, collections with
	* sentinels need fewer NULL pointer checks)
	*
	* - a sentinel provides many handy functions to operate on the list
	*
	* Note: do not allocate the sentinel (or any list cell) on the stack, because
	* it would lead some list nodes to hold a pointer to a stack value, i.e., to
	* an invalid capability. This would manifest as a crash while using the list.
	*/
	ds::linked_list::Sentinel<LinkedObject::ObjectRing> objects = {};

	int test_list()
	{
	debug_log("Testing the list implementation.");

	// Number of elements we will add to the list in the test. Must be
	// divisible by two.
	static constexpr int NumberOfListElements = 30;

	auto heapAtStart = heap_quota_remaining(MALLOC_CAPABILITY);

	TEST(objects.is_empty(), "Newly created list is not empty");

	// Create heap-allocated objects, and link them into the linked list.
	for (int i = 0; i < NumberOfListElements; i++)
	{
	Timeout t{UnlimitedTimeout};
	LinkedObject o = static_cast<LinkedObject >(
	heap_allocate(&t, MALLOC_CAPABILITY, sizeof(LinkedObject)));
	TEST(Capability{o}.is_valid(), "Cannot allocate linked object");

	// Use the object integer as an index.
	o->data = i;
	// The list node has not yet been initialized.
	o->ring.cell_reset();

	// Test that we can retrieve the object from the link node and
	// that this results in a capability which is identical to what
	// we got from the allocator.
	TEST(Capability{o} == Capability{LinkedObject::from_ring(&(o->ring))},
	"The container of method does not return the right object");
	TEST(Capability{LinkedObject::from_ring(&(o->ring))}.is_valid(),
	"Capability retrieved from `from_ring` is invalid");

	// Add the new object to the list through the sentinel node.
	objects.append(&(o->ring));
	}

	TEST(!objects.is_empty(), "The list is empty after adding objects");

	// Test that the sentinel can be used to retrieve the first and last
	// elements of the list as expected.
	TEST(LinkedObject::from_ring(objects.last())->data ==
	NumberOfListElements - 1,
	"Last element of the list is incorrect, expected {}, got {}",
	NumberOfListElements - 1,
	LinkedObject::from_ring(objects.last())->data);
	TEST(objects.last()->cell_next() == &objects.sentinel,
	"Last element in not followed by the sentinel");
	TEST(objects.last() == objects.sentinel.cell_prev(),
	"Sentinel is not preceeded by the last element");

	TEST(LinkedObject::from_ring(objects.first())->data == 0,
	"First element of the list is incorrect, expected {}, got {}",
	0,
	LinkedObject::from_ring(objects.last())->data);
	TEST(objects.first()->cell_prev() == &objects.sentinel,
	"First element in not preceeded by the sentinel");
	TEST(objects.first() == objects.sentinel.cell_next(),
	"Sentinel is not followed by the first element");

	// Test that we can go through the list by following `cell_next`
	// pointers as expected.
	int counter = 0;
	// While at it, retrieve a pointer to the middle element which we will
	// use to cleave the list later.
	LinkedObject::ObjectRing *middle = nullptr;
	// We reach the sentinel when we have gone through all elements of the
	// list.
	for (auto *cell = objects.first(); cell != &objects.sentinel;
	cell = cell->cell_next())
	{
	struct LinkedObject *o = LinkedObject::from_ring(cell);
	TEST(
	o->data == counter,
	"Ordering of elements in the list is incorrect, expected {}, got {}",
	o->data,
	counter);
	if (counter == NumberOfListElements / 2)
	{
	middle = cell;
	}
	counter++;
	}

	TEST(middle != nullptr, "Could not find middle element of the list");

	// Cut the list in the middle. `middle` is now a handle to the (valid)
	// collection of objects [middle, last] that have become detached from
	// the sentinel.
	ds::linked_list::remove(middle, objects.last());

	// This should leave us with a list of size `NumberOfListElements / 2`.
	counter = 0;
	for (auto *cell = objects.first(); cell != &objects.sentinel;
	cell = cell->cell_next())
	{
	counter++;
	}
	TEST(counter == NumberOfListElements / 2,
	"Cleaving didn't leave a list with the right number of elements");

	// Now remove (and free) a single element from the list.
	TEST(LinkedObject::from_ring(objects.first())->data == 0,
	"First element of the list is incorrect, expected {}, got {}",
	0,
	LinkedObject::from_ring(objects.first())->data);
	// We must keep a reference to the removed object to free it, as
	// `remove` returns a pointer to the residual list (return value which
	// we do not use here), not to the removed element.
	LinkedObject::ObjectRing *removedCell = objects.first();
	ds::linked_list::remove(objects.first());
	heap_free(MALLOC_CAPABILITY, LinkedObject::from_ring(removedCell));
	TEST(LinkedObject::from_ring(objects.first())->data == 1,
	"First element of the list is incorrect after removing the first "
	"element, expected {}, got {}",
	1,
	LinkedObject::from_ring(objects.first())->data);
	TEST(objects.first()->cell_prev() == &objects.sentinel,
	"First element in not preceeded by the sentinel after removing the "
	"first object");

	// We are done with the list, free it.
	counter = 0;
	LinkedObject::ObjectRing *cell = objects.first();
	while (cell != &objects.sentinel)
	{
	struct LinkedObject *o = LinkedObject::from_ring(cell);
	cell = cell->cell_next();
	heap_free(MALLOC_CAPABILITY, o);
	counter++;
	}

	TEST(counter == (NumberOfListElements / 2) - 1,
	"Incorrect number of elements freed, expected {}, got {}",
	(NumberOfListElements / 2) - 1,
	counter);

	// Now that the list is freed, reset the sentinel.
	objects.reset();

	TEST(objects.is_empty(), "Reset-ed list is not empty");

	// We must also free the span of the list which we removed earlier.
	// This time use the `::search` method to go through the collection.
	ds::linked_list::search(
	middle, [&counter](LinkedObject::ObjectRing *&cell) {
	// `unsafe_remove` does not update the node pointers of the
	// removed cell. This is great here because we will free the
	// object anyways. We could also use `remove` here.
	auto l = ds::linked_list::unsafe_remove(cell);
	heap_free(MALLOC_CAPABILITY, LinkedObject::from_ring(cell));
	// `l` is the predecessor of `cell` in the residual ring, so
	// this does exactly what we want when `::search` iterates.
	cell = l;
	counter++;
	return false;
	});
	// `::search` does not visit the element passed (`middle`)
	heap_free(MALLOC_CAPABILITY, LinkedObject::from_ring(middle));
	counter++;

	TEST(counter == NumberOfListElements - 1,
	"Incorrect number of elements freed, expected {}, got {}",
	NumberOfListElements - 1,
	counter);

	// Check that we didn't leak anything in the process
	auto heapAtEnd = heap_quota_remaining(MALLOC_CAPABILITY);
	TEST(heapAtStart == heapAtEnd,
	"The list leaked {} bytes ({} vs. {})",
	heapAtEnd - heapAtStart,
	heapAtStart,
	heapAtEnd);

	debug_log("Done testing the list.");
	return 0;
	}