Enable customizing PageShift to set PageSize for embedded targets (#19129)

* Enable customizing PageSize (via PageShift).

This enables adjusting PageSize for embedded targets without abusing
cpu16.

* copy nimPageXYZ settings for mmpaptest

* add docs for Nim manual

* add docs for Nim manual

* docs tweaks

Co-authored-by: Jaremy Creechley <jaremy.creechley@panthalassa.com>

doc/nimc.rst

@@ -656,6 +656,30 @@ is not available but C's `malloc` is. You can use the `nimAllocPagesViaMalloc`
 define to use `malloc` instead of `mmap`. `nimAllocPagesViaMalloc` is currently
 only supported with `--gc:arc` or `--gc:orc`. (Since version 1.6)
 
+nimPage256 / nimPage512 / nimPage1k
+===================================
+
+Adjust the page size for Nim's GC allocator. This enables using
+`nimAllocPagesViaMalloc` on devices with less RAM. The default
+page size requires too much RAM to work.
+
+Recommended settings:
+
+- < 32 kB of RAM use `nimPage256`
+
+- < 512 kB of RAM use `nimPage512`
+
+- < 2 MB of RAM use `nimPage1k`
+
+Initial testing hasn't shown much difference between 512B or 1kB page sizes
+in terms of performance or latency. Using `nimPages256` will limit the
+total amount of allocatable RAM.
+
+nimMemAlignTiny
+===============
+
+Sets `MemAlign` to `4` bytes which reduces the memory alignment
+to better match some embedded devices.
 
 Nim for realtime systems
 ========================

lib/system/bitmasks.nim

@@ -10,14 +10,18 @@
 # Page size of the system; in most cases 4096 bytes. For exotic OS or
 # CPU this needs to be changed:
 const
-  PageShift = when defined(cpu16): 8 else: 12 # \
+  PageShift = when defined(nimPage256) or defined(cpu16): 8
-    # my tests showed no improvements for using larger page sizes.
+              elif defined(nimPage512): 9
+              elif defined(nimPage1k): 10
+              else: 12 # \ # my tests showed no improvements for using larger page sizes.
+
   PageSize = 1 shl PageShift
   PageMask = PageSize-1
 
 
   MemAlign = # also minimal allocatable memory block
-    when defined(useMalloc):
+    when defined(nimMemAlignTiny): 4
+    elif defined(useMalloc):
       when defined(amd64): 16 
       else: 8
     else: 16

tests/mmaptest.nim

@@ -19,8 +19,11 @@ proc `+!!`(p: pointer, size: int): pointer {.inline.} =
   result = cast[pointer](cast[int](p) + size)
 
 const
-  PageShift = when defined(cpu16): 8 else: 12 # \
+  PageShift = when defined(nimPage256) or defined(cpu16): 8
-    # my tests showed no improvements for using larger page sizes.
+              elif defined(nimPage512): 9
+              elif defined(nimPage1k): 10
+              else: 12 # \ # my tests showed no improvements for using larger page sizes.
+
   PageSize = 1 shl PageShift
 
 var p = osAllocPages(3 * PageSize)