Palanqin, an ARM Cortex M0 emulator for DOS
Copyright (c) 2020, Robert Clausecker <fuz@fuz.su>
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.
# 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.
B705
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).