duskos

dusk os fork
git clone git://git.alexwennerberg.com/duskos
Log | Files | Refs | README | LICENSE

commit ce549e15e3e655b0f460039d251a737c5421f176
parent ac9dde7d06f3fb9bf01006894cd19b64cbcc15d0
Author: Virgil Dupras <hsoft@hardcoded.net>
Date:   Tue, 27 Jun 2023 11:33:33 -0400

doc: add alignment discipline section

Diffstat:
Mfs/doc/usage.txt | 31+++++++++++++++++++++++++++++++
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 +you're aligned. + +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", +this code: + + ," 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