
#
#    Mecrisp-Quintus - A native code Forth implementation for RISC-V
#    Copyright (C) 2018  Matthias Koch
#
#    This program is free software: you can redistribute it and/or modify
#    it under the terms of the GNU General Public License as published by
#    the Free Software Foundation, either version 3 of the License, or
#    (at your option) any later version.
#
#    This program is distributed in the hope that it will be useful,
#    but WITHOUT ANY WARRANTY; without even the implied warranty of
#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#    GNU General Public License for more details.
#
#    You should have received a copy of the GNU General Public License
#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
#


Mecrisp-Quintus: A native code RISC-V Forth, currently for RISC-V 32 IM(C) and MIPS M4K.

HIC SUNT DRACONES - HIC SUNT DRACONES - HIC SUNT DRACONES

This still an early experimental release, so beware: Monsters may be inside !


# -----------------------------------------------------------------------------
  Similarities to Mecrisp-Stellaris and Differences:
# -----------------------------------------------------------------------------

Functionally mostly compatible with Mecrisp-Stellaris,
just with less strong optimisations at this early release.

Everything is 4-aligned, no h, and no c, available.

Shifts decode the lowest 5 bits only on Risc-V.
Therefore, ar/r/lshift behave like "31 and ar/r/lshift".
32 lshift does nothing.

Mecrisp-Quintus makes heavy use of PC-relative calls, which render inlining harmful.
If you port code from Mecrisp-Stellaris, remove "inline" flags.

Specials available in Mecrisp-Quintus which are not found in Mecrisp-Stellaris:

        reset           ( -- ) Soft reboot
        h@signed        ( addr -- n ) Fetch halfword with sign extension
        c@signed        ( addr -- n ) Fetch byte     with sign extension
        addrinflash?    ( addr -- ? ) Location in flash memory ?
        addrinram?      ( addr -- ? ) Location in ram memory ?
        skipdefinition  ( addr -- addr* ) Skip after the next ret opcode
        uj-encoding?    ( x -- bitmask true | x false ) Opcode contruction tool for unconditional jumps
        sb-endocing?    ( x -- bitmask true | x false ) Opcode contruction tool for   conditional jumps
        r.s             ( many -- many R: many -- many ) Prints return stack contents


# -----------------------------------------------------------------------------
  How to assemble:
# -----------------------------------------------------------------------------

You need a few packages which come with Debian 10:

apt-get install binutils-riscv64-linux-gnu binutils-mipsel-linux-gnu qemu-user-static srecord


# -----------------------------------------------------------------------------
  Hacking
# -----------------------------------------------------------------------------

If you replace the definitions in multiplydivide.s it will run on basic RV32I.
Only the low 16 registers are in use, so you can easily change this for RV32E, too.

  x0  : Contains zero. Hardwired in silicon.
  x1  : "Link register", holds link back and is also used to compose long calls with auipc and jalr
  x2  : SP Stack pointer for return stack.
  x3  : Loop index
  x4  : Loop limit
  x5  : Scratch register, needs to be saved.
  x6  : Scratch register, needs to be saved.
  x7  : Scratch register, needs to be saved.
  x8  : TOS Top of data stack.
  x9  : PSP Data stack pointer.
  x10 : Scratch register, needs to be saved.
  x11 : Scratch register, needs to be saved.
  x12 : Scratch register, needs to be saved.
  x13 : Scratch register, needs to be saved.
  x14 : Free scratch register, not saved across calls.
  x15 : Free scratch register, not saved across calls.

  x16 to x31 : Unused in vanilla cores.

  Besides x0=zero, nothing is enforced by hardware on this architecture.

  Acrobatics compiler is using x16 to x25 are free scratch registers, not saved across calls.
