X-Git-Url: http://www2.svjatoslav.eu/gitweb/?p=fifth.git;a=blobdiff_plain;f=doc%2Findex.org;fp=doc%2Findex.org;h=79b559293f7645a1b97353658b45f9829a36ddc9;hp=fca86408c86083dc97759bdbeea4fecdef7a3478;hb=a913785891f6089f929cf5e12720d1da1269de51;hpb=92bdcd72ccafd7ca2ea44a704ab06356d28fb2dd diff --git a/doc/index.org b/doc/index.org index fca8640..79b5592 100644 --- a/doc/index.org +++ b/doc/index.org @@ -46,16 +46,20 @@ 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, @@ -73,22 +77,22 @@ 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. @@ -118,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 | @@ -174,13 +178,13 @@ 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 @@ -206,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. +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 -- -46 depth ( -- depth ) returns current depth of data stack. +Put image1 into image2, at location x, y with transparency support -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 +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 @@ -948,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.