00 Title Card

quote, and unquote,

Machine Forth Primitives

For RISC and Position-Independent Architectures

Samuel A. Falvo II <kc5tja@arrl.net>

2024 September 28

01 The Problem

• Working on a new Machine Forth implementation for a virtual RISC-V machine project.
• Not very Forth-like yet; still riddled with lots of assembly language.
• Even for simple programs, the need to embed strings in code is a hard requirement.

    defer, _start

    :, _emit ( n - )
        $2A x0 a7 ori,  ecall,  ;,

    :, .h  CHAR h x0 a0 ori, _emit ;,
    :, .e  CHAR e x0 a0 ori, _emit ;,
    :, .l  CHAR l x0 a0 ori, _emit ;,
    :, .o  CHAR o x0 a0 ori, _emit ;,
    
    :, .hello ( - )
        .h .e .l .l .o cr ;,

    ' .hello >BODY @ is, _start

02 Why

• RISC-V lacks the ability to load any immediate wider than 12 bits in a single instruction.

    ORI Xn,X0,$ABC  ; only 12 bit immediate

• RISC-V lacks the ability to load any immediate wider than 32 bits in two instructions.

    LUI Xn,$ABCDF000    ; Upper 20 bits loaded as immediate
    ADDI Xn,Xn,$F12     ; Lower 12 bits merged in
    ; BTW, why $ABCDF000 and not $ABCDE000?  ;-)

• RISC-V lacks any means of loading a 64-bit immediate whatsoever.
  • Only means of loading a 64-bit constant (such as a memory address, like you’d use to point at a string in memory) is to fetch a 64-bit value already pre-computed and stored in what’s called a constant pool.
  • Or you can synthesize it with >= 2 instructions, which can be faster in some cases.

    AUIPC Xn,ConstantPool-*  ; Xn = PC + (ConstantPool - PC) = ConstantPool
    LD    Xm,offset(Xn)      ; LD = Load Double-word

03 Solution = Work Around

• RISC-V offers the JAL instruction, which records a return address in any arbitrary register.

    JAL X0,branchTarget  ; Unconditional JUMP to branchTarget
    JAL X1,branchTarget  ; Unconditional CALL to branchTarget
    ...
    JAL X31,branchTarget  ; Unconditional CALL to branchTarget

• Use JAL to “skip over” an arbitrary-sized buffer, while simultaneously setting a register to point at the following data.

    JAL X4,forwardLabel
    .word arbitrary-data-goes-here  ; guaranteed 4-byte alignment!
    .byte padding-if-required
forwardLabel:
    ORI X5,X0,size-of-data-goes-here

• The target of the JAL instruction can set another register with the size of the skipped blob.

04 Solution = Work Around

• quote, ( reg - cs-quo ) encodes the initial JAL instruction.
• unquote, ( cs-quo reg - ) encodes the final target and, if reg != 0, calculates the length of the blob skipped.
• AHEAD == 0 quote, (kinda…)
• THEN == 0 unquote, (kinda…)
• It is fully position-independent. RISC-V uses offsets for everything; thus, generated code works anywhere without needing to record relocation records in some loader format.

: defer, ( - )                         : S", ( - )
  CREATE 0 quote, , ( JAL X0,... )       nextReg quote,
  DOES>  @ THERE - ra jal, ;             ( ..place string at HERE.. )
                                         nextReg unquote, ;
: is, ( a - )
  ' >BODY @ SWAP OVER ( aJAL a aJAL )
  -  ( aJAL disp )
  SWAP mergeU ;

05 Implementation

: quote, ( xr -- aJAL )
  ( Jumps AHEAD, except sets xr to point at code immediately following. )
  THERE SWAP 0 SWAP jal, ;
  
: unquote, ( aJAL xr -- )
  ( Resolves prior quote, and sets xr to length of block spanned. )
  OVER THERE SWAP - 4 - ( aJAL xr len; 4 accounts for JAL insn )
  TALIGN >R >R ( aJAL || xr len )
  THERE OVER - ( aJAL disp || xr len )
  OVER mergeU R> R> ( xr len )
  OVER IF
    SWAP x0 SWAP ori,
  ELSE
    2DROP
  THEN ;

06 Why Use Quote and Unquote

• Arbitrary text.

    S", Hello world" _type

• A convenient “code quotation” for callbacks (e.g., consider how a generic sort routine might work, as in C’s standard library).

    vectorAddr vectorLength (<< ( a b - f ) 2DUP U< >>) SortVector
    \     Code quotation ---^-------------------------^

• Reserving up to 4K of space to serve as module-scope state.

:, myState ( - )
  gp quote, /MY-STATE TALLOT TALIGN x0 unquote, ;,

• Implementing DEFER and IS.

07 Alternatives

• AHEAD/THEN
• Used to implement (most) control structures (BEGIN/WHILE/REPEAT, etc.)
• Can also be used to implement DEFER and IS.
• However, neither AHEAD nor THEN produce any values at run-time that you can use to cheaply track a buffer.
• Your compiler code is responsible for tracking enough state to know where and how big a skipped blob is.
• Might work better for CPUs which lack cheap position-independent code mechanisms (e.g., Intel or 68K).

08 The End

Thank you for watching; I’ll be happy to answer questions via the Generalities mailing list.

• Samuel A. Falvo II <kc5tja@arrl.net>
• 2024 September 28