~vdupras/duskos

1bb10f8bddb861e44d0d8598db23564c49315f3d — Virgil Dupras 15 hours ago b8114d1 master
doc/data: pimp up PSP/RSP description
1 files changed, 12 insertions(+), 7 deletions(-)

M fs/doc/data.txt
M fs/doc/data.txt => fs/doc/data.txt +12 -7
@@ 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