Commit | Line | Data |
---|---|---|
58ffc348 KD |
1 | ================== |
2 | Memblock simulator | |
3 | ================== | |
4 | ||
5 | Introduction | |
6 | ============ | |
7 | ||
8 | Memblock is a boot time memory allocator[1] that manages memory regions before | |
9 | the actual memory management is initialized. Its APIs allow to register physical | |
10 | memory regions, mark them as available or reserved, allocate a block of memory | |
11 | within the requested range and/or in specific NUMA node, and many more. | |
12 | ||
13 | Because it is used so early in the booting process, testing and debugging it is | |
14 | difficult. This test suite, usually referred as memblock simulator, is | |
15 | an attempt at testing the memblock mechanism. It runs one monolithic test that | |
16 | consist of a series of checks that exercise both the basic operations and | |
17 | allocation functionalities of memblock. The main data structure of the boot time | |
18 | memory allocator is initialized at the build time, so the checks here reuse its | |
19 | instance throughout the duration of the test. To ensure that tests don't affect | |
20 | each other, region arrays are reset in between. | |
21 | ||
22 | As this project uses the actual memblock code and has to run in user space, | |
23 | some of the kernel definitions were stubbed by the initial commit that | |
24 | introduced memblock simulator (commit 16802e55dea9 ("memblock tests: Add | |
25 | skeleton of the memblock simulator")) and a few preparation commits just | |
26 | before it. Most of them don't match the kernel implementation, so one should | |
27 | consult them first before making any significant changes to the project. | |
28 | ||
29 | Usage | |
30 | ===== | |
31 | ||
32 | To run the tests, build the main target and run it: | |
33 | ||
34 | $ make && ./main | |
35 | ||
04d94909 SH |
36 | A successful run produces no output. It is possible to control the behavior |
37 | by passing options from command line. For example, to include verbose output, | |
38 | append the `-v` options when you run the tests: | |
946dccb3 | 39 | |
04d94909 | 40 | $ ./main -v |
946dccb3 RM |
41 | |
42 | This will print information about which functions are being tested and the | |
43 | number of test cases that passed. | |
44 | ||
04d94909 SH |
45 | For the full list of options from command line, see `./main --help`. |
46 | ||
47 | It is also possible to override different configuration parameters to change | |
48 | the test functions. For example, to simulate enabled NUMA, use: | |
58ffc348 KD |
49 | |
50 | $ make NUMA=1 | |
51 | ||
04d94909 | 52 | For the full list of build options, see `make help`. |
58ffc348 KD |
53 | |
54 | Project structure | |
55 | ================= | |
56 | ||
57 | The project has one target, main, which calls a group of checks for basic and | |
58 | allocation functions. Tests for each group are defined in dedicated files, as it | |
59 | can be seen here: | |
60 | ||
61 | memblock | |
62 | |-- asm ------------------, | |
63 | |-- lib |-- implement function and struct stubs | |
64 | |-- linux ------------------' | |
65 | |-- scripts | |
66 | | |-- Makefile.include -- handles `make` parameters | |
67 | |-- tests | |
68 | | |-- alloc_api.(c|h) -- memblock_alloc tests | |
69 | | |-- alloc_helpers_api.(c|h) -- memblock_alloc_from tests | |
70 | | |-- alloc_nid_api.(c|h) -- memblock_alloc_try_nid tests | |
71 | | |-- basic_api.(c|h) -- memblock_add/memblock_reserve/... tests | |
72 | | |-- common.(c|h) -- helper functions for resetting memblock; | |
73 | |-- main.c --------------. dummy physical memory definition | |
74 | |-- Makefile `- test runner | |
75 | |-- README | |
76 | |-- TODO | |
77 | |-- .gitignore | |
78 | ||
79 | Simulating physical memory | |
80 | ========================== | |
81 | ||
82 | Some allocation functions clear the memory in the process, so it is required for | |
83 | memblock to track valid memory ranges. To achieve this, the test suite registers | |
84 | with memblock memory stored by test_memory struct. It is a small wrapper that | |
85 | points to a block of memory allocated via malloc. For each group of allocation | |
86 | tests, dummy physical memory is allocated, added to memblock, and then released | |
87 | at the end of the test run. The structure of a test runner checking allocation | |
88 | functions is as follows: | |
89 | ||
90 | int 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 | ||
100 | There's no need to explicitly free the dummy memory from memblock via | |
101 | memblock_free() call. The entry will be erased by reset_memblock_regions(), | |
102 | called at the beginning of each test. | |
103 | ||
104 | Known issues | |
105 | ============ | |
106 | ||
107 | 1. Requesting a specific NUMA node via memblock_alloc_node() does not work as | |
108 | intended. Once the fix is in place, tests for this function can be added. | |
109 | ||
110 | 2. Tests for memblock_alloc_low() can't be easily implemented. The function uses | |
111 | ARCH_LOW_ADDRESS_LIMIT marco, which can't be changed to point at the low | |
112 | memory of the memory_block. | |
113 | ||
114 | References | |
115 | ========== | |
116 | ||
117 | 1. Boot time memory management documentation page: | |
118 | https://www.kernel.org/doc/html/latest/core-api/boot-time-mm.html |