equi

commit db589f39045efd61ecd2bbdc7ec670d23c090021
parent 3c24cccd9d9b467b5f3e6e40f2ed1e449cb5d810
Author: Luxferre <lux@ferre>
Date:   Sat,  6 Aug 2022 08:19:09 +0300

Fixed readme in terms of real RAM layout and how to compile on cc

Diffstat:
M
equi.c
 | 
3
++-
M
equi.md
 | 
40
++++++++++++++++++++++++++++++++--------

2 files changed, 34 insertions(+), 9 deletions(-)
diff --git a/equi.c b/equi.c
@@ -89,13 +89,14 @@ struct EquiRAM {
   ushort pc; /* program counter */
   ushort msp; /* main stack pointer */
   ushort rsp; /* return stack pointer */
+  uchar lsp; /* literal stack pointer */
   ushort cbp; /* compilation buffer pointer */
   ushort cltp; /* compilation lookup table pointer */
   struct EquiFlags flags;
   ushort gpd_start;
   ushort cmd_start;
   ushort cmd_size;
-  uchar reserved[207]; /* reserved space */
+  uchar reserved[206]; /* reserved space */
   struct CLTEntry clt[CLT_ENTRIES_MAX]; /* compilation lookup table */
   uchar gpd[GPD_AREA_SIZE];
   uchar cmdbuf[CMD_BUF_SIZE];
diff --git a/equi.md b/equi.md
@@ -32,13 +32,16 @@ Address range|Size (bytes)|Purpose
 0x0100-0x01ff|256         |Return stack
 0x0200-0x021f|32          |Literal stack
 0x0220-0x0221|2           |PC
-0x0222-0x0223|2           |CBP
-0x0224-0x0225|2           |CLTP
-0x0226       |1           |Flags (II/CM/IM)
-0x0227-0x0228|2           |GPD area start (set to 0x2300 by default)
-0x0229-0x022a|2           |Command buffer start (set to 0x5000 by default)
-0x022b-0x022c|2           |Command buffer size (set to 0x5700 by default)
-0x0227-0x02ff|211         |Reserved for internal usage by the interpreter and future extensions
+0x0222-0x0223|2           |MSP (main stack pointer)
+0x0224-0x0225|2           |RSP (return stack pointer)
+0x0226       |1           |LSP (literal stack pointer)
+0x0227-0x0228|2           |CBP (compilation buffer pointer)
+0x0229-0x022a|2           |CLTP (compilation lookup table pointer)
+0x022b       |1           |Flags (II/CM/IM)
+0x022c-0x022d|2           |GPD area start (set to 0x2300 by default)
+0x022e-0x022f|2           |Command buffer start (set to 0x5000 by default)
+0x0230-0x0231|2           |Command buffer size (set to 0x5700 by default)
+0x0232-0x02ff|206         |Reserved for internal usage by the interpreter and future extensions
 0x0300-0x22ff|8192        |Compilation lookup table (CLT) - up to 1024 compiled words (6 bytes for literal + 2 bytes for CBP address each) by default
 0x2300-0x4fff|11520       |General purpose data (GPD) area
 0x5000-0xa6ff|22272       |Command buffer area
@@ -129,6 +132,27 @@ Being a purely PC-oriented low-level runtime/programming environment, Equi has t
 - doesn't fully implement `P` instruction but instead outputs its parameters to the standard error stream and puts three 0x0000 values back onto the stack,
 - sandboxes the `{` and `}` operations using the file you supply in the command-line parameter. If you don't supply the file, these operations will effectively do nothing except putting 0x0000 (success status) onto the stack.
 
-The source code file should compile using any mainstream C compiler with C89 support, like GCC/DJGPP, Clang, TCC etc. However, it is also being developed to be compilable with CC65 compiler for targets like Apple II or Atari 800. All the machine/target specific configuration is done at compile time, using compiler command-line switches. Here are the instructions to build Equi using different known C compilers:
+The source code file should compile using any mainstream C compiler with C89 support, like GCC/DJGPP, Clang, TCC etc. However, it is also being developed to be compilable with CC65 compiler for targets like Apple II or Atari 800. All the machine/target specific configuration is done at compile time, using compiler command-line switches. Here are the instructions to build Equi using different known C compilers.
 
+The following constants can be adjusted at compile time:
+
+- `STACK_SIZE` - main and return stacks size in bytes (65535 max);
+- `LIT_STACK_SIZE` - literal stack size in bytes (255 max);
+- `GPD_AREA_START` - GPD area start address in the virtual RAM;
+- `CMD_BUF_START` - command buffer start address in the virtual RAM;
+- `CMD_BUF_SIZE` - command buffer size in bytes (65535 max);
+
+### Building with GCC/Clang/MinGW (for current mainstream targets)
+
+Build with default parameters:
+
+```
+cc --std=c89 -Os -o equi equi.c
+```
+
+Build with reconfiguring the defaults - specify any of the above constants after `-D` switch:
+
+```
+cc --std=c89 -Os [-DSTACK_SIZE=... ...] -o equi equi.c
+```