X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;ds=inline;f=doc%2Findex.org;h=79b559293f7645a1b97353658b45f9829a36ddc9;hb=1a9256b173a7c94a017d6480acdf2f67d49bae36;hp=6a0958e9e49976559644acfdb0d0efcab48e7961;hpb=7ad7475c2abf891a92b457339aaa0c20c40634d1;p=fifth.git
diff --git a/doc/index.org b/doc/index.org
index 6a0958e..79b5592 100644
--- a/doc/index.org
+++ b/doc/index.org
@@ -1,28 +1,31 @@
#+TITLE: Fifth - virtual machine, operating system, programming language
------
-- [[http://www2.svjatoslav.eu/gitweb/?p=fifth.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.
-
-- Program author:
- - Svjatoslav Agejenko
- - Homepage: http://svjatoslav.eu
- - Email: mailto://svjatoslav@svjatoslav.eu
-
-- [[http://www.svjatoslav.eu/programs.jsp][other applications hosted at svjatoslav.eu]]
-
* (document settings) :noexport:
** use dark style for TWBS-HTML exporter
-#+HTML_HEAD:
-#+HTML_HEAD:
-#+HTML_HEAD: "
+#+HTML_HEAD:
+#+HTML_HEAD:
+#+HTML_HEAD:
#+HTML_HEAD:
+* General
+- This program is free software: released under Creative Commons Zero
+ (CC0) license
+
+- Program author:
+ - Svjatoslav Agejenko
+ - Homepage: https://svjatoslav.eu
+ - Email: mailto://svjatoslav@svjatoslav.eu
+
+- [[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
@@ -30,29 +33,33 @@ 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
+Fifth is programming lanquage & operating system, running on [[id:9b251eb9-aff6-4025-94bf-25e89e26d54a][virtual
+machine]], 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.
- [[file:5TH_ET.txt][Example Fifth source file - text editor]]
** screenshots
-- [[file:screenshots/start.png]]
- - Startup screen diplaying Fifth logo and full file list.
+[[file:screenshots/start.png]]
-- [[file:screenshots/dictionary.png]]
- - Sample words defined. Most of the words are commands that can be
- executed interactively from command line or from file. When
- executed they can be selectively compiled or interpreted.
+Startup screen diplaying Fifth logo and full file list.
-- [[file:screenshots/text editor.png]]
- - Built in text editor.
+[[file:screenshots/dictionary.png]]
+
+Sample words defined. Most of the words are commands that can be
+executed interactively from command line or from file. When executed
+they can be selectively compiled or interpreted.
+
+
+[[file:screenshots/text editor.png]]
+
+Built in text editor.
* Installation
Just unpack all files, witout altering original directory structure,
@@ -60,28 +67,32 @@ 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]]
+Read more about [[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
+*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.
+*imageFile* - files contained within 'disk.raw', just an extracted form.
-[source] - source files
- [emulator] - emulator source
- [util] - utilites
+*source* - source files
+ *emulator* - emulator source
+ *util* - utilites
-disk.raw - Virtual disk file, has filesystem inside.
-emulator.com - main executable.
+*disk.raw* - Virtual disk file, has filesystem inside.
+*emulator.com* - main executable.
#+END_VERSE
-* Software/Hardware/Human requirements
+* Requirements
** Software
- MS-DOS 6.22, with HIMEM.SYS loaded.
- Mouse driver if you have a mouse.
@@ -111,20 +122,20 @@ their color (black or white).
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 |
@@ -167,14 +178,17 @@ run through headers backwards and find needed entry.
| | | with address to module |
|------+----------------+----------------------------|
| 2 | imm. submodule | immediately call to module |
-** Memory map (average)
-| | | |
-|---------+--------+-----------------------------|
-| 0 | ~4096 | core |
-| 1500000 | ~32000 | highlevel Fifth boot code |
-| 200000h | | core startup messages area |
-| 5200000 | | end of dynamic memory space |
+** 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 |
* Virtual machine
+:PROPERTIES:
+:ID: 9b251eb9-aff6-4025-94bf-25e89e26d54a
+:END:
Using CPU emulator slows it down but I shouldn't now think too mutch
about, and waste my time on batteling with problems whitch results on
complex design of PC hardware. Also it allows me to use existing DOS
@@ -196,103 +210,98 @@ CPU has following registers:
| IP | instruction pointer |
| DSP | data stack pointer |
| RSP | return stack pointer |
-
+** instruction set
+*** overview table
Virtual CPU, commands (most of them are avaiable as ordinary commands
-in programming lanquage):
-
-#+BEGIN_VERSE
-
-code mnemonic description
-
-0 nop does notheing
-1 halt halt CPU ( return to DOS on emulator )
-
-2 kbd@ ( -- c ) read scancode of pressed or released key.
- Returns 0, if no data avaiable.
-3 num ( -- n ) put immidiate number into datastack
-
-4 jmp jump to specified code
-5 call jump to specified code, save return address to
- return stack.
-
-6 1+ ( n -- n+1 )
-7 1- ( n -- n-1 )
-
-8 dup ( n -- n n ) duplicate top of data stack
-9 drop ( n -- ) drop last element in data stack
-
-10 if ( n -- ) jump to addr if top element was 0
-11 ret jump to code, specified in return stack.
-
-12 c@ ( addr -- n ) read byte from memory at specified address
-13 c! ( n addr -- ) store byte to specified memory
-
-14 push ( DSTK -> RSTK ) move top of datastack to returnstack
-15 pop ( RSTK -> DSTK ) move top of returnstack to datastack
-
-16
-17 rot ( n1 n2 n3 -- n2 n3 n1) rotate stack elements
-
-18 disk@ ( FromDiskSect ToMem -- ) read 1KB from disk into RAM
-19 disk! ( FromMem ToDiskSect -- ) write 1KB to disk
-
-20 @ ( addr -- n ) read 32 bit number from memory
-21 ! ( n addr -- ) store 32 bit number to memory
-
-22 over ( n1 n2 -- n1 n2 n1 ) self explaining ...
-23 swap ( n1 n2 -- n2 n1 ) -,,-
-
-24 + ( n1 n2 -- n1+n2 ) -,,-
-25 - ( n1 n2 -- n1-n2 ) -,,-
-
-26 * ( n1 n2 -- n1*n2 ) -,,-
-27 / ( n1 n2 -- n1/n2 ) -,,-
-
-28 > ( n1 n2 -- result ) is true when n1 > n2
-29 < ( n1 n2 -- result ) is true when n1 < n2
-
-30 not ( n1 -- not_n1 ) logical not
-31 i ( -- n ) copies top of return stack into datastack
-
-32 cprt@ ( addr -- n ) read one byte from hardware port
-33 cprt! ( n addr -- ) store one byte to hardware port
-
-34 i2 ( -- n ) like "i" but takes socond top stack element.
-35 i3 ( -- n ) like "i" but takes third top stack element.
-
-36 shl ( n amount -- n ) left bit shift
-37 shr ( n amount -- n ) right bit shift
-
-38 or ( n1 n2 -- n ) logical or
-39 xor ( n1 n2 -- n ) exclusive logical or
-
-40 vidmap ( addr -- ) copy memory from "addr" to video memory.
-
-41 mouse@ ( -- x y button ) read mouse coordinates & buttons
-
-42 vidput ( addr1 addr2 x y -- ) put image1 into image2, at
- location x, y. Does clipping, so part of a big image
- can be mapped into smaller one.
-
-43 cmove ( addr1 addr2 amount ) move memory from addr1 to addr2
- if addr1 is greater than addr2 then count address
- foward while moving, elseway starts from end and
- counts backwards, so no data loss will occure on
- overlapping.
-
-44 cfill ( c addr amount -- ) fill memory starting at "addr"
- with "c" bytes.
-
-45 tvidput ( addr1 addr2 x y -- ) same as "vidput" but treats
- color 255 in source image as transparent.
-
-46 depth ( -- depth ) returns current depth of data stack.
-
-47 charput ( colorfg colorbg addrsrc addrdest x y )
- draw character to image buffer located at "addrdest"
- to specified x & y location. Decodes 8 bytes from
- source to bits, used to draw character.
-#+END_VERSE
+in programming language):
+
+
+| # | name | stack footprint | description |
+|----+--------------+--------------------------------------+-------------------------------------------------------------|
+| 0 | nop | -- | does nothing |
+| 1 | halt | -- | halt CPU ( return to DOS on emulator ) |
+| 2 | [[id:820b1b90-4f4c-4ab1-b49f-9b4a52ea2528][kbd@]] | -- c | read scancode of pressed or released key |
+| 3 | num | -- n | put immidiate number into datastack |
+| 4 | jmp | -- | jump to specified code |
+| 5 | call | | jump to specified code, save return address to return stack |
+| 6 | 1+ | n -- n+1 | |
+| 7 | 1- | n -- n-1 | |
+| 8 | dup | n -- n n | duplicate top of data stack |
+| 9 | drop | n -- | drop last element in data stack |
+| 10 | if | n -- | jump to addr if top element was 0 |
+| 11 | ret | | jump to code, specified in return stack. |
+| 12 | c@ | addr -- n | read byte from memory at specified address |
+| 13 | c! | n addr -- | store byte to specified memory |
+| 14 | push | DSTK -> RSTK | move top of datastack to returnstack |
+| 15 | pop | RSTK -> DSTK | move top of returnstack to datastack |
+| 16 | | | |
+| 17 | rot | n1 n2 n3 -- n2 n3 n1 | rotate stack elements |
+| 18 | disk@ | FromDiskSect ToMem -- | read 1KB from disk into RAM |
+| 19 | disk! | FromMem ToDiskSect -- | write 1KB to disk |
+| 20 | @ | addr -- n | read 32 bit number from memory |
+| 21 | ! | n addr -- | store 32 bit number to memory |
+| 22 | over | n1 n2 -- n1 n2 n1 | |
+| 23 | swap | n1 n2 -- n2 n1 | |
+| 24 | + | n1 n2 -- n1+n2 | |
+| 25 | - | n1 n2 -- n1-n2 | |
+| 26 | * | n1 n2 -- n1*n2 | |
+| 27 | / | n1 n2 -- n1/n2 | |
+| 28 | > | n1 n2 -- result | is true when n1 > n2 |
+| 29 | < | n1 n2 -- result | is true when n1 < n2 |
+| 30 | not | n1 -- not_n1 | logical not |
+| 31 | i | -- n | copies top of return stack into datastack |
+| 32 | cprt@ | addr -- n | read one byte from hardware port |
+| 33 | cprt! | n addr -- | store one byte to hardware port |
+| 34 | i2 | -- n | like "i" but takes second top stack element |
+| 35 | i3 | -- n | like "i" but takes third top stack element. |
+| 36 | shl | n amount -- n | left bit shift |
+| 37 | shr | n amount -- n | right bit shift |
+| 38 | or | n1 n2 -- n | logical or |
+| 39 | xor | n1 n2 -- n | exclusive logical or |
+| 40 | vidmap | addr -- | copy memory from "addr" to video memory. |
+| 41 | mouse@ | -- x y button | read mouse coordinates & buttons |
+| 42 | [[id:238e8b03-57b6-424d-bfee-b6bb652cefbc][vidput]] | addr1 addr2 x y -- | put image1 into image2, at location x, y |
+| 43 | [[id:79e1916f-4103-42cc-ac10-bb1ee776ed50][cmove]] | addr1 addr2 amount | move memory from addr1 to addr2 |
+| 44 | cfill | c addr amount -- | fill memory starting at "addr" with "c" bytes. |
+| 45 | [[id:ab45247c-44c3-464d-9e2a-337f483b4616][tvidput]] | addr1 addr2 x y -- | put image with transparency support |
+| 46 | depth | -- depth | returns current depth of data stack. |
+| 47 | [[id:4bb479cf-aae0-4128-9868-f016c286a162][charput]] | colorfg colorbg addrsrc addrdest x y | draw text character |
+
+*** kbd@ - read scancode of pressed or released key
+:PROPERTIES:
+:ID: 820b1b90-4f4c-4ab1-b49f-9b4a52ea2528
+:END:
+Returns 0 if no data available.
+*** vidput - put image1 into image2, at location x, y
+:PROPERTIES:
+:ID: 238e8b03-57b6-424d-bfee-b6bb652cefbc
+:END:
+Does clipping, so part of a big image can be mapped into smaller one.
+*** cmove - copy memory array
+:PROPERTIES:
+:ID: 79e1916f-4103-42cc-ac10-bb1ee776ed50
+:END:
+Move memory from addr1 to addr2. If addr1 is greater than addr2 then
+count address foward while moving, elseway starts from end and counts
+backwards, so no data loss occurs when memory regions partially
+overlap.
+*** tvidput - put image with transparency support
+:PROPERTIES:
+:ID: ab45247c-44c3-464d-9e2a-337f483b4616
+:END:
+Stack footprint
+: addr1 addr2 x y --
+
+Put image1 into image2, at location x, y with transparency support
+
+Color 255 in source image is treated as transparent.
+*** charput - draw text character
+:PROPERTIES:
+:ID: 4bb479cf-aae0-4128-9868-f016c286a162
+:END:
+Draw character to image buffer located at "addrdest" to specified x &
+y location. Decodes 8 bytes from source to bits, used to draw
+character.
* Fifth source format
Fifth uses a different character table and codes than ASCII (still
@@ -938,11 +947,11 @@ imgfill ( color x y imgbuf -- ) Fill image region starting at location
X & Y with specified color.
#+END_VERSE
** Trigonometry functions
-#+BEGIN_VERSE
-sin ( a -- result ) 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 "sin" function.
-#+END_VERSE
+*** 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.