.. index:: dictionary, flag codes, word list, error messages, atomic,compule only .. _dictionary: > :ref:`What's New ?` < Dictionary ========== .. _example-dict-listing: Example Dictionary Listing -------------------------- :: Address: 0000DFD4 Link: 0000DFEC Flags: 00000040 Code: 0000DFE4 Name: pull-down Address: 0000DFEC Link: 0000E024 Flags: 00001820 Code: 0000DFFC Name: green-on Address: 0000E024 Link: 0000E05C Flags: 00001820 Code: 0000E034 Name: green-off see green-on 0000DFFC: 2090 movs r0 #90 0000DFFE: 04C0 lsls r0 r0 #13 0000E000: 3080 adds r0 #80 0000E002: 0100 lsls r0 r0 #4 0000E004: 6983 ldr r3 [ r0 #18 ] 0000E006: 2280 movs r2 #80 0000E008: 0092 lsls r2 r2 #2 0000E00A: 4313 orrs r3 r2 0000E00C: 6183 str r3 [ r0 #18 ] 0000E00E: 4770 bx lr Forth Definition Components --------------------------- :: Address Link Flags Code Name Word Header Fields ^^^^^^^^^^^^^^^^^^ ======== ================================================================================================================================= Name Description ======== ================================================================================================================================= ADDRESS Start of the definition block, always 16 Bytes before the CODE section LINK Address of the next definition, the one after this one FLAGS see "FLAG Codes" below CODE The address of the start of the executable code for this Word. Call this address to execute this Word. NAME The name of the definition (Word) ======== ================================================================================================================================= .. _dict-flags: FLAG Codes ^^^^^^^^^^ Taken from: mecrisp-stellaris-source/common/datastackandmacros.s ======== ======== ===================================================================================================================== Flag RA Only? Description ======== ======== ===================================================================================================================== 0x0000 Visible, non-immediate 0x0008 Opcodable; 0: special case 1: plusminus 2: computational logic 3: DC unequal 4: push 5: memory Write, 0x0010 Immediate 0x0020 Inline - that means, it's contents will be inlined until $4130, the ret opcode is found. On ARM, this is either $4770 bx lr or $BD00 pop {pc}. 0x0030 Immediate+Inline means: Immediate, Compile-Only 0x0080 Ramallot means that RAM is reserved and initialised by catchflashpointers for this definition on startup 0x0040 0-foldable, e.g. constants 0x0041 1-foldable, e.g. 1+ 0x0042 2-foldable, e.g. swap, xor 0x0043 3-foldable 0x0044 4-foldable 0x0045 5-foldable 0x0046 6-foldable 0x0047 7-foldable 0x0100 buffers in compiletoflash mode 0x0200 Y Allocator, this definition has individal optimisation code and a second entry point for the optimiser after the first bx lr or pop {pc} opcode. 0x0400 Y Jump Eaters, this definition can handle cached jump instructions itself, for merging of comparisons with control structures. 0x0800 Y Bxlr, is used once for ; and means that despite ; is immediate we can keep the direct bx lr return without the need to write the push {lr} opcode first for a later pop {pc}. Usually, the optimiser falls back to the push {lr} ... pop {pc} sequence as soon as a call is compiled or something flagged as immediate is encountered. 0x1000 Y Inlinecache, denotes that this definition carries an automatically generated inline cache table, which allows recompilation of this definition elsewhere with local optimisations in place. 0x2000 Y Literator, never shows up in the dictionary, but appears in inline cache table to denote literals instead of code entry point with flag pairs. 0x4000 Y User, is unused in all Mecrisp-Stellaris cores. This flag is free for the user, and the loadable vocabulary extension relies on it. 0xFFFF Invisible ======== ======== ===================================================================================================================== RA Core Register Usage ---------------------- Register Purpose Notes r0 Free scratch register Saved on interrupt entry by hardware r1 Free scratch register Saved on interrupt entry by hardware r2: Free scratch register Saved on interrupt entry by hardware r3: Free scratch register Saved on interrupt entry by hardware r4: Inner loop count Needs Push and Pop when used otherwise r5: Inner loop limit Needs Push and Pop when used otherwise r6=TOS: Top-Of-Stack Stack design is interrupt safe ) r7=PSP: Parameter Stack Pointer Stack design is interrupt safe ) r8: Unused r9: Unused r10: Unused r11: Unused r12: Unused Saved on interrupt entry by hardware r13=SP: Return Stack Pointer r14=LR: Link Register r15=PC: Program Counter, always odd .. index:: number bases Number Bases ------------ +--------+-----------+----------------------------------------+ | prefix | Base | *exactly ANS* | +========+===========+================+=======================+ | % | binary | ( - - ) | Sets base to 2 | +--------+-----------+----------------+-----------------------+ | # | decimal | ( - - ) | Sets base to 10 | +--------+-----------+----------------+-----------------------+ | $ | hex | ( - - ) | Sets base to 16 | +--------+-----------+----------------+-----------------------+ | | base | ( - - a-addr ) | Base variable address | +--------+-----------+----------------+-----------------------+ Data Types ---------- =========== ===== ================================================================================== Name Bits Description =========== ===== ================================================================================== Word 32 Native Mecrisp-Stellaris data length Cell 32 Same as Word above Half Word 16 Half Word length Character 8 One Byte Bit 1 Smallest =========== ===== ================================================================================== Key to Tables ------------- ======== =================================== ======================================================== ======================================================== Phrase Description Comment Examples ======== =================================== ======================================================== ======================================================== n, n1, single-length signed integer -2147483648 to 2147483647 $80000000 . -2147483648, $7FFFFFFF . 2147483647 d, d1, double-length signed integer -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 $FFFFFFFF $FFFFFFFF m* d. 1 ok. ( -1 * -1 = 1 ) u, u1, single-length unsigned integer 0 to 4294967295 $FFFFFFFF u. 4294967295, ud, ud1 unsigned double-length integer 0 to 18,446,744,065,119,617,025 $FFFFFFFF $FFFFFFFF um* ud. 18446744065119617025 c character (byte) 8 bits, 0 to 255 $FF h halfword 16 bits, 0 to 65,535 $FFFF x cell logic, memory operations, logging, bitmaps ... a-addr cell address h-addr half word address c-addr character (byte) address R: return stack flag Binary 1 or 0 "name" input stream token ======== =================================== ======================================================== ======================================================== .. _cmessages: Compiler Error Messages ----------------------- Derived by grepping the source for "write", "writeln" and "Fehler" (error). ===================================================== ========================== ========================================================================================= Message Source Comments ===================================================== ========================== ========================================================================================= Jump too far Dreaded conditional jump range limitation. Workaround: create new Word with offending code. Cannot write into core ! flash16bytesblockwrite.s Cannot write into core ! flash.s Create needs name ! compiler-flash.s Often caused by a lone ";" Flash full compiler-flash.s The chip Flash Memory is full. :ref:`is compile only` interpreter.s Cannot be used interactively, must be inside a Definition (Word) :ref:`Jump too far` controlstructures.s All jumps use Thumb 1 short opcodes. Solution; split your code into smaller Words Not enough RAM compiler-flash.s Not enough RAM is available to complete the Word not found. interpreter.s Name of word, constant, variable, etc cannot be found, usually a source typo ok. interpreter.s All is good! Ram full compiler-flash.s The chip RAM is full Redefine compiler-flash.s A Word, constant, variable, etc has been defined more than once Stack underflow interpreter.s The Data Stack is empty, you tried to pop data off it, but there is no data there Stack not balanced. compiler.s The Return Stack is unbalanced, use of >R and R> was not equal Stack overflow interpreter.s The Data Stack is full, default size is 64 elements, same as the Return Stack. Structures don't match controlstructures.s Example: a missing "then" from a "if else then" statement Unhandled Interrupt ! interrupts-common.s A Interrupt has been triggered, but no code is handling it. See :ref:`Exceptions` Variables collide with dictionary compiler-flash.s Wrong address or data for writing flash ! flash.s for your MCU See :ref:`notes` ===================================================== ========================== ========================================================================================= .. index:: terminal-io Terminal-IO ----------- +--------------------------------------------------------------------------+ | *Exactly ANS, some logical extension* | +==============+==================+========================================+ | emit? | ( - - Flag ) | Ready to send a character ? | +--------------+------------------+----------------------------------------+ | key? | ( - - Flag ) | Checks if a key is waiting | +--------------+------------------+----------------------------------------+ | key | ( - - Char ) | Waits for and fetches the pressed key | +--------------+------------------+----------------------------------------+ | emit | ( Char - - ) | Emits a character | +--------------+------------------+----------------------------------------+ | hook-emit? | ( - - a-addr ) | Hooks for redirecting | +--------------+ | terminal IO on the fly | | hook-key? | | | +--------------+ | | | hook-key | | | +--------------+ | | | hook-emit | | | +--------------+------------------+----------------------------------------+ | serial-emit? | ( - - Flag ) | Serial interface | +--------------+ | terminal routines | | serial-key? | | as default communications | +--------------+------------------+----------------------------------------+ | serial-key | ( - - Char ) | Waits for and fetches the pressed key | +--------------+------------------+----------------------------------------+ | serial-emit | ( Char - - ) | Emits a character | +--------------+------------------+----------------------------------------+ | hook-pause | ( - - a-addr ) | Hook for a multitasker | +--------------+------------------+----------------------------------------+ | pause | ( - - ) | Task switch, none for default | +--------------+------------------+----------------------------------------+ .. char-manip: Character Manipulation ^^^^^^^^^^^^^^^^^^^^^^ How to convert numbers to characters and convert characters to numbers. ================= ============== =============================================== ============================================== ========================= Command Stack Notation Description Code or Comment Result ================= ============== =============================================== ============================================== ========================= [char] * ( - - char ) Compiles code of following char when executed When used in a definition (function, Word) char * ( - - char ) Gives code of following char char 3 hex. 00000033 ok. emit ( char - - ) Emits a character $33 emit 3 ok. ================= ============== =============================================== ============================================== ========================= .. index:: stack Stack Jugglers -------------- .. _stack-single: Single-Jugglers ^^^^^^^^^^^^^^^ +---------------------------------------------------------------------------------------------------------------------------------------------+---------------+ | *Exactly ANS, some logical extension* | RA Core Only ?| +====================+=======================================================+================================================================+===============+ | depth | ( - - +n ) | Gives number of single-cell stack items. | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | nip | ( x1 x2 - - x2 ) | Drop the first item below the top of the stack | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | drop | ( x - - ) | | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | rot | ( x1 x2 x3 - - x2 x3 x1 ) | | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | -rot | ( x1 x2 x3 - - x3 x1 x2 ) | | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | swap | ( x1 x2 - - x2 x1 ) | | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | tuck | ( x1 x2 - - x2 x1 x2 ) | | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | over | ( x1 x2 - - x1 x2 x1 ) | | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | ?dup | ( x - - 0 | x x ) | | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | dup | ( x - - x x ) | | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | pick | ( ... xi+1 xi ... x1 x0 i - - ... x1 x0 xi ) | Copy a element X levels down the stack to the top of the stack | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | >r | ( x - - ) (R: - - x ) | Push to Return Stack (the Return Stack must be balanced) | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | r> | ( - - x ) (R: x - - ) | Pull from Return Stack | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | r@ | ( - - x ) (R: x - - x ) | Copy from Return Stack | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | rdrop | ( - - ) (R: x - - ) | | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | rdepth | ( - - +n ) | Gives number of return stack items. | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | rpick | ( i - - xi ) R: ( ... xi ... x0 - - ... xi ... x0 ) | | | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | :ref:`roll` | ( xu xu-1 ... x0 u -- xu-1 ... x0 xu ) | Remove u. Rotate u+1 items on the top of the stack. | Yes | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ | :ref:`-roll` | ( xu-1 ... x0 xu u -- xu xu-1 ... x0 ) | | Yes | +--------------------+-------------------------------------------------------+----------------------------------------------------------------+---------------+ Double-Jugglers ~~~~~~~~~~~~~~~ +-------------------------------------------------------------------------------+ | *They perform the same for double numbers* | +===============+===============================================================+ | 2nip | ( x1 x2 x3 x4 - -x3 x4 ) | +---------------+---------------------------------------------------------------+ | 2drop | ( x1 x2 - - ) | +---------------+---------------------------------------------------------------+ | 2rot | ( x1 x2 x3 x4 x5 x6 - - x3 x4 x5 x6 x1 x2 ) | +---------------+---------------------------------------------------------------+ | 2-rot | ( x1 x2 x3 x4 x5 x6 - - x5 x6 x1 x2 x3 x4 ) | +---------------+---------------------------------------------------------------+ | 2swap | ( x1 x2 x3 x4 - - x3 x4 x1 x2 ) | +---------------+---------------------------------------------------------------+ | 2tuck | ( x1 x2 x3 x4 - - x3 x4 x1 x2 x3 x4 ) | +---------------+---------------------------------------------------------------+ | 2over | ( x1 x2 x3 x4 - - x1 x2 x3 x4 x1 x2 ) | +---------------+---------------------------------------------------------------+ | 2dup | ( x1 x2 - - x1 x2 x1 x2 ) | +---------------+---------------------------------------------------------------+ | 2>r | ( x1 x2 - - ) (R: - -x1 x2 ) | +---------------+---------------------------------------------------------------+ | 2r> | ( - - x1 x2 ) (R: x1 x2 - - ) | +---------------+---------------------------------------------------------------+ | 2r@ | ( - - x1 x2 ) (R: x1 x2 - -x1 x2 ) | +---------------+---------------------------------------------------------------+ | 2rdrop | ( - - ) (R: x1 x2 - - ) | +---------------+---------------------------------------------------------------+ .. index:: stack pointers Stack pointers ~~~~~~~~~~~~~~ +-----------------------------------------------------------------------------------+ | Stack Pointers | +===============+================+==================================================+ | sp@ | ( - - a-addr ) | Fetch data stack pointer | +---------------+----------------+--------------------------------------------------+ | sp! | ( a-addr - - ) | Store data stack pointer | +---------------+----------------+--------------------------------------------------+ | rp@ | ( - - a-addr ) | Fetch return stack pointer | +---------------+----------------+--------------------------------------------------+ | rp! | ( a-addr - - ) | Store return stack pointer | +---------------+----------------+--------------------------------------------------+ .. index:: logic Logic ----- +-------------------------------------------------------------------------------------------------------+ | *exactly ANS, some logical extensions* | +===============+===============================+=======================================================+ | arshift | ( x1 u - - x2 ) | Arithmetric right-shift of u bit-places | +---------------+-------------------------------+-------------------------------------------------------+ | rshift | ( x1 u - - x2 ) | Logical right-shift of u bit-places | +---------------+-------------------------------+-------------------------------------------------------+ | lshift | ( x1 u - - x2 ) | Logical left-shift of u bit-places | +---------------+-------------------------------+-------------------------------------------------------+ | shr | ( x1 - - x2 ) | Logical right-shift of one bit-place | +---------------+-------------------------------+-------------------------------------------------------+ | shl | ( x1 - - x2 ) | Logical left-shift of one bit-place | +---------------+-------------------------------+-------------------------------------------------------+ | ror | ( x1 - - x2 ) | Logical right-rotation of one bit-place | +---------------+-------------------------------+-------------------------------------------------------+ | rol | ( x1 - - x2 ) | Logical left-rotation of one bit-place | +---------------+-------------------------------+-------------------------------------------------------+ | bic | ( x1 x2 - - x3 ) | Bit clear, identical to "not and" | +---------------+-------------------------------+-------------------------------------------------------+ | not | ( x1 - - x2 ) | Invert all bits | +---------------+-------------------------------+-------------------------------------------------------+ | xor | ( x1 x2 - - x3 ) | Bitwise Exclusive-OR | +---------------+-------------------------------+-------------------------------------------------------+ | or | ( x1 x2 - - x3 ) | Bitwise OR | +---------------+-------------------------------+-------------------------------------------------------+ | and | ( x1 x2 - - x3 ) | Bitwise AND | +---------------+-------------------------------+-------------------------------------------------------+ | false | ( - - 0 ) | False-Flag | +---------------+-------------------------------+-------------------------------------------------------+ | true | ( - - -1 ) | True-Flag | +---------------+-------------------------------+-------------------------------------------------------+ | clz | ( x1 - - u ) | Count leading zeros | +---------------+-------------------------------+-------------------------------------------------------+ .. index:: single number math Single Number Math ------------------ ========================== ================================ ============================================================ *exactly ANS* *some logical extensions* ========================== ================================ ============================================================ u/mod ( u1 u2 - - u3 u4 ) 32/32 = 32 rem 32 Division u1 / u2 = u4 remainder u3 /mod ( n1 n2 - - n3 n4 ) n1 / n2 = n4 rem n3 mod ( n1 n2 - - n3 ) n1 / n2 = remainder n3 / ( n1 n2 - - n3 ) n1 / n2 = n3 \* ( u1 n1 u2 n2 - - u3 n3 ) 32*32 = 32 Multiplication :ref:`min` ( n1 n2 - - n1 n2 ) Keeps smaller of top two items :ref:`max` ( n1 n2 - - n1 n2 ) Keeps greater of top two items :ref:`umin` ( u1 u2 - - u1 u2 ) Keeps unsigned smaller :ref:`umax` ( u1 u2 - - u1 u2 ) Keeps unsigned greater 2- ( u1 n1 - - u2 n2 ) Subtracts two, optimized 1- ( u1 n1 - - u2 n2 ) Subtracts one, optimized 2+ ( u1 n1 - - u2 n2 ) Adds two, optimized 1+ ( u1 n1 - - u2 n2 ) Adds one, optimized even ( u1 n1 - - u2 n2 ) Makes even. Adds one if uneven. 2* ( n1 - - n2 ) Arithmetric left-shift 2/ ( n1 - - n2 ) Arithmetric right-shift abs ( n - - u ) Absolute value negate ( n1 - - n2 ) Negate \- ( u1|n1 u2|n2 - - u3|n3 ) Subtraction \+ ( u1|n1 u2|n2 - - u3|n3 ) Addition ========================== ================================ ============================================================ .. index:: double number math Double Number Math ------------------ +----------------------------------------------------------------------------------------------------------+ | *exactly ANS, some logical extensions* | +===============+===============================+==========================================================+ | um* | ( u1 u2 - - ud ) | 32*32 = 64 Multiplication | +---------------+-------------------------------+----------------------------------------------------------+ | ud* | ( ud1 ud2 - - ud3 ) | 64*64 = 64 Multiplication | +---------------+-------------------------------+----------------------------------------------------------+ | udm* |(ud1 ud2 - - ud3-Low ud4-High )| 64*64=128 Multiplication | +---------------+-------------------------------+----------------------------------------------------------+ | um/mod | ( ud u1 - - u2 u3 ) | ud / u1 = u3 remainder u2 | +---------------+-------------------------------+----------------------------------------------------------+ | ud/mod| ( ud1 ud2 - - ud3 ud4 ) | 64/64 = 64 rem 64 Division ud1 / ud2 = ud4 remainder ud3 | +---------------+-------------------------------+----------------------------------------------------------+ | m* | ( n1 n2 - - d ) | n1 * n2 = d | +---------------+-------------------------------+----------------------------------------------------------+ | m/mod | ( d n1 - - n2 n3 ) | d / n1 = n3 remainder r2 | +---------------+-------------------------------+----------------------------------------------------------+ | d/mod | ( d1 d2 - - d3 d4 ) | d1 / d2 = d4 remainder d3 | +---------------+-------------------------------+----------------------------------------------------------+ | d/ | ( d1 d2 - - d3 ) | d1 / d2 = d3 | +---------------+-------------------------------+----------------------------------------------------------+ | \*/ | ( n1 n2 n3 - - n4 ) | n1 * n2 / n3 = n4 | +---------------+-------------------------------+----------------------------------------------------------+ | u*/ | ( u1 u2 u3 - - u4 ) | u1 * u2 / u3 = u4 | +---------------+-------------------------------+----------------------------------------------------------+ | \*/mod | ( n1 n2 n3 - - n4 n5 ) | n1 * n2 / n3 = n5 remainder n4 | +---------------+-------------------------------+----------------------------------------------------------+ | u*/mod | ( u1 u2 u3 - - u4 u5 ) | u1 * u2 / u3 = u5 remainder u4 | +---------------+-------------------------------+----------------------------------------------------------+ | d2* | ( d1 - - d2 ) | Arithmetric left-shift | +---------------+-------------------------------+----------------------------------------------------------+ | d2/ | ( d1 - - d2 ) | Arithmetric right-shift | +---------------+-------------------------------+----------------------------------------------------------+ | dshl | ( ud1 - - ud2 ) | Logical left-shift, same as d2* | +---------------+-------------------------------+----------------------------------------------------------+ | dshr | ( ud1 - - ud2 ) | Logical right-shift | +---------------+-------------------------------+----------------------------------------------------------+ | dabs | ( d - - ud ) | Absolute value | +---------------+-------------------------------+----------------------------------------------------------+ | dnegate | ( d1 - - d2 ) | Negate | +---------------+-------------------------------+----------------------------------------------------------+ | d- | ( ud1|d1 ud2|d2 - - ud3|d3 ) | Subtraction | +---------------+-------------------------------+----------------------------------------------------------+ | d+ | ( ud1|d1 ud2|d2 - - ud3|d3 ) | Addition | +---------------+-------------------------------+----------------------------------------------------------+ | s>d | ( n - - d ) | Turn a single into a double | +---------------+-------------------------------+----------------------------------------------------------+ .. index:: fixed point arithmetic Fixed Point Arithmetic ---------------------- .. seealso:: Fixed Point Page :ref:`Fixed Point Examples` *s31.32 fixed point numbers, speciality!* +--------------------------------------------------------------------------------------------------------------------------------+ | *Fixpoint numbers are stored ( n-comma n-whole ) and can be handled like signed double numbers* | +========+==========================================+============================================================================+ | d+ | ( df1 df2 - - df3 ) | Addition of two fixpoint numbers | +--------+------------------------------------------+----------------------------------------------------------------------------+ | d- | ( df1 df2 - - df3 ) | Subtraction of two fixpoint numbers | +--------+------------------------------------------+----------------------------------------------------------------------------+ | f/ | ( df1 df2 - - df3 ) | Division of two fixpoint numbers | +--------+------------------------------------------+----------------------------------------------------------------------------+ | f* | ( df1 df2 - - df3 ) | Multiplication | +--------+------------------------------------------+----------------------------------------------------------------------------+ | hold< | ( char - - ) | Adds character to pictured number output buffer from behind | +--------+------------------------------------------+----------------------------------------------------------------------------+ | f#S | ( n-comma1 - - n-comma2 ) | Adds 32 comma-digits to number output | +--------+------------------------------------------+----------------------------------------------------------------------------+ | f# | ( n-comma1 - - n-comma2 ) | Adds one comma-digit to number output | +--------+------------------------------------------+----------------------------------------------------------------------------+ | f\. | ( df - - ) | Prints a fixpoint number with 32 fractional digits | +--------+------------------------------------------+----------------------------------------------------------------------------+ | f.n | ( df n - - ) | Prints a fixpoint number with n fractional digits | +--------+------------------------------------------+----------------------------------------------------------------------------+ | number | ( c-addr length - - 0 ) | Tries to convert a string to a number. 0 = FAILED | | +------------------------------------------+----------------------------------------------------------------------------+ | | ( c-addr length - - n 1 ) | 1 = success, a 32 byte number is on the STACK | | +------------------------------------------+----------------------------------------------------------------------------+ | | ( c-addr length - - n-low n-high 2 ) | 2 = success, TWO 32 bit numbers, a HIGH BYTE and a LOW BYTE on the STACK | +--------+------------------------------------------+----------------------------------------------------------------------------+ .. index:: decision making Decision Making --------------- .. index:: single-comparisons Single-Comparisons ^^^^^^^^^^^^^^^^^^ +---------------------------------------------------------------------+ | *exactly ANS, some logical extensions* | +=====================================================================+ | Unigned Comparisons | +----------------+-----------------------+----------------------------+ | u<= | ( u1 u2 - - flag ) | u1 less-or-equal u2 | +----------------+-----------------------+----------------------------+ | u>= | ( u1 u2 - - flag ) | u1 greater-or-equal u2 | +----------------+-----------------------+----------------------------+ | u> | ( u1 u2 - - flag ) | u1 greater-than u2 | +----------------+-----------------------+----------------------------+ | u< | ( u1 u2 - - flag ) | u1 less-than u2 | +----------------+-----------------------+----------------------------+ .. index:: signed-comparisons Signed Comparisons ^^^^^^^^^^^^^^^^^^ +---------------------------------------------------------------------+ | *exactly ANS, some logical extensions* | +=====================================================================+ +----------------+-----------------------+----------------------------+ | <= | ( n1 n2 - - flag ) | n1 less-or-equal n2 | +----------------+-----------------------+----------------------------+ | >= | ( n1 n2 - - flag ) | n1 greater-or-equal n2 | +----------------+-----------------------+----------------------------+ | > | ( n1 n2 - - flag ) | n1 greater-than n2 | +----------------+-----------------------+----------------------------+ | < | ( n1 n2 - - flag ) | n1 less-than n2 | +----------------+-----------------------+----------------------------+ | 0< | ( n - flag ) | n less than zero | +----------------+-----------------------+----------------------------+ | 0<> | ( n - - flag ) | n not equal to zero | +----------------+-----------------------+----------------------------+ | 0= | ( n - - flag ) | n equals zero | +----------------+-----------------------+----------------------------+ | <> | ( n1 n2 - - flag ) | n1 not-equals n2 | +----------------+-----------------------+----------------------------+ | = | ( n1 n2 - - flag ) | n1 equals n2 | +----------------+-----------------------+----------------------------+ .. index:: double-comparisons Double-Comparisons ^^^^^^^^^^^^^^^^^^ +-----------------------------------------------------------+ | They perform the same for double numbers. | +================+==========================================+ | du> | ( ud1 ud2 - - flag ) | +----------------+------------------------------------------+ | du< | ( ud1 ud2 - - flag ) | +----------------+------------------------------------------+ | d> | ( d1 d2 - - flag ) | +----------------+------------------------------------------+ | d< | ( d1 d2 - - flag ) | +----------------+------------------------------------------+ | d0< | ( d - - flag ) | +----------------+------------------------------------------+ | d0= | ( d - - flag ) | +----------------+------------------------------------------+ | d<> | ( d1 d2 - - flag ) | +----------------+------------------------------------------+ | d= | ( d1 d2 - - flag ) | +----------------+------------------------------------------+ .. index:: test, toggle, clear and set .. _bit-tests: Bits: Test, Toggle, Clear and Set --------------------------------- Note: TRUE = 1, FALSE = 0. If a Bit is HIGH it leaves TRUE on the stack, otherwise FALSE ==================== ======================== ======================================== Word Stack Comment Description ==================== ======================== ======================================== cbit@ ( mask c-addr - - flag ) Test bit in byte-location hbit@ ( mask h-addr - - flag ) Test bit in halfword-location :ref:`bit@` ( mask a-addr - - flag ) Test bit in word-location cxor! ( mask c-addr - - ) Toggle bit in byte-location hxor! ( mask h-addr - - ) Toggle bit in halfword-location xor! ( mask a-addr - - ) Toggle bit in word-location cbic! ( mask c-addr - - ) Clear bit in byte-location hbic! ( mask h-addr - - ) Clear bit in halfword-location bic! ( mask a-addr - - ) Clear bit in word-location cbis! ( mask c-addr - - ) Set bit in byte-location hbis! ( mask h-addr - - ) Set bit in halfword-location bis! ( mask a-addr - - ) Set bit in word-location ==================== ======================== ======================================== .. index:: memory status, free ram, free flash, free memory, ram, flash Memory Status ------------- ======== ==================== ========================================================= Word Stack Comment Description ======== ==================== ========================================================= unused ( - - free memory ) Displays memory depending on compile mode (Ram or Flash) ======== ==================== ========================================================= .. index:: memory access Memory Access ------------- * subtle differences to ANS, special cpu-specific extensions .. _not-atomic: * Fetch-Modify-Store operations like +! or bic! are NOT :ref:`ATOMIC`. ================ ========================= ========================================================================================= =============== Word Stack Comment Description :ref:`Compiling Word?` ================ ========================= ========================================================================================= =============== move ( c-addr1 c-addr2 u - - ) Moves u Bytes in Memory fill ( c-addr u c ) Fill u Bytes of Memory with value c 2constant name ( ud|d - - ) Makes a double constant. Y constant name ( u|n - - ) Makes a single constant. i.e. "$1024 constant one-kb" Y 2variable name ( ud|d - - ) Makes an initialized double variable Y variable name ( u|n - - ) Makes an initialized single variable. i.e. "0 variable one-kb" Y nvariable name ( n1*u|n n1 - - ) Makes an initialized variable with specified size of n1, Maximum is 15 words Y buffer: name ( u - - ) Creates a :ref:`buffer` in RAM u bytes in length Y 2@ ( a-addr - - ud|d ) Fetches double number from memory 2! ( ud|d a-addr - - ) Stores double number in memory @ ( a-addr - - u|n ) Fetches single number from memory ! ( u|n a-addr - - ) Stores single number in memory +! ( u|n a-addr - - ) Plus Store, use to increment a variable, register etc h@ ( c-addr - - char ) Fetches halfword from memory h! ( char c-addr ) Stores halfword in memory h+! ( u|n a-addr - - ) Add to halfword memory location c@ ( c-addr - - char ) Fetches byte from memory c! ( char c-addr ) Stores byte in memory c+! ( u|n a-addr - - ) Add to byte memory location ================ ========================= ========================================================================================= =============== .. index:: string formatting String Formatting ---------------------------- String Routines ^^^^^^^^^^^^^^^ .. warning:: " may not render properly on your browser, hence copying and pasting commands that use " may fail. Click on "Show Source" to see the correct character. +------------------------------------------------------------------------------------------------------------------------------------------------+ | *exactly ANS, some logical extensions* | +===============================+===============================+================================================================================+ | type | ( c-addr length - - ) | Prints a string. | +-------------------------------+-------------------------------+--------------------------------------------------------------------------------+ | s" Hello" | ( - - c-addr length ) | Compiles a string and gives back its address and length when executed | +-------------------------------+-------------------------------+--------------------------------------------------------------------------------+ | ." Hello" | ( - - ) | Compiles a string and prints it when executed. | +-------------------------------+-------------------------------+--------------------------------------------------------------------------------+ | ( Comment ) | Ignore Comment | | +-------------------------------+-------------------------------+--------------------------------------------------------------------------------+ | \\ Comment | Comment to end of line | | +-------------------------------+-------------------------------+--------------------------------------------------------------------------------+ | cr | ( - - ) Emits line feed | | +-------------------------------+-------------------------------+--------------------------------------------------------------------------------+ | bl | ( - - 32 ) ASCII for Space | | +-------------------------------+-------------------------------+--------------------------------------------------------------------------------+ | space | ( - - ) Emits space | | +-------------------------------+-------------------------------+--------------------------------------------------------------------------------+ | spaces | ( n - - ) | Emits n spaces if n is positive | +-------------------------------+-------------------------------+-----------+--------------------------------------------------------------------+ | :ref:`compare` | ( caddr-1 len-1 c-addr-2 len-2 - - flag ) | Compares two strings | +-------------------------------+-------------------------------------------+--------------------------------------------------------------------+ | accept | ( c-addr maxlength - - length ) | Read input into a string. | +-------------------------------+-------------------------------------------+--------------------------------------------------------------------+ .. index:: counted string routines Counted String Routines ~~~~~~~~~~~~~~~~~~~~~~~ .. warning:: " may not render properly on your browser, hence copying and pasting commands that use " may fail. Click on "Show Source" to see the correct character. +--------------------------------------------------------------------------------------------------------------------------------+ | *exactly ANS, some logical extensions* | +===============+================================+===============================================================================+ | ctype | ( cstr-addr - - ) | Prints a counted string. | +---------------+--------------------------------+-------------------------------------------------------------------------------+ | c" Hello" | ( - - cstr-addr ) | Compiles a counted string and gives back its address when executed. | +---------------+--------------------------------+-------------------------------------------------------------------------------+ | cexpect | ( cstr-addr maxlength - - ) | Read input into a counted string. | +---------------+--------------------------------+-------------------------------------------------------------------------------+ | count | ( cstr-addr - - c-addr length )| Convert counted string into addr-length string | +---------------+--------------------------------+-------------------------------------------------------------------------------+ | skipstring | ( cstr-addr - - a-addr ) | Increases the pointer to the aligned end of the string. | +---------------+--------------------------------+-------------------------------------------------------------------------------+ .. index:: pictured numerical output .. _pictured-numerical-output: :ref:`Pictured Numerical Output` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-----------------------------------------------------------------------------------------------------------------------------------+ | Pictured Numerical output | +===============+===============================+===================================================================================+ | .digit | ( u - - char ) | Converts a digit to a char | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | digit | ( char - - u true | false ) | Converts a char to a digit | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | [char] * | ( - - char ) | Compiles code of following char when executed | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | char * | ( - - char ) | gives code of following char | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | hold | ( char - - ) | Adds character to pictured number output buffer from the front. | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | hold< | ( char - - ) | Adds character to pictured number output buffer from behind | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | sign | ( n - - ) | Add a minus sign to pictured number output buffer, if n is negative | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | #S | ( ud1|d1 - - 0 0 ) | Add all remaining digits from the double length number to output buffer | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | f#S | ( n-comma1 - - n-comma2 ) | Adds 32 comma-digits to number output | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | # | ( ud1|d1 - - ud2|d2 ) | Add one digit from the double length number to output buffer | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | f# | ( n-comma1 - - n-comma2 ) | Adds one comma-digit to number output | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | #> | ( ud|d - - c-addr len ) | Drops double-length number and finishes pictured numeric output ready for type | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | <# | ( - - ) | Prepare pictured number output buffer | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | u. | ( u - - ) | Print unsigned single number | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | \. | ( n - - ) | Print single number | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | ud. | ( ud - - ) | Print unsigned double number | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ | d. | ( d - - ) | Print double number | +---------------+-------------------------------+-----------------------------------------------------------------------------------+ .. index:: deep insights Deep Insights ------------- +--------------------------------------------------------------------------------------------+ | Deep Insights | +===============+=====================+======================================================+ | words | ( - - ) | Prints list of defined words and properties | +---------------+---------------------+------------------------------------------------------+ | list | ( - - ) | Prints all defined words. From; dissasembler-mx.txt | +---------------+---------------------+------------------------------------------------------+ | .s | ( many - - many ) | Prints stack contents, signed | +---------------+---------------------+------------------------------------------------------+ | u.s | ( many - - many ) | Prints stack contents, unsigned | +---------------+---------------------+------------------------------------------------------+ | h.s | ( many - - many ) | Prints stack contents, unsigned, hex | +---------------+---------------------+------------------------------------------------------+ | hex. | ( u - - ) | Prints 32 bit unsigned in hex base, needs emit only. | | | | This is independent of number subsystem. | +---------------+---------------------+------------------------------------------------------+ .. index:: user input and interpretation User Input and Interpretation ----------------------------- +-------------------------------------------------------------------------------------------------------------------------------+ | *exactly ANS, some logical extensions* | +===============+===============================+===============================================================================+ | query | ( - - ) | Fetches user input to input buffer | +---------------+-------------------------------+-------------------------------------------------------------------------------+ | tib | ( - - cstr-addr ) | Input buffer | +---------------+-------------------------------+-------------------------------------------------------------------------------+ | current-source| ( - - addr ) | Double-Variable which contains source | +---------------+-------------------------------+-------------------------------------------------------------------------------+ | tsource | ( c-addr len - - ) | Change source | +---------------+-------------------------------+-------------------------------------------------------------------------------+ | source | ( - - c-addr len ) | Current source | +---------------+-------------------------------+-------------------------------------------------------------------------------+ | >in | ( - - addr ) | Variable with current offset into source | +---------------+-------------------------------+-------------------------------------------------------------------------------+ | token | ( - - c-addr len ) | Cuts one token out of input buffer | +---------------+-------------------------------+-------------------------------------------------------------------------------+ | parse | ( char - - c-addr len ) | Cuts anything delimited by char out of input buffer | +---------------+-------------------------------+-------------------------------------------------------------------------------+ | evaluate | ( any addr len - - any ) | Interpret given string | +---------------+-------------------------------+-------------------------------------------------------------------------------+ | interpret | ( any - - any ) | Execute, compile, fold, optimize... | +---------------+-------------------------------+-------------------------------------------------------------------------------+ | quit | ( many - - ) (R: many - - ) | Resets Stacks | +---------------+-------------------------------+-------------------------------------------------------------------------------+ | hook-quit | ( - - a-addr ) | Hook for changing the inner quit loop | +---------------+-------------------------------+-------------------------------------------------------------------------------+ .. index:: dictionary expansion .. _compiletoflash: Dictionary Expansion -------------------- +-------------------------------------------------------------------------------------------------------------------------+ | *exactly ANS, some logical extension* | +===============+=========================+===============================================================================+ | align | ( - - ) | Aligns dictionary pointer | +---------------+-------------------------+-------------------------------------------------------------------------------+ | aligned | ( c-addr - - a-addr ) | Advances to next aligned address | +---------------+-------------------------+-------------------------------------------------------------------------------+ | cell+ | ( x - - x+4 ) | Add size of one cell | +---------------+-------------------------+-------------------------------------------------------------------------------+ | cells | ( n - - 4*n ) | Calculate size of n cells | +---------------+-------------------------+-------------------------------------------------------------------------------+ | allot | ( n - - ) | tries to advance Dictionary Pointer by n bytes, aborts, | | | | if not enough space available | +---------------+-------------------------+-------------------------------------------------------------------------------+ | here | ( - - a-addr|c-addr ) | Gives current position in Dictionary | +---------------+-------------------------+-------------------------------------------------------------------------------+ | , | ( u|n - - ) | appends a single number to dictionary | +---------------+-------------------------+-------------------------------------------------------------------------------+ | ><, | ( u|n - - ) | reverses high and low-halfword, then appends it to dictionary | +---------------+-------------------------+-------------------------------------------------------------------------------+ | h, | ( u|n - - ) | appends a halfword to dictionary | +---------------+-------------------------+-------------------------------------------------------------------------------+ | compiletoram? | ( - - ? ) | currently compiling into ram ? | +---------------+-------------------------+-------------------------------------------------------------------------------+ | compiletoram | ( - - ) | makes ram the target for compiling | +---------------+-------------------------+-------------------------------------------------------------------------------+ | compiletoflash| ( - - ) | makes :ref:`flash memory` the target for compiling | +---------------+-------------------------+-------------------------------------------------------------------------------+ | forgetram | ( - - ) | Forget definitions in ram without a reset | +---------------+-------------------------+-------------------------------------------------------------------------------+ Speciality! ^^^^^^^^^^^ ============================= ========================================= =================================================================================================================================== Words Stack Comment Description ============================= ========================================= =================================================================================================================================== string, ( c-addr len - - ) Inserts a string of maximum 255 characters without runtime literal, ( u|n - - ) Compiles a literal with runtime :ref:`inline,` ( a-addr - - ) Inlines the choosen subroutine call, ( a-addr - - ) Compiles a call to a subroutine jump, ( Hole-for-Opcode Destination ) Writes an unconditional Jump to a-addr-Destination with the given Bitmask as Opcode into the halfword sized h-addr-Hole cjump, ( Hole-for-Opcode Destination Bitmask ) Writes a conditional Jump to a-addr-Destination with the given Bitmask as Opcode into the halfword sized h-addr-Hole ret, ( - - ) compiles a ret opcode flashvar-here ( - - a-addr ) Gives current RAM management pointer dictionarystart ( - - a-addr ) Current entry point for dictionary search dictionarynext ( a-addr - - a-addr flag ) Scans dictionary chain and returns true if end is reached. ============================= ========================================= =================================================================================================================================== .. index:: chip specials .. _special.words: Special Words Depending on MCU Capabilities ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ============================= ========================================= =================================================================================================================================== Words Stack Comment Description ============================= ========================================= =================================================================================================================================== :ref:`c,` ( char - - ) Appends a byte to dictionary. NOT AVAILABLE ON ALL MCU'S. Check with ' c, or just look in 'words'. halign ( - - ) Makes Dictionary Pointer even, if uneven. movwmovt, ( x Register - - ) Generate a movw/movt-Sequence to get x into any given Register. M3/M4 only :ref:`registerliteral,` ( x Register - - ) Generate shortest possible sequenceto get x into given low Register. On M0: A movs-lsls-adds... sequence M3/M4: movs / movs-mvns / movw / movw-movt 12bitencoding ( x - - x false | bitmask true ) Can x be encoded as 12-bit :ref:`immediate` ? eraseflash ( - - ) Erases everything after --- Flash Dictionary --- Clears Ram, Restarts Forth. Does not erase Mecrisp-Stellaris eraseflashfrom ( a-addr -- ) Starts erasing at this address. Clears Ram. Restarts Forth. flashpageerase ( a-addr -- ) Erase one 1k flash page only. Take care: No Reset, no dictionary reinitialisation. hflash! ( u|n a-addr -- ) Writes halfword to flash ============================= ========================================= =================================================================================================================================== .. index:: flags and inventory, flags Flags and Inventory ------------------- ============================= ================================ =================================================================================================================================== Speciality! Stack Comment Description ============================= ================================ =================================================================================================================================== :ref:`smudge` ( - - ) Makes current definition visible, burns collected flags to flash and takes care of proper ending :ref:`inline` ( - - ) Takes the code of a word, and puts it in place of a call to this word immediate ( - - ) Will not compile this word into the dictionary but execute the word immediately compileonly ( - - ) Makes current definition compileonly setflags ( char - - ) Sets Flags with a mask. This isn't immediate, (create) name ( - - ) Names a location; space may be allocated at this location, or it can be set to contain a string or other initialized value. Instance behavior returns the address of the beginning of this space. Use FIG-style ! find ( c-addr len - - a-addr flags) Searches for a String in Dictionary. Gives back flags, which are different to ANS! ============================= ================================ =================================================================================================================================== .. index:: folding .. _folding_table: Folding ------- ============================= ============================= =============================================================== =================================================================== Speciality! Stack Comment Description Applies To ============================= ============================= =============================================================== =================================================================== 0-:ref:`foldable` ( - - ) Current word becomes :ref:`foldable` with 0 constants constants variables ['] [char] 1-:ref:`foldable` ( - - ) 1 constant ?dup drop negate 2-:ref:`foldable` ( - - ) 2 constants \+ \- \* swap nip 3-:ref:`foldable` ( - - ) 3 constants rot 4-:ref:`foldable` ( - - ) 4 constants d+ d- 2swap 5-:ref:`foldable` ( - - ) 5 constants 6-:ref:`foldable` ( - - ) 6 constants 7-:ref:`foldable` ( - - ) 7 constants ============================= ============================= =============================================================== =================================================================== .. index:: compiler essentials, postpone Compiler Essentials ------------------- **The true POWER of Forth resides in the Words listed in this table.** +-----------------------------------------------------------------------------------------------------------------------------+ | *subtle differences to ANS* | +=========================+===================+===============================================================================+ | execute | ( a-addr - - ) | Calls subroutine | +-------------------------+-------------------+-------------------------------------------------------------------------------+ | recurse | ( - - ) | Lets the current definition call itself | +-------------------------+-------------------+-------------------------------------------------------------------------------+ | ' name | ( - - a-addr ) | Tries to find name in dictionary gives back executable address | +-------------------------+-------------------+-------------------------------------------------------------------------------+ | ['] name | ( - - a-addr) | Tick that compiles the executable address of found word as literal | +-------------------------+-------------------+-------------------------------------------------------------------------------+ | postpone | ( - - ) | See :ref:`Glossary` | +-------------------------+-------------------+-------------------------------------------------------------------------------+ | :ref:`` | ( - - ) | Makes Dictionary header and reserves space for special call. | +-------------------------+-------------------+-------------------------------------------------------------------------------+ | does> | ( - - ) | executes: ( - -a-addr ) Gives address to where you have stored data. | +-------------------------+-------------------+-------------------------------------------------------------------------------+ | create name | ( - - ) | Create a definition with default action which cannot be changed later. | | | | Use instead. Equivalent to : create ; | +-------------------------+-------------------+-------------------------------------------------------------------------------+ | state | ( - - a-addr ) | Address of state variable | +-------------------------+-------------------+-------------------------------------------------------------------------------+ | ] | ( - - ) | :ref:`Switch to compile state` | +-------------------------+-------------------+-------------------------------------------------------------------------------+ | [ | ( - - ) | :ref:`Switch to execute state` | +-------------------------+-------------------+-------------------------------------------------------------------------------+ | ; | ( - - ) | Finishes new definition | +-------------------------+-------------------+-------------------------------------------------------------------------------+ | : name | ( - - ) | Opens new definition | +-------------------------+-------------------+-------------------------------------------------------------------------------+ .. index:: control structures, if, then, else, case Control Structures ------------------ *Internally, they have complicated compile-time stack effects.* Summary ^^^^^^^ ======================= ============================================================================================================================================================ Structure Description ======================= ============================================================================================================================================================ DO … LOOP Finite loop incrementing by 1 DO … +LOOP Finite loop incrementing by X BEGIN … UNTIL Indefinite loop terminating when is 'true' BEGIN … WHILE … REPEAT Indefinite loop terminating when is 'false' BEGIN … AGAIN Infinite loop IF … ELSE … THEN Two-branch conditional; performs words following IF it is 'true' and words following ELSE if it is 'false'. THEN marks the point at which the paths merge. IF … THEN Like the two-branch conditional, but with only a 'true' clause. ======================= ============================================================================================================================================================ Decisions ^^^^^^^^^ +---------------+-------------------+-------------------------------------------------------------------------------+ | Decisions | | *exactly ANS* | +===============+===================+===============================================================================+ | then | ( - - ) | This is the common flag if ... [else ...] then structure. | +---------------+-------------------+-------------------------------------------------------------------------------+ | else | ( - - ) | flag if ... [else ...] then | +---------------+-------------------+-------------------------------------------------------------------------------+ | if | ( flag - - ) | structure. | +---------------+-------------------+-------------------------------------------------------------------------------+ Syntax ~~~~~~ "IF that's the case, do this, ELSE do that ... and THEN continue with ..." :: flag if ... then flag if ... else ... then Case ^^^^ +-----------------------------------+-------------------------------------------------------------------------------+ | Case | *exactly ANS* | +===============+===================+===============================================================================+ | case | ( n - -n ) | Begins case structure | +---------------+-------------------+-------------------------------------------------------------------------------+ | of | ( m - - ) | Compares m with n, choose this if n=m | +---------------+-------------------+-------------------------------------------------------------------------------+ | ?of | ( n flag - - ) | Flag-of, for custom comparisions | +---------------+-------------------+-------------------------------------------------------------------------------+ | endof | ( - - ) | End of one possibility | +---------------+-------------------+-------------------------------------------------------------------------------+ | endcase | ( n - - ) | Ends case structure, discards n | +---------------+-------------------+-------------------------------------------------------------------------------+ Syntax ~~~~~~ :: n case m1 of ... endof m2 of ... endof flag ?of ... endof all others endcase .. index:: loops Indefinite Loops ^^^^^^^^^^^^^^^^ A loop structure in which the words contained within the loop continue to repeat until some truth condition changes state (true-to-false or false-to-true). In Forth, the indefinite loops begin with the word BEGIN. ==================== ============================================================== ========================================================================================== Indefinite Loops Stack Comment Exactly ANS ==================== ============================================================== ========================================================================================== repeat ( - - ) Finish of a middle-flag-checking loop. while ( flag - - ) Check a flag in the middle of a loop until ( flag - - ) Begin ... flag until loops as long flag is true again ( - - ) begin ... again is an endless loop begin ( - - ) ==================== ============================================================== ========================================================================================== Syntax ~~~~~~ :: begin ... again begin ... flag until begin ... flag while ... repeat .. index:: definite loops .. _definite-loops: Definite Loops ^^^^^^^^^^^^^^ A loop structure in which the words contained within the loop repeat a definite number of times. In Forth, this number depends on the starting and ending counts (index and limit) which are placed on the stack prior to the execution of the word DO. ==================== ============================================================== ========================================================================================== Definite Loops Stack Comment Exactly ANS ==================== ============================================================== ========================================================================================== i ( - -u|n ) Gives innermost loop index j ( - -u|n ) Gives second loop index k ( - -u|n ) Gives third loop index unloop (R: old-limit old-index - - ) Drops innermost loop structure, pops back old loop structures to loop registers exit ( - - ) Returns from current definition. Compiles a ret opcode. leave ( - - ) (R: old-limit old-index - - ) Leaves current innermost loop promptly :ref:`+loop<+loop>` ( u|n - - ) (R: unchanged | old-limit old-index - - ) If you want the index to go up by some number other than one each time around. :ref:`loop` ( - - ) (R: unchanged | old-limit old-index - - ) Increments current loop index register by one and checks whether to continue or not. ?do ( Limit Index - - ) (R: unchanged | - -old-limit old-index ) Begins a loop if limit and index are not equal :ref:`do ` ( Limit Index - - ) (R: - -old-limit old-index ) Begins a loop ==================== ============================================================== ========================================================================================== Syntax ~~~~~~ :: limit index do ... loop .. index:: dictionary: common hardware access Common Hardware Access ---------------------- +-------------------------------------------------------------------------------------+ | | +=======================+=================+===========================================+ | reset | ( - - ) | Reset on hardware level | +-----------------------+-----------------+-------------------------------------------+ | dint | ( - - ) | Disables Interrupts | +-----------------------+-----------------+-------------------------------------------+ | eint | ( - - ) | Enables Interrupts | +-----------------------+-----------------+-------------------------------------------+ | eint? | ( - - ) | Are Interrupts enabled ? | +-----------------------+-----------------+-------------------------------------------+ | nop | ( - - ) | No Operation. Hook for unused handlers ! | +-----------------------+-----------------+-------------------------------------------+ | ipsr | ( - - ipsr ) | Interrupt Program Status Register | +-----------------------+-----------------+-------------------------------------------+ | unhandled | ( - - ) | Message for unhandled interrupts. | +-----------------------+-----------------+-------------------------------------------+ | irq-systick | ( - - a-addr ) | Memory locations for IRQ-Hooks | +-----------------------+-----------------+-------------------------------------------+ | irq-fault | ( - - a-addr ) | For all faults | +-----------------------+-----------------+-------------------------------------------+ | irq-collection | ( - - a-addr ) | Collection of all unhandled interrupts | +-----------------------+-----------------+-------------------------------------------+