#+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: you can redistribute it and/or modify
- it under the terms of the [[https://www.gnu.org/licenses/lgpl.html][GNU Lesser General Public License]] as
- published by the Free Software Foundation, either version 3 of the
- License, or (at your option) any later version.
+- 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://www.svjatoslav.eu/projects/][Other software projects hosted at svjatoslav.eu]]
+- [[https://www.svjatoslav.eu/projects/][Other software projects hosted at svjatoslav.eu]]
** Source code
-- [[http://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=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]]
-- [[http://www2.svjatoslav.eu/gitweb/?p=fifth.git;a=summary][Browse Git repository online]]
+- [[https://www2.svjatoslav.eu/gitweb/?p=fifth.git;a=summary][Browse Git repository online]]
- Clone Git repository using command:
- : git clone http://www2.svjatoslav.eu/git/fifth.git
+ : git clone https://www2.svjatoslav.eu/git/fifth.git
-* Warning
+* !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://www3.svjatoslav.eu/projects/sixth/][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 and not updated since.
+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.
-- [[file:5TH_ET.txt][Example Fifth source file - text editor]]
-** screenshots
-- [[file:screenshots/start.png]]
- - Startup screen diplaying Fifth logo and full file list.
+** Screenshots
-- [[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/start.png]]
-- [[file:screenshots/text editor.png]]
- - Built in text editor.
+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]]
+
+Built in 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]]
+: 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
+*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.
-- 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
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 |
| | | 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 |
-* Virtual machine
-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 |
-
-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 <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 ) 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
-
-* 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
+** 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
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
-** 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
++ 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