Palanqin, an ARM Cortex M0 emulator for DOS

Homepage: https://github.com/clausecker/palanqin

Copyright (c) 2020, Robert Clausecker <fuz@fuz.su>

Note

This software is in alpha state. It is not ready for use and the only program known to work with it is Mecrisp Stellaris in the upcoming 2.5.4b release. All of its aspects are subject to change and cannot be expected to remain stable.

Second alpha release

https://github.com/clausecker/palanqin/releases/tag/v0.2

Notable improvements:

• improve emulation speed by 30%

• handle undefined instructions better

• add B705 opcode to execute a DOS interrupt

• add contrib/advent and contrib/stellaris as example software packages to be used with Palanqin

• implement MRS Rd, spec_reg

Examples

An example program is provided in contrib/advent. Make sure a copy of the gcc-arm-embedded toolchain is provided in your PATH and then type

cd contrib/advent; sh build.sh

to compile it. Then, open a DOSBOX in the project root directory and type

PALANQIN CONTRIB\ADVENT\ADVENT.IMG

to run the advent binary.

As another example, a variant of Mecrisp Stellaris adapted for Palanqin is provided in contrib/stellaris. Make sure a copy of the gcc-arm-embedded toolchain is provided in your PATH and then type

cd contrib/stellaris; sh build.sh

to compile it. Forth binaries with some useful words preloaded can then be found in

contrib/stellaris/palanqin/precompiled/stelaqin.bin
contrib/stellaris/palanqin-ra/precompiled/stelaqin.bin

where the ra version has a more sophisticated compiler with register allocation.

Register contents on reset

R0:  program image base address
R1:  memory size
SP: value taken from the vector table
PC: value taken from the vector table

# Memory map

   0x00000000 -- 0x000fffff    program image (adj. to load addr)
   0x10000000 -- 0x100fffff    host memory (unadjusted)
   0x20000000 -- 0x200fffff    same as 0x00000000 -- 0x000fffff
   0x30000000 -- 0x300fffff    same as 0x10000000 -- 0x100fffff
   0x40000000 -- 0x400fffff    8086 IO address space
   0xe0000000 -- 0xe00fffff    emulated PPB
   0xf0000000 -- 0xf00fffff    emulator escape hatches

The Cortex M0 program image is loaded right after 256 bytes of emulator stack space and extends all the way to the end of the program. Address translation is performed by the emulator such that emulated addresses 0x00000000 seen by ARM code corresponds to the load address of the program.

The PPB and escape hatches aren’t implemented yet. This memory map is subject to change.

Escape hatches

The otherwise undefined instructions 0xb700 – 0xb7ff are used to interact with the host system. Escape hatch opcodes that aren’t currently implemented behave like an undefined instruction.

????

Perform a host software interrupt. On entry, the 8086 registers are set up as described below. On exit from the interrupt handler, the 8086 register values are copied into the ARM registers.

R0: AX
R1: CX
R2: DX
R3: BX
R4: SP (exit only)
R5: BP
R6: SI
R7: DI
R8: ES
R9: interrupt number
R10: SS (exit only)
R11: DS
R12: flags (exit only)
SP: unchanged
LR: unchanged
PC: advanced past the SVC instruction

The software interrupt is executed on the host stack; the value given for SS:SP is ignored. The arithmetic flags (NZCV) are translated into x86 flags on entry to the software interrupt. On exit, the flags are translated back into NZCV and also saved into R12.

????

Perform a far call into native code. The behaviour is the same as for BKPT #0xf0, except R9 is taken to contain a far pointer (segment/offset) to the function you want to call. The function is called on the host stack.

????

Perform software interrupts/far calls on the emulated stack. The register usage is as above, except that SS:SP is taken from R10 and R4.

0xb700

Terminate the emulation and return to the host. The contents of R0 are used to form an error level.

0xb701

Print the current register contents to the terminal.

0xb702

Print the low byte of R0 to the console (DOS function 0x02).

0bx703

Read a character from the console without echo (DOS function 0x08). High ASCII characters are returned with 0x100 added to the character code.

0xb704

Check for the availability of a keystroke. Return -1 or 0 in R0 to indicate if a keystroke is available (-1) or not available (0).