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