X-Git-Url: http://www2.svjatoslav.eu/gitweb/?p=fifth.git;a=blobdiff_plain;f=doc%2Findex.org;fp=doc%2Findex.org;h=fca86408c86083dc97759bdbeea4fecdef7a3478;hp=a0f8319f6e124f39133dad0a36978a4c8db87f30;hb=HEAD;hpb=88e8cc5df07b69e5620a972f89038ce61448a902 diff --git a/doc/index.org b/doc/index.org index a0f8319..c370a29 100644 --- a/doc/index.org +++ b/doc/index.org @@ -1,16 +1,6 @@ #+TITLE: Fifth - virtual machine, operating system, programming language -* (document settings) :noexport: -** use dark style for TWBS-HTML exporter -#+HTML_HEAD: -#+HTML_HEAD: -#+HTML_HEAD: -#+HTML_HEAD: * General - - This program is free software: released under Creative Commons Zero (CC0) license @@ -20,6 +10,7 @@ - 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]] @@ -39,32 +30,40 @@ Currently I try to implement those new ideas in the project called 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. +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: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/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]] -- [[file:screenshots/text editor.png]] - - Built in text editor. +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 ). +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: @@ -74,65 +73,72 @@ 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 | @@ -175,707 +181,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 | -* 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 | - -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 - -* 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 ( -- ) compiles new dictionary entry without specifying - new module type. - ex: head myentry - -: ( -- ) creates new code module -; ( -- ) ends module (immideate) - ex: : hello ." hi there" ; - -const ( n -- ) defines new constant. - ex: 2147483647 const max - -:i ( -- ) same as ":" but this module will be executed - immideately even in compile mode. - ex: :i ( 41 scan ; - -create ( -- ) 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 - -" " ( -- ) compile string and its size into core. - ex: create Mystring " This is it's contects" - -str " ( -- ) just shorter way for defining strings. - ex: str Mystring This is it's contenc" - -var ( -- ) define new 32 bit variable. - ex: var result - -' ( -- n ) return memory address of given entry. - ex: ' init - -forget ( -- ) 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 ( -- ) 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 ( -- ) 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 -- ) 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 DynStrHand -- ) - Create new file and save all data from dynamic memory - block to it. - -fsDload ( DynStr DynHand -- ) - Load whole file into dynamic memory block. - -fsDloadnew ( DynStr -- DynHand ) - 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. - -." " ( -- ) 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 - - - - 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 @@ -930,30 +242,37 @@ mousedo ( -- ) Updates mouse coordinates and keys. Parse mouse 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.