doc/index.org

   1 #+TITLE: Fifth - virtual machine, operating system, programming language
   2
   3 * General
   4 - This program is free software: released under Creative Commons Zero
   5   (CC0) license
   6
   7 - Program author:
   8   - Svjatoslav Agejenko
   9   - Homepage: https://svjatoslav.eu
  10   - Email: mailto://svjatoslav@svjatoslav.eu
  11
  12 - [[https://www.svjatoslav.eu/projects/][Other software projects hosted at svjatoslav.eu]]
  13
  14 ** Source code
  15 - [[https://www2.svjatoslav.eu/gitweb/?p=fifth.git;a=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]]
  16
  17 - [[https://www2.svjatoslav.eu/gitweb/?p=fifth.git;a=summary][Browse Git repository online]]
  18
  19 - Clone Git repository using command:
  20   : git clone https://www2.svjatoslav.eu/git/fifth.git
  21
  22 * !Project deprecated!
  23 Current implementation does not support object oriented
  24 programming. While working on Fifth I got lots of cool new ideas that
  25 require reimplementation of everything.
  26
  27 Currently I try to implement those new ideas in the project called
  28 [[https://www3.svjatoslav.eu/projects/sixth/][Sixth]].
  29
  30 System is built many years ago when I was still using DOS as a primary
  31 operating system.
  32 * Introduction
  33 Fifth is a combination of:
  34 - [[id:da7fff9b-0b67-4843-828a-52a404d7f401][Programming language]] (inspired by Forth).
  35 - Operating system.
  36 - [[id:9b251eb9-aff6-4025-94bf-25e89e26d54a][Virtual machine]] with custom instruction set.
  37 - [[file:5TH_ET.txt][Example Fifth source file - text editor]]
  38 ** screenshots
  39 [[file:screenshots/start.png]]
  40
  41 Startup screen diplaying Fifth logo and full file list.
  42
  43 [[file:screenshots/dictionary.png]]
  44
  45 Sample words defined. Most of the words are commands that can be
  46 executed interactively from command line or from file. When executed
  47 they can be selectively compiled or interpreted.
  48
  49
  50 [[file:screenshots/text editor.png]]
  51
  52 Built in text editor.
  53
  54 * Installation
  55 Just unpack all files, witout altering original directory structure,
  56 somewhere in your hard disk. For example: C:\MISC\FIFTH\....  To run
  57 fifth you need minimally just 2 files.  emulator itself ( EMULATOR.EXE
  58 or EMULATOR.COM ), and virtual disk file ( DISK.RAW ).
  59
  60 Read more about [[id:0759f3e0-28bb-4901-9e4f-09ef41732173][Fifth distribution directory tree description]].
  61
  62 * Fifth distribution directory tree description
  63 :PROPERTIES:
  64 :ID:       0759f3e0-28bb-4901-9e4f-09ef41732173
  65 :END:
  66 After downloading and unpacking the ZIP file you shoud get directory
  67 tree similar to this:
  68
  69 #+BEGIN_VERSE
  70 *DOC*                   - Fifth documentation
  71   *commands*            - documentation on Fifth built-in commands
  72   *modules*             - documentation on additional commands, realized as loadable modules
  73   *shots*               - Fifth screenshots
  74
  75 *imageFile*             - files contained within 'disk.raw', just an extracted form.
  76
  77 *source*                - source files
  78   *emulator*            - emulator source
  79   *util*                - utilites
  80
  81 *disk.raw*                - Virtual disk file, has filesystem inside.
  82 *emulator.com*            - main executable.
  83 #+END_VERSE
  84
  85 * Requirements
  86 ** Software
  87 - MS-DOS 6.22, with HIMEM.SYS loaded.
  88 - Mouse driver if you have a mouse.
  89 - Does work only when CPU is in real mode.
  90 - To recompile ASM sources I used FASM (Flat Assembler).
  91 - I ran QBasic utilities on QB 4.5 .
  92 - VESA support by BIOS, or external driver (UNIVBE).
  93 ** Hardware
  94 - Minimum CPU 386.
  95 - 64 KB free RAM below 640KB,
  96 - 2 MB of free XMS.
  97 - VESA compatible video card.
  98 ** Human
  99 - Beginner level Forth knowledge is recommended.
 100 - Lots of enthusiasm.
 101 * Numbers representation within Fifth
 102
 103 Because we are in full experimentation mode here (no regard for
 104 compatibility whatsoever), why not to try also alternative number
 105 representation ?
 106
 107 Here alternative hexadecimal number representation format is devised:
 108
 109 [[file:numbers.png][file:numbers.png]]
 110
 111 Essentially square is split into 4 triangles. Each triangle represents
 112 one bit.
 113
 114 Fifth uses this hexadecimal format as primary throughout entire
 115 system.
 116
 117 See also: [[https://en.wikipedia.org/wiki/Bibi-binary][Bibi-binary]].
 118
 119 * Disk file map, and it's data structures
 120 Core and high-level boot code is stored outside of the filesystem to
 121 allow easy access to it, at early booting time, when filesystem is not
 122 yet initialized.
 123 ** Disk allocation
 124 | offset | length | description          |
 125 |--------+--------+----------------------|
 126 | 0      | ~4 Kb  | Fifth core           |
 127 | 4 Kb   | ~32 Kb | high-level boot code |
 128 | 37 Kb  | ~65 Kb | FAT                  |
 129 | 101 Kb | ~16 MB | filesystem data area |
 130 ** FAT entry format:
 131 | code | meaning                  |
 132 |------+--------------------------|
 133 |   -2 | last sector              |
 134 |   -1 | empty sector             |
 135 | 0 -- | .. pointer to next block |
 136 ** File entry format
 137 | offset | length | description            |
 138 |--------+--------+------------------------|
 139 |      0 |      4 | extension              |
 140 |      4 |     16 | name                   |
 141 |     20 |      4 | entry point            |
 142 |     24 |      4 | size                   |
 143 |     28 |      4 | last modification time |
 144 * Core architecture
 145 Fifth core is simply some amount of already compiled into machine code
 146 and linked together modules (entries in other words). In compilation
 147 process modules is compiled one by one and simply stored on top of
 148 already existing and growing core. Separately from core is kept
 149 dictionary, this is special list that contain names of compiled
 150 modules, variables etc. and they locations in core. Constants use
 151 dictionary space only. Random word can be removed from dictionary at
 152 any time. Currently dictionary can contain at most 1000 entries.
 153 ** Dictionary entry format
 154 | offset | length | description           |
 155 |--------+--------+-----------------------|
 156 |      0 |      4 | 0 &lt; previous entry |
 157 |        |        | 0 = last              |
 158 |        |        | -1 = empty            |
 159 |--------+--------+-----------------------|
 160 |      4 |     15 | module name string    |
 161 |--------+--------+-----------------------|
 162 |     19 |      1 | entry type            |
 163 |--------+--------+-----------------------|
 164 |     20 |      4 | entry data            |
 165
 166 Core headers as linked list of module names make up something like
 167 dictionary.  When some entry address is needed compiler can quickly
 168 run through headers backwards and find needed entry.
 169 ** Possible module types
 170 | type | description    | "execute" action           |
 171 |------+----------------+----------------------------|
 172 |    0 | data           | compile "num" instruction  |
 173 |      |                | with address to module     |
 174 |------+----------------+----------------------------|
 175 |    1 | submodule      | compile "call" instruction |
 176 |      |                | with address to module     |
 177 |------+----------------+----------------------------|
 178 |    2 | imm. submodule | immediately call to module |
 179 ** Memory map
 180 | location | size   | description                 |
 181 |----------+--------+-----------------------------|
 182 |        0 | ~4096  | core                        |
 183 |  1500000 | ~32000 | highlevel Fifth boot code   |
 184 |  200000h |        | core startup messages area  |
 185 |  5200000 |        | end of dynamic memory space |
 186 * Dynamically loadable modules
 187 ** Keyboard driver
 188 #+BEGIN_VERSE
 189
 190 KBD_@           ( -- code ) get scancodes for pressed keys from keyboard.
 191 KBD_down?       ( key -- result ) check is key with specified scancode
 192                 currently pressed down.
 193 KBD_SC2FSCII    ( code -- FSCII ) convert key scancode into FSCII code,
 194                 or in FSK (Fifth standard keycode).
 195 KBD_F@          ( -- FSCII ) read pressed key FSCII or FSK, returns -1 if no
 196                 keys are pressed.
 197 KBD_FW@         ( -- FSCII ) read pressed key FSCII or FSK, if no keys is
 198                 are pressed then waits until there is.
 199
 200                 FSK
 201                 ---
 202 In HEX.
 203
 204 FC      backspace
 205 FD      TAB
 206 FE      enter
 207 FF      space
 208
 209 400     ESC
 210 401 ... F1 ...
 211 410     up
 212 411     right
 213 412     down
 214 413     left
 215 414     INS
 216 415     DEL
 217 416     home
 218 417     end
 219 418     PG/UP
 220 419     PG/DN
 221 #+END_VERSE
 222 ** Mouse driver
 223 #+BEGIN_VERSE
 224 mousex  var     Mouse x coordinate.
 225 mousey  var     Mouse y coordinate.
 226 mousekeyl var   Mouse left key.
 227 mousekeym var   Mouse middle key.
 228 mousekeyr var   Mouse right key.
 229 mousec  var     Display current mouse coordinates in top left part of screen,
 230                 if true. (good for debugging)
 231 mousepointer var  Image buffer, holding current mouse pointer.
 232 mouseadd        ( ModuleAddr x1 x2 y1 y2 -- ) Add specified area on screen,
 233                 into mause click buffer. If any mouse button is clicked on
 234                 that area, module at "ModuleAddr" will be executed.
 235 mousebe var     Amount of buffer elements.
 236 mousedo         ( -- ) Updates mouse coordinates and keys. Parse mouse
 237                 click buffer, and draw mouse cursor to "screen".
 238 #+END_VERSE
 239 ** 2D graphic library
 240
 241 + lineh ( color len x y imgbuf -- ) :: draws horisontal line from X,Y
 242   coordinates to right, with specified length.
 243
 244 + linev ( color len x y imgbuf -- ) :: draws vertical line down, from
 245   coordinates X,Y, with specified length.
 246
 247 + box ( color x2 x1 y2 y1 imgbuf -- ) :: draws rectangular box. x2
 248   bust be >= x1, y2 must be >= y1.
 249
 250   #+begin_example
 251     x1,y1-----------+
 252       |             |
 253       |             |
 254       +-----------x2,y2
 255   #+end_example
 256
 257 + flipv ( imgbuf -- ) :: flip image vertically.
 258
 259 + imgcoltrans ( ImgBuf Color ToColor -- ) :: Translate all pixels in
 260   specified image with "Color" into "ToColor".
 261
 262 + imgfill ( color x y imgbuf -- ) :: Fill image region starting at
 263   location X & Y with specified color.
 264
 265 ** Trigonometry functions
 266 *** sin ( a -- result )
 267 :PROPERTIES:
 268 :ID:       9a66ca9c-eb5f-45aa-8116-71763081f2fb
 269 :END:
 270 Return sinus from given angle "a", 360ø is 2000. So 1000 represents
 271 180ø angle.  Result will be in range -10'000 to 10'000, instead of ñ1.
 272 *** cos ( a -- result )
 273 Return cosinus from given angle.  Parameters are like in [[id:9a66ca9c-eb5f-45aa-8116-71763081f2fb][sin]] function.