@@ 3,9 3,9 @@
## PSP and RSP
The Parameter Stack and Return Stack are of course fundamental structures in
-Dusk. They are implemented as a registers PSP/RSP beginning at a predefined
-"top" address (PSTOP and RSTOP sysvars) and going down as items are pushed to
-it. Therefore, the register always point to the top item of the stack. When the
+Dusk. They are implemented as registers PSP/RSP beginning at a predefined "top"
+addresses (PSTOP and RSTOP sysvars) and going down as items are pushed to them.
+Therefore, the registers always point to the top item of the stack. When the
register is the same as PSTOP/RSTOP, the stack is empty.
The actual registers assigned to PSP/RSP depend on the CPU. See [doc/hw] for
@@ 16,10 16,15 @@ width. Those stacks are not opaque and their memory can be referenced. For
example, "[]>r" copies an arbitrary range of memory into the Return Stack, while
of course correctly aligning the data to 32-bit.
-On top of this, the Return Stack is more special: on most CPUs, the RSP is also
-the "hardware" stack pointer, where native "calls" push their return address.
-That address is opaque to Forth and should only be "consumed" with HAL's
-"exit," (or CPU-specific assembler of course).
+The Parameter stack has a peculiarity: it has an extra register assigned for
+the top of stack. That's HAL's W register. PSP still indicate stack size, but
+the first item in the stack (PSTOP-4) is "wasted" as it contains whatever the
+W register happened to contain before the first item was pushed to PS.
+
+The Return Stack is also special: on most CPUs, the RSP is also the "hardware"
+stack pointer, where native "calls" push their return address. That address is
+opaque to Forth and should only be "consumed" with HAL's "exit," (or
+CPU-specific assembler of course).
TODO: this paragraph above has been added with the anticipation of an upcoming
amd64 kernel running in 64-bit mode, where RSP push/pop are always 64-bit and