Author: Virgil Dupras <firstname.lastname@example.org>
Date: Tue, 27 Jun 2023 11:33:33 -0400
doc: add alignment discipline section
1 file changed, 31 insertions(+), 0 deletions(-)
diff --git a/fs/doc/usage.txt b/fs/doc/usage.txt
@@ -492,6 +492,37 @@ considered in your search.
Then, look in doc/dict. If it's in there, then it's either defined in the native
kernel code or in xcomp/bootlo.fs.
+## Alignment discipline
+Some platforms that Dusk OS runs on (ARM) have restrictions with regards to
+unaligned memory access: 16-bit memory access have to be done on even addresses
+and 32-bit ones have to be done on addresses divisible by 4.
+This imposes what we call an "alignment discipline" on all of Dusk OS' code.
+The biggest unalignment source is already handled by the kernel: all new
+dictionary entries are always created aligned. Therefore, whenever to use
+"create" or "value" or other such words, you don't have to worry about whether
+However, in some cases, you do have to worry about alignment as an operator:
+"here" is not always aligned! For example, starting from an aligned "here",
+ ," foo"
+results in "here" becoming unaligned because 3 bytes were written.
+This type of situations mostly arises in structs' ":new" methods, but can arise
+in other contexts too.
+Therefore, the general rule is that when you're about to access memory related
+to here in 16-bit or 32-bit mode, you need to align "here". You can do so with
+the "align4" word, but there's also the shortcut "here#" which aligns "here" and
+then yield it.
+Therefore, the general rule of thumb is: use "here#" instead of "here".
## What now?
This document covers Dusk's basic functionalities. You can try a few things in