119 lines · plain
1==================2Memblock simulator3==================4 5Introduction6============7 8Memblock is a boot time memory allocator[1] that manages memory regions before9the actual memory management is initialized. Its APIs allow to register physical10memory regions, mark them as available or reserved, allocate a block of memory11within the requested range and/or in specific NUMA node, and many more.12 13Because it is used so early in the booting process, testing and debugging it is14difficult. This test suite, usually referred as memblock simulator, is15an attempt at testing the memblock mechanism. It runs one monolithic test that16consist of a series of checks that exercise both the basic operations and17allocation functionalities of memblock. The main data structure of the boot time18memory allocator is initialized at the build time, so the checks here reuse its19instance throughout the duration of the test. To ensure that tests don't affect20each other, region arrays are reset in between.21 22As this project uses the actual memblock code and has to run in user space,23some of the kernel definitions were stubbed by the initial commit that24introduced memblock simulator (commit 16802e55dea9 ("memblock tests: Add25skeleton of the memblock simulator")) and a few preparation commits just26before it. Most of them don't match the kernel implementation, so one should27consult them first before making any significant changes to the project.28 29Usage30=====31 32To run the tests, build the main target and run it:33 34$ make && ./main35 36A successful run produces no output. It is possible to control the behavior37by passing options from command line. For example, to include verbose output,38append the `-v` options when you run the tests:39 40$ ./main -v41 42This will print information about which functions are being tested and the43number of test cases that passed.44 45For the full list of options from command line, see `./main --help`.46 47It is also possible to override different configuration parameters to change48the test functions. For example, to simulate enabled NUMA, use:49 50$ make NUMA=151 52For the full list of build options, see `make help`.53 54Project structure55=================56 57The project has one target, main, which calls a group of checks for basic and58allocation functions. Tests for each group are defined in dedicated files, as it59can be seen here:60 61memblock62|-- asm ------------------,63|-- lib |-- implement function and struct stubs64|-- linux ------------------'65|-- scripts66| |-- Makefile.include -- handles `make` parameters67|-- tests68| |-- alloc_api.(c|h) -- memblock_alloc tests69| |-- alloc_helpers_api.(c|h) -- memblock_alloc_from tests70| |-- alloc_nid_api.(c|h) -- memblock_alloc_try_nid tests71| |-- basic_api.(c|h) -- memblock_add/memblock_reserve/... tests72| |-- common.(c|h) -- helper functions for resetting memblock;73|-- main.c --------------. dummy physical memory definition74|-- Makefile `- test runner75|-- README76|-- TODO77|-- .gitignore78 79Simulating physical memory80==========================81 82Some allocation functions clear the memory in the process, so it is required for83memblock to track valid memory ranges. To achieve this, the test suite registers84with memblock memory stored by test_memory struct. It is a small wrapper that85points to a block of memory allocated via malloc. For each group of allocation86tests, dummy physical memory is allocated, added to memblock, and then released87at the end of the test run. The structure of a test runner checking allocation88functions is as follows:89 90int memblock_alloc_foo_checks(void)91{92 reset_memblock_attributes(); /* data structure reset */93 dummy_physical_memory_init(); /* allocate and register memory */94 95 (...allocation checks...)96 97 dummy_physical_memory_cleanup(); /* free the memory */98}99 100There's no need to explicitly free the dummy memory from memblock via101memblock_free() call. The entry will be erased by reset_memblock_regions(),102called at the beginning of each test.103 104Known issues105============106 1071. Requesting a specific NUMA node via memblock_alloc_node() does not work as108 intended. Once the fix is in place, tests for this function can be added.109 1102. Tests for memblock_alloc_low() can't be easily implemented. The function uses111 ARCH_LOW_ADDRESS_LIMIT marco, which can't be changed to point at the low112 memory of the memory_block.113 114References115==========116 1171. Boot time memory management documentation page:118 https://www.kernel.org/doc/html/latest/core-api/boot-time-mm.html119