tests: Add tests for the memory allocator

The allocator in NEAlloc.c and NEAlloc.h didn't have tests, which made
it hard to refactor the code.

tests/allocator/Makefile

@@ -0,0 +1,220 @@
+#---------------------------------------------------------------------------------
+.SUFFIXES:
+#---------------------------------------------------------------------------------
+
+ifeq ($(strip $(DEVKITARM)),)
+$(error "Please set DEVKITARM in your environment. export DEVKITARM=<path to>devkitARM")
+endif
+
+include $(DEVKITARM)/ds_rules
+
+#---------------------------------------------------------------------------------
+# TARGET is the name of the output
+# BUILD is the directory where object files & intermediate files will be placed
+# SOURCES is a list of directories containing source code
+# INCLUDES is a list of directories containing extra header files
+# DATA is a list of directories containing binary files embedded using bin2o
+# GRAPHICS is a list of directories containing image files to be converted with grit
+# AUDIO is a list of directories containing audio to be converted by maxmod
+# ICON is the image used to create the game icon, leave blank to use default rule
+# NITRO is a directory that will be accessible via NitroFS
+#---------------------------------------------------------------------------------
+TARGET   := $(shell basename $(CURDIR))
+BUILD    := build
+SOURCES  := source
+INCLUDES := include
+DATA     := data
+GRAPHICS :=
+AUDIO    :=
+ICON     :=
+
+# specify a directory which contains the nitro filesystem
+# this is relative to the Makefile
+NITRO    :=
+
+# These set the information text in the nds file
+GAME_TITLE     := Nitro Engine example
+GAME_SUBTITLE1 := built with devkitARM
+GAME_SUBTITLE2 := http://devitpro.org
+
+#---------------------------------------------------------------------------------
+# options for code generation
+#---------------------------------------------------------------------------------
+ARCH := -marm -mthumb-interwork -march=armv5te -mtune=arm946e-s
+
+CFLAGS   := -g -Wall -O3\
+            $(ARCH) $(INCLUDE) -DARM9
+CXXFLAGS := $(CFLAGS) -fno-rtti -fno-exceptions
+ASFLAGS  := -g $(ARCH)
+LDFLAGS   = -specs=ds_arm9.specs -g $(ARCH) -Wl,-Map,$(notdir $*.map)
+
+#---------------------------------------------------------------------------------
+# any extra libraries we wish to link with the project (order is important)
+#---------------------------------------------------------------------------------
+LIBS := -lNE -lfat -lnds9
+
+# automatigically add libraries for NitroFS
+ifneq ($(strip $(NITRO)),)
+LIBS := -lfilesystem -lfat $(LIBS)
+endif
+# automagically add maxmod library
+ifneq ($(strip $(AUDIO)),)
+LIBS := -lmm9 $(LIBS)
+endif
+
+#---------------------------------------------------------------------------------
+# list of directories containing libraries, this must be the top level containing
+# include and lib
+#---------------------------------------------------------------------------------
+LIBDIRS := $(LIBNDS) $(PORTLIBS) $(DEVKITPRO)/nitro-engine
+
+#---------------------------------------------------------------------------------
+# no real need to edit anything past this point unless you need to add additional
+# rules for different file extensions
+#---------------------------------------------------------------------------------
+ifneq ($(BUILD),$(notdir $(CURDIR)))
+#---------------------------------------------------------------------------------
+
+export OUTPUT := $(CURDIR)/$(TARGET)
+
+export VPATH := $(CURDIR)/$(subst /,,$(dir $(ICON)))\
+                $(foreach dir,$(SOURCES),$(CURDIR)/$(dir))\
+                $(foreach dir,$(DATA),$(CURDIR)/$(dir))\
+                $(foreach dir,$(GRAPHICS),$(CURDIR)/$(dir))
+
+export DEPSDIR := $(CURDIR)/$(BUILD)
+
+CFILES   := $(foreach dir,$(SOURCES),$(notdir $(wildcard $(dir)/*.c)))
+CPPFILES := $(foreach dir,$(SOURCES),$(notdir $(wildcard $(dir)/*.cpp)))
+SFILES   := $(foreach dir,$(SOURCES),$(notdir $(wildcard $(dir)/*.s)))
+PNGFILES := $(foreach dir,$(GRAPHICS),$(notdir $(wildcard $(dir)/*.png)))
+BINFILES := $(foreach dir,$(DATA),$(notdir $(wildcard $(dir)/*.*)))
+
+# prepare NitroFS directory
+ifneq ($(strip $(NITRO)),)
+  export NITRO_FILES := $(CURDIR)/$(NITRO)
+endif
+
+# get audio list for maxmod
+ifneq ($(strip $(AUDIO)),)
+  export MODFILES	:=	$(foreach dir,$(notdir $(wildcard $(AUDIO)/*.*)),$(CURDIR)/$(AUDIO)/$(dir))
+
+  # place the soundbank file in NitroFS if using it
+  ifneq ($(strip $(NITRO)),)
+    export SOUNDBANK := $(NITRO_FILES)/soundbank.bin
+
+  # otherwise, needs to be loaded from memory
+  else
+    export SOUNDBANK := soundbank.bin
+    BINFILES += $(SOUNDBANK)
+  endif
+endif
+
+#---------------------------------------------------------------------------------
+# use CXX for linking C++ projects, CC for standard C
+#---------------------------------------------------------------------------------
+ifeq ($(strip $(CPPFILES)),)
+#---------------------------------------------------------------------------------
+  export LD := $(CC)
+#---------------------------------------------------------------------------------
+else
+#---------------------------------------------------------------------------------
+  export LD := $(CXX)
+#---------------------------------------------------------------------------------
+endif
+#---------------------------------------------------------------------------------
+
+export OFILES_BIN   :=	$(addsuffix .o,$(BINFILES))
+
+export OFILES_SOURCES := $(CPPFILES:.cpp=.o) $(CFILES:.c=.o) $(SFILES:.s=.o)
+
+export OFILES := $(PNGFILES:.png=.o) $(OFILES_BIN) $(OFILES_SOURCES)
+
+export HFILES := $(PNGFILES:.png=.h) $(addsuffix .h,$(subst .,_,$(BINFILES)))
+
+export INCLUDE  := $(foreach dir,$(INCLUDES),-iquote $(CURDIR)/$(dir))\
+                   $(foreach dir,$(LIBDIRS),-I$(dir)/include)\
+                   -I$(CURDIR)/$(BUILD)
+export LIBPATHS := $(foreach dir,$(LIBDIRS),-L$(dir)/lib)
+
+ifeq ($(strip $(ICON)),)
+  icons := $(wildcard *.bmp)
+
+  ifneq (,$(findstring $(TARGET).bmp,$(icons)))
+    export GAME_ICON := $(CURDIR)/$(TARGET).bmp
+  else
+    ifneq (,$(findstring icon.bmp,$(icons)))
+      export GAME_ICON := $(CURDIR)/icon.bmp
+    endif
+  endif
+else
+  ifeq ($(suffix $(ICON)), .grf)
+    export GAME_ICON := $(CURDIR)/$(ICON)
+  else
+    export GAME_ICON := $(CURDIR)/$(BUILD)/$(notdir $(basename $(ICON))).grf
+  endif
+endif
+
+.PHONY: $(BUILD) clean
+
+#---------------------------------------------------------------------------------
+$(BUILD):
+	@mkdir -p $@
+	@$(MAKE) --no-print-directory -C $(BUILD) -f $(CURDIR)/Makefile
+
+#---------------------------------------------------------------------------------
+clean:
+	@echo clean ...
+	@rm -fr $(BUILD) $(TARGET).elf $(TARGET).nds $(SOUNDBANK)
+
+#---------------------------------------------------------------------------------
+else
+
+#---------------------------------------------------------------------------------
+# main targets
+#---------------------------------------------------------------------------------
+$(OUTPUT).nds: $(OUTPUT).elf $(GAME_ICON)
+$(OUTPUT).elf: $(OFILES)
+
+# source files depend on generated headers
+$(OFILES_SOURCES) : $(HFILES)
+
+# need to build soundbank first
+$(OFILES): $(SOUNDBANK)
+
+#---------------------------------------------------------------------------------
+# rule to build solution from music files
+#---------------------------------------------------------------------------------
+$(SOUNDBANK) : $(MODFILES)
+#---------------------------------------------------------------------------------
+	mmutil $^ -d -o$@ -hsoundbank.h
+
+#---------------------------------------------------------------------------------
+%.bin.o %_bin.h : %.bin
+#---------------------------------------------------------------------------------
+	@echo $(notdir $<)
+	@$(bin2o)
+
+#---------------------------------------------------------------------------------
+# This rule creates assembly source files using grit
+# grit takes an image file and a .grit describing how the file is to be processed
+# add additional rules like this for each image extension
+# you use in the graphics folders
+#---------------------------------------------------------------------------------
+%.s %.h: %.png %.grit
+#---------------------------------------------------------------------------------
+	grit $< -fts -o$*
+
+#---------------------------------------------------------------------------------
+# Convert non-GRF game icon to GRF if needed
+#---------------------------------------------------------------------------------
+$(GAME_ICON): $(notdir $(ICON))
+#---------------------------------------------------------------------------------
+	@echo convert $(notdir $<)
+	@grit $< -g -gt -gB4 -gT FF00FF -m! -p -pe 16 -fh! -ftr
+
+-include $(DEPSDIR)/*.d
+
+#---------------------------------------------------------------------------------------
+endif
+#---------------------------------------------------------------------------------------

tests/allocator/source/main.c

@@ -0,0 +1,501 @@
+// SPDX-License-Identifier: CC0-1.0
+//
+// SPDX-FileContributor: Antonio Niño Díaz, 2008-2011, 2019, 2022
+//
+// This file is part of Nitro Engine
+
+// Nitro Engine comes with a general-purpose memory allocator. This file
+// contains several tests for it.
+
+#include <stdio.h>
+
+#include <nds.h>
+
+#include <NEAlloc.h>
+
+#define POOL_START_ADDR     0x1000000
+#define POOL_END_ADDR       0x2000000
+#define POOL_SIZE           (POOL_END_ADDR - POOL_START_ADDR)
+
+#define POOL_START          (void *)POOL_START_ADDR
+#define POOL_END            (void *)POOL_END_ADDR
+
+#define POOL_INITIALIZE()                           \
+    NEChunk *alloc;                                 \
+    NE_AllocInit(&alloc, POOL_START, POOL_END);
+
+#define POOL_DEINITIALIZE()                         \
+    NE_AllocEnd(&alloc);
+
+#define ASSERT(cond)                                \
+    if (!(cond)) {                                  \
+        printf("Line %d\n", __LINE__);              \
+    }
+
+#define ASSERT_MSG(cond, msg)                       \
+    if (!(cond)) {                                  \
+        printf("Line %d: %s\n", __LINE__, msg);     \
+    }
+
+// Pointer to address
+#define A(p) ((uintptr_t)p)
+// Address to pointer
+#define P(a) ((void *)a)
+
+// Test that the pointer advances as expected when allocating memory, and that
+// chunks that are too small are aligned to 16 bytes.
+void test_alloc_align(void)
+{
+    printf("%s\n", __func__);
+
+    POOL_INITIALIZE();
+
+    uintptr_t addr = POOL_START_ADDR;
+    void *ptr;
+
+    ptr = NE_Alloc(alloc, 64);
+    ASSERT(A(ptr) == addr);
+    addr += 64;
+
+    ptr = NE_Alloc(alloc, 32);
+    ASSERT(A(ptr) == addr);
+    addr += 32;
+
+    ptr = NE_Alloc(alloc, 16);
+    ASSERT(A(ptr) == addr);
+    addr += 16;
+
+    ASSERT_MSG(16 == NE_ALLOC_MIN_SIZE, "Unexpected NE_ALLOC_MIN_SIZE");
+
+    ptr = NE_Alloc(alloc, 8);
+    ASSERT(A(ptr) == addr);
+    addr += NE_ALLOC_MIN_SIZE;
+
+    ptr = NE_Alloc(alloc, 4);
+    ASSERT(A(ptr) == addr);
+    addr += NE_ALLOC_MIN_SIZE;
+
+    POOL_DEINITIALIZE();
+}
+
+// Test that a freed chunk can be reused
+void test_free(void)
+{
+    printf("%s\n", __func__);
+
+    POOL_INITIALIZE();
+
+    uintptr_t addr = POOL_START_ADDR;
+
+    void *ptr1 = NE_Alloc(alloc, 256);
+    ASSERT(A(ptr1) == addr);
+    addr += 256;
+
+    void *ptr2 = NE_Alloc(alloc, 256);
+    ASSERT(A(ptr2) == addr);
+
+    // Free the first chunk
+    int ret = NE_Free(alloc, ptr1);
+    ASSERT(ret == 0);
+
+    void *ptr3 = NE_Alloc(alloc, 256);
+    ASSERT(A(ptr3) == A(ptr1));
+
+    POOL_DEINITIALIZE();
+}
+
+// Several tests to lock and unlock chunks
+void test_lock_unlock(void)
+{
+    printf("%s\n", __func__);
+
+    POOL_INITIALIZE();
+
+    uintptr_t addr = POOL_START_ADDR;
+    int ret;
+
+    // Try locking a chunk that is used
+
+    void *ptr = NE_Alloc(alloc, 256);
+    ASSERT(A(ptr) == addr);
+
+    ret = NE_Lock(alloc, ptr);
+    ASSERT(ret == 0);
+
+    // Try to free a locked chunk
+
+    ret = NE_Free(alloc, ptr);
+    ASSERT(ret == -3);
+
+    // Unlock a chunk that is locked
+
+    ret = NE_Unlock(alloc, ptr);
+    ASSERT(ret == 0);
+
+    // Try unlocking a chunk that is used
+
+    ret = NE_Unlock(alloc, ptr);
+    ASSERT(ret == -2);
+
+    // Try unlocking a chunk that has just been freed
+
+    ret = NE_Free(alloc, ptr);
+    ASSERT(ret == 0);
+
+    ret = NE_Unlock(alloc, ptr);
+    ASSERT(ret == -2);
+
+    // Try locking a chunk that has just been freed
+
+    ret = NE_Lock(alloc, ptr);
+    ASSERT(ret == -2);
+
+    // Now, allocate a new chunk that uses half of the memory and lock it. Then,
+    // try to allocate more than half of memory and check it fails.
+
+    ptr = NE_Alloc(alloc, POOL_SIZE / 2);
+    ASSERT(A(ptr) == POOL_START_ADDR);
+
+    ret = NE_Lock(alloc, ptr);
+    ASSERT(ret == 0);
+
+    void *fail = NE_Alloc(alloc, (POOL_SIZE / 2) + 1024);
+    ASSERT(fail == NULL);
+
+    ret = NE_Unlock(alloc, ptr);
+    ASSERT(ret == 0);
+
+    ret = NE_Free(alloc, ptr);
+    ASSERT(ret == 0);
+
+    POOL_DEINITIALIZE();
+}
+
+// Tests to verify that allocation fails under some conditions
+void test_alloc_fail(void)
+{
+    printf("%s\n", __func__);
+
+    POOL_INITIALIZE();
+
+    uintptr_t addr = POOL_START_ADDR;
+    int ret;
+    void *ptr;
+
+    // Try to allocate zero bytes
+
+    ptr = NE_Alloc(alloc, 0);
+    ASSERT(ptr == NULL);
+
+    // Try to allocate the maximum size
+
+    ptr = NE_Alloc(alloc, POOL_SIZE);
+    ASSERT(A(ptr) == addr);
+
+    ret = NE_Free(alloc, ptr);
+    ASSERT(ret == 0);
+
+    // Try to allocate more than the limit
+
+    void *fail = NE_Alloc(alloc, POOL_SIZE + 1);
+    ASSERT(fail == NULL);
+
+    // Fragment the memory pool and try to allocate the remaining space, which
+    // should fail.
+
+    ptr = NE_Alloc(alloc, POOL_SIZE / 4);
+    ASSERT(A(ptr) == addr);
+
+    void *ptr2 = NE_Alloc(alloc, POOL_SIZE / 2);
+    ASSERT(A(ptr2) == (addr + (POOL_SIZE / 4)));
+
+    ret = NE_Free(alloc, ptr);
+    ASSERT(ret == 0);
+
+    NEMemInfo info; // Get information about the remaining free memory
+    ret = NE_MemGetInformation(alloc, &info);
+    ASSERT(ret == 0);
+
+    ASSERT(info.free == (POOL_SIZE / 2));
+
+    fail = NE_Alloc(alloc, info.free);
+    ASSERT(fail == NULL);
+
+    POOL_DEINITIALIZE();
+}
+
+// Test statistics calculation
+void test_statistics(void)
+{
+    printf("%s\n", __func__);
+
+    POOL_INITIALIZE();
+
+    uintptr_t addr = POOL_START_ADDR;
+    int ret;
+
+    const size_t size = POOL_SIZE / 8;
+
+    // Allocate a few chunks
+
+    void *ptr1 = NE_Alloc(alloc, size);
+    ASSERT(A(ptr1) == addr);
+    addr += size;
+
+    void *ptr2 = NE_Alloc(alloc, size);
+    ASSERT(A(ptr2) == addr);
+    addr += size;
+
+    void *ptr3 = NE_Alloc(alloc, size);
+    ASSERT(A(ptr3) == addr);
+    addr += size;
+
+    void *ptr4 = NE_Alloc(alloc, size);
+    ASSERT(A(ptr4) == addr);
+
+    // Free one of them
+
+    ret = NE_Free(alloc, ptr2);
+    ASSERT(ret == 0);
+
+    // Lock one of them
+
+    ret = NE_Lock(alloc, ptr4);
+    ASSERT(ret == 0);
+
+    // Get statistics
+
+    NEMemInfo info;
+    ret = NE_MemGetInformation(alloc, &info);
+    ASSERT(ret == 0);
+
+    ASSERT(info.free == (5 * POOL_SIZE / 8));
+    ASSERT(info.used == (2 * POOL_SIZE / 8));
+    // Note: Locked memory isn't added to the total
+    ASSERT(info.locked == (1 * POOL_SIZE / 8));
+    ASSERT(info.total == (7 * POOL_SIZE / 8));
+
+    ASSERT(info.free_percent == (100 * 5 / 7));
+
+    POOL_DEINITIALIZE();
+}
+
+int count_num_chunks(NEChunk *list)
+{
+    int count = 0;
+
+    for ( ;list != NULL; list = list->next)
+        count++;
+
+    return count;
+}
+
+int verify_consistency(NEChunk *list, void *start, void *end)
+{
+    if (list == NULL)
+        return 0;
+
+    // The first chunk should start at the start of the memory pool
+    if (list->start != start)
+        return -1;
+
+    for ( ; list->next != NULL; list = list->next)
+    {
+        // The end of a chunk should be the start of the next one
+        if (list->end != list->next->start)
+            return -2;
+    }
+
+    // The last chunk should end at the end of the memory pool
+    if (list->end != end)
+        return -3;
+
+    return 0;
+}
+
+// Test that the internal linked list is in the expected state
+void test_internal_list_state(void)
+{
+    NEChunk *alloc;
+    int ret, count;
+
+    // Test with invalid linked list
+
+    ret = NE_AllocInit(NULL, POOL_START, POOL_END);
+    ASSERT(ret == -1);
+
+    // Test with switched start and end
+
+    ret = NE_AllocInit(&alloc, POOL_END, POOL_START);
+    ASSERT(ret == -2);
+
+    // Initialize a valid list
+
+    ret = NE_AllocInit(&alloc, POOL_START, POOL_END);
+    ASSERT(ret == 0);
+
+    count = count_num_chunks(alloc);
+    ASSERT(count == 1);
+
+    // Allocate a few chunks
+
+    void *ptr[10];
+    for (int i = 0; i < 10; i++)
+    {
+        ptr[i] = NE_Alloc(alloc, 1024);
+        ASSERT(A(ptr[i]) == POOL_START_ADDR + (1024 * i));
+    }
+
+    count = count_num_chunks(alloc);
+    ASSERT(count == 11); // 10 chunks + chunk with all remaining memory
+
+    // Free the first chunk and then the second one so that it is merged with
+    // the first one.
+
+    ret = NE_Free(alloc, ptr[0]);
+    ASSERT(ret == 0);
+
+    count = count_num_chunks(alloc);
+    ASSERT(count == 11);
+
+    ret = NE_Free(alloc, ptr[1]);
+    ASSERT(ret == 0);
+
+    count = count_num_chunks(alloc);
+    ASSERT(count == 10);
+
+    ret = verify_consistency(alloc, POOL_START, POOL_END);
+    ASSERT(ret == 0);
+
+    // Free the last chunk so that it is merged with the remaining free memory
+
+    ret = NE_Free(alloc, ptr[9]);
+    ASSERT(ret == 0);
+
+    count = count_num_chunks(alloc);
+    ASSERT(count == 9);
+
+    ret = verify_consistency(alloc, POOL_START, POOL_END);
+    ASSERT(ret == 0);
+
+    ret = NE_Free(alloc, ptr[8]); // Do it again to test it
+    ASSERT(ret == 0);
+
+    count = count_num_chunks(alloc);
+    ASSERT(count == 8);
+
+    ret = verify_consistency(alloc, POOL_START, POOL_END);
+    ASSERT(ret == 0);
+
+    // Free two chunks with one chunk the middle. Then, free that chunk and see
+    // if the three chunks are merged into one.
+
+    ret = NE_Free(alloc, ptr[3]);
+    ASSERT(ret == 0);
+    ret = NE_Free(alloc, ptr[5]);
+    ASSERT(ret == 0);
+
+    count = count_num_chunks(alloc);
+    ASSERT(count == 8);
+
+    ret = NE_Free(alloc, ptr[4]);
+    ASSERT(ret == 0);
+
+    count = count_num_chunks(alloc);
+    ASSERT(count == 6);
+
+    ret = verify_consistency(alloc, POOL_START, POOL_END);
+    ASSERT(ret == 0);
+
+    // Deallocate invalid list
+
+    ret = NE_AllocEnd(NULL);
+    ASSERT(ret == -1);
+
+    // Deallocate list correctly
+
+    ret = NE_AllocEnd(&alloc);
+    ASSERT(ret == 0);
+}
+
+// Known random number generator to always generate the same sequence of numbers
+// and make this test reproducible.
+int rand(void)
+{
+    static unsigned long int next = 1;
+    next = next * 1103515245 + 12345;
+    return (unsigned int)(next / 65536) % 32768;
+}
+
+// Stress test
+void test_stress(void)
+{
+    printf("%s\n", __func__);
+
+    POOL_INITIALIZE();
+
+#define NUM_PTRS 32
+
+    int ret;
+    void *ptr[NUM_PTRS];
+
+    for (int i = 0; i < NUM_PTRS; i++)
+        ptr[i] = NULL;
+
+    for (int i = 0; i < 300000; i++)
+    {
+        unsigned int selected = rand() % NUM_PTRS;
+
+        if (ptr[selected] == NULL)
+        {
+            // Unallocated pointer. Allocate it. The number of chunks is too
+            // small to ever fill the memory with this chunk size, so it should
+            // always be allocated.
+
+            size_t size = (rand() & 0x3FFF) + 1;
+
+            void *p = NE_Alloc(alloc, size);
+            ASSERT(p != NULL);
+
+            ptr[selected] = p;
+        }
+        else
+        {
+            // Allocated pointer. Deallocate it.
+            ret = NE_Free(alloc, ptr[selected]);
+            ASSERT(ret == 0);
+            ptr[selected] = NULL;
+        }
+
+        // Verify list every now and then
+        if ((i % 64) == 0)
+        {
+            ret = verify_consistency(alloc, POOL_START, POOL_END);
+            ASSERT(ret == 0);
+        }
+    }
+
+    POOL_DEINITIALIZE();
+}
+
+int main(void)
+{
+    // This test doesn't use Nitro Engine at all. Initialize the default console
+    // of libnds to print the results of the tests.
+    consoleDemoInit();
+
+    test_alloc_align();
+    test_free();
+    test_lock_unlock();
+    test_alloc_fail();
+    test_statistics();
+    test_internal_list_state();
+    test_stress();
+
+    printf("Done!");
+
+    while (1)
+        swiWaitForVBlank();
+
+    return 0;
+}