#+TITLE: Fifth - virtual machine, operating system, programming language
-* (document settings) :noexport:
-** use dark style for TWBS-HTML exporter
-#+HTML_HEAD: <link href="https://bootswatch.com/3/darkly/bootstrap.min.css" rel="stylesheet">
-#+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
-#+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.5/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>
* General
- This program is free software: released under Creative Commons Zero
(CC0) license
- 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]]
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 [[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
+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 command line or from file. When executed
-they can be selectively compiled or interpreted.
+executed interactively from the command line or from a file. When
+executed, they can be selectively compiled or interpreted.
[[file:screenshots/text editor.png]]
* 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 ).
+somewhere in your hard disk. For example:
-Read more about [[id:0759f3e0-28bb-4901-9e4f-09ef41732173][Fifth distribution directory tree description]].
+: 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:
* 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).
+- 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
-- 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.
+- 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 this hexadecimal format as primary throughout entire
+system.
+
+See also: [[https://en.wikipedia.org/wiki/Bibi-binary][Bibi-binary]].
-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
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
| 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
-and resident drivers services in real mode. So I don't need to deal
-with hardware too mutch. It also allows me to use all free XMS for
-flat code & data storage.
-
-Current emulator emulates 1 CPU. It has 2 stacks, ~50 instructions,
-and 4GB flat address space (theoretically). I'm not sure that DOS
-6.22 that I currently prefer can handle more than 64 MB of RAM. While
-I tried to keep instructionset simple, I was forced to put in lot of
-complex instructions to make it's performance acceptable on
-emulator. On actual silicon ~20 instructions is enaugh (I think).
-
-Maybe one day similar system will run directly on custom silicon chip :)
-
-
-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 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 <dword> | -- n | put immidiate number into datastack |
-| 4 | jmp <dword> | -- | jump to specified code |
-| 5 | call <dword> | | 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 <dword> | 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 | <unused> | | |
-| 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
-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. |
-* Fifth commands
-** Compilation & miscellaneous
-#+BEGIN_VERSE
-init module ( -- )
- First module, control is passed to on startup. Contains
- initialization routines. Also it is the last core module.
- All new modules on top of it comes as result of executing
- external source files.
-
-head <name> ( -- ) compiles new dictionary entry without specifying
- new module type.
- ex: head myentry
-
-: <name> ( -- ) creates new code module
-; ( -- ) ends module (immideate)
- ex: : hello ." hi there" ;
-
-const <name> ( n -- ) defines new constant.
- ex: 2147483647 const max
-
-:i <name> ( -- ) same as ":" but this module will be executed
- immideately even in compile mode.
- ex: :i ( 41 scan ;
-
-create <name> ( -- ) same as "head" , but specify module type as data.
- ex: create LotoResults 5 , 13 , 52 , 12 , 11 , 3 ,
-
-allot ( n -- ) allocate n bytes in dictionary.
- ex: create MyArray 100 allot
-
-" <string>" ( -- ) compile string and its size into core.
- ex: create Mystring " This is it's contects"
-
-str <name> <string>" ( -- ) just shorter way for defining strings.
- ex: str Mystring This is it's contenc"
-
-var <name> ( -- ) define new 32 bit variable.
- ex: var result
-
-' <module> ( -- n ) return memory address of given entry.
- ex: ' init
-
-forget <name> ( -- ) erases from RAM given entry and all entries what was
- defined after it.
- ex: forget myprog
-
-[ ( -- ) set interpret mode (immideate)
-] ( n -- ) set compile mode and compile top stack element
- in as literal. Together [ .... ] cobination provides good
- way to compute some values only once, at compile time,
- rather than every time while program is running.
- ex: : calculate - [ 4 MyConst1 + MyConst2 * ] ;
-
-defer <name> ( -- ) creates new module, with jump instruction.
- Later address where to jump can be modified by "is" command.
- This provides method of foward referencing. So you can use
- modules what not jet exist.
-is ( address1 address2 -- ) address1 - where to jump, address2 -
- address of module created by defer command.
- ex: defer dispver
- : run dispver ." running ..." ;
- ... whatever ...
- : (dispver ." Version 9.99 " ;
- ' (dispver ' dispver is
-
- Now if I type "run" on the screen appears:
- Version 9.99 running ...
-
-asc <char> ( -- ) reads char ascii code and treats it as literal.
- (immideate)
- ex: : BreakLine 30 do asc - emit loop ;
- same as:
- : BreakLine 30 do 45 emit loop ;
-
-dyninc ( handle -- ) execute code in dynamic memory handle.
- automatically deallocates it when done.
-
-include ( filenumber -- ) execute code in specified file.
-
-words ( -- ) display existing blocks in core.
-
-bye ( -- ) exit from Fifth
-
-fkey ( -- c )
- Read one byte from input stream.
-
-sadd ( c addr -- )
- Add one byte "c" to string located at "addr" and updates
- string length.
-
-scan ( c -- )
- Read input stream and store it to pad until it finds c .
- It ignores all "c" bytes until it finds any non "c" byte.
- in other words:
- c is: "
- input stream: """"This is test !"aoeu idh
- result: This is test !
-
- Is useful for breaking text lines into words.
-
-skey ( -- c )
- So called safe "fkey". Reads data from input stream
- but converts characters with ASCII codes: 9 13 10
- to spaces.
-
-str=str? ( adr1 adr2 -- result )
- Compares string at "adr1" with string at "adr2", returns
- true flag if they are equal or false if they are not.
- true = -1
- false = 0
-
-find ( -- addr )
- Searches whole dictionary for word in "pad". If found,
- returns it address, if not, returns 0.
-
-execute ( -- )
- Execute word located in "pad". Depending on "mode".
-
-dta ( addr -- DataAddr )
- Calculates address of dictionary entry data area, from
- entry point.
-
-2num ( -- num result )
- Attempt to convert string located in "pad" into numeric
- value. If succeed returns number and true as result.
- If not, returns whatever and false as result.
-
-dadd ( addr length -- )
- Add to dictionary data located at "addr", with specified
- length.
-
-lit ( n -- )
- Act with number depending on "mode". When interpreting,
- leaves it in stack.
-
-
-incmod ( addr -- )
- Add to dictionary data located at "addr"+1 , length is taken
- from "addr".
-
-here ( -- n )
- return "h" contents.
-
-mode var 8 bit
- Holds input stream parser operation mode.
- 0 = interpreting
- 1 = compiling
-
-pad var 128 bytes
- Holds temprorary strings.
-
-h var 32 bit
- Pointer to free byte in memory, always at the end of the
- dictionary. Each time when something is stored
- by "c," command, pointer is incareased.
-
-lp var 32 bit
- Pointer to last dictionary word. Each time when new word is
- compiled or erased by "forget", this pointer is updated.
-
-modulechk ( Dstr<filename> -- ) check if module is loaded, if not
- immideately load it.
-
-ne ( entrydata entrytype -- ) Compile new dictionary entry.
- It's name must be in "pad".
-#+END_VERSE
-** Conditionals & control flow
-#+BEGIN_VERSE
-if ( flag -- ) (immideate)
- "if 1.. else 2.. then" or
- "if 1.. then" construction. Conditional execution.
- Performs "1.." if "flag" was true,
- elseway performs "2.." if exist. Execution continues after
- word "then".
- ex: 1 if ." nonzero" else ." zero" then
-
->= ( n1 n2 -- result ) true if (n1 = n2) or (n1 > n2)
- ex: 5 3 >= if ." first number is greater or equal" then
-
-<= ( n1 n2 -- result ) true if (n1 = n2) or (n1 < n2)
-= ( n1 n2 -- result ) true if n1 = n2
-
-do ( count -- ) (immideate)
- "do .. loop" construction. Performs ".." "count" times.
- In every step "count" is decareased until it is 0.
- ex: : test 5 do i .d loop ;
- result: 4 3 2 1 0
-
-doexit ( -- ) exit from "do .. loop"
-
-for ( count top -- ) (immideate)
- "for .. loop" construction. Performs ".." (top - count) times.
- In every step "count" is incareased until it reaches "top" .
- ex: : test 4 10 for i .d loop ;
- result: 4 5 6 7 8 9
-
-forexit ( -- ) exit from "for .. loop"
-
-until ( -- ) (immideate)
- "until .. loop" construction. Performs ".." until flag become
- true. False by default. Top of return stack holds flag.
-
-done ( -- ) exit from "until .. loop"
-
-#+END_VERSE
-** Disk & file access
-#+BEGIN_VERSE
-diskload ( FromDisk ToMem amount -- )
- Load specified abount of bytes from disk into memory.
-
-disksave ( FromMem ToDisk amount -- )
- save specified abount of bytes from memory into disk.
-
-format ( -- ) Erase all files.
-
-fsDfilesize@ ( handle -- size )
- Return size of opened file.
-
-fsDcurloc@ ( handle -- location )
- Return current location in file.
-
-fsDupdated@ ( handle -- updated? )
- Return true if file was updated,
- ie. write operations occured.
-
-fssave ( FromMem DestFileHandle amount -- )
- Save data to file.
-
-fsload ( SrcFileHandle ToMem amount -- )
- Load data from file.
-
-fseof ( handle -- bytesLeft )
- Return amount of bytes left till end of file.
- Useful before read operation.
-
-fsls ( -- ) List all files and lists (directories,folders)
- in current path.
-
-fslsr ( -- ) Same as "fsls" but recursively scans also sub lists.
-
-fscl ( DynStrHand -- )
- Change list (path)
-
-fscreate ( DynStrHand -- DescPnt )
- Create new file or list. Can create multiple lists at once.
- ex: when creating:
- "\listGAMES\listSTRATEGY\listSIMWORLD\5th-runme"
- and only "\listGAMES\" already exist, then
- "listSTRATEGY" and "listSIMWORLD" lists will be created,
- and empty file "5th-runme" placed in there.
-
-fsDsave ( DynHand<data> DynStrHand<filename> -- )
- Create new file and save all data from dynamic memory
- block to it.
-
-fsDload ( DynStr<SrcFileName> DynHand<DataDest> -- )
- Load whole file into dynamic memory block.
-
-fsDloadnew ( DynStr<SrcFileName> -- DynHand<DataDest> )
- Load whole file into new dynamic memory block.
-#+END_VERSE
-** Dynamic memory
-#+BEGIN_VERSE
-dynal ( size -- handle )
- Allocate dynamic memory block and return it's handle.
-
-dynde ( handle -- )
- Deallocate dynamic memory block.
-
-dynp ( handle -- addr )
- Returns pointer to memory where dynamic block
- data begins.
-
-dyns ( handle -- size )
- Returns size of dynamic block.
-
-dynresize ( NewSize handle -- )
- Nondestructively resize dynamic block.
-
-dync@ ( addr handle )
- Read one byte from dynamic block.
-
-dync! ( byte addr dynhandle )
- Write one byte to dynamic block.
-
-dyn@ ( addr handle )
- Read 32 bit number from dynamic block.
- Address will spacify, whitch number, not byte.
-
-dyn! ( 32BitNum addr dynhandle )
- Write 32 bit number to dynamic block.
- Address will spacify, whitch number, not byte.
-
-dyncon ( size "name" -- )
- Allocate dynamic block with specified size, and
- create constant honding its handle.
- ex: 100 dyncon MyNewBlock
-
-dyn. ( handle -- )
- Write contenc of dynamic memory block to screen.
-#+END_VERSE
-** Graphics and text
-#+BEGIN_VERSE
-. ( n -- ) print number on screen
-
-d. ( n -- ) print number on screen in decimal
-
-? ( addr -- ) print 32 bit value located at addr.
-
-." <string>" ( -- ) print string into screen. Immideately
- compiles.
- ex: : greeting ." Hello, World" ;
-
-tab. ( -- ) print tabulator
-
-calccol ( b g r -- c ) calculate color what best matches given
- Blue Green & Red values. Values must be in range 0 - 255.
-
-imgalloc ( xsize ysize -- imgbuf ) allocate image buffer for
- specified size.
-
-imgsize ( imgbuf -- ) print on the screen X & Y size of image
- buffer.
-
-point ( x y imgbuf -- addr ) returns memory address for specified
- pixel.
-
-pset ( color x y imgbuf -- ) set graphic point
-
-boxf ( x1 x2 y1 y2 imgbuf color -- ) draw filled box
-
-cls ( imgbuf -- ) clear image buffer
-
-setpal ( b g r color -- ) set palette value for specified color.
- values bust be in size 0 - 63.
-
-putchar ( char color x y imgbuf -- ) put graphic character in
- imagebuffer to specified (x & y) location.
-
-scroll ( x y imgbuf -- ) scroll in imgbuf.
-
-scrollf ( color x y screen -- ) scroll and fill empty space with
- given color.
-
-at! ( x y -- ) set cursor location
-curc! ( color -- ) set text color
-curb! ( solor -- ) set backround color
-
-colnorm ( -- ) set text color to normal
-colneg ( -- ) set text color to negative (selected)
-
-dyntype ( dynhandle -- ) display contenc of dynamic memory on screen
-fsdisp ( file -- ) clear screen, display file, and wait for key
-
-type ( addr length -- )
- Types on the screen string, from memory at addr and
- specified length.
-
-write ( addr -- )
- Types on the screen string, from memory at "addr"+1
- length is taken from "addr" .
-
-screen const 32 bit
- Holds handle of screen buffer.
-
-copyscreen ( SrcImgHandle DestImgHandle -- ) copy contenc of source
- image to destination image. Source and destination images
- must have same size.
-#+END_VERSE
-** Math, memory & stack manipulation
-#+BEGIN_VERSE
-off ( n -- ) writes 0 to given address, good for zeroing variable.
- ex: MyVariable off
-on ( n -- ) writes -1 (true flag) to given address.
- ex: MyVariable on
-
-2dup ( n1 n2 -- n1 n2 n1 n2 )
-2drop ( n1 n2 -- )
-nip ( n1 n2 -- n2 )
-neg ( n1 -- -n1 ) negotiate
-bit@ ( n bit -- result ) return specified bit from n.
- ex: 38 2 bit@ (result will be 1)
-to32bit ( n1 n2 n3 n4 -- n32 ) treat 4 last stack elements as bytes
- and unite them into 32 bit dword. Most significant byte
- on top.
- ex: 12 76 23 11 to32bit result: 186076172
-
-to8bit ( n32 -- n1 n2 n3 n4 ) break 32 bit number into 4 bytes.
- Useful if you need to send 32 bit numbers thru 8 bit COM
- port.
- ex: 186076172 to8bit result: 12 76 23 11
-
-mod ( n1 n2 -- reminder ) divide n1 by n2 and returns reminder.
- ex: 12 5 mod result: 2
-
-bound ( low n high -- n ) check if n is in given bounds,
- if not then incarease/decarease it to match bounds.
- ex: 5 80 15 bound result: 15
- 5 10 15 bound result: 10
- 5 -10 15 bound result: 5
-
-bound? ( low n high -- result ) returns true if n is in the
- given bounds.
-
-tab ( col -- spaces) calculate amount of spaces to add
- ta reach next tabulation from given column.
-
-count ( addr -- addr+1 n )
- Useful for returning bytes from constantly incareasing
- address. Module "type" is nice example.
-
-c, ( n -- )
- store one byte at memory specified by "h". And incarease
- "h" by 1.
-
-, ( n -- )
- store 32 bit number at memory specified by "h". And
- incarease "h" by 4.
-
-cmove ( addr1 addr2 n -- )
- copy "n" amount of bytes from memory at "addr1" to memory
- at "addr2".
-
-rnd ( limit -- result )
- generates random number in range 0 to "limit"-1.
-
-abs ( n -- |n| )
- returns absolute value of "n"
-#+END_VERSE
-** Dynamic & static strings
-Fifth supports both static and dynamic strings. Static strings must
-have predefined space reserved, and string mustn't exceed this
-length. They manipulation is faster. But they use more memory. Static
-string memory address is used to refer to the string.
-
-Dynamic strings can have at any time length form 0 to 0FFh, They take
-up only memory they currently need. They are held in dynamic memory
-blocks, so dynamic block handle is used to refer to this string.
-
-Both types of strings are stored in the way, where first (0th) byte
-holds current string length, following bytes are string itself.
-
-
-#+BEGIN_VERSE
-Dynamic:
-
-Dstral ( -- handle )
- Allocate new string.
-
-Dstrlen ( handle -- length )
- Return string length.
-
-c+Dstr ( chr handle -- )
- Add one byte to end of the string.
-
-c+lDstr ( chr handle -- )
- Add one byte to left side (beginning) of the string.
-
-Dstr. ( handle -- )
- Write contec of string into screen.
-
-Dstrsure ( size Dstr -- )
- Makes sure that at least rquested
- "size" (amount of characters) is allocated for given
- dynamic string.
-
-Dstr2str ( handle address -- )
- Copy dyamic string into static memory space.
-
-str2Dstr ( address handle -- )
- Copy static string into dyamic string.
-
-Dstr+str ( Dstr addr -- )
- Add contenc of dynamic string to static string.
-
-D" any string" ( -- Dstr )
- Moves specified string into dynamic string called "defDstr".
-
-D> any_string ( -- Dstr )
- Moves specified string into dynamic string called "defDstr".
- Space marks end of string!
-
-D>2 any_string ( -- Dstr )
- Moves specified string into dynamic string called "defDstr2".
- Space marks end of string!
-
-Dstr+Dstr ( Dstr1 Dstr2 -- )
- Adds "Dstr1" to "Dstr2" and places result into "Dstr2".
-
-Dstrclear ( Dstr -- )
- Clears contenc of dynamic string.
-
-Dstr2Dstr ( Dstr1 Dstr2 -- )
- Moves "Dstr1" to "Dstr2".
-Dstr ( data" name -- )
- Creates new dynamic string and moves specified data into it.
- Then creates new constant with given "name" holding created
- dynamic string handle.
-
- ex: Dstr Hello, my name is Sven!" message \ creates it
- message Dstr. \ tests it
-
-Dstrlscan ( char Dstr -- loc )
- Searches dynamic string for "char", from left to right,
- returns first found "char" location in string, or 0,
- if not found.
-
-Dstrrscan ( char Dstr -- loc )
- Searches dynamic string for "char", from right to left,
- returns first found "char" location in string, or 0,
- if not found.
-
-Dstrlscane ( char Dstr -- loc )
- Same as "Dstrlscan" buf returns string length+1 as location.
-ΓΏ
-Dstrleft ( amo Dstr -- )
- Only specified amount of characters from left remains
- in dynamic string. ie. cut right part out.
-
-Dstrright ( amo Dstr -- )
- Only specified amount of characters from right remains
- in dynamic string. ie. cut left part out.
-
-Dstrcutl ( amo Dstr -- )
- Cut specified amount of characters from left of dynamic
- string out.
-
-Dstrsp ( char Dstr1 Dstr2 -- )
- Separate dynamic string in Dstr1 into two parts,
- using "char" as separator. First part will be stored in
- "Dstr2", second part in "Dstr1".
- ex: asc \ \ ..separator
- D> listF\listLIB\5TH_DRVMOUSE \ ..separate from
- defDstr2 \ ..place result in
- Dstrsp \ separation command
- defDstr Dstr. \ will be: listLIB\5TH_DRVMOUSE
- defDstr2 Dstr. \ will be: listF
-
-Dv ( addr -- )
- Allocates empty dynamic string, and places it's handle
- into given address.
-
-Df ( addr -- )
- Reads dynamic string handle from given address and
- deallocates (frees) it.
-
-ex: var mystring1
- : testmodule
- mystring1 Dv \ allocates string
-
- <whatever>
-
- mystring1 Df ; \ deallocates it again when no longer needed.
-#+END_VERSE
* Dynamically loadable modules
** Keyboard driver
#+BEGIN_VERSE
click buffer, and draw mouse cursor to "screen".
#+END_VERSE
** 2D graphic library
-#+BEGIN_VERSE
-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.
- x1,y1-----------+
- | |
- | |
- +-----------x2,y2
-
-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.
-#+END_VERSE
+
++ 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:
projects / fifth.git / blobdiff