#+TITLE: Fifth - virtual machine, operating system, programming language
------
-- [[http://www2.svjatoslav.eu/gitweb/?p=sixth.git;a=snapshot;h=HEAD;sf=tgz][download latest snapshot]]
-
-- This program is free software; you can redistribute it and/or modify it under
- the terms of version 3 of the [[https://www.gnu.org/licenses/lgpl.html][GNU Lesser General Public License]] or later as
- published by the Free Software Foundation.
+* General
+- This program is free software: released under Creative Commons Zero
+ (CC0) license
- Program author:
- Svjatoslav Agejenko
- - Homepage: http://svjatoslav.eu
+ - Homepage: https://svjatoslav.eu
- Email: mailto://svjatoslav@svjatoslav.eu
-- [[http://svjatoslav.eu/programs.jsp][other applications hosted at svjatoslav.eu]]
-
-* (document settings) :noexport:
-** use dark style for TWBS-HTML exporter
-#+HTML_HEAD: <link href="https://bootswatch.com/darkly/bootstrap.min.css" rel="stylesheet">
-#+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
-#+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.1/js/bootstrap.min.js"></script>"
-#+HTML_HEAD: <style type="text/css">
-#+HTML_HEAD: footer {background-color: #111 !important;}
-#+HTML_HEAD: pre {background-color: #111; color: #ccc;}
-#+HTML_HEAD: </style>
+- [[https://www.svjatoslav.eu/projects/][Other software projects hosted at svjatoslav.eu]]
+
+** Source code
+- [[https://www2.svjatoslav.eu/gitweb/?p=fifth.git;a=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]]
+
+- [[https://www2.svjatoslav.eu/gitweb/?p=fifth.git;a=summary][Browse Git repository online]]
+
+- Clone Git repository using command:
+ : git clone https://www2.svjatoslav.eu/git/fifth.git
+
* !Project deprecated!
Current implementation does not support object oriented
programming. While working on Fifth I got lots of cool new ideas that
require reimplementation of everything.
Currently I try to implement those new ideas in the project called
-[[http://www2.svjatoslav.eu/gitbrowse/sixth/doc/index.html][Sixth]]
+[[https://www3.svjatoslav.eu/projects/sixth/][Sixth]].
System is built many years ago when I was still using DOS as a primary
operating system.
* Introduction
-Fifth is programming lanquage & operating system, running on [[emulator.html][virtual
-CPU]], with custom instruction set. It is much like Charles Chunk
-Moore's Forth, it also uses stack architecture, and many commands are
-similar. Basically I got familiar with concepts of Forth, and being
-inspired created my own system.
+Fifth is a combination of:
+- [[id:da7fff9b-0b67-4843-828a-52a404d7f401][Programming language]] (inspired by Forth).
+- Operating system.
+- [[id:9b251eb9-aff6-4025-94bf-25e89e26d54a][Virtual machine]] with custom instruction set.
+
+** Screenshots
+
+[[file:screenshots/start.png]]
+
+Startup screen diplaying Fifth logo and full file list.
+
+[[file:screenshots/dictionary.png]]
+
+Sample words defined. Most of the words are commands that can be
+executed interactively from the command line or from a file. When
+executed, they can be selectively compiled or interpreted.
+[[file:screenshots/text editor.png]]
-[[shots/index.html][Screenshots]]
+Built in text editor.
-Read more about:
-- [[file:emulator.html][Virtual CPU]]
-- [[file:commands/index.html][Built-in commands]]
-- [[file:modules/index.html][Additional commands, realized as loadable modules]]
-- [[file:5TH_ET.txt][Example Fifth source file - text editor]]
* Installation
Just unpack all files, witout altering original directory structure,
-somewhere in your hard disk. For example: C:\MISC\FIFTH\.... To run
-fifth you need minimally just 2 files. emulator itself ( EMULATOR.EXE
-or EMULATOR.COM ), and virtual disk file ( DISK.RAW ).
-
-Read more about [[files.txt][distribution directory layout]]
-* Software/Hardware/Human requirements
-** Software:
-- MS-DOS 6.22, with HIMEM.SYS loaded.
-- Mouse driver if you have a mouse.
-- Does work only when CPU is in real mode.
-- To recompile ASM sources I used FASM (Flat Assembler).
-- I ran QBasic utilities on QB 4.5 .
-- VESA support by BIOS, or external driver (UNIVBE).
-** Hardware:
-- Minimum CPU 386.
-- 64 KB free RAM below 640KB,
-- 2 MB of free XMS.
-- VESA compatible video card.
-** Human:
-- Beginner level Forth knowledge is recommended.
-- Lots of enthusiasm.
-* Numbers representation
+somewhere in your hard disk. For example:
+
+: C:\MISC\FIFTH\
+
+To run fifth you need minimally just 2 files:
+- EMULATOR.COM :: Virtual CPU emulator
+- DISK.RAW :: Virtual disk file
+
+For more information, please refer to [[id:0759f3e0-28bb-4901-9e4f-09ef41732173][Fifth distribution directory
+tree description]].
+
+* Fifth distribution directory tree description
+:PROPERTIES:
+:ID: 0759f3e0-28bb-4901-9e4f-09ef41732173
+:END:
+After downloading and unpacking the ZIP file you shoud get directory
+tree similar to this:
+
+#+BEGIN_VERSE
+*DOC* - Fifth documentation
+ *commands* - documentation on Fifth built-in commands
+ *modules* - documentation on additional commands, realized as loadable modules
+ *shots* - Fifth screenshots
+
+*imageFile* - files contained within 'disk.raw', just an extracted form.
+
+*source* - source files
+ *emulator* - emulator source
+ *util* - utilites
+
+*disk.raw* - Virtual disk file, has filesystem inside.
+*emulator.com* - main executable.
+#+END_VERSE
+
+* Requirements
+** Software
+- MS-DOS 6.22 with HIMEM.SYS loaded.
+- Mouse driver (optional, if you have a mouse).
+- CPU is initialized into [[https://en.wikipedia.org/wiki/Unreal_mode][Unreal Mode]] during operation.
+- To recompile ASM sources, you can use FASM (Flat Assembler).
+- To run Quick Basic utilities, use Microsoft Quick Basic 4.5.
+- VESA support through BIOS or external driver (UNIVBE).
+
+** Hardware
+- A minimum of a i386 CPU.
+- 64 KB of free RAM below 640KB.
+- 2 MB of free [[https://en.wikipedia.org/wiki/Extended_memory][extended memory]].
+- A VESA-compatible video card.
+
+* Numbers representation within Fifth
+
+Because we are in full experimentation mode here (no regard for
+compatibility whatsoever), why not to try also alternative number
+representation ?
+
+Here alternative hexadecimal number representation format is devised:
[[file:numbers.png][file:numbers.png]]
-Because I can define everything, starting from CPU, why not try also
-alternative and unique number representation ?
+Essentially square is split into 4 triangles. Each triangle represents
+one bit.
-Fifth uses its hexdecimal number representation as primary. Numbers
-shape is formed by dividing a square into four parts. And manipulating
-their color (black or white).
-* Disk file map, and it's data structures
+Fifth uses this hexadecimal format as primary throughout entire
+system.
+See also: [[https://en.wikipedia.org/wiki/Bibi-binary][Bibi-binary]].
+* Disk file map, and it's data structures
Core and high-level boot code is stored outside of the filesystem to
allow easy access to it, at early booting time, when filesystem is not
yet initialized.
-** disk allocation
+** Disk allocation
| offset | length | description |
|--------+--------+----------------------|
| 0 | ~4 Kb | Fifth core |
-| 4 Kb | ~32Kb | high-level boot code |
-| 37 Kb | ~65Kb | FAT |
-| 101Kb | ~16MB | filesystem data area |
+| 4 Kb | ~32 Kb | high-level boot code |
+| 37 Kb | ~65 Kb | FAT |
+| 101 Kb | ~16 MB | filesystem data area |
** FAT entry format:
| code | meaning |
|------+--------------------------|
| -2 | last sector |
| -1 | empty sector |
| 0 -- | .. pointer to next block |
-** file entry format
+** File entry format
| offset | length | description |
|--------+--------+------------------------|
| 0 | 4 | extension |
modules, variables etc. and they locations in core. Constants use
dictionary space only. Random word can be removed from dictionary at
any time. Currently dictionary can contain at most 1000 entries.
-** dictionary entry format
+** Dictionary entry format
| offset | length | description |
|--------+--------+-----------------------|
| 0 | 4 | 0 < previous entry |
| | | with address to module |
|------+----------------+----------------------------|
| 2 | imm. submodule | immediately call to module |
-** Memory map: (average)
-| <loc> | <size> | <desc> |
-|---------+--------+-----------------------------|
-| 0 | ~4096 | core |
-| 1500000 | ~32000 | highlevel Fifth boot code |
-| 200000h | | core startup messages area |
-| 5200000 | | end of dynamic memory space |
-* Fifth source format
-Fifth uses a different character table and codes than ASCII (still
-almost similar). I call it FSCII (Fifth Standard Code for Information
-Interchange) for example space character is not 32 but 255 instead. I
-plan to use mainly HEX numbers, and create new characters to represent
-numeric values. So typical nemric characters "0123..." is treated
-like ordinary letters.
-** FSCII:
-
-| DEC | HEX | function |
-|--------+-------+----------------------------------------|
-| 0 - 15 | 0 - F | HEX numbers |
-| 252 | FC | backspace |
-| 253 | FD | tabulator (TAB) |
-| 254 | FE | carriage return (CR) |
-| 255 | FF | space |
-| else | | ordinary characters, same as in ASCII. |
+** Memory map
+| location | size | description |
+|----------+--------+-----------------------------|
+| 0 | ~4096 | core |
+| 1500000 | ~32000 | highlevel Fifth boot code |
+| 200000h | | core startup messages area |
+| 5200000 | | end of dynamic memory space |
+* Dynamically loadable modules
+** Keyboard driver
+#+BEGIN_VERSE
+
+KBD_@ ( -- code ) get scancodes for pressed keys from keyboard.
+KBD_down? ( key -- result ) check is key with specified scancode
+ currently pressed down.
+KBD_SC2FSCII ( code -- FSCII ) convert key scancode into FSCII code,
+ or in FSK (Fifth standard keycode).
+KBD_F@ ( -- FSCII ) read pressed key FSCII or FSK, returns -1 if no
+ keys are pressed.
+KBD_FW@ ( -- FSCII ) read pressed key FSCII or FSK, if no keys is
+ are pressed then waits until there is.
+
+ FSK
+ ---
+In HEX.
+
+FC backspace
+FD TAB
+FE enter
+FF space
+
+400 ESC
+401 ... F1 ...
+410 up
+411 right
+412 down
+413 left
+414 INS
+415 DEL
+416 home
+417 end
+418 PG/UP
+419 PG/DN
+#+END_VERSE
+** Mouse driver
+#+BEGIN_VERSE
+mousex var Mouse x coordinate.
+mousey var Mouse y coordinate.
+mousekeyl var Mouse left key.
+mousekeym var Mouse middle key.
+mousekeyr var Mouse right key.
+mousec var Display current mouse coordinates in top left part of screen,
+ if true. (good for debugging)
+mousepointer var Image buffer, holding current mouse pointer.
+mouseadd ( ModuleAddr x1 x2 y1 y2 -- ) Add specified area on screen,
+ into mause click buffer. If any mouse button is clicked on
+ that area, module at "ModuleAddr" will be executed.
+mousebe var Amount of buffer elements.
+mousedo ( -- ) Updates mouse coordinates and keys. Parse mouse
+ click buffer, and draw mouse cursor to "screen".
+#+END_VERSE
+** 2D graphic library
+
++ lineh ( color len x y imgbuf -- ) :: draws horisontal line from X,Y
+ coordinates to right, with specified length.
+
++ linev ( color len x y imgbuf -- ) :: draws vertical line down, from
+ coordinates X,Y, with specified length.
+
++ box ( color x2 x1 y2 y1 imgbuf -- ) :: draws rectangular box. x2
+ bust be >= x1, y2 must be >= y1.
+
+ #+begin_example
+ x1,y1-----------+
+ | |
+ | |
+ +-----------x2,y2
+ #+end_example
+
++ flipv ( imgbuf -- ) :: flip image vertically.
+
++ imgcoltrans ( ImgBuf Color ToColor -- ) :: Translate all pixels in
+ specified image with "Color" into "ToColor".
+
++ imgfill ( color x y imgbuf -- ) :: Fill image region starting at
+ location X & Y with specified color.
+
+** Trigonometry functions
+*** sin ( a -- result )
+:PROPERTIES:
+:ID: 9a66ca9c-eb5f-45aa-8116-71763081f2fb
+:END:
+Return sinus from given angle "a", 360ø is 2000. So 1000 represents
+180ø angle. Result will be in range -10'000 to 10'000, instead of ñ1.
+*** cos ( a -- result )
+Return cosinus from given angle. Parameters are like in [[id:9a66ca9c-eb5f-45aa-8116-71763081f2fb][sin]] function.
projects / fifth.git / blobdiff