DuckStack is a simple stack-based bytecode VM for executing compiled duckyScript binaries.

duckyPad uses it for HID macro scripting.

• 32-Bit Data Path, 16-bit Addressing.
• Shared Executable & Stack Region
• Variable-length Instructions
• Functions with Arguments, Locals, & Recursions.
• HID-specific Instructions

• Architecture Overview
  • Memory Maps
• Instruction Set
• String Encoding
• Printing Variables
• Run-time Exceptions
• Calling Convention
• Standalone Compiler

duckStack uses 32-bit variables, arithmetics, and stack width.

Addressing is 16-bit, executable 64KB max.

• Single Data Stack
• Flat memory map
• Byte-addressed
• Program Counter (PC)
  • 16-bit byte-addressed
• Stack Pointer (SP)
  • 16-bit byte-addressed
  • Points to the next free stack slot
• Frame Pointer (FP)
  • Points to current function base frame

• Binary executable is loaded at 0x0
• Stack grows from 0xEFFF towards smaller address
  • Each item 4 bytes long
  • In actual implementation, SP can be 4-byte aligned for better performance.
• Smaller executable allows larger stack, vise versa.

• Similar to duckyPad Pro
  • Just with less usable space due to limited RAM

Variable-length between 1 to 5 bytes.

• First byte (Byte 0): Opcode.
• Byte 1 - 4: Optional payload.
• ⚠️ All multi-byte payloads are Little-endian

• 1 stack item = 4 bytes
• PUSHR / POPR Offset is a byte-addressed signed 16-bit integer
  • Positive: Towards larger address / Base of Stack
  • Negative: Towards smaller address / Top of Stack (TOS)

• All single-byte instructions

• Pop ONE item off TOS as ADDR
  • Then...

• Pop TWO item off TOS
  • First ADDR, then VAL
  • Then...

Binary as in involving two operands.

• All single-byte instructions
• Pop TWO items off TOS
  • First item: Left-hand-side
  • Second item: Right-hand-side
• Perform operation
• Push result back on TOS

• All single-byte instructions
• Pop ONE items off TOS
• Perform operation
• Push result back on TOS

• All single-byte instructions

The following commands involves user-provided strings:

• STRING/ STRINGLN
• OLED_PRINT / OLED_CPRINT
• GOTO_PROFILE
• PUTS()

Strings are zero-terminated and appended at the end of the binary executable.

The starting address of a string is pushed onto stack before calling one of those commands, who pops off the address and fetch the string there.

Identical strings are deduplicated and share the same address.

STRING Hello World!
STRINGLN Hello World!
OLED_PRINT Hi there!

3    PUSHC16   16    0x10          ;STRING Hello World!
6    STR                           ;STRING Hello World!
7    PUSHC16   16    0x10          ;STRINGLN Hello World!
10   STRLN                         ;STRINGLN Hello World!
11   PUSHC16   29    0x1d          ;OLED_PRINT Hi there!
14   OLED_PRNT                     ;OLED_PRINT Hi there!
15   HALT
16   DATA: b'Hello World!\x00'
29   DATA: b'Hi there!\x00'

When printing a variable, its info is embedded into the string between two separator bytes.

• 0x1f for Global Variables
  • Contains: Little-endian memory address
  • [0x1f][ADDR_LSB][ADDR_MSB][Format Specifiers][0x1f]
• 0x1e for Local variables & arguments inside functions
  • Contains: FP-Relative Offset
  • [0x1e][OFFSET_LSB][OFFSET_MSB][Format Specifiers][0x1e]

VAR foo = 255
STRING Count is: $foo%02x

3    PUSHC16   255   0xff          ;VAR foo = 255
6    POPI      63488 0xf800        ;VAR foo = 255
9    PUSHC16   14    0xe           ;STRING Count is: $foo%02x
12   STR                           ;STRING Count is: $foo%02x
13   HALT                          
14   DATA: b'Count is: \x1f\x00\xf8%02x\x1f\x00'

Exceptions such as Division-by-Zero, Stack Over/Underflow, etc, result in immediate termination of the VM execution.

• Multiple arguments, one return value.
• Supports nested and recursive calls
• TOS grows towards smaller address

Outside function calls, FP points to base of stack.

When calling a function: foo(a, b, c)

• Caller pushes 32-bit arguments right to left to stack
  • Don't push if no args.

Caller then executes CALL instruction, which:

• Constructs a 32b value frame_info
  • Top 16b: current_FP
  • Bottom 16b: return_address
• Pushes frame_info to TOS
• Sets FP to TOS
• Jumps to the function address

Once in function, callee uses ALLOC n to make space for local variables.

To reference arguments and locals, FP + Byte_Offset is used.

• Negative offset towards smaller address / TOS / locals.
  • FP - 4 points to first local, etc
• Positive offset towards larger address / base of stack / args.
  • FP + 4 points to leftmost argument, etc
• Use PUSHR + Offset and POPR + Offset to read/write to args and locals.

At end of a function, return_value is on TOS.

• If no explicit RETURN statement, 0 is returned.

Callee executes RET n instruction, which:

• Pops off return_value into temp location
• Pop off items until frame_info is on TOS
  • AKA SP + 4 == FP
• Pops off frame_info
  • Loads previous FP into FP
  • Loads return address into PC
• Pops off n arguments
• Pushes return_value back on TOS
• Resumes execution at PC
• Return value now on TOS for caller to use

Normally, duckyScript compilation is taken care of in the configurator.

But of course you can also try a standalone version below.

• Download / clone this repo
• Prepare a duckyScript source file test.txt
  • Learn More: Writing duckyScript
• In ds_compiler directory, run:

python3 ./dsvm_make_bytecode.py test.txt test.dsb

A minimal C-based VM is provided. Based on real duckyPad firmware, but uses placeholders for hardware commands.

In ds_c_vm folder, run python3 ./compile.py to compile the source. (Or write your own Makefile)

Run the VM: ./main test.dsb

Set PRINT_DEBUG to 1 in main.h for execution and stack trace.

Please feel free to open an issue, ask in the official duckyPad discord, or email dekuNukem@gmail.com!