Index by Themes
Glossary of I/O Commands


Glossary of 'Avise4.3' Arithmetic and System Commands

(updated 12 February 2006)

In contrast to the previous version, 'Avise 4.x' is restricted to a postfix style programming syntax. This is due to the fact that it experimentally compiles a subroutine threaded code instead of a token threaded code. So the the "recursive descent" and the assignment to left-side variables used to make the previous version somewhat "Basic-like" became too complicated in this context.
For every command, a "stack comment" added:
(stack before -- stack after),
where the TOS (top of stack) is written righthand. But only the upper stack entries, which are influenced by the command are written.
When a command needs to be followed by a (name)string, this is additionally noted separated by a semicolon.

Note: in the following text, "argument" or "operand" means TOS for postscript operations, "first argument" or "left argument" means NOS, "second argument" or "right argument" means TOS, the same order Forth stack comments are written. The phrases "returned" and "pushed" mean as much as "put on the stack" whereas "popped" means "taken from the stack".


$

( -- )
When used as a command, i.e. separated with a space from the subsequent code, it switches number interpreter and console output to HEXADECIMAL format. This number base is valid until next & command or until the next INIT or hardware reset. If you want the system to start with HEX numbers, write an appropriate AUTOSTART function

Alternatively, when used as a number prefix (not separated with a space from the subsequent number text), only this number is interpreted as HEXADECIMAL, the number base is not changed.


&

( -- )
Switches number interpreter and console output to DECIMAL format.
This is a command, not a unitary prefix. This number base is valid until next $ command.

When the command $ or & is entered during compilation, this has only an effect to the function beeing just compiled, active number base is not affected.
However: When $ or & is executed during runtime of a user compiled function, this number base remains valid until next number base command.


*

( X1 X2 -- X3 )
Signed multiplication (16x16bit) to get the resulting factor X3 in 16 bit format. Take care for possible overflow. Then you may use */ instead.

Example: X1 X2 *


*/

( X1 X2 X3 -- XQL XQH )
Combined scaling function: Unsigned multiplication X1*X2 (16x16bit) into a 32 bit intermediate result- this is divided by 16 bit value X3 to get the resulting quotient XQH XQL in 32 bit format
After execution, XQH, which is TOS should be checked if 0.


*/MOD

( X1 X2 X3 -- MOD XQL XQH )
Combined scaling function: Unsigned multiplication X1*X2 (16x16bit) into a 32 bit intermediate result- this is divided by 16 bit value X3 to get the resulting quotient XQH XQL in 32 bit format and the remainder of the division XR in 16 bit format. This is a somewhat complicated but mighty operation.

Example:
X1 X2 X3 */MOD
<> 0 IF ABORT ENDIF


+

( X1 X2 -- X3 )
16 bit addition: X3 := X1 + X2 ;
Overflow will set the highlevel carry flag CARRY. Circular overflow, i.e. appropriate for signed as well as for unsigned numbers.

Example: X1 X2 +


-

( X1 X2 -- X3 )
Borrow will set the highlevel carry flag CARRY.Circular overflow, i.e. appropriate for signed as well as for unsigned numbers. Alternative meaning: unary operator (minus sign). Then no space between - and number is allowed.


-ROT

( X1 X2 X3 -- X3 X1 X2 )
Postfix specific operator. Rotates the top of stack down to the 3rd stack position.
Opposite direction of rotation see ROT.


.  (period)

( X -- )
Transmits the argument data via serial interface as ASCII text expressed in the active number base (default=decimal, may be set to hex) plus one leading space.
See EMIT, too.

Example:
VAR KARL
$41 KARL WR
KARL RD .


.$

( X -- )
Transmits the argument data via serial interface as ASCII text hex number, independent of the active number base plus one leading space.
See . (period), too.


."

( X -- )
Compiles the following ASCII text until delimiting " (quote) to be transmitted at runtime via serial interface.


.S

( -- )
Simple debugging or system monitoring tool. Emits (non destructive) the contents of data stack and the first 8 user defined variables in order of definition via serial interface. This function is called by the single step debugger, too. But when .S is called out of the debugger, execution is not halted.


/

( X1 X2 -- X3 )
Signed division 16/16bit to 16 bit
For remainder see MOD


Ø=

( X -- T|F )
Postfix specific operator. Returns TRUE on the stack, if the argument is equal to zero. Can be used as inverter for boolean flags.


: (colon)

( -- ; name string)
The Colon operator does start the definition of a new user function with the name, wich is picked from the terminal input next after the colon separated by spaces. The length of the name must be limitied to 12 characters or less. Number strings and names of kernel words must be avoided. Earlier user functions can be overridden (without warning). The colon command does switch 'Avise' into the compiling state. I.e. all words entered beween the name word and the final "RET" will not be executed but compiled into the new word.

Example:
: SUM 2 + 3 . RET


<

( X1 X2 -- T|F)
Compare operator. Returns 1(=TRUE) if the left argument is less than the right argument, else returns 0 (=FALSE).
Signed compare. For unsigned compare, see U<.

Example: IF(X1 < X2) ." LESS" ENDIF
Postfix example: X1 X2 <| IF ." LESS" ENDIF


<<

( X1 -- X2 )
Shift left the bits of the first argument "x" by "n" positions (second argument). Least significant bits, where data is shifted out, are filled with "0".

Example:
VAR KARL
KARL 3 SHL


<=

( X1 X2 -- T|F)
Compare operator. Returns 1(=TRUE) if the left argument is less than or equal to the right argument, else returns 0 (=FALSE).
Signed compare.


<>

( X1 X2 -- T|F)
Compare operator. Returns 1(=TRUE) if the left argument is unequal to the right argument, else returns 0 (=FALSE).


=

( X1 X2 -- T|F)
Compare operator. Returns 1(=TRUE) if the left argument is equal to the right argument, else returns 0 (=FALSE).


>

( X1 X2 -- T|F)
Compare operator. Returns 1(=TRUE) if the left argument is greater than the right argument, else returns 0 (=FALSE).
Signed compare. For unsigned compare, see U>.


>=

( X1 X2 -- T|F)
Compare operator. Returns 1(=TRUE) if the left argument is greater than or equal the right argument, else returns 0 (=FALSE).
Signed compare.


>>

( X1 -- X2 )
Shift right the bits of the first argument "x" by "n" positions (second argument). Most significant bits, where data is shifted out, are filled with "0". Example see SHL


ABORT

( -- )
Unconditional warm start of 'Avise' will be executed. That means: stacks and console buffers are reset. Values of variables and I/O configuration remain unchanged.


ABS

( X -- |X| )
Interpret argument as signed number and return its absolute value. I.e.: if bit 15 of x is set, the two's complement of x is returned.


ACHECK

( X1 addr(X2) DELTA -- T|F )
This operator is used to track analog input states and trigger messages when they are changed.

It is called with 3 arguments where X1 usually is an input value, addr(X2) usually is a variable where the reference value X2 is stored and DELTA is the is the message trigger level.
If ABS(X1-X2) < delta, then false=0 is returned.
If ABS(X1-X2) >= DELTA, then TRUE=1 is returned and X1 is simultaneously stored as new reference at addr(X2).


AND

( X1 X2 -- X3 )
Bitwise 16 bit logical AND.


AUTOEXE

( -- ; name string)
Called in the manner: AUTOEXE <name>, it makes <name> an autostarting function, which is automatically executed after cold start before control of 'Avise' is handled to the operator terminal. You can leave the AUTOEXE function at every time by sending a tilde character ~ =hexFE via the serial interface. Calling AUTOEXE with an improper name will disable the autofunction at system start.
Example:
AUTOEXE USERFUN
How to clear AUTOEXE function:
AUTOEXE NONSENSE


BCHECK

( X1 addr(X2) -- T|F )
This operator is used to compare data words and trigger messages when they are changed.

It is called with 2 arguments where X1 usually is an input value, addr(X2) usually is a variable where the reference value X2 is stored.
If X1 = X2 then false=0 is returned.
If X1 <> X2, then TRUE=1 is returned and X1 is simultaneously stored as new reference at addr(X2).


BCLR

( b addr -- )
Clear bit (set to 0=L) at position "b" (0...15) of the pair of SRAM bytes at address "addr" and "addr+1".
According to the AVR memory model, this can be a user declared variable, a controller register, controller SRAM ( addresses <= 0xff) or an i/o register. a read-modify-write operation is performed, which may give unwanted results at certain i/o registers (take care for the difference between port and pin !).

Example:
VAR KARL
9 KARL BCLR


BREAK

( -- )
Sets a breakpoint into the code of a user programmed function. When the breakpoint is executed, the display of .S is transmitted to the terminal display, then program execution is halted. Program flow will continue, when the TAB byte (0x09) is received via serial interface. By default, breakpoints are generally deactivated. They can be activated (and subsequently deactivated) with the DEBUG command. Deactivated breakpoints are still present in the object code, but need very few runtime oberhead.


BSET

( b addr -- )
Set bit (set to 1=H) at position "b" (0...15) of the pair of SRAM bytes at address "addr" and "addr+1".
According to the AVR memory model, this can be a user declared variable, a controller register, controller SRAM (addresses <= 0xff) or an i/o register. a read-modify-write operation is performed, which may give unwanted results at certain i/o registers (take care for the difference between port and pin !).


BTST

( b addr -- T|F )
Test bit at position "b" (0...15) of the pair of SRAM bytes at address "addr" and "addr+1". TRUE is reported, if bit is set (=1, high), FALSE else
According to the AVR memory model, this can be a user declared variable, a controller register, controller SRAM (addresses <= 0xff) or an i/o register.


CARRY

( -- T|F )
Reflects if the last executed of the following operators did cause an overflow (carry or borrow): + , INK, - , DEK. In case of overflow, if explicitely called, CARRY returns +1 (!) else it returns 0. This can be a great help in 32 bit arithmetics.
Note: the carry flag used here is independent of the CPU carry flag.


CONST

( X -- ; name string)
Declares a constant (16 bit integer)

Example: CONST KARL 347


DEBUG

( T|F -- )
Calling DEBUG(1) activates the single step debugger. Calling DEBUG(0) deactivates the single step debugger. Then the program is running free with very little runtime overhead.


DEK

( X -- X-1 )
Postfix specific operator, decrease top of stack by one. Cyclic behaviour.


DOFOR

Runtime primitive which is compiled by FOR.
Not directly user applicable. Listed here only as reference for SEE output..


DOLIT

Runtime primitive, which returns compiled numeric values .
Not directly user applicable. Listed here only as reference for SEE output.


DONEXT

Runtime primitive, which is compiled by NEXT.
Not directly user applicable. Listed here only as reference for SEE output.


DOSTR

Runtime primitive, which is compiled by .".
Not directly user applicable. Listed here only as reference for SEE output.


DROP

( X -- )
Postfix specific operator. Deletes the top of the stack and pops all stack entries up by one position.


DSWAP

( X1 X2 X3 X4 -- X3 X4 X2 X1 )
Postfix specific operator. Does exchange the upper two data stack entries with the third and fourth ones. May be helpful for user defined 32 bit functions.


DUP

( X -- X X )
Postfix specific operator. Duplicates the top op the stack and pushes all stack entries down by one position.


ELSE

( -- )
Introduces to the FALSE alternative at conditional branches.


EMIT

( b -- )
Transmits the low-byte of TOS "raw" via the serial interface . No check if the data is printable. THe high-byte of TOS is ignored


ENDIF

( -- )
Does finish a conditional branch structure beginning with IF.


ERB

( addr -- b )
Reads one byte from the CPU internal EEPROM to the data stack.


EWB

( b addr -- )
Writes one byte from the data stack to the CPU internal EEPROM.


EXIT

( -- )
Returns from a use function. Same runtime behaviour as RET, but marks a side-exit out of a function. Does not stop the compiler.


FOR

(<start> <stop> -- ; VAR name)
Introduces a counted loop: <start> <stop> FOR <variable> ... NEXT.
<variable> is the loop counter, which is put into a variable for easier manipulation of stepping during the loop. With the start index <start> the loop is performed first, with the stop index <stop> the loop is performed last. The default count step is 1, the direction of stepping is automatically detected by signed compare of start and stop index.
See DO, NEXT and LEAVE for further information.


FORGET

( -- ;name string)
Deletes the user-compiled function, variable or constant <namestring> and all functions, variables and constants, which are compiled later. Resets the compile memory pointer, accordingly.

FORGET may only be called interactively, it must not be compiled into user words!


GO

Runtime primitive which is compiled by ELSE. Performs an unconditional branch at runtime
Not directly user applicable. Listed here only as reference for SEE output..


IF

( T|F -- )
Compiles a conditional jump to the respective ELSE or ENDIF.

Example:
LUEGE IF 1 . ELSE 0 . ENDIF


IFNOTGO

Runtime primitive which is compiled by IF and UNTIL. Performs a conditional branch at runtime if TOS is FALSE
Not directly user applicable. Listed here only as reference for SEE output..


INIT

( -- )
Unconditional cold start of 'Avise' will be executed. I.e. a microcontroller reset is forced, all memory and I/O will be reninitalized. If set, an AUTOEXE function will be executed before the command interpreter can be reached by the user.


INK

( X -- X+1 )
Postfix specific operator, increases top of stack by one. Cyclic behaviour.


KEY

( -- b )
Returns a byte from the input buffer of the serial interface. If the buffer is empty, KEY does wait until a byte arrives.
Attention: No timeout limit. Deadlock situations may arise ! Can be resoved by typing a tilde ~ on the console keyboard.


KEY?

( -- 0 or b 1 )
Checks if data are in the input buffer of the serial interface.
If none, immediately a zero byte (FALSE) is returned. If any data are in the buffer, then the eldest byte is moved from the buffer and returned on the stack. Above, as TOS, is put 1(TRUE). Bytes once read out the buffer cannot be stored back.

Example:
AT TEST := KEY? ;
IF (TEST <> 0)
  AT CHAR := ;
ENDIF


LEAVE

( -- )
Immediately leaves the innermost DO ... NEXT structure and continues execution behind the respective NEXT (compiled as DONEXT) token. Loop parameters are removed from stack. The variable, which holds the actual loop counter, is left unchanged.


MEM

( -- )
Returns information about free memory. The message contains the following information:
"S" is the free memory of the symbol table divided by 8. This is the number of new items which will fit into the table if the average name length is 5 characters.
"C" is the number of flash memory segments which are still available for user programs, i.e. the max. number of user functions which still may be programmed.
"V" is the number of variables still available for declaration.

Example:MEM S:63 C:64 V:36 ok


MOD

( X1 X2 -- X3 )
Remainder of signed division 16/16bit to 16 bit

Example:X1 X2 MOD


MS

( X -- )
Triggers an internal countdown with duration of x time steps of ONE millisecond each. The AVR microcontroller's timer #0 is used and during this time it is not available for lowlevel user action. Else no direct action is performed, program flow is going on after starting the timer. Further evaluation of timing action see TIME and WAIT.

Example: 32 MS WAIT


NEXT

( -- )
Loop end point of a FOR...NEXT structure. Internally the loop counter is incremented/decremented. If the stop value is reached, program continues execution behind NEXT. Else program execution restarts looping behind FOR.


NOT

( X -- /X )
Every bit of the argument is inverted to its logical complement ("one's complement").


OPS

( -- )
Displays a list of all currently available kernel operators as well as user defined functions, variables and constants of 'Avise'. Each user defined function name is followed by its code address in SRAM.
With some types of terminal programs a problem may arise when many user functions are defined. Then the top of the display may scroll out of the display. Send TAB to the serial port to freeze the display, send any character to the serial port to reactivate the display process .


OR

( X1 X2 -- X3 )
Bitwise 16 bit logical OR.

Postfix example: X1 X2 OR


OVER

( X1 X2 -- X1 X2 X1 )
Postfix specific operator. Copy the second stack element over the top of the stack. Now it will be the top of the stack and all other entries are pushed down one position.


RB

( addr -- b )
Reads one data byte from the microcontroller SRAM memory space. According to the AVR memory model, this can be a "general purpose" CPU register, an I/O register or any byte else.


RD

( addr -- X )
Reads one data word from the microcontroller SRAM memory space. According to the AVR memory model, this can be a user declared variable or any pair of bytes else.
The data must be stored "little endian" style: low byte at "addr", high byte at "addr+1". Example:
KARL RD .


REPEAT

( -- )
Mark the beginning of an uncounted REPEAT ... UNTIL loop


RET

( -- )
Returns from a user function. Same runtime function as EXIT, but does finish the compilation, too.


ROL

( X1 -- X2 )
Rotate left the bits of the first argument "x" by "n" positions (second argument). No intermediate storage in a carry flag.
This command is especially prepared to build user shift and rotate commands with word length of more than 16 bit. Then use masking AND and combining OR techniques. Example see SHL


ROR

( X1 -- X2 )
Rotate right the bits of the first argument "x" by "n" positions (second argument).
Comment see ROL.


ROT

( X1 X2 X3 -- X2 X3 X1 )
Postfix specific operator. Rotate the upper three elements of the data stack. The third element will be rotated to the top of the stack. The previous two top elements are pushed down one position.
Opposite direction of rotation see -ROT.


SEE

( -- ;name string)
Simple decompiler for user-compiled functions. Emits the content of the function <name> via serial interface to the terminal display. The compiled code is always displayed in postfix format as it is burnt into the EEPROM chip. It is much differing from infix style source code - especially in conditional structures and loops. SEE is not comfortable in any way, but in case of problems it gives a straight view into the code as it is executed at runtime.
SEE can only be called interactively, it must not be compiled into user functions!


SEETEMP

( -- ;name string)
Same output as SEE, but displays temporarily compiled code from SRAM (until termination of the compiler due to error). Still unresolved branch destinations are filled with zero. Must be called immediately after compilation because this SRAM region may be overwritten.


SWAP

( X1 X2 -- X2 X1 )
Postfix specific operator. Does exchange the upper two data stack entries. (swaps data words, to be distinguished from the AVR machine command "SWAP"!)


TIME

( X -- )
Returns the actual value of countdown timer on the stack. Time scale and start value were set by MS. User can decide what to do with this information.


U<

( X1 X2 -- T|F)
Compare operator. Returns 1(=TRUE) if the left argument is less than the right argument, else returns 0 (=FALSE).
UNsigned compare. For signed compare, see <.


U>

( X1 X2 -- T|F)
Compare operator. Returns 1(=TRUE) if the left argument is greater than the right argument, else returns 0 (=FALSE).
UNsigned compare. For signed compare, see >.

Example: IF(X1 U> X2) ." UGRTR" ENDIF
Postfix example: X1 X2 U> IF 1 . ENDIF


UNTIL

( T|F -- )
Finishes a loop structure started with REPEAT.
If the argument is "FALSE" (i.e. exactly = Ø), program execution will continue looping behind REPEAT.
If the top of stack is "TRUE" (i.e. not equal Ø), program continues execution behind UNTIL.

Example:
REPEAT ...... KEY? UNTIL BUCHSTABE WR


VAR

( -- ;name string)
Immediate function for declaration of variables, which reserves a parameter field in the CPU SRAM. Variable is initialised with zero value.

Example: VAR KARL


WAIT

( X -- )
May be used after a MS command to pause execution until the timer has counted down to zero. No exit out of this delay is possible except entering the tilde character ~ = 0xFE via serial interface, which will initiate a warm start!


WB

( b addr -- )
Writes one data byte into the microcontroller SRAM memory space. According to the AVR memory model, this can be a "general purpose" CPU register, an I/O register or any byte else.

Attention: most "general purpose" registers and many I/O resources are internally used by 'Avise'. Wrong operation may cause buggy operation of 'Avise'. Hardware reset or INIT command normally will clear this malfunction.


WR

( X addr -- )
Writes one data word into the microcontroller SRAM memory space. According to the AVR memory model, this can be a user declared variable or any pair of bytes else.
The data word will be stored "little endian" style: low byte at "addr", high byte at "addr+1".

Example:
VAR KARL
3 KARL WR


XOR

( X1 X2 -- X3)
Bitwise 16 bit logical EXCLUSIVE OR.

Example: X1 X2 XOR


{

( -- )
Opens a comment. Normally the rest of the line until CR is regarded as a comment now. Alternatively, a corresponding bracket '}' will finish the comment.


Index by Themes
Glossary of I/O Commands