some notes about array alignment

docs/source/syntaxreference.rst

@@ -134,7 +134,9 @@ Directives
     - ``force_output`` (in a block) will force the block to be outputted in the final program.
       Can be useful to make sure some data is generated that would otherwise be discarded because the compiler thinks it's not referenced (such as sprite data)
     - ``align_word`` (in a block) will make the assembler align the start address of this block on a word boundary in memory (so, an even memory address).
+      Warning: if you use this to align array variables in the block, these have to be initialized with a value to make them stay in the block and get aligned properly. Otherwise they'll end up at a random spot in the BSS section and the alignment doesn't apply there.
     - ``align_page`` (in a block) will make the assembler align the start address of this block on a page boundary in memory (so, the LSB of the address is 0).
+      Warning: if you use this to align array variables in the block, these have to be initialized with a value to make them stay in the block and get aligned properly. Otherwise they'll end up at a random spot in the BSS section and the alignment doesn't apply there.
     - ``merge`` (in a block) will merge this block's contents into an already existing block with the same name. Useful in library scenarios.
     - ``splitarrays`` (block or module) makes all word-arrays in this scope lsb/msb split arrays (as if they all have the @split tag). See Arrays.
     - ``no_symbol_prefixing`` (block) makes the compiler *not* use symbol-prefixing when translating prog8 code into assembly.

docs/source/technical.rst

@@ -18,6 +18,9 @@ it won't actually increase the size of the resulting program binary.
 Prog8 takes care of properly filling this memory area with zeros at program startup and then reinitializes
 the subset of variables that have a nonzero initialization value.
 
+Arrays with initialization values are not put into BSS but just occupy a sequence of bytes in
+the program memory: their values are not reinitialized at program start.
+
 It is possible to relocate the BSS section using a compiler option
 so that more system ram is available for the program code itself.
 

docs/source/todo.rst

@@ -35,7 +35,7 @@ Compiler:
     - OR.... make all this more generic and use some %segment option to create real segments for 64tass?
     - (need separate step in codegen and IR to write the "golden" variables)
 
-- need variable alignment tag instead of block alignment tag, you want to align the data not the code in the block perse
+- do we need (array)variable alignment tag instead of block alignment tag? You want to align the data, not the code in the block?
 - ir: block alignment doesn't translate well to variables in the block (the actual stuff that needs to be aligned in memory)  but: need variable alignment tag instead of block alignment tag, really
 - ir: idea: (but LLVM IR simply keeps the variables, so not a good idea then?...): replace all scalar variables by an allocated register. Keep a table of the variable to register mapping (including the datatype)
   global initialization values are simply a list of LOAD instructions.