Glossary of 'Avise2.4' general commands:
(updated 22 Apr 2002)

In the versions for the AT90S4433 some functions are missing due to lack of code memory. Enter WORDS to get a list of functions of your specific version. Differences between different hardware versions are outlined where necessary

$

Switches number interpreter and console output to HEXADECIMAL format (is default after INIT and ABORT).
This is a command, not a unitary prefix. Number base is valid until next % command.

See comment below "%".

%

Switches number interpreter and console output to DECIMAL format.
This is a command, not a unitary prefix. Number base is valid until next INIT or $ command.

Comment on validity range of $ and %: During compiling state, $ and % are compiled and further more immediately executed. Immediate execution is necessary in this case to convert number strings correctly into their binary value. Compilation of the $ or % token is necessary to get correct number output at runtime.
Generally, when compiling state is starting, the number base which was active during interpreting state remains valid. During compilation the base can be changed at any time and stays valid until the next change under compiling state. When compilation is finished (by ; (semicolon) or by error), the number base is reset to the value it had when compilation started.
This means: when the command $ or % is entered during compilation, this has only an effect to the function beeing just compiled.
However: When $ or % is executed during runtime of a user compiled function, this number base remains valid after the execution has finished.

*

Unsigned multiplication 16x16bit to 16 bit: x3 = x1 * x2

*/

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 (note:this is differing from standard Forth behaviour).
After execution, TOS should be checked if 0.

*/MOD

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 (note:this is differing from standard Forth behaviour) and the remainder of the division xR in 16 bit format.
After execution, TOS should be checked if 0.

+

16 bit addition: x3 = x1 + x2
without carry handling. Circular overflow, i.e. appropriate for signed as unsigned numbers.

-

16 bit subtraction: x3 = x1 - x2
Circular overflow, i.e. appropriate for signed as unsigned numbers. Alternative meaning: unary operator (minus sign). Then no space between - and number is allowed.

-ROT

Rotates the top of stack down to the 3rd stack position.
Reverse direction of rotation see ROT

.

Transmits the top of stack data via serial interface in its ASCII representation and acitve number base (default=hex, may be set to decimal) plus one leading space. See EMIT, too.

."

Compile time behaviour: First compiles the DOSTR token. Next, it compiles the following ASCII text until next " quotation.
Attention: the ." token must be separated by a SPACE from the following text. This SPACE will not be part of the compiled text.
Runtime behaviour: see DOSTR .

.S

Simple debugging or system monitoring tool. Emits (non destructive) the contents of data stack and variables V0 to V7 (AT90S4433 versions) rsp. the first 8 user defined variables in order of definition (other versions with larger SRAM) 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.

/

Unsigned division 16/16bit to 16 bit x3 = x1/ x2
For remainder see MOD

Ø=

Returns TRUE on the stack, if x is equal to zero. Can be used as inverter for boolean flags.

:

The Colon command does start the definition of a new user word (function, command) with the name, wich is picked from the terminal input next after the colon separated by spaces. The colon command does switch 'Avise' into the compiling state. I.e. all words entered beween the name word and the final semicolon will not be executed but compiled into the new word. 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.
When operating 'Avise' with external EEPROM: when using ":" the new function is compiled into the external serial EEPROM. To compile into much faster CPU internal EEPROM, use Z:
When operating 'Avise' only with EEPROM: when using ":" the new function is compiled into the CPU internal EEPROM. Z: is not available
Due to lack of code memory, the error handling of ''Avise'' is not perfect at this point. If you use names of existing functions, these may be blocked in future by the new word. Numbers are parsed before names, i.e. if you name a word as a valid hex number, this word will always be interpreted as number. No error messages or warnings will displayed in these critical cases.

;

The semicolon command does finish a user compiled word. Now the new word is linked into the actual symbol table of ''Avise'' and the engine returns into interpreting state.

<

Returns TRUE on the stack, if x1 is smaller than x2, else FALSE.
Signed compare. For unsigned compare, see U<.

<=

Returns TRUE on the stack, if x1 is smaller than or equal to x2, else FALSE.
Signed compare.

<>

Returns TRUE on the stack, if x1 is not equal to x2.

=

Returns TRUE on the stack, if x1 is equal to x2.

>

Returns TRUE on the stack, if x1 is greater than x2.
Signed compare.

>=

Returns TRUE on the stack, ifx1 is greater than or equal to x2.
Signed compare. For unsigned compare, see U>=.

1+

Increase top of stack by one. Same effect as 1<SPACE>+, but more compact and faster. Cyclic behaviour.

1-

Decrease top of stack by one. Same effect as 1<SPACE>-, but more compact and faster. Cyclic behaviour.

ABORT

The ABORT token is compiled into the function beeing defined. There it will be executed at runtime.
Interpreting state: ( -- )
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

Interpret x 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.

AND

Bitwise 16 bit logical AND.

AUTOEXE

Puts the numeric code b of any token into an autostarting function, which is automatically executed after INIT or hardware reset, before control of 'Avise' is handled to the operator terminal. You can leave the AUTOEXE function at every time by sending a tilde character ~ =0xFE via serial interface. This is catched directly in the serial interrupt handler at very low system level and will immediately throw 'Avise' to its error handler. Putting FF AUTOEXE <RETURN> will disable the autofunction at system start and instantly give access to the operator terminal.

BEGIN

Mark the beginning of an uncounted "open" loop
At compile time it puts the actual compile-to address on the stack to be resolved later by UNTIL. At runtime it is no more present.

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 interactively or during program operation.

CALL

Call a user programmed piece of machine code put into the AVR flash memory

Introduction of user programs to be called by CALL is performed as follows: 'Avise' kernel is supplied as Intel hex object code. Assemble your own code into the free part of memory (using the ORG assembly directive. Merge the Intel hex files with a plain ASCII text editor: As all records have different address fields, put the new part after the kernel records, except the terminator record, which must stay the last. Use of C or Basic compilers is not recommended, as these tools make complex use of register and SRAM resources and might destroy the memory setup of the calling 'Avise' kernel.

Keep in mind, that ''Avise'' internally makes use of all 32 machine registers of the AVR controller. The following registers can be used without loss of data and without the need of restoration: r0, r3, r4, r22, r23, r24, r25, r30, r31. SREG needs not to be saved. NEVER use r2, r5, r6, r7, r16, r17, r20, r21, r28, r29 in your own programs. You must save each register else before use and restore it when you return to the kernel.

The register pair XL,XH (r26, r27) is the '''Avise''' data stack pointer. Register pair r18=TOSL and r19=TOSH is used as TOS ("top of stack"). This feature is appropriate to handle data into user functions and vice versa. Example, how the DUP and the W command (write to SRAM) are implemented within 'Avise 2.4':

DUP: 	st -X,TOSH
	st -X,TOSL
	ret

WRITE: 
; if address lower 0x060 then write single byte
; else write word. 
	mov ZL,TOSL
	mov ZH,TOSH	;address
	ld TOSL,X+      ;pop data  from stack
	ld TOSH,X+
	tst ZH
	brne WR10
	cpi ZL,0x61
	brcs WR20
WR10:   std Z+1,TOSH
WR20:   st Z,TOSL
	ld TOSL,X+      ;pop data  from stack
	ld TOSH,X+
	ret

CARRY?

Reflects if the last executed one of the following functions did cause an overflow (carry or borrow): + , 1+ , +W , - , 1- , -W. This can be a great help in 32 bit arithmetics.
Note: the carry flag used here is independent of the CPU carry flag.

DEBUG

If the stack parameter is "TRUE", i.e. not equal zero, the single step debugger is started. That means: after any compiled BREAK command, line by line ''Avise'' does put out the system state (details see .S). Then it does halt until the TAB key on the user terminal is pressed.
If the stack parameter is" FALSE", i.e. equal to zero, no BREAK commands are executed. Then the program is running free with very little runtime overhead.

DO

Does put the loopback address on the stack, later consumed by LOOP. Details not important for user.
Runtime behaviour: see DODO
Please note that the DO-LOOP structure of Avise does work much different from standard Forth implementations (we say much better).

DODO

Runtime primitive, which is compiled by DO to perform its runtime actions:
Takes the loop parameters (loop start index, end index, memory address of actual loop index) from the stack, takes the LEAVE address from the program code and puts them to the appropriate memory cells. Once the loop is entered, all the work of DODO is done.
Please note that - differing from standard Forth implementations - the loop is executed last with the end index. The actual loop index is held in a variable for better handling comfort.
Not directly user applicable. Listed here only as reference for SEE output.

DOELSE

Runtime primitive to perform an absolute unconditional jump to the code address, which is compiled just following the DOELSE token.
Look at DOIF too, for conditional jump.
In most Forth systems else, this jump function is named BRANCH

DOELSE is not directly applicable to the user. The compiler does insert it to do the runtime action of the word ELSE. It is listed here only for understanding output of SEE.

DOIF

Runtime primitive to manage a conditional FORWARD jump in the program flow.
The decision is made by evaluating the top of stack: x= 0 (FALSE): Go to the address, which is compiled just following the DOIF token. With 'Avise', jumps are only possible within a range of 256 bytes. To handle this problem for versions with 512 bytes of internal EEPROM when jumping over the page boundary, DOIF is distinguished from DOUNTIL, which manages a BACKWARD jump. In most Forth versions, the combined effect of both is named ?BRANCH.
x <> 0 (TRUE): Continue interpretation beginning from the token compiled 2 bytes behind the DOIF token.
See DOELSE too, for unconditional jump.
DOIF is normally not applied by the user. The compiler does insert it for evaluation of the word IF. It is listed here only for understanding the output of SEE.

DOLIT

Runtime primitive, which puts a compiled data word on the data stack. The data value is compiled directly following the DOLIT token. There are 2 bytes compiled following the DOLIT token. The first one is the high byte of x, the following one is the low byte of x. DOLIT is always compiled in context with input of numbers in compiling state. Internal control operation, not directly user applicable. Listed here only as reference for SEE output.

DOLOOP

Runtime primitive, which is compiled by LOOP to perform its runtime actions:
Compare the actual loop index with the end value.
If equal continue linear execution from the token compiled 2 bytes behind the LOOP token.
If not equal increment loop index (if actual index is smaller than end index - signed compare ) -- or decrement loop index ( if actual index is greater than end index- Signed compare) and go to the loop return address, which is compiled just following the DOLOOP token.
DOLOOP is not directly user applicable. Listed here only as reference for SEE output.

DOSTR

Runtime primitive, which EMITs the following text bytes until NULL byte.
DOSTR is not directly applicable by the user. It is listed here only for understanding the output of SEE.

DOUNTIL

Runtime primitive to manage a conditional BACKWARD jump in the program flow.
DOUNTIL is normally not applied by the user. The compiler does insert it for evaluation of the word UNTIL. It is listed here only for understanding the output of SEE. Further comment see DOIF

DOVAR

Runtime primitive which puts the next two bytes on the data stack - which represent the address of a variable parameter field .
Behaviour is very similar to DOLIT, but it is handled separately for systematic reasons.
DOVAR is not directly applicable by the user. It is listed here only for understanding the output of SEE.

DROP

Deletes the top of the stack and pops all stack entries up by one position.

DUP

Duplicates the top op the stack and pushes all stack entries down by one position.

ELSE

ENDIF

Does finish a conditional branch structure beginning with IF.
The ENDIF token is consumed from source code at compile time. At runtime there is no more token present.

EMIT

Transmits the lower byte of TOS as a raw 8 bit data via the serial interface . No check if the data is printable.

EOC

End of Code compiled by ; (semicolon). Same runtime function as EXIT, but has a signalling effect on some internal process. Not directly applicable by user.

EXIT

Finishes the execution of a secondary word and returns to a higher nesting level of program flow. Is implied by ; (semicolon), but can be explicitely used for side-exits within a word definition, too.

FORGET

Deletes the user-compiled word <namestring> and all words, which are compiled later. Resets the compile memory pointer, accordingly.

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

IF

Does compile a conditional jump to the respective ENDIF or ELSE. Details are not important for user.
Runtime: ( b -- )
Marks the beginning of a forward directed conditional branch.
Differing from other programming languages, IF makes the decision evaluating the top of the stack, which is present when the runtime equivalent of IF is started. As usual, the stack entry is consumed this way.

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 AUTO funciton will be executed before the command interpreter can be reached by the user. See AUTOEXE.

KEY

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 !

KEY?

Checks if data are in the input buffer of the serial interface.
If none, immediately a zero byte (FALSE) is put on the stack. If any data are in the buffer, then the eldest byte is moved from the buffer to the stack. Above it, a TRUE data is packed on the top of the stack. Bytes once read out the buffer cannot be stored back.

LEAVE

Immediately leaves the innermost DO ... LOOP structure and continues execution behind the respective DOLOOP token. Loop parameters are removed from stack. The variable, which holds the actual loop counter, is left unchanged.

LOOP

Returning point of a DO-LOOP structure: The compiler does substitute the LOOP token by its runtime primitive DOLOOP and compiles the LEAVE destination behind DODO. Details are not important for user.
Runtime behaviour: see DOLOOP

LSHIFT

Shift left the bits of the 2nd stack entry "x" by "n" positions.

MEM

Display of the actual values of compile memory pointers in internal and external EEPROM as well as the VAR assignment pointer.

MOD

Remainder of unsigned division 16/16bit to 16 bit x3 = MOD( x1 / x2)

MS

Does trigger an internal countdown with duration of x time steps of ONE microsecond 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.

NOT

Every bit of x1 is inverted to its logical complement ("one's complement").

OR

Bitwise 16 bit logical OR.

OVER

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 by one position.

ROL

Rotate left the bits of the 2nd stack entry "b" by "n" positions. 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 8 bit. Use masking AND and combining OR techniques.

ROR

Rotate right the bits of the 2nd stack entry "b" by "n" positions.
Comment see ROL

ROT

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 by one position.
Opposite direction of rotation see -ROT.

ROT4

Rotate the upper four elements of the data stack. The fourth element will be rotated to the top of the stack. The previous three top elements are pushed down by one position. This word is useful for construction of stack operations with word length of more than 8 resp.16 bit.

RSHIFT

Shift right the bits of the 2nd stack entry "x" by "n" positions.

SEE

Simple decompiler for user-compiled words. Emits the content of the word <name> via serial interface to the terminal display. Differing from other Forth decompilers, it doesn't list the words by name, but by token codes. The compiled code is differing from 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. Before work with SEE, call WORDS and print a screenshot to list the token codes in numeric order.
Reconstruction of GOTO or LOOP destinations:
According to the general behaviour of ''Avise'', every compiled secondary word is restricted to one page of memory. The page size is dependent on the type of external serial EEPROM: with 24C256 the page size is 256 Bytes, with 24C2128 the page size is 128 Bytes, with 24C643 or equiv. the page size is 64 Bytes. As an exception for CPU types with more than 256 bytes of internal EEPROM, it is possible to cross over the page boundary at 256 bytes without conflicts.This way, a one byte address completely describes the absolute jump destination. In the listing produced by SEE every token code is preceeded by the real physical byte address where it is compiled. This makes reconstruction of DOLIT, DOVAR, DOIF, DOELSE, DOUNTIL, DODO, DOLOOP and LEAVE target addresses more convenient.

SEE can only be called interactively, it must not be compiled into user words!

SWAP

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

SYS

Reset the internal watchdog timer. Sometimes necessary in very long user functions. Can be used as a dummy NOP code, too.

TIME

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

U<

Returns TRUE on the stack, if x1 is smaller than x2, else FALSE.
UNsigned compare. For signed compare see <.

U>

Returns TRUE on the stack, if x1 is greater than x2.
UNsigned compare. For signed compare see >.

UNTIL

Finishes a loop structure started with BEGIN. Will be replaced by the compiler with a DOUNTIL token.
If the top of stack is "FALSE" (i.e. exactly = Ø), execution will continue linear from the token compiled 2 behind after the DOUNTIL token.
If the top of stack is "TRUE" (i.e. not equal Ø), execution will go to the address, which is compiled just after the DOUNTIL token.

VAR

Immediate function for declaration of variables, which reserves a parameter field in the CPU SRAM. Variable is initialised with zero value. Furthermore, updates pointer to empty variable parameter fields.
Differing from other programming languages, call of a variable gives the address of the variable, not the value!
During declaration, the variable is initialized with value 0
When a VARiable is called by name in interpreter mode: the address of the variable parameter field is put on the data stack.
When a VARiable is called by name in compiling mode: compiles the token DOVAR followed by the address of the variable parameter field.
Example:

VAR PARAMETER
PARAMETER . \ prints the address where the value of the variable is stored
234 PARAMETER W \sets the variable
PARAMETER R . \ prints the actual value of the variable

WAIT

May be used after a MS call to pause execution until the timer countdown is reached. No exit out of this delay is possible except entering the tilde character ~ = 0xFE via serial interface, which will initiate a warm start!

WORDS

Displays a list of all currently available words (functions, commands) of 'Avise'. Each word name is followed by its token code in hexadecimal notation.
Display is done in two parts: first all kernel words are listed. This block is followed by a list of all user defined words (if any present). 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. Using the ATOOL terminal: press ESC to freeze the display, make a screenshot or print the screen, press SPACE to unfreeze the display.

XOR

Bitwise 16 bit logical EXCLUSIVE OR.

Z:

The Z: command does start the definition of a new user word (function, command) with the name, wich is picked from the terminal input next after the "Z:" string separated by spaces.
By use of Z:, the new function is compiled into the much faster internal EEPROM.
Only available when external EEPROM is supported. For versions with CPU internal EEROM only, use :(colon)
For further comment, see :(colon).

\

Opens a comment. The backslash must be separated by spaces from preceeding and following text. Normally the rest of the line until CR is regarded as a comment now. Alternatively, a second Backslash (separated by spaces, too) will finish the comment. In standard Forth systems, normal brackets ( ) are used to "comment out" parts of code temporarily for test or optimization purpose. This useful feature is available in ''Avise'' with a set of two backslashes.