Re: [PATCH 1/3] memblock tests: update style of comments for memblock_add_*() functions

[David Hildenbrand <david@redhat.com>]

On 20.04.22 13:19, Rebecca Mckeever wrote:
> Update comments in memblock_add_*() functions to match the style used
> in tests/alloc_*.c by rewording to make the expected outcome more apparent
> and, if more than one memblock is involved, adding a visual of the
> memory blocks.
> 
> Signed-off-by: Rebecca Mckeever <remckee0@gmail.com>
> ---
>  tools/testing/memblock/tests/basic_api.c | 75 +++++++++++++++++-------
>  1 file changed, 54 insertions(+), 21 deletions(-)
> 
> diff --git a/tools/testing/memblock/tests/basic_api.c b/tools/testing/memblock/tests/basic_api.c
> index fbc1ce160303..cdf112d25343 100644
> --- a/tools/testing/memblock/tests/basic_api.c
> +++ b/tools/testing/memblock/tests/basic_api.c
> @@ -26,8 +26,8 @@ static int memblock_initialization_check(void)
>  /*
>   * A simple test that adds a memory block of a specified base address
>   * and size to the collection of available memory regions (memblock.memory).
> - * It checks if a new entry was created and if region counter and total memory
> - * were correctly updated.
> + * Expect to create a new entry. The region counter and total memory get
> + * updated.
>   */
>  static int memblock_add_simple_check(void)
>  {
> @@ -55,8 +55,8 @@ static int memblock_add_simple_check(void)
>  /*
>   * A simple test that adds a memory block of a specified base address, size
>   * NUMA node and memory flags to the collection of available memory regions.
> - * It checks if the new entry, region counter and total memory size have
> - * expected values.
> + * Expect to create a new entry. The region counter and total memory get
> + * updated.
>   */
>  static int memblock_add_node_simple_check(void)
>  {
> @@ -87,9 +87,15 @@ static int memblock_add_node_simple_check(void)
>  
>  /*
>   * A test that tries to add two memory blocks that don't overlap with one
> - * another. It checks if two correctly initialized entries were added to the
> - * collection of available memory regions (memblock.memory) and if this
> - * change was reflected in memblock.memory's total size and region counter.
> + * another:
> + *
> + *  |        +--------+        +--------+  |
> + *  |        |   r1   |        |   r2   |  |
> + *  +--------+--------+--------+--------+--+
> + *
> + * Expect to add two correctly initialized entries to the collection of
> + * available memory regions (memblock.memory). The total size and
> + * region counter fields get updated.
>   */
>  static int memblock_add_disjoint_check(void)
>  {
> @@ -125,10 +131,20 @@ static int memblock_add_disjoint_check(void)
>  
>  /*
>   * A test that tries to add two memory blocks, where the second one overlaps
> - * with the beginning of the first entry (that is r1.base < r2.base + r2.size).
> - * After this, it checks if two entries are merged into one region that starts
> - * at r2.base and has size of two regions minus their intersection. It also
> - * verifies the reported total size of the available memory and region counter.
> + * with the beginning of the first entry (that is r1.base < r2.base + r2.size):
> + *
> + *  |    +----+----+------------+          |
> + *  |    |   r|2   |   r1       |          |
> + *  +----+----+----+------------+----------+
> + *       ^    ^
> + *       |    |
> + *       |    r1.base
> + *       |
> + *       r2.base
> + *
> + * Expect to merge the two entries into one region that starts at r2.base
> + * and has size of two regions minus their intersection. The total size of
> + * the available memory is updated, and the region counter stays the same.
>   */
>  static int memblock_add_overlap_top_check(void)
>  {
> @@ -163,11 +179,20 @@ static int memblock_add_overlap_top_check(void)
>  
>  /*
>   * A test that tries to add two memory blocks, where the second one overlaps
> - * with the end of the first entry (that is r2.base < r1.base + r1.size).
> - * After this, it checks if two entries are merged into one region that starts
> - * at r1.base and has size of two regions minus their intersection. It verifies
> - * that memblock can still see only one entry and has a correct total size of
> - * the available memory.
> + * with the end of the first entry (that is r2.base < r1.base + r1.size):
> + *
> + *  |  +--+------+----------+              |
> + *  |  |  | r1   | r2       |              |
> + *  +--+--+------+----------+--------------+
> + *     ^  ^
> + *     |  |
> + *     |  r2.base
> + *     |
> + *     r1.base
> + *
> + * Expect to merge the two entries into one region that starts at r1.base
> + * and has size of two regions minus their intersection. The total size of
> + * the available memory is updated, and the region counter stays the same.
>   */
>  static int memblock_add_overlap_bottom_check(void)
>  {
> @@ -203,9 +228,17 @@ static int memblock_add_overlap_bottom_check(void)
>  /*
>   * A test that tries to add two memory blocks, where the second one is
>   * within the range of the first entry (that is r1.base < r2.base &&
> - * r2.base + r2.size < r1.base + r1.size). It checks if two entries are merged
> - * into one region that stays the same. The counter and total size of available
> - * memory are expected to not be updated.
> + * r2.base + r2.size < r1.base + r1.size).
> + *
> + *  |   +-------+--+-----------------------+
> + *  |   |       |r2|      r1               |
> + *  +---+-------+--+-----------------------+
> + *      ^
> + *      |
> + *      r1.base
> + *
> + * Expect to merge two entries into one region that stays the same.
> + * The counter and total size of available memory are not updated.
>   */
>  static int memblock_add_within_check(void)
>  {
> @@ -236,8 +269,8 @@ static int memblock_add_within_check(void)
>  }
>  
>  /*
> - * A simple test that tries to add the same memory block twice. The counter
> - * and total size of available memory are expected to not be updated.
> + * A simple test that tries to add the same memory block twice. Expect
> + * the counter and total size of available memory to not be updated.
>   */
>  static int memblock_add_twice_check(void)
>  {

Reviewed-by: David Hildenbrand <david@redhat.com>

-- 
Thanks,

David / dhildenb