@@ 1,7 1,7 @@
# Harmonized Assembly Layer
The Harmonized Assembly Layer is a set of words implemented by all assemblers
-which have the same semantics and compile native code that have consistent
+which have the same semantics and compile native code that has consistent
results on all architectures. For example, "RSP) 2 +) 16b) +," will, on all
arches, compile a set of instructions that will result in the 16-bit addition
of RSP+2 into the Work register. On i386, this is the same as
@@ 15,7 15,7 @@ binary space compared to direct assembler instructions, but in general, the
result is pretty good and direct assembler should be needed only in the tightest
of the loops.
-At boot, bare Dusk system only has the Low HAL (see below) loaded. If you want
+At boot, a bare Dusk system only has the Low HAL (see below) loaded. If you want
to load the High HAL, do "f<< asm/hal.fs". The will load the assembler for the
native architecture.
@@ 23,15 23,15 @@ native architecture.
### Low vs High
-The core code of DuskCC is implemented in HAL. If you look at xcomp/bootlo,
-you'll see tons of HAL references. This allows core words to be fast without
-having to implement them natively for each supported architecture.
+Dusk's core is implemented in HAL. If you look at xcomp/bootlo, you'll see tons
+of HAL references. This allows core words to be fast without having to implement
+them natively for each supported architecture.
This means that the HAL has to be implemented at the *kernel* level, a concept
which is completely wicked: the kernel isn't only a kernel, it's an assembler
implemented in native code.
-The HAL, however, contains many concepts that aren't needed for xcomp/bootlo and
+The HAL, however, contains many features that aren't needed for xcomp/bootlo and
that if they were to be implemented in native code within the kernel, would
represent a burden too heavy to be worth it.
@@ 52,7 52,7 @@ example, on i386, W=eax A=edi PSP=esi and RSP=esp.
### W and A registers
-The HAL operate over 3 main locations: the W register, the A register, and
+The HAL mainly operates over 3 locations: the W register, the A register, and
memory addresses.
The W register is the "work" register and the default destination of all HAL
@@ 85,13 85,13 @@ operand (see below) can we refer directly to a value in a register.
### &) operand modifier
The &) word takes an input operand and returns its reference counterpart. For
-example, m) becomes i), W) becomes W&), etc. This also works with displacements.
-For example, "RSP) 4 +) &)" yields an operand that points to RSP+4.
+example, m) becomes i), W) becomes a direct reference to W, etc. This also works
+with displacements. For example, "RSP) 4 +) &)" yields an operand that points
+to RSP+4.
This operand might not be adressable directly by the host CPU. In that case, the
HAL operator will compile two instructions. For example, "RSP) 4 +) &) +," under
-i386 would yield "bx sp 4 +) lea, ax bx add,". Only RSP) and PSP) can be
-referenced with displacement.
+i386 would yield "bx sp 4 +) lea, ax bx add,".
The "&)" word never writes instructions directly, only operator words. The
"lea," above wouldn't be written when "&)" is called, but when "+," is.
@@ 112,13 112,13 @@ result directly in address $1234 without affecting W.
"upscaled" to 32-bit with regards to flags settings and carry management
(the C flag is never set in 16b) or 8b) mode).
-This also applies to cmp, which means that, for example,
-"$4242 LIT>W, RSP) 8b) cmp," will never set the Z flag because even if RSP) is
-$42, comparison is done one the whole W register.
+This also applies to compare, which means that, for example,
+"$4242 LIT>W, RSP) 8b) compare," will never set the Z flag because even if RSP)
+is $42, comparison is done one the whole W register.
### Branching and flags
-The HAL can generate branching, conditional or not, throufg its "branch"
+The HAL can generate branching, conditional or not, through its "branch"
instructions. "branchC,", the conditional branching generator, takes a "cond"
argument. This argument is generated by words like "Z)", ">)", etc. and the
number it yields is arch-specific. The idea is that through this number, the
@@ 136,13 136,13 @@ the necessary native instructions to make it so, at the cost of speed. For this
reason, we minimize flag guarantees in HAL words.
Arithmetic conditions (">)", "<=)", etc.) have no associated flag and can only
-be used after a "cmp,".
+be used after a "compare,".
-If you look at branching word signature, you'll notice something weird: the take
-an address parameter and yield an address result. This is because those words
-can be used for both backward branching or forward branching. What they do is to
-write down a branch to the supplied address, but also yield an address to the
-memory location that can then be used by "branch!".
+If you look at branching words signatures, you'll notice something weird: the
+take an address parameter and yield an address result. This is because those
+words can be used for both backward branching or forward branching. What they do
+is to write down a branch to the supplied address, but also yield an address to
+the memory location that can then be used by "branch!".
Therefore, a backward branch looks like "begin .. branch, drop" and a forward
branch looks like "0 branch, .. here swap branch!"
@@ 165,8 165,6 @@ m) addr -- op Absolute address
16b) op -- op Make op 16-bit
32b) op -- op Make op 32-bit (default)
-Maximum displacement in Low HAL: 8-bit
-
Branching and conditions:
Z)
@@ 201,7 199,7 @@ Instructions:
[@], op -- Read indirect source into dest
[!], op -- Write indirect source into dest
compare, op -- Compare source to dest
-[+n], n op -- *Z* Add n to indirect source without affecting dest
+[+n], n op -- *Z* Add n to source without affecting dest
addr, op -- Store the effective address of the operand in dest
ps+, n -- Add n to PSP