Forth v6 Function Glossary (E-O)

This glossary provides detailed definitions for the general purpose words (Forth functions) available in the v6 Forth kernel. Separate glossaries define the assembler and C debugging words available. A separate page lists all the Functions that Disable Interrupts.

For help in understanding the notation used in the following function definitions, consult the description of stack symbols, abbreviations and naming conventions.

Software development in Forth uses the Codeblocks-based Mosaic IDE Plus Integrated Development Environment; this is the same IDE used for software development in C. While Forth programmers will not use the IDE's GNU C (GCC) compiler, the IDE provides a full-featured text editor and customized terminal for rapid Forth code downloads and interactive Forth debugging sessions with the 9S12 (HCS12) processor on the controller board.

This glossary is split into three web pages, for words beginning with the following characters (in ASCII alphabetical) order:

ECT.CLEAR.INTERRUPT.FLAG ( channel_id -- )

Clears the associated flag bit of the specified channel_id in the Enhanced Capture Timer (ECT) system.  The channel_id can be the channel number in the range 0 to 7 of an input capture (IC) or output compare (OC), or it can be one of the constants TCNT.OVERFLOW, PULSE.A.EDGE, PULSE.A.OVERFLOW, PULSE.B.OVERFLOW, or MODULUS.UNDERFLOW.  In general, any interrupt service routine prompted by the ECT system must clear the associated flag bit, unless ECT.FAST.CLEAR has been called to automatically clear the flag bit when an associated result register is accessed.

ECT.FAST.CLEAR ( -- )

Writes a 1 to the TFCCA bit in the TSCR1 register to configure the Enhanced Capture Timer (ECT) system for automatic clearing of the relevant flag bit when an associated result register is accessed.  This eliminates the need for service code to explicitly clear the flag bit (for example, in an interrupt service routine) by invoking ECT.CLEAR.INTERRUPT.FLAG or by a direct write to the flag register.  After this routine is executed, the fast clear mode stays in effect until the next power-up or hardware reset.

See also ECT.STANDARD.CLEAR

Implementation detail: In fast clear mode, a read from an input capture register or a write to an output compare channel clears the CnF flag bit in TFLG1; any access to the TCNT free-running counter register clears the TOF flag in TFLG2; any access to the PACN3 or PACN2 pulse accumulator registers clears the PAOVF and PAIF flags in PAFLG; and any access to the PACN1 and PACN0 registers clears the PBOVF bit in the PBFLG register.  Consult the ECT Block User Guide from Motorola for detailed descriptions of these register bits.

ECT.INTERRUPT.DISABLE ( channel_id -- )

Clears the associated interrupt bit of the specified channel_id in the Enhanced Capture Timer (ECT) system to disable the interrupt associated with the specified channel.  The channel_id can be a channel number in the range 0 to 7 of an input capture (IC) or output compare (OC), or it can be TCNT.OVERFLOW, PULSE.A.EDGE, PULSE.A.OVERFLOW, PULSE.B.OVERFLOW, or MODULUS.UNDERFLOW.  After a power-up or hardware reset, the ECT interrupts are disabled.

See also ECT.INTERRUPT.ENABLE

CAUTION: Do not pass interrupt identifiers that end in .ID as parameters to this routine.

ECT.INTERRUPT.ENABLE ( channel_id -- )

Sets the associated interrupt bit of the specified channel_id in the Enhanced Capture Timer (ECT) system to enable the interrupt associated with the specified channel.  The channel_id can be a channel number in the range 0 to 7 of an input capture (IC) or output compare (OC), or it can be or it can be TCNT.OVERFLOW, PULSE.A.EDGE, PULSE.A.OVERFLOW, PULSE.B.OVERFLOW, or MODULUS.UNDERFLOW.  After a power-up or hardware reset, the ECT interrupts are disabled.

See also ECT.INTERRUPT.DISABLE

CAUTION: Do not pass interrupt identifiers that end in .ID as parameters to this routine.

ECT.OVERFLOW.ID ( -- n )

Returns the interrupt identity code for the enhanced counter/timer (ECT) overflow interrupt.  Used as an argument for ATTACH.
Pronunciation: e-c-t-overflow-i-d

ECT.PRESCALER ( n -- )

Sets the specified n as the prescaler associated with the free-running TCNT counter in the Enhanced Capture Timer (ECT) system.  The TCNT frequency is 20 MHz divided by n, and the corresponding TCNT period is 50 nanoseconds times n.  Valid values for the prescaler n are decimal 1, 2, 4, 8, 16, 32, 64, 128; other values are converted to one of these values.  The default prescaler set at warm/cold startup is 32, yielding a 1.6 microsecond TCNT period, and a 104.8 ms rollover (overflow) time.  The TCNT free-running counter is the master clock for the input captures, output compares, gated pulse accumulators, and modulus counter functions of the ECT system.

Implementation note: It is highly recommended that TCNT is maintained as a free-running counter that cannot be stopped.  This implies that bits CLK1 and CLK0 bits in the PACTL register be kept equal to zero, the TEN (timer enable) bit in TSCR1 = 1 (set at warm/cold); and the TCRE (timer counter reset enable) bit in TSCR2 = 0 (cleared at warm/cold).  The kernel drivers follow this rule; specifically, the TCSR1 and TSCR2 registers are properly initialized at startup, and the PULSE.A.SETUP function which writes to the PACTL register keeps the CLK1 and CLK0 bits zeroed.  Writing other values to these bits may make it impossible to use TCNT for general purpose software timing by the application program.  Note that none of the kernel (operating system) functions rely on TCNT for software timing; rather, the multitasker uses the RTI (real-time interrupt) as a time base.

ECT.STANDARD.CLEAR ( -- )

Undoes the effect of ECT.FAST.CLEAR, and reverts to the default condition in which the flag bits of the Enhanced Capture Timer (ECT) must be explicitly cleared by the application program by invoking ECT.CLEAR.INTERRUPT.FLAG or by a direct write to the relevant flag register.

ECT0.ID ( -- n )

Returns the interrupt identity code for the enhanced counter/timer (ECT) channel 0 interrupt.  Used as an argument for ATTACH.
Pronunciation: ect-zero-i-d

ECT1.ID ( -- n )

Returns the interrupt identity code for the enhanced counter/timer (ECT) channel 1 interrupt.  Used as an argument for ATTACH.
Pronunciation: ect-one-i-d

ECT2.ID ( -- n )

Returns the interrupt identity code for the enhanced counter/timer (ECT) channel 2 interrupt.  Used as an argument for ATTACH.
Pronunciation: ect-two-i-d

ECT3.ID ( -- n )

Returns the interrupt identity code for the enhanced counter/timer (ECT) channel 3 interrupt.  Used as an argument for ATTACH.
Pronunciation: ect-three-i-d

ECT4.ID ( -- n )

Returns the interrupt identity code for the enhanced counter/timer (ECT) channel 4 interrupt.  Used as an argument for ATTACH.
Pronunciation: ect-four-i-d

ECT5.ID ( -- n )

Returns the interrupt identity code for the enhanced counter/timer (ECT) channel 5 interrupt.  Used as an argument for ATTACH.
Pronunciation: ect-five-i-d

ECT6.ID ( -- n )

Returns the interrupt identity code for the enhanced counter/timer (ECT) channel 6 interrupt.  Used as an argument for ATTACH.
Pronunciation: ect-six-i-d

ECT7.ID ( -- n )

Returns the interrupt identity code for the enhanced counter/timer (ECT) channel 7 interrupt.  Used as an argument for ATTACH.
Pronunciation: ect-seven-i-d

EE2VARIABLE ( <name> -- )

Removes the next <name> from the input stream, defines a child eevariable called <name>, and EEALLOTs two cells (4 bytes) in the EEPROM area, advancing the EEP pointer.  When <name> is executed, it leaves the extended address xaddr of the two cells reserved in the eeprom area to hold the eevariable's contents.  Use as:

EE2VARIABLE <name>

This defining word is segment-relocation-smart, and <name> leaves the correct xaddress on the stack even when invoked inside a library or application segment that is relocated to a code location and EEPROM starting xaddress that are different from the initial compilation address.  The ee2variables defined by this routine are read using the standard 2@ operator, and are written to by dropping the page and invoking (EE2!).
Pronunciation: e-e-two-variable
Attributes: D

EEALLOT ( n -- )

Reserves n bytes in the EEPROM area by incrementing the EEPROM pointer EEP by n.  An error occurs if the ALLOT operation causes EEP to be incremented outside the allowed EEPROM region of 0x400 to 0xBFF (0xC00-0xFFF are reserved for use by the operating system).
Pronunciation: e-e-allot

EEFVARIABLE ( <name> -- )

Removes the next <name> from the input stream, defines a child eefvariable called <name>, and EEALLOTs two cells (4 bytes) in the EEPROM area, advancing the EEP pointer.  When <name> is executed, it leaves the extended address xaddr of the two cells reserved in the eeprom area to hold the eevariable's contents. <name> is typically used to hold a floating point value.  Use as:

EEFVARIABLE <name>

This defining word is segment-relocation-smart, and <name> leaves the correct xaddress on the stack even when invoked inside a library or application segment that is relocated to a code location and EEPROM starting xaddress that are different from the initial compilation address.  The eefvariables defined by this routine are read using the standard F@ operator, and are written to by dropping the page and invoking (EEF!).
Pronunciation: e-e-f-variable
Attributes: D

EEHERE ( -- xaddr )

Places on the stack the xaddr of the next available location in the EEPROM area.  The user-available EEPROM area is at addresses 0x400 to 0xBFF.  Equivalent to EEP X@
Pronunciation: e-e-here
Attributes: U

EEP ( -- xaddr )

User variable that contains the 32-bit EEPROM pointer.  The contents of EEP are placed on the stack by EEHERE and are modified by EEALLOT.  The command EEP X@ is equivalent to EEHERE; it yields the xaddr of the next available EEPROM location.  The user-available EEPROM area is at addresses 0x400 to 0xBFF.
Pronunciation: e-e-p
Attributes: U

EEPROTOTYPE: ( <forth.eevariable.name> <${prototype.string}$> -- )

Declares a prototype string.  For the specified <forth.eevariable.name> corresponding to an EEPROM variable (eevariable) that is created while the C.CALLABLE system variable is true, declares and saves a C prototype string equal to the contents of the specified prototype.string which is delimited by a stating ${ and an ending }$ delimiter.  The prototype string is exported by the routines that BUILD (export) library and application segments.  The prototype string is parsed by the COMPOSE.C.HEADERS and COMPOSE.C.HEADERS.FOR routines to generate C macro definitions for the eevariable in the *.h file.

EEPROTOTYPE: parses from the input stream a single- or multi-line long-string that starts with ${ and ends with the }$ delimiter.  At least one space is required before the ${ delimiter, and a space or carriage return is required after the }$ delimiter.  The prototype string is saved in the forth names area pointed to by NP in RAM, and the offset from the xnfa to the x$addr is stored in the 3-byte +PROTOTYPE$ field of the forth header.  The maximum allowed length of the prototype string is 1 Kbyte, and the saved string can cross the name-page boundary. <forth.eevariable.name> must be C-callable; that is, it must be defined while the C.CALLABLE system variable is true.  The prototype string must contain a single space-delimited type specifier followed by a single space-delimited C eevariable name.  Do not use a semicolon in the prototype string.  The <forth.eevariable.name> and ${ must be on the same line as EEPROTOTYPE:.

A single-word return type specifier such as void or char* must be used in the prototype string.  The eevariable name must be the second space-delimited word in the prototype string inside the ${ }$ delimiters.  In the case of a return type specifier such as char*, the char and * cannot have an intervening space.  If a more complex return type specifier is required, use C.HEADERS: to define a C header text block that includes a TYPEDEF that creates a single-word type specifier, and use this in the prototype string.

Example of use:

C.CALLABLE ON   \ make these c-callable
EEFVARIABLE  LIBEEVAR1  EEPROTOTYPE: LIBEEVAR1 ${ float libeevar1 }$  \ no ; in eevar prototype!
EEVARIABLE   LIBEEVAR2  EEPROTOTYPE: LIBEEVAR2 ${ int libeevar2   }$  \ no ; in eevar prototype!
C.CALLABLE OFF   \ revert to default non-c-callable

EEVARIABLE ( <name> -- )

Removes the next <name> from the input stream, defines a child eevariable called <name>, and EEALLOTs a cell (2 bytes) in the EEPROM area, advancing the EEP pointer.  When <name> is executed, it leaves the extended address xaddr of the cell reserved in the eeprom area to hold the eevariable's contents.  Use as:

EEVARIABLE <name>

This defining word is segment-relocation-smart, and <name> leaves the correct xaddress on the stack even when invoked inside a library or application segment that is relocated to a code location and EEPROM starting xaddress that are different from the initial compilation address.  The eevariables defined by this routine are read using the standard @ operator, and are written to by dropping the page and invoking (EE!).
Pronunciation: e-e-variable
Attributes: D

EEXVARIABLE ( <name> -- )

Removes the next <name> from the input stream, defines a child eexvariable called <name>, and EEALLOTs two cells (4 bytes) in the EEPROM area, advancing the EEP pointer.  When <name> is executed, it leaves the extended address xaddr of the two cells reserved in the eeprom area to hold the eevariable's contents. <name> is typically used to hold an xaddress.  Use as:

EEXVARIABLE <name>

This defining word is segment-relocation-smart, and <name> leaves the correct xaddress on the stack even when invoked inside a library or application segment that is relocated to a code location and EEPROM starting xaddress that are different from the initial compilation address.  The eexvariables defined by this routine are read using the standard X@ operator, and are written to by dropping the page and invoking (EEX!).

CAUTION: Make sure that the xaddress that you store into the eexvariable is not subject to relocation as a library or application segment is relocated.
Pronunciation: e-e-x-variable
Attributes: D

ELSE ( -- )

Used in a colon definition to mark the beginning of the else portion of an IF … ELSE … ENDIF conditional structure (ENDIF and THEN are synonyms).  Use as:

flag
IF     words to execute if flag is true
ELSE   words to execute if flag is false
ENDIF

If the flag passed to IF is true, when ELSE is encountered control is passed to the word following ENDIF.  If the flag passed to IF is FALSE, control is immediately passed to the word following ELSE.

Attributes: C, I

EMIT ( char -- )

Displays char by sending it via the serial I/O port.  EMIT is a vectored routine that executes the routine whose xcfa is installed in the user variable UEMIT.  The default installed routine called is EMIT1 which sends the character via the primary serial port (supported by the processor’s SCI0 hardware UART).  EMIT2 may be installed in UEMIT by USE.SERIAL2 or SERIAL2.AT.STARTUP; EMIT2 sends the character via the secondary serial port (supported by the processor’s SCI1 hardware UART).

See also EMIT1 and EMIT2

Attributes: M, U

EMIT1 ( char -- )

Displays a character by sending it via the primary serial port (serial1) supported by the processor’s SCI0 hardware UART.  Before sending the character, EMIT1 waits (if necessary) for the previous character to be sent, and executes PAUSE while waiting.  The most significant byte of the input data stack cell is ignored.  EMIT1 is the default EMIT routine installed in the UEMIT user variable after the special cleanup mode is invoked or if SERIAL1.AT.STARTUP has been executed.  If the value in SERIAL.ACCESS is RELEASE.AFTER.LINE, EMIT1 does not GET or RELEASE the SERIAL1.RESOURCE.  If SERIAL.ACCESS contains RELEASE.ALWAYS, EMIT1 GETs and RELEASEs the SERIAL1.RESOURCE.  If SERIAL.ACCESS contains RELEASE.NEVER, EMIT1 GETs but does not RELEASE the SERIAL1.RESOURCE.

See also EMIT, UEMIT, EMIT2, SERIAL.ACCESS
Pronunciation: emit-one
Attributes: M

EMIT2 ( char -- )

Writes the specified ascii character to the output buffer of the secondary serial port (serial2) for subsequent transmission.  The serial2 port is supported by the processor’s SCI1 hardware UART.  Before sending the character, EMIT1 waits (if necessary) for the previous character to be sent, and executes PAUSE while waiting.  The most significant byte of the input data stack cell is ignored.  EMIT2 can be made the default EMIT routine installed in the UEMIT user variable after each reset or restart by executing SERIAL2.AT.STARTUP.  If the value in SERIAL.ACCESS is RELEASE.AFTER.LINE, EMIT2 does not GET or RELEASE the SERIAL2.RESOURCE.  If SERIAL.ACCESS contains RELEASE.ALWAYS, EMIT2 GETs and RELEASEs the SERIAL2.RESOURCE.  If SERIAL.ACCESS contains RELEASE.NEVER, EMIT2 GETs but does not RELEASE the SERIAL2.RESOURCE.

See also EMIT, UEMIT, EMIT1, SERIAL.ACCESS
Pronunciation: emit-two
Attributes: M

ENABLE.BOOT.VECTORS ( -- )

Undoes the effect of DISABLE.BOOT.VECTORS, allowing any boot vectors installed by SET.BOOT.VECTOR to be executed upon subsequent restarts.

Implementation detail: Clears a configuration bit in reserved system EEPROM to enable the execution of all installed boot vectors.

ENABLE.INTERRUPTS ( -- )

Clears the interrupt mask bit (the I bit) in the condition code register to globally enable interrupts.

END-CODE ( sys -- | balances CODE )

A synonym for END.CODE

END.CODE ( sys -- | balances CODE )

Terminates an assembly code definition which started with CODE or XCODE or RCODE.  Executes SMUDGE so that the header created by CODE or XCODE can be found in the dictionary.  Checks to make sure that no extra items were left on the stack during the definition process.  Stores the contents of CURRENT into CONTEXT so that ASSEMBLER is no longer the search vocabulary.

END.LOAD.SEGMENT ( -- )

Terminates the currently loading segment as specified by THIS.SEGMENT.  Clears THIS.SEGMENT, THIS.SEGMENT.XBASE, THIS.SEGMENT.XNFA, and LIBRARY.IS.COMPILING.  This causes reversion to the default kernel segment. Writes a 3-byte xnfa.offset calculated as [latest - segment.xnfa] into the xcfa field of the segment header (this field was zeroed when the segment was declared to indicate that segment compilation was in progress).  This approach of storing a reference to the last header in the segment header allows the segment declaration header to contain enough information to relocate or dump all of the names in the segment.  This routine does not write the segment code size, variable area size, or EEPROM area size into the segment structure; these are set by END.SEGMENT.  See END.SEGMENT for a description of actions taken when terminating a compiling (as opposed to a loading) segment.

END.SEGMENT ( -- )

Terminates the currently compiling segment as specified by THIS.SEGMENT.  Clears THIS.SEGMENT, THIS.SEGMENT.XBASE, THIS.SEGMENT.XNFA, and LIBRARY.IS.COMPILING.  This causes reversion to the default kernel segment. Writes a 3-byte xnfa.offset calculated as [latest - segment.xnfa] into the xcfa field of the segment header (this field was zeroed when the segment was declared to indicate that segment compilation was in progress).  This approach of storing a reference to the last header in the segment header allows the segment declaration header to contain enough information to relocate or dump all of the names in the segment.  This routine writes the segment code size, variable area size, EEPROM area size, and code checksum into the segment structure.  See END.LOAD.SEGMENT for a description of actions taken when terminating a loading (as opposed to a compiling) segment.

ENDCASE ( n -- )

Used inside a colon definition to mark the end of a CASE statement which implements a multi-decision control structure.  Use as:

n1 CASE
   n2 OF  ...words to be executed if n1 = n2    ENDOF
   n3 OF  ...words to be executed if n1 = n3    ENDOF
   n4 OF  ...words to be executed if n1 = n4    ENDOF
   words to be executed if n1 doesn't equal n2 or n3 or n4
ENDCASE

An error is issued if CASE and ENDCASE are not properly paired in a definition.

See also CASE, OF, ENDOF, RANGE.OF, and URANGE.OF

Attributes: C, I

ENDIF ( -- )

Synonym for THEN.  Used inside a colon definition to mark the end of an

  ''IF'' ... ELSE ... ENDIF

or IF … ENDIF

conditional structure.  The word following ENDIF is executed after the IF or ELSE (if present) part of the conditional executes.  An error is issued if ENDIF is not paired with IF or ELSE in a colon definition.
Pronunciation: end-if
Attributes: C, I

ENDIFTRUE ( -- )

Marks the end of a conditional structure that is used outside a colon definition.  Use as:

flag  IFTRUE .... OTHERWISE ....  ENDIFTRUE

or

flag  IFTRUE ....  ENDIFTRUE

The execution mode conditional structure can be used to conditionally compile portions of source code.  IFTRUE/OTHERWISE/ENDIFTRUE statements can be nested.

See also IFTRUE and OTHERWISE
Pronunciation: end-if-true

ENDOF ( -- )

Used inside a CASE … ENDCASE structure to mark the end of a conditional statement that starts with OF or RANGE.OF or URANGE.OF.  If the OF portion of the case statement is true, ENDOF branches to the word after ENDCASE.  An error is issued if OF and ENDOF are not properly paired.

See also CASE, ENDCASE, OF, RANGE.OF, and URANGE.OF
Pronunciation: end-of
Attributes: C, I

ERASE ( xaddr\u -- | u = byte count )

Stores a zero byte in each of u consecutive bytes beginning at xaddr.  The specified region may cross page boundaries.  Does nothing if u = 0.

ESC.HANDLER ( -- xaddr )

This system variable holds the 32-bit xcfa (execution xaddress) of a function that is executed by EXPECT and QUERY whenever the ‘ESCape’ key is detected as part of the input stream.  The default contents equal the xcfa of NO.OP (that is, by default no action is taken when escape is detected).

Example of use: To cause the bell character to be emitted whenever the escape character is detected, execute:

CFA.FOR  BEEP  ESC.HANDLER  X!

Pronunciation: escape-handler

EVALUATE ( x$addr -- )

Interprets the counted string located at x$addr.  Use as:

" <words to be executed>" EVALUATE

The string need not end with a space.  EVALUATE provides one method of compiling a reference to a word that has not yet been defined.  For example,

: EARLY.WORD
   ...
   " INITIALIZE.EVERYTHING" EVALUATE
   ...
;

Even though the routine INITIALIZE.EVERYTHING has not yet been defined, EARLY.WORD will call it if INITIALIZE.EVERYTHING has been defined by the time EARLY.WORD is finally executed at runtime.  Note that EVALUATE must search the dictionary at runtime to be able to execute INITIALIZE.EVERYTHING.  For a more efficient means of implementing forward references, see REDEFINE and R:

Implementation detail: EVALUATE saves the contents of the input stream variables UTIB, #TIB, and >IN, then sets these variables to reference the specified x$addr, then calls INTERPRET, and finally restores the original values to the input stream variables.  Note that the standard TIB input stream is not useable by any of the functions called by EVALUATE.

EXECUTE ( xcfa -- )

Executes (calls) the routine whose executable machine instructions begin at the specified code field xaddress.  The xcfa can be on any page.

EXIT ( -- )

Specifies a termination point in a definition.  EXIT is an immediate word that compiles code that, when later executed, clears the locals off the return stack (if present), and pops the top value off the return stack and returns control to the calling word.  When compiled into a definition, EXIT causes the word to terminate at that point when the word is later executed.  An unchecked (and usually severe) error occurs if the return stack does not hold a valid return address (for example, if EXIT is used between >R and R> or inside a DO…LOOP or FOR…NEXT loop).  To exit a definition from inside a single DO…LOOP, execute UNLOOP (which removes 2 items from the rstack) to discard the loop index and limit from the return stack before calling EXIT.  One UNLOOP is needed for each nested DO… LOOP.  To exit a definition from inside a FOR…NEXT loop, call R>DROP to discard the loop index before calling EXIT.  One R>DROP is needed for each nested FOR…NEXT.

Attributes: C, I

EXPECT ( xaddr\+n -- )

Receives a string of characters from the serial port and stores them in a buffer in memory starting at xaddr.  Terminates when +n characters have been received or a carriage return occurs, whichever occurs first.  Characters are echoed via the serial port.  The carriage return is neither saved in the buffer nor echoed.  Tab characters are echoed; however, they are saved in the buffer as TAB.WIDTH (default = 1) spaces.  The backspace or delete character (ascii 8 or 127) removes the most recently received character from the buffer unless there are no characters in the buffer.  Null characters (ascii 0) and linefeeds (ascii 10) are ignored.  XON and XOFF characters are ignored except that they cause the XMIT.DISABLE flag in the user area to be set if XOFF is received or cleared if XON is received.  If the ESCape character is detected, the xcfa contained in the user variable ESC.HANDLER is executed; the default escape handler operation is NO.OP.  Character case is not altered.  The user variable SPAN is set equal to the number of characters received (but not including the terminating carriage return, if present).  EXPECT is called by QUERY to accept serial input to the TIB.

Attributes: M

F! ( r\xaddr -- )

Stores a floating point number at xaddr.  A synonym for 2!.
Pronunciation: f-store

F* ( r1\r2 -- r3 )

Multiplies floating point number r1 by r2 giving r3.
Pronunciation: f-star
Attributes: S

F** ( r1\r2 -- r3 )

r3 equals r1 raised to the r2 power; i.e., r3 = r1^r2. Overflows if r1 is negative.
Pronunciation: f-star-star
Attributes: S

F+ ( r1\r2 -- r3 )

Adds floating point number r2 to r1 giving the sum r3.
Pronunciation: f-plus
Attributes: S

F- ( r1\r2 -- r3 )

Subtracts floating point number r2 from r1 giving the difference r3.
Pronunciation: f-minus
Attributes: S

F. ( r -- )

Displays r using the default format as specified by the most recent execution of FIXED FLOATING or SCIENTIFIC.  FLOATING is the default format after executing FP.DEFAULTS or after a cold restart.

See also F>FIXED$, F>SCIENTIFIC$, and F>FLOATING$
Pronunciation: f-dot
Attributes: M, S

F.OVER.N ( r\w -- r\w\r )

Copies the floating point value r located under the top data stack cell to the top of the data stack.
Pronunciation: f-over-n

F/ ( r1\r2 -- r3 )

Divides floating point number r1 by r2 giving the result r3.
Pronunciation: f-slash
Attributes: S

F0< ( r -- flag )

Flag is TRUE if floating point number r is less than zero, FALSE otherwise.
Pronunciation: f-zero-less-than

F0<= ( r -- flag )

Flag is TRUE if floating point number r is less than or equal to 0, FALSE otherwise.
Pronunciation: f-zero-less-than-or-equal

F0<> ( r -- flag )

Flag is TRUE if the floating point number is not equal to zero, and FALSE otherwise.
Pronunciation: f-zero-not-equal

F0= ( r -- flag )

Flag is TRUE if the floating point number equals zero and FALSE otherwise.
Pronunciation: f-zero-equal

F0> ( r -- flag )

If floating point number r is greater than zero, flag equals TRUE; otherwise, flag equals FALSE.
Pronunciation: f-zero-greater-than

F0>= ( r -- flag )

Flag is TRUE if floating point number r is greater than or equal to 0, FALSE otherwise.
Pronunciation: f-zero-greater-than-or-equal

F2* ( r1 -- r2 )

Floating point number r2 equals r1 * 2.
Pronunciation: f-two-star
Attributes: S

F2/ ( r1 -- r2 )

Floating point number r2 equals r1 divided by 2.
Pronunciation: f-two-slash
Attributes: S

F2DROP ( r1\r2 -- )

Drops two floating point numbers (4 cells) from the data stack.
Pronunciation: f-two-drop

F2DUP ( r1\r2 -- r1\r2\r1\r2 )

Duplicates the top two floating point numbers on the data stack.
Pronunciation: f-two-dupe

F< ( r1\r2 -- flag )

Flag is TRUE if floating point number r1 is less than r2, FALSE otherwise.
Pronunciation: f-less-than

F<= ( r1\r2 -- flag )

Flag is TRUE if floating point number r1 is less than or equal to r2.
Pronunciation: f-less-than-or-equal

F<> ( r1\r2 -- flag )

Flag is TRUE if the two floating point numbers are not equal and FALSE otherwise.
Pronunciation: f-not-equal

F= ( r1\r2 -- flag )

Flag is TRUE if the two floating point numbers are equal and FALSE otherwise.
Pronunciation: f-equal

F> ( r1\r2 -- flag )

Flag is TRUE if floating point number r1 is greater than r2, FALSE otherwise.
Pronunciation: f-greater-than

F>$ ( r -- x$addr\flag )

Converts r to a counted ascii string starting at x$addr in the format specified by the latest execution of the FLOATING, SCIENTIFIC, or FIXED format-specification functions.  If FLOATING (the default after a COLD restart) has been specified, this routine calls F>FLOATING$. If SCIENTIFIC has been specified, this routine calls F>SCIENTIFIC$. If FIXED has been specified, this routine call F>FIXED$. The output flag is always true in FLOATING or SCIENTIFIC modes.  The output flag is false if FIXED has been specified and the number cannot be represented in the specified number of LEFT.PLACES and RIGHT.PLACES.

See also FLOATING, SCIENTIFIC, FIXED, F>FLOATING$, F>SCIENTIFIC$, and F>FIXED$
Pronunciation: f-to-string
Attributes: S

F>= ( r1\r2 -- flag )

Flag is TRUE if floating point number r1 is greater than or equal to r2.
Pronunciation: f-greater-than-or-equal

F>FIXED$ ( r -- x$addr\flag )

Converts r to a counted ascii string starting at x$addr in FIXED format.  If the conversion is successful, flag is TRUE.  If r cannot be represented as an ascii string in FIXED format (i.e., if the values of LEFT.PLACES and RIGHT.PLACES are inappropriate) then x$addr contains the string won'tfit and flag is false.  The FIXED format is composed of (an optional) sign, LEFT.PLACES digits, a decimal point, RIGHT.PLACES digits, and a trailing space:

-xxx.yyy

If the NO.SPACES flag is false (the default condition), the field size equals LEFT.PLACES + RIGHT.PLACES + 3 and numbers are decimal aligned.  The size of the string is clamped to a maximum of 32 characters.  Setting TRAILING.ZEROS true displays all trailing zeros to the right of the decimal point to a maximum of RIGHT.PLACES.
Pronunciation: f-to-fixed-string
Attributes: S

F>FLOATING$ ( r -- x$addr\true )

Converts r to an ascii string at x$addr using FLOATING format which selects FIXED format unless the number can be displayed with greater resolution using scientific notation, in which case SCIENTIFIC format is used (see F>FIXED$ and F>SCIENTIFIC$).  If FILL.FIELD if OFF (the default condition), the string is displayed using the minimum possible field size, and numbers are not decimal aligned.  If FILL.FIELD is ON, the field size of the string is always equal to the scientific field size, which is MANTISSA.PLACES + 8, and numbers are decimal aligned for neat display of tabular data.  The string includes a trailing space unless NO.SPACES is true.  The flag on top of the stack is always true because any valid floating point number can be represented in the FLOATING format.
Pronunciation: f-to-floating-string
Attributes: S

F>R ( r -- )
Return stack: ( R: -- r )

Transfers the top floating point number on the data stack to the return stack.
Pronunciation: f-to-r
Attributes: C

F>SCIENTIFIC$ ( r -- x$addr\true )

Converts r into a text string at x$addr using SCIENTIFIC format.  The format is: (an optional) sign, single digit, decimal point, MANTISSA.PLACES digits, E, exponent sign, 2-digit exponent, and a trailing space:

-1.xxxxE-yy

The field size is equal to MANTISSA.PLACES + 8. The string includes a trailing space unless NO.SPACES is true.  The flag on top of the stack is always true because any valid floating point number can be represented in the SCIENTIFIC format.
Pronunciation: f-to-scientific-string
Attributes: S

F@ ( xaddr -- r )

Fetches a floating point number from xaddr.  A synonym for 2@.
Pronunciation: f-fetch

FABS ( r1 -- r2 )

r2 is the absolute value of r1. If floating point number r1 is negative, applies FNEGATE to r1 giving the positive number r2; otherwise, r2 = r1.
Pronunciation: f-abs
Attributes: S

FACOS ( r1 -- r2 )

r2 is the arc-cosine of r1. r2 is expressed in radians.
Pronunciation: f-a-cos
Attributes: S

FALN ( r1 -- r2 )

r2 equals the natural anti-log of r1; i.e., r2 = e^r1.
Pronunciation: f-a-l-n
Attributes: S

FALOG10 ( r1 -- r2 )

r2 equals the base 10 anti-log of r1; i.e., r2 = 10^r1.
Pronunciation: f-a-log-ten
Attributes: S

FALOG2 ( r1 -- r2 )

r2 equals the base 2 anti-log of r1; i.e., r2 = 2^r1.
Pronunciation: f-a-log-two
Attributes: S

FALSE ( -- flag | flag = 0 )

Puts a boolean false flag equal to 0 on the data stack .

FASIN ( r1 -- r2 )

r2 is the arcsine of r1. r2 is expressed in radians.
Pronunciation: f-a-sine
Attributes: S

FATAN ( r1 -- r2 )

r2 is the arctangent of r1. r2 is expressed in radians.
Pronunciation: f-a-tan
Attributes: S

FCONSTANT ( r <name> -- )

Removes the next <name> from the input stream and defines a child word called <name> which when executed leaves the floating point value r on the data stack.  r is stored in the definitions area of the dictionary. <name> is referred to as an fconstant. Use as:

r FCONSTANT <name>

Pronunciation: f-constant
Attributes: D

FCOS ( r1 -- r2 )

r2 is the cosine of r1. r1 is expressed in radians.
Pronunciation: f-cos
Attributes: S

FDROP ( r -- )

Drops a floating point number (two cells) from the data stack.
Pronunciation: f-drop

FDUP ( r -- r\r )

Duplicates the top floating point number (two cells) on the data stack.
Pronunciation: f-dupe

FDUP>R ( r -- r )
Return stack: ( R: -- r )

Copies the top floating point number on the data stack to the return stack.
Pronunciation: f-dup-to-r
Attributes: C

FIELD ( u <name> -- )

Defines a field constant <name> which when executed adds u to the extended address on the top of the data stack. <name>'s stack picture is ( xaddr – xaddr + u ).  It is recommended that <name> begin with a + to suggest its runtime behavior of adding the offset u to the top data stack item.  FIELD is the low level word called by all of the words that create members in structures.

See also MEMBER->

Attributes: D

FILL ( xaddr\u\b -- | u = byte count, b = fill value )

The specified byte b is stored in each of u consecutive addresses beginning at xaddr.  The specified region may cross page boundaries.  Does nothing if u = 0.

See also FILL.MANY

FILL.ARRAY ( array.xpfa\char -- )

Stores char into each byte of the specified array.

FILL.FIELD ( -- xaddr )

A user variable that contains a 16-bit flag.  If the flag is true, floating point numbers printed in FLOATING format are padded with spaces to yield a constant field width irrespective of whether the number is printed in scientific notation or fixed notation, and numbers printed in fixed notation are decimal aligned.  This leads to neat printouts of tabular data.  If the flag is false, the field width is not padded out.  The default value is false.

See also F>FLOATING$ and FP.DEFAULTS

Attributes: U

FILL.MANY ( xaddr\d\b -- | d = byte count, b = fill value )

The specified byte b is stored in each of d consecutive addresses beginning at xaddr.  The specified region may cross page boundaries.  Does nothing if d = 0.

FIND ( <name> -- [ xcfa\flag ] or [ 0 ] )

Executes BL WORD to parse the next space-delimited word from the input stream, and then searches the dictionary for a match of the parsed word, returning the xcfa under a nonzero flag if the word is found, or a 0 flag if the word is not found.  If a definition that includes the LOCALS{ statement is compiling, FIND first searches the VLOCALS vocabulary for a match to $addr.  If no match is found, FIND searches the CONTEXT vocabulary.  Then, if the word is not found and if the CONTEXT and CURRENT vocabularies are different, it searches the CURRENT vocabulary.  If the word is not found in the dictionary, it leaves a 0 on the stack.  If the word is found, (FIND) leaves the word's extended code field address and a flag on the stack.  For non-kernel non-local segments, (FIND) aborts if a matching segment entry is not found in required.segment table.  The 2 msbits of the returned xcfa encode additional information: bit6 is set if the target xcfa is in a non-local library (as opposed to an application segment), and bit7 is set if a page-relative call is required (e.g., if the found word is in the currently compiling segment).  The returned xcfa is the absolute code field address.  For kernel routines, this is the xcfa stored in the header of the found word, while for nonkernel routines, the returned xcfa is calculated as:

 {xcfa.offset from header} + {segment.xbase from eeprom segment table}

The returned flag at the top of the stack has an msbyte = 0xFF (to guarantee a nonzero flag) and the lsbyte equals the header.type field from the header of the found word.  A COLD restart will occur if more than 255 page changes are made during the search through either vocabulary.  This prevents the interpreter from going on an infinite search through a corrupted dictionary.  A COLD restart will also occur if POCKET is not in common memory.

See also (FIND)

FIND.LIB2LIB ( <name> -- [ segment.xhandle\xcfa.offset&segment.index\flag ] or [ 0 ] )

Executes BL WORD to parse the next space-delimited word from the input stream, and then searches the dictionary for a match of the parsed word, returning the information needed to compile a “handle-relative” call to the found word if the word is defined in a different library than the library that is now compiling.  If a definition that includes the LOCALS{ statement is compiling, FIND.LIB2LIB first searches the VLOCALS vocabulary for a match to <name>. If no match is found, it searches the CONTEXT vocabulary.  Then, if the word is not found and if the CONTEXT and CURRENT vocabularies are different, it searches the CURRENT vocabulary.  If the word is not found in the dictionary, it leaves a 0 on the stack.  If the word is found, FIND.LIB2LIB leaves the word's segment.xhandle under its code field address offset under its code page offset (in the least significant byte) augmented by the segment index (in the most significant byte) under a flag on the stack.  If the word is in the kernel or the currently compiling segment (as indicated by THIS.SEGMENT), then the returned segment.xhandle is 0\0. For non-kernel non-local segments, the segment.xhandle is obtained by searching the current segment’s required.segment table for a match to the segment.index stored in the found word’s header, and returning the xaddress of the matching table entry.  This routine aborts if a matching segment entry is not found in the required.segment table.  The code address- and page-offsets and the segment index are fetched directly from the found word’s header.  Note that the returned code field address parameters are offsets that must be added to the segment xbase.addr which is stored in the eeprom segment table indexed by the returned segment index.  The returned flag at the top of the stack has an msbyte = 0xFF (to guarantee a nonzero flag) and the lsbyte equals the header.type field from the header of the found word.  A COLD restart will occur if more than 255 page changes are made during the search through either vocabulary.  This prevents the interpreter from going on an infinite search through a corrupted dictionary.  A COLD restart will also occur if POCKET is not in common memory.

See also (FIND.LIB2LIB)
Pronunciation: find-lib-to-lib

FIND.RELATIVE ( <name> -- [ xcfa.offset&segment.index\flag ] or [ 0 ] )

Executes BL WORD to parse the next space-delimited word from the input stream, and then searches the dictionary for a match of the parsed word, returning the information needed to compile a relative call to the found word.  This function performs the same actions as FIND.LIB2LIB, with the simple difference that this function does not return the segment.xhandle.

See also FIND.LIB2LIB

FINT ( r1 -- r2 )

If the absolute value of r1 is less than 2^31, r2 is the floating point representation of the integer part (truncated toward zero) of r1. For these numbers, FINT is the equivalent of DINT DFLOT.  If the absolute value of r1 exceeds 2^31, FINT returns r2 = r1 and sets the OVERFLOW flag.
Pronunciation: f-int

FIXED ( -- )

Sets the default printing format used by PrintFP, F. and F>$ to fixed.  Numbers are decimal aligned, and RIGHT.PLACES and LEFT.PLACES determine the field width.

See also F>FIXED$

FIXED. ( r -- )

Prints r using FIXED format.  Does not change the default printing format.

See also F>FIXED$
Pronunciation: fixed-dot
Attributes: M, S

FIXX ( r -- n )

Rounds r to the nearest integer n.  OVERFLOW is set if needed.

See also DFIXX

Attributes: S

FLN ( r1 -- r2 )

r2 is the natural logarithm of r1.
Pronunciation: f-l-n
Attributes: S

FLOAT.SIZE ( -- n )

Returns the constant value 4 which is the number of bytes in a parameter of type float that is passed to or returned by a C-callable function.  This size specifier is used in the PARAMS( statement that describes the input and output parameters of a C-callable function.

See also PARAMS(

FLOATING ( -- )

Sets the default printing format used by PrintFP, F. and F>$ to floating.  The floating format uses FIXED format if the number can be represented with the same or more significant digits as it would if it were represented in SCIENTIFIC format.  Otherwise, it uses SCIENTIFIC format.

See also F>FLOATING$

FLOATING. ( r -- )

Prints r using FLOATING format.

See also F>FLOATING$
Pronunciation: floating-dot
Attributes: M, S

FLOG10 ( r1 -- r2 )

r2 is the base 10 logarithm of r1.
Pronunciation: f-log-ten
Attributes: S

FLOG2 ( r1 -- r2 )

r2 is the base 2 logarithm of r1.
Pronunciation: f-log-two
Attributes: S

FLOOR ( r1 -- r2 )

r2 is the floating point representation of the greatest integer less than or equal to r1.

Attributes: S

FLOT ( n -- r )

Converts the 16 bit integer n to its floating point representation r.

See also DFLOT
Pronunciation: float
Attributes: S

FMAX ( r1\r2 -- [r1] or [r2] )

Retains the greater of r1 and r2.
Pronunciation: f-max

FMIN ( r1\r2 -- [r1] or [r2] )

Retains the lesser of r1 and r2.
Pronunciation: f-min

FNEGATE ( r1 -- r2 )

r2 is the negative of r1.
Pronunciation: f-negate

FNUMBER ( x$addr -- [r\-1] or [0] )

Attempts to convert the space-delimited counted ascii string at x$addr into a valid floating point number r.  Returns r under a true flag if the conversion is successful; otherwise returns a false flag.  x$addr is the address of the text string's count byte.  The string at x$addr must end with a blank; the blank may or may not be included in the count.  Strings parsed by the commands BL WORD obey this rule.  For sting input routines that also accept integer and double integer numeric representations, see also NUMBER and $>F.
Pronunciation: f-number
Attributes: S

FOR ( u1 -- )
Return stack: ( R: -- u1 )

Used inside a colon definition to mark the beginning of a count-down loop structure that is terminated by NEXT.  Sets up loop index u1 on the return stack.  Use as:

u1 FOR  <words to be executed u1+1 times>
NEXT

0 FOR…NEXT executes 1 time, 1 FOR…NEXT executes 2 times, 65,535 FOR…NEXT executes 65,536 times, etc.  Because the loop index is maintained on the return stack, caution must be exercised when using the operators >R and R> inside a loop.  FOR…NEXT loops may be nested as long as each FOR is matched with a corresponding NEXT in the same definition as FOR; otherwise, an error is issued.  FOR … NEXT loops execute faster than DO … LOOP constructs.  The word I may be used inside a FOR NEXT loop.  J I' and LEAVE may not be used in a FOR NEXT loop.

Attributes: C, I

FORGET ( <name> -- )

Removes <name> from the input stream and searches for it in the CURRENT vocabulary.  If <name> is found, deletes it from the dictionary and removes all words defined after <name> by adjusting DP, NP, and the xhandle of the CURRENT vocabulary (LATEST).  If <name> is in the VFORTH vocabulary and if the hash table has been built, each forgotten header is delinked from the hash.  An error occurs if <name> is not found.  Heap space is not de-allocated by FORGET; use of ON.FORGET solves this problem.  When a word is about to be forgotten, FORGET checks to see if its name is ON.FORGET.  Words with the name ON.FORGET are executed before being forgotten.  This allows the deletion of heap items or other cleanup actions.  FORGETing a standard function definition does not de-allocate space in the variable area or EEPROM area.  Use of ANEW or of the LIBRARY and APPLICATION segment-defining words for dictionary cleanup avoids this problem; See their glossary entries.  FORGET performs the following actions when a segment header defined by LIBRARY or APPLICATION is forgotten: decrements the LAST.SEGMENT system variable if it equals the header's segment.index, which keeps last.segment correct even as segments are forgotten; calls OPEN.LAST.SEGMENT which sets THIS.SEGMENT, EEP, VP, DP, and NP to have the values they had when the prior segment was closed by END.SEGMENT; and sets THIS.SEGMENT.XBASE, THIS.SEGMENT.XNFA, and LIBRARY.IS.COMPILING to take on values specified in the EEPROM segment array for the prior segment.  Use FORGET with caution; it is possible to FORGET the entire operating system!

FORTH ( -- )

Specifies FORTH as the vocabulary to be searched first during dictionary searches.  Implementation detail: stores the 32-bit xhandle of the FORTH vocabulary into the user variable CONTEXT.

FORTH.HEADERS: ( <header.name> <${long.string}$> -- )

Defines one or more lines of text between the ${ and }$ delimiters of the long.string that will be printed into the Forth header file of the currently compiling library application segment when the segment is composed or built (exported). <header.name> is a placeholder, and it must be unique.  The long.string starts with ${ and ends with the }$ delimiter.  There must be a space before the ${ and a space or carriage return after the }$. The <header.name> and ${ must be on the same line as FORTH.HEADERS:.

Example:

FORTH.HEADERS: 4TH.HEADS ${ ( these comments go into the forth file)

( second comment line)

}$

Note that you need not put the terminating }$ on a separate line; putting it on the line above would simply delete a carriage return from the text dump.

IMPLEMENTATION DETAILS: The text long.string is stored in the forth names area during the compilation of the segment, but does not take up space in the final loaded library.  If the names page boundary is crossed during the definition of header.name, this routine aborts with an error.  The long.string itself can cross the name-page boundary without error.  The <header.name> has a bit set in its function.type field identifying it as a Forth header text name, and this causes the library dump to print the text long.string during the segment export.  The xaddress of the text long.string can be obtained as:

NFA.FOR <header.name> NFA>L$ DROP

FOVER ( r1\r2 -- r1\r2\r1 )

Places a copy of r1 on top of the data stack.
Pronunciation: f-over

FP&STRING.POP ( -- )
Return stack: ( R: 11 cells -- )

Pops off the return stack the values of the scratchpad user variables placed there by FP&STRING.PUSH and restores the popped values to the user area.  Also restores PAD to the value it had before FP&STRING.PUSH executed.  FP&STRING.PUSH and FP&STRING.POP are intended to be used in interrupt service routines that call floating point operations and/or floating point string conversion and/or integer string conversion operations.

If a word in this glossary that is marked with the ‘S’ attribute is called from within an interrupt service routine, the service routine should begin with FP&STRING.PUSH and end with FP&STRING.POP.  Execution time is approximately 10 microseconds.
Pronunciation: f-p-and-string-pop
Attributes: S

FP&STRING.PUSH ( xaddr -- | xaddr is temporary PAD )
Return stack: ( R: -- 11 cells )

Pushes onto the return stack the values of the scratchpad user variables that are modified by words that call the basic floating point operators F+ F- F* and F/ or by words that perform floating point or integer string conversion.  Also installs the specified xaddr as the value of PAD.  The saved items are later removed from the return stack and restored to the user area by FP&STRING.POP.  FP&STRING.PUSH is intended to be used in interrupt service routines that call floating point or number/string conversion operations.

If a word in this glossary that is marked with the ‘S’ attribute is called from within an interrupt service routine, the service routine should begin with FP&STRING.PUSH and end with FP&STRING.POP.  FP&STRING.PUSH should be executed by the interrupt service routine before the first floating point or conversion function is called to save the scratchpad values on the return stack and to establish a temporary PAD.  Executing FP&STRING.POP at the end of the interrupt service routine restores the scratchpad variables and PAD to their prior values.

Using FP&STRING.PUSH and FP&STRING.POP prevents conflicts when both the foreground (i.e., non-interrupt-invoked) program and the interrupt service routine call floating point and/or string conversion operations; if the interrupt routine does not save and restore the scratchpad variables, it may corrupt a floating point or conversion operation in the foreground program.  Integer and floating point string conversion use the 32 bytes below PAD for string generation, so establishing a new PAD address prevents conflicts between foreground and interrupt-invoked number conversion routines.

Execution time is approximately 10 microseconds.  If FP&STRING.PUSH is called inside an interrupt service routine, there is no need to call FP.PUSH, since FP&STRING.PUSH saves the FP.ERROR variable that FP.PUSH saves, plus additional variables.

See also FP.PUSH
Pronunciation: f-p-and-string-push

FP.DEFAULTS ( -- )

Initializes floating point user variables to default values.  Sets the number base to DECIMAL, makes FLOATING the default print format, sets LEFT.PLACES = 4, RIGHT.PLACES = 3, MANTISSA.PLACES = 4, and sets TRAILING.ZEROS, NO.SPACES, and FILL.FIELD false.
Pronunciation: f-p-defaults
Attributes: S

FP.ERROR ( -- xaddr )

A user variable containing a 16-bit error flag.  Set by many floating point operations and by OVERFLOW and UNDERFLOW.  Can be checked after any floating point operation to detect an underflow or overflow error.  Contents of 0 indicates no error, 1 indicates underflow, and -1 indicates overflow.

See also FP.PUSH
Pronunciation: f-p-error
Attributes: U

FP.POP ( -- )
Return stack: ( R: flag -- | flag = FP.ERROR )

Pops off the return stack the value of the FP.ERROR user variables placed there by FP.PUSH and restores the value to the user area.  FP.PUSH and FP.POP are intended to be used in interrupt service routines that call floating point operations.  If the FP.ERROR flag is not being used in your program, you do not have to use FP.PUSH and FP.POP.  Execution time is less than 1 microsecond.
Pronunciation: f-p-pop
Attributes: S

FP.PUSH ( -- )
Return stack: ( R: -- flag | flag = fp.error )

Pushes onto the return stack the value of the FP.ERROR user variable that is modified by all words that call the basic floating point operators F+ F- F* and F/. The item is later removed from the return stack and restored to the user area by FP.POP.  FP.PUSH is intended to be used in interrupt service routines that call floating point operations.  FP.PUSH should be executed by the interrupt service routine before the first floating point function is called to save FP.ERROR on the return stack.  Executing FP.POP at the end of the interrupt service routine restores FP.ERROR to its prior value.  Using FP.PUSH and FP.POP prevents conflicts when both the foreground (i.e., non-interrupt-invoked) program and the interrupt service routine call floating point operations.  If the FP.ERROR flag is not being used in your program, you do not have to use FP.PUSH and FP.POP.  Execution time is less than 1 microsecond.

See also FP&STRING.PUSH
Pronunciation: f-p-push

FPICK ( r\wn-1\...w1\w0\+n -- r\wn-1\...\w1\w0\r | 0 ≤ +n ≤ 255 )

Copies the floating point number whose most significant cell is the nth item on the stack (0-based, not including n) to the top of the stack.  An unchecked error occurs if there are fewer than +n+2 cells on the data stack. 0 FPICK is equivalent to FDUP, 1 FPICK is equivalent to X.OVER.N, 2 FPICK is equivalent to FOVER.
Pronunciation: f-pick

FR> ( -- r )
Return stack: ( R: r -- )

Transfers the top floating point number on the return stack to the data stack.
Pronunciation: f-r-from
Attributes: C

FR>DROP ( -- )
Return stack: ( R: r -- )

Removes the top floating point number from the return stack.
Pronunciation: f-r-from-drop
Attributes: C

FR@ ( -- r )
Return stack: ( R: r -- r )

Copies the top floating point number on the return stack to the data stack.
Pronunciation: f-r-fetch
Attributes: C

FRAME.DROP ( [+n bytes]\+n -- )

Drops +n bytes (in addition to +n) from the data stack.  If +n is odd, +n is incremented first so that an integer number of two-byte cells is dropped.  FRAME.DROP is usually used to drop items placed on the stack by STACK.FRAME.

See also STACK.FRAME

FRANDOM ( -- r | 1.0 ≤ r < 2.0 )

r is a pseudo-random floating point number greater than or equal to 1.0 and less than 2.0.

See also RANDOM# and RANDOM.GAUSSIAN
Pronunciation: f-random

FREE.HANDLE ( -- xaddr )

A variable that holds the 16-bit address of the next available handle in the current heap.  xaddr is equal to CURRENT.HEAP - 12. Initialized by IS.HEAP.

FROM.HEAP ( d -- [xhandle] or [0\0] | d = number of bytes )

If d bytes are available in the heap, allocates them and returns a 32-bit xhandle whose contents equal the base xaddress of the allocated heap item.  Adjusts d upward so that it is an even multiple of 4, and allocates the heap item so that its base address is an even multiple of 4. Returns 0\0 if there is not enough heap space to perform the allocation, or if the allocated handle is within 5 bytes of the bottom of CURRENT.HEAP's page (handles must be on the same page as CURRENT.HEAP).

FROM.IO ( offset\module_num\xaddr\+n -- )

Transfers +n bytes to the buffer starting at xaddr, starting at the specified offset (0 ≤ offset ≤ 255) in the Wildcard with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  The buffer is allowed to cross one or more page boundaries.  This routine disables interrupts for 1.5 microseconds per byte, and total execution time is approximately 3.5 microseconds per byte.  To transfer data from a smart processor-carrying Wildcard, use FROM.SMART.IO

FROM.SMART.IO ( offset\module_num\xaddr\+n -- )

Transfers +n bytes to the buffer starting at xaddr, starting at the specified offset (0 ≤ offset ≤ 255) in the smart (processor-carrying) Wildcard with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  The buffer is allowed to cross one or more page boundaries.  While special operators like FROM.SMART.IO, SMART.IO.C@, SMART.IO.@, and SMART.IO.2@ are required to read a smart processor-carrying Wildcard, the standard IO write functions such as TO.IO, IO.C!, IO.!, and IO.2! can be used to write to them.  This routine disables interrupts for 5.8 microseconds per byte, and total execution time is approximately 8.3 microseconds per byte.

See also FROM.IO.REGISTER and TO.IO

FROT ( r1\r2\r3 -- r2\r3\r1 )

Rotates the top three floating point numbers on the data stack.
Pronunciation: f-rote

FRTI ( r1 -- r2 )

Rounds r1 to the nearest integer and returns the result r2. OVERFLOW is set if necessary.
Pronunciation: f-round-to-integer
Attributes: S

FSCALE ( r1\n -- r2 )

Adds the signed integer n to the (base 2) exponent of r1 to compute r2. This provides a fast way of multiplying r1 by a power of 2 (if n is positive) or dividing r1 by a power of 2 (if n is negative).  OVERFLOW is set if necessary.
Pronunciation: f-scale
Attributes: S

FSIN ( r1 -- r2 )

r2 is the sine of r1. r1 is expressed in radians.
Pronunciation: f-sine
Attributes: S

FSQRT ( r1 -- r2 )

r2 is the square root of r1. r2 is zero if r1 is negative.
Pronunciation: f-square-root
Attributes: S

FSWAP ( r1\r2 -- r2\r1 )

Exchanges the top two floating point numbers on the stack.
Pronunciation: f-swap

FTAN ( r1 -- r2 )

r2 is the tangent of r1. r1 is expressed in radians.
Pronunciation: f-tan
Attributes: S

FUNCTION.TYPE ( -- xaddr )

A 16-bit system variable.  The least significant byte stored in this variable is transferred by CREATE, XCREATE, or (CREATE) to the function.type field in a newly created header.

FVARIABLE ( <name> -- )

Removes the next <name> from the input stream, defines a child word called <name>, and VALLOTs 2 cells in the variable area.  When <name> is executed, it leaves the extended address xaddr of the two cells reserved in the variable area to hold <name>'s contents. <name> is referred to as an fvariable. Use as:

FVARIABLE <name>

This defining word is segment-relocation-smart, and <name> performs the correct actions even when invoked inside a library or application segment that is relocated to a code location and variable area starting xaddress that are different from its initial compilation address.
Pronunciation: f-variable
Attributes: D

F^N ( r1\n -- r2 )

Raises r1 to the nth power and returns the result r2; r2 = r1^n.
Pronunciation: f-to-the-n
Attributes: S

GET ( xresource -- )

Used in a multitasking system to gain access to a shared resource.  PAUSEs until the resource variable whose address is xresource is available, and then GETs the resource by storing the task id (i.e., the STATUS xaddr) of the requesting task into the xresource. 0\0 in xresource indicates that the resource is available, and a non-zero value that is not equal to the requesting task's id indicates that another task controls the resource.  To ensure that the state of the resource is correctly determined, GET disables interrupts for 0.25 to 1microsecond.

See also ?GET, RELEASE, and RESOURCE.VARIABLE:

Attributes: M

H.INSTANCE: ( u <name> -- | u = size of heap item )

Creates a heap instance.  Removes <name> from the input stream, creates a header for <name> in the dictionary, and allots and erases a 6-byte parameter field associated with <name> in the variable area.  See HEAP.STRUCTURE.PF for a description of the contents of the parameter field.  Does not allocate space in the heap; this is done when the command ALLOCATED is executed.  When <name> is executed, its stack picture is picture is

( -- [xaddr] or [0\0] )

where xaddr is the base address of the item in the heap, and where 0\0 is returned if heap space has not been ALLOCATED.  The size u of the item in the heap is stored in the code field of <name> for later use by the word SIZE.OF.  This defining word is segment-relocation-smart, and <name> performs the correct actions even when invoked inside a library or application segment that is relocated to a code location and variable area starting xaddress that are different from its initial compilation address.  Typical use:

size.of.heap.item  H.INSTANCE:  <name>
SIZE.OF <name>   '  <name>   ALLOCATED
 <name>    ( -- base.xaddr.of.heap.item )

Pronunciation: h-instance
Attributes: D

HALT ( -- )

An infinite loop whose action is to put the calling task ASLEEP and execute PAUSE.  Typically used to terminate a task action that is not an infinite loop.

Attributes: M

HANDLE.PTR ( -- xaddr )

A variable that holds the 16-bit address of the next available location that can be allocated as a handle in the current heap.  xaddr is equal to CURRENT.HEAP - 10. Initialized by IS.HEAP.
Pronunciation: handle-pointer

HAS.PFA ( -- )

Sets the has-pfa bit in the header of the most recently defined word in the CURRENT vocabulary.  If set, this bit indicates that the word has a parameter field.  HAS.PFA is executed by <DBUILDS and <VBUILDS and by defining words including VARIABLE CONSTANT INTEGER: and their double number counterparts and synonyms.  The word ' (i.e., tick) checks the has-pfa bit when calculating the parameter field address of a word. ?HAS.PFA can be used to determine whether the has-pfa bit is set.
Pronunciation: has-p-f-a

HASH.INDEX ( n1 -- n2 | n1 = count&1st_char; n2 = hash_index )

Calculates the hash table index n2 based on the input parameter n1. For a given <name> in the dictionary, input parmeter n1 contains the count of <name> in the most significant byte, and the upper case first character of <name> in the least significant byte.  To find the xaddress of the corresponding entry in the hash table, use HASH.INDEX>XADDR.

See also BUILD.HASH.TABLE

Implementation detail: Counts > 31 map to zero, and non-alphabet chars map to a 0 character code.  The hash table index order is as follows:

[non-alpha]:0-31, [A]:0-31, [B]:0-31 ... [Z]:0-31

HASH.INDEX>XADDR ( hash.index -- xaddr-1 )

Based on the hash-table index (typically provided by HASH.INDEX), returns an xaddress that points 1 byte below the corresponding 3-byte entry in the hash table.  The 1-byte offset lets us use 2@ to fetch the 3byte contents (but note that the msbyte of fetched contents will be garbage).

See also BUILD.HASH.TABLE

HEAP.PTR ( -- xaddr )

A variable that holds the extended address of the next available byte in the current heap.  xaddr equals CURRENT.HEAP - 8. Initialized by IS.HEAP.
Pronunciation: heap-pointer

HEAP.STRUCTURE.PF ( -- u | u = minimum size of a heap parameter field )

Places on the stack the minimum number of bytes needed to allocate a parameter field for a heap item (u = 6 bytes).  HEAP.STRUCTURE.PF is a structure defined as:

STRUCTURE.BEGIN: HEAP.STRUCTURE.PF
   PAGE-> +HEAP.PAGE      \ page of current.heap and heap.handle
   HNDL-> +HEAP.HANDLE    \ contains base addr of heap item
   ADDR-> +CURRENT.HEAP   \ specifies which heap the item is in
STRUCTURE.END

See also H.INSTANCE:, +HEAP.PAGE, +HEAP.HANDLE, and +CURRENT.HEAP
Pronunciation: heap-structure-p-f

HERE ( -- xaddr )

Places on the stack the xaddr of the next available location in the definitions area.  Equivalent to DP X@

Attributes: U

HEX ( -- )

Sets the numeric conversion base to sixteen by storing decimal 16 into the user variable BASE.

HEX. ( u -- )

Prints u as unsigned hexadecimal integer with a leading 0x and one trailing space.  Does not change the current number BASE.
Pronunciation: hex-dot
Attributes: M, S

HEXD. ( ud -- )

Prints ud as unsigned hexadecimal number with a leading 0x and one trailing space.  Does not change the current number BASE.
Pronunciation: hex-d-dot
Attributes: M, S

HEXD.R ( ud\+b -- )

Prints ud as unsigned hexadecimal number with zero or more leading spaces and a leading 0x right justified in field of minimum width +b.  Does not change the current number BASE.
Pronunciation: hex-d-dot-r
Attributes: M, S

HEXD>R$ ( ud\+b -- )

Converts ud to unsigned hexadecimal number string with zero or more leading spaces and a leading 0x right justified in field of minimum width +b.  Does not change the current number BASE.
Pronunciation: hex-d-to-r-string
Attributes: S

HNDL-> ( u1 <name> -- u2 )

Adds a named member to the structure being defined and reserves room for a 16-bit field in the structure that will hold a handle (a handle is an address where another address is stored).  Removes <name> from the input stream and creates a structure field called <name>. u1 is the structure offset initialized by STRUCTURE.BEGIN:. u2 is the updated offset to be used by the next member defining word or by STRUCTURE.END.  When <name> is later executed, it adds its offset u1 to the extended address found on the data stack which is typically the start xaddress of an instance of the data structure; the result is the xaddress of the desired member in the structure.
Pronunciation: handle
Attributes: D

HOLD ( char -- )

Inserts char into the numeric output string to the left of the prior character in the string and decrements the headerless pointer #PTR.  HOLD is used between <# and #> commands to create a pictured numeric string.

Attributes: S

HOLDING.REG.FORCE.LATCH ( -- )

If enable_holding_flag and latch_mode_flag are true as set by the IC.PULSE.CONFIG function, then this routine forces the contents of the input capture registers TC0-TC3 and their corresponding 8-bit pulse accumulators to be latched into the holding registers.

Implementation detail: sets the ICLAT bit in the MCCTL register.

I ( -- w )
Return stack: ( R: w -- w )

Places a copy of the current (innermost) loop index on the data stack.  Cannot be used if additional items have been placed on the return stack (for example, using >R).  Typical use:

DO ... I ...  LOOP

or

DO ... I ... +LOOP

or

FOR ... I ... NEXT

Pronunciation: i
Attributes: C

I' ( -- w1 )
Return stack: ( R: w1\w2 -- w1\w2 )

Used inside a DO…LOOP or DO…+LOOP structure. Places a copy of the current (innermost) loop limit on the data stack. Cannot be used if additional items have been placed on the return stack (for example, using >R).  Typical use:

DO ... I' ...  LOOP

Use I to obtain the loop index, and I' to obtain the loop limit.

Pronunciation: i-prime
Attributes: C

I+ ( n1 -- n2 | n2 = n1 + I )
Return stack: ( R: w1 -- w1 )

Used inside a DO…LOOP or DO…+LOOP or FOR … NEXT structure.  Adds the current (innermost) loop index I to n1 and places the result n2 on the data stack.  Cannot be used if additional items have been placed on the return stack (for example, using >R).  Typical use:

DO ... n1 I+ ...  LOOP

Pronunciation: i-plus
Attributes: C

I- ( n1 -- n2 | n2 = n1 - I )
Return stack: ( R: w1 -- w1 )

Used inside a DO…LOOP or DO…+LOOP or FOR … NEXT structure.  Subtracts the current (innermost) loop index I from n1 and places the result n2 on the data stack.  Cannot be used if additional items have been placed on the return stack (for example, using >R).  Typical use:

DO ... n1 I- ...  LOOP

Pronunciation: i-minus
Attributes: C

IIC.ID ( -- n )

Returns the interrupt identity code for the IIC (Inter-IC) 2-wire multi-drop serial port.  This bus is sometimes called the I-squared-C (I2C) port.  Used as an argument for ATTACH.
Pronunciation: i-i-c-i-d

IC.1024.CYCLE.DELAY ( -- n )

A constant that is passed to IC.NOISE.DELAY to configure the input capture noise suppression delay.  Each cycle of delay corresponds to 50 nanoseconds, so passing this constant to IC.NOISE.DELAY sets up a 51.2 microsecond noise delay.  In other words, pulses of less than 51.2 microseconds duration will not be captured when this option is configured, and this limits the effect of spurious noise.  The noise suppression delay is disabled by default after a power-up or hardware reset.

See also IC.NOISE.DELAY, IC.DELAY.DISABLED, IC.256.CYCLE.DELAY, and IC.512.CYCLE.DELAY

IC.256.CYCLE.DELAY ( -- n )

A constant that is passed to IC.NOISE.DELAY to configure the input capture noise suppression delay.  Each cycle of delay corresponds to 50 nanoseconds, so passing this constant to IC.NOISE.DELAY sets up a 12.8 microsecond noise delay.  In other words, pulses of less than 12.8 microseconds duration will not be captured when this option is configured, and this limits the effect of spurious noise.  The noise suppression delay is disabled by default after a power-up or hardware reset.

See also IC.NOISE.DELAY, IC.DELAY.DISABLED, IC.512.CYCLE.DELAY, and IC.1024.CYCLE.DELAY

IC.512.CYCLE.DELAY ( -- n )

A constant that is passed to IC.NOISE.DELAY to configure the input capture noise suppression delay.  Each cycle of delay corresponds to 50 nanoseconds, so passing this constant to IC.NOISE.DELAY sets up a 25.6 microsecond noise delay.  In other words, pulses of less than 25.6 microseconds duration will not be captured when this option is configured, and this limits the effect of spurious noise.  The noise suppression delay is disabled by default after a power-up or hardware reset.

See also IC.NOISE.DELAY, IC.DELAY.DISABLED, IC.256.CYCLE.DELAY, and IC.1024.CYCLE.DELAY

IC.DELAY.DISABLED ( -- n )

A constant that is passed to IC.NOISE.DELAY to disable the input capture noise suppression delay.  This is the default condition after a power-up or hardware reset.

See also IC.NOISE.DELAY, IC.256.CYCLE.DELAY, IC.512.CYCLE.DELAY, and IC.1024.CYCLE.DELAY

IC.FIRST.POLARITY ( -- n )

For the four latched input capture channels, returns a bit-encoded value n that represents the polarity of the first edge that has caused an input capture to occur after the corresponding capture latch has been read.  Bit 0 corresponds to IC0, bit 1 corresponds to IC1, bit 2 corresponds to IC2, and bit3 corresponds to IC3. A bit value of 0 means that the first input capture has been caused by a falling edge, and a bit value of 1 means that the first input capture has been caused by a rising edge.  The default result after a reset is 0.

IC.HOLDING.READ ( channel_id -- u )

For the specified buffered input capture channel_id in the range 0 to 3, reads and returns the 16-bit value u from the corresponding input capture holding register TC0, TC1H, TC2H, or TC3H.  The specified channel must be configured as an input capture (as opposed to an output compare) by invoking the INPUT.CAPTURE function.  Consult the glossary entries for IC.PULSE.CONFIG, IC.OVERWRITE.OK, and IC.NO.OVERWRITE for more information about the IC holding registers.  Briefly, if the latch_mode flag passed to IC.PULSE.CONFIG is true, then the input capture register contents are latched into the holding register when the modulus counter equals zero, or when the HOLDING.REG.FORCE.LATCH function is invoked.  If the latch_mode flag passed to IC.PULSE.CONFIG is false, then the captures are in “queued mode”, and the holding registers are loaded from the IC register upon each new capture, subject to the IC.OVERWRITE.OK or IC.NO.OVERWRITE provision.  Do not use this function for pulse accumulator channels; See the glossary entry for PULSE.HOLDING.READ.

IC.NO.OVERWRITE ( channel_id -- )

For a valid input capture channel_id in the range 0 to 7, configures the channel such that the input capture and its holding register (if present) cannot be overwritten until read by the application program; See the OC.IC.REG.READ and IC.HOLDING.READ functions.

Implementation detail: This routine sets the specified bit in the ICOVW register to prevent an IC register or IC holding register to be overwritten by a new event before it is empty.  The default state at reset is that overrides are ok.

IC.NOISE.DELAY ( n -- | n =delay_id )

Configures all of the input captures such that pulses shorter than the specified delay (relative to the 50 nanosecond E-clock period) are ignored.  Valid input parameters are the constants IC.DELAY.DISABLED, IC.256.CYCLE.DELAY (12.8us), IC.512.CYCLE.DELAY (25.6us), or IC.1024.CYCLE.DELAY (51.2us); See their glossary entries.  The noise delay feature is disabled by default after a power-up or hardware reset.

IC.OVERWRITE.OK ( channel_id -- )

For a valid input capture channel_id in the range 0 to 7, configures the channel such that the input capture and its holding register (if present) can be overwritten even though they have not been read by the application program; See the OC.IC.REG.READ and IC.HOLDING.READ functions.

Implementation detail: This routine clears the specified bit in the ICOVW register to allow an IC register or IC holding register to be overwritten by a new event before it is empty.  The default state at reset is that overrides are ok.

IC.PULSE.CONFIG ( share37\share26\share15\share04\2_events\255_pulsemax\holding\latch_mode-- )

Configures the input capture and pulse accumulator subsystem.  All 8 input parameters are 16-bit integer flags; the stack picture gives them descriptive names.  Each of the input parameter flags specifies a single bit that is combined into a 8-bit value and written to the ICSYS register to configure the input capture and pulse accumulator subsystem.

The default state after a reset is all flags equal to zero; in other words, all bits in the ICSYS register are 0 after a reset.  ICSYS is a write-once register, so this function can only be executed one time after each power-up or hardware reset; attempting to execute it again will have no effect until the processor hardware is reset.

The first four input parameters configure input capture sharing.  If the share37 boolean flag is true (nonzero), then an input capture event on IC3 is also treated as a capture event on IC7. If the share26 flag is true, then an input capture event on IC2 is also treated as a capture event on IC6. If the share15 flag is true, then an input capture event on IC1 is also treated as a capture event on IC5. If the share04 flag is true, then an input capture event on IC0 is also treated as a capture event on IC4.

If the 255_pulsemax flag is true, all 8-bit pulse accumulators count to 0xFF and then stop.  The remaining three flags (holding, latch_mode, and 2_events) configure the holding registers for input captures IC0-3 and 8-bit pulse accumulators 0-3. If the holding and latch_mode flags are both false, then the 2_events flag is relevant; when true, 2_events specifies that the associated flag bit will not be set until 2 capture events have transpired (one capture is in the holding register, and the second is in the IC register).  If either the holding or latch_mode flags is true, then a single input capture event sets the corresponding flag bit.  If latch_mode is true, latching into the holding register (and clearing of 8-bit pulse accumulators) occurs when the modulus down counter reaches 0, or when a zero is written into the count register using MOD.COUNTER.LOAD and MOD.COUNTER.UPDATE, or when HOLDING.REG.FORCE.LATCH is executed.

The pulse accumulators require that both the holding and latch_mode flags are true to utilize the holding registers, as the queued mode of transferring to the holding registers applies only to input captures, not the associated pulse accumulators.

For more information on the Input Capture and Pulse Accumulator subsystems, See the ECT (Enhanced Capture Timer) Block User Guide published by Motorola.

ID. ( xnfa -- )

Prints the name of the routine associated with the extended name field address xnfa.  Letters not saved in the header are printed as ___ . The printed name is followed by a space.  If the word is smudged (for example, if an error occurred during compilation of the word, or if SMUDGE: was invoked), it is not printed.  An unchecked error occurs if xnfa is not a valid name field address.
Pronunciation: i-d-dot
Attributes: M

IF ( flag -- )

Used inside a colon definition to mark the beginning of a conditional structure.  If flag is FALSE execution continues after the subsequent ELSE or ENDIF (THEN and ENDIF are synonyms).  If flag is TRUE execution continues with the word immediately following IF, and when ELSE is encountered (if present), control is transferred to the word following ENDIF.  Use as:

flag    IF        words to execute if flag is true
   ENDIF

or as:

flag    IF        words to execute if flag is true
   ELSE    words to execute if flag is false
   ENDIF

Attributes: C, I

IFTRUE ( flag -- )

Marks the start of the true portion of a conditional structure that is used in execution mode outside a colon definition.  Use as:

 flag  IFTRUE .... OTHERWISE ....  ENDIFTRUE

If the flag passed to IFTRUE is true, the code between IFTRUE and OTHERWISE is executed, and the code between OTHERWISE and ENDIFTRUE is skipped.  If the flag is false, the code between IFTRUE and OTHERWISE is skipped and execution continues with the words following OTHERWISE.  Another valid syntax is:

flag  IFTRUE ....  ENDIFTRUE

If the flag passed to IFTRUE is true, the code between IFTRUE and ENDIFTRUE is executed.  If the flag is false, the code between IFTRUE and ENDIFTRUE is skipped.  IFTRUE is analogous to IF but it is used outside of a colon definition.  The execution mode conditional structure can be used to conditionally compile portions of source code.  An unchecked error occurs if IFTRUE is used without a corresponding ENDIFTRUE.  IFTRUE statements can be nested.
Pronunciation: if-true

IIC.104KHZ.23PERCENT ( -- n )

A constant that is passed to IIC.INIT to initialize the IIC (Inter-IC 2-wire serial bus) baud rate to 104 KHz, with a 23% data hold time as a percentage of the clock period.  The value n is stored by IIC.INIT into the IBFD register.  The typical maximum IIC bus frequency is 100 KHz, and a good target for the data hold time as a percentage of the clock period is 25% (34.5% is the maximum allowed).  While the IIC system cannot run at a master clock rate of exactly 100 KHz, the closest choices are the 104 KHz as set by this constant, and 96 KHz as set by the IIC.96KHZ.25PERCENT constant.  For a 10 KHz IIC master, See the glossary entry for IIC.10KHZ.13PERCENT.  To specify a customized IIC baud rate, See the glossary entry for IIC.FREQUENCIES.  The maximum attainable IIC clock frequency on the PDQ hardware is 1000 KHz.

IIC.10KHZ.13PERCENT ( -- n )

A constant that is passed to IIC.INIT to initialize the IIC (Inter-IC 2-wire serial bus) baud rate to 10 KHz, with a 13% data hold time as a percentage of the clock period.  The value n is stored by IIC.INIT into the IBFD register.  The typical maximum IIC bus frequency is 100 KHz, and the maximum data hold time as a percentage of the clock period is 34.5%. For a 100 KHz IIC master, See the glossary entries for IIC.96KHZ.25PERCENT and IIC.104KHZ.23PERCENT.  To specify a customized IIC baud rate, See the glossary entry for IIC.FREQUENCIES.  The maximum attainable IIC clock frequency on the PDQ hardware is 1000 KHz.

IIC.96KHZ.25PERCENT ( -- n )

A constant that is passed to IIC.INIT to initialize the IIC (Inter-IC 2-wire serial bus) baud rate to 96 KHz, with a 25% data hold time as a percentage of the clock period.  The value n is stored by IIC.INIT into the IBFD register.  The typical maximum IIC bus frequency is 100 KHz, and a good target for the data hold time as a percentage of the clock period is 25% (34.5% is the maximum allowed).  While the IIC system cannot run at a master clock rate of exactly 100 KHz, the closest choices are the 96 KHz as set by this constant, and 104 KHz as set by the IIC.104KHZ.23PERCENT constant.  For a 10 KHz IIC master, See the glossary entry for IIC.10KHZ.13PERCENT.  To specify a customized IIC baud rate, See the glossary entry for IIC.FREQUENCIES.  The maximum attainable IIC clock frequency on the PDQ hardware is 1000 KHz.

IIC.ARB.LOST.ERROR ( -- n )

A constant equal to 2 which is logically OR’d together with any other error conditions encountered during an IIC (Inter-IC 2-wire serial bus) data transfer to indicate that IIC bus arbitration was lost during the data transfer.  The resulting combined error result is placed into the IIC.ERROR variable and returned by the IIC send and receive functions.  An error value of zero means that no error occurred.  To analyze and respond to a nonzero error condition, the application program can perform a logical AND of the error result with this IIC.ARB.LOST.ERROR constant; a nonzero result means that bus arbitration was lost during the IIC data exchange.  This typically results from a non-responsive slave or a multi-master conflict.

See also IIC.ERROR

IIC.ERROR ( -- xaddr )

A system variable.  When executed, it returns the xaddress of a 16-bit variable that holds the error result of the most recent IIC (Inter-IC 2-wire serial bus) data transfer.  IIC.ERROR is cleared at the start of each IIC send or receive operation.  If the contents of this variable equal zero after an IIC data transfer, there was no error.  If the contents are non-zero, then an error occurred, and the contents equal the logical OR of the identifying error bitmasks.  The error condition can be determined by sequentially performing a logical AND of the original contents of IIC.ERROR with the following bitmask error types: IIC.TIMEOUT.ERROR, IIC.ARB.LOST.ERROR, IIC.NAK.ERROR, IIC.XMIT.BUF.OVERFLOW, and IIC.RCV.BUF.OVERFLOW.  Any AND operation whose result equals the tested-for error constant indicates that the named error was encountered.

IIC.FREQUENCIES ( -- )

This function prints a formatted table of all 192 possible contents of the IBFD (IIC Bus Frequency Divider) register in both hex and decimal, followed by the corresponding decimal IIC (Inter-IC 2-wire serial) bus frequency in kHz (rounded to the nearest kHz) and the corresponding decimal data hold time as a percentage of clock period.  This function is useful if you do not want to use one of the three named baud rate constants (IIC.96KHZ.25PERCENT, IIC.104KHZ.23PERCENT, or IIC.10KHZ.13PERCENT).  The typical maximum IIC bus frequency is 100 KHz, and a good target for the data hold time as a percentage of the clock period is 25% (34.5% is the maximum allowed).  The maximum attainable IIC clock frequency on the PDQ hardware is 1000 KHz.  While the IIC system cannot run at a master clock rate of exactly 100 KHz, the closest choices are 96 KHz and 104 KHz as set by the IIC.96KHZ.25PERCENT and IIC.104KHZ.23PERCENT constants.  For a 10 KHz IIC master, use IIC.10KHZ.13PERCENT.  To use this function, type IIC.FREQUENCIES interactively at the terminal and examine the resulting data table to select the IBFD register contents that yield the desired IIC bus clock frequency and the data hold time as a percentage of the clock period, and then pass the selected IBFD constant to the IIC.INIT function.  When IIC.FREQUENCIES is executed, the first few lines of the resulting printout look like this:

Pass the selected IBFD constant to IICInit (or to IIC.INIT in Forth).
0xIBFD  IBFD  SCL.KHZ  SDA.HOLD%  (decimal)
 0x0     0      1000      35
 0x1     1       909      32
 0x2     2       833      33
 …

Attributes: M, S

IIC.INIT ( n1\n2 -- | n1= ibfd_contents; n2 = my_slave_address )

This routine initializes and configures the IIC (Inter-IC 2-wire multi-drop serial bus) software for interrupt-based operation compatible with the IIC driver functions built into the operating system.  The input parameters are the contents to be written to the IBFD baud rate register, and the slave IIC address.  The ibfd_contents parameter is typically one of the pre-defined constants IIC.96KHZ.25PERCENT, IIC.104KHZ.23PERCENT, or IIC.10KHZ.13PERCENT; if a different baud rate is required, See the glossary entry for IIC.FREQUENCIES.  The my_slave_address input parameter should be an even number between 2 and 254. In other words, the address should occupy a single byte with the least significant bit equal to zero; this satisfies the requirements of the IIC protocol as implemented on the HCS12 processor.  To prevent contention, the assigned slave address must be unique on the connected IIC network.  The IIC control register is configured for interrupt-enabled IIC transfers starting in the slave reception mode with standard acknowledgement.  PORTJ pins 6 and 7 are set high if they are outputs to ensure that they idle in the inactive high state.  This routine ATTACHes the IIC interrupt service routine which runs during data transfers; note that the ATTACH routine disables interrupts for many milliseconds the first time it runs while EEPROM is being programmed; be careful to ensure that this does not adversely affect your application.  After the EEPROM is initialized by this routine, subsequent invocations of this function will not need to re-write the EEPROM, so interrupts will not be disabled.  This IIC.INIT routine does NOT globally enable interrupts; the application must invoke ENABLE.INTERRUPTS or some equivalent interrupt-enabling function such as START.TIMESLICER before attempting an IIC data transfer.  This function erases all of the IIC control variables and buffers, including: IIC.XMIT.BUF.EMPTY, IIC.RCV.BUF.FULL, IIC.ERROR, IIC.XMIT.BUF.OFFSET, IIC.RCV.BUF.OFFSET, IIC.MASTER.RECEIVER, IIC.NUM.BYTES.TO.XMIT, IIC.NUM.BYTES.TO.RCV, IIC.XMIT.BUFFER, and IIC.RCV.BUFFER.  The IIC.XMIT.BUF.SIZE and IIC.RCV.BUF.SIZE variables are set to their default values of decimal 32 bytes each, and the IIC.XMIT.BUF.PTR and IIC.RCV.BUF.PTR variables are initialized to point to the default 32-byte buffers in reserved system RAM.  If you need to create larger transmit and receive buffers, allocate the new buffers in common RAM, call this IIC.INIT routine, then write the buffer sizes into IIC.XMIT.BUF.SIZE and IIC.RCV.BUF.SIZE, and write the respective 16-bit buffer base addresses into IIC.XMIT.BUF.PTR and IIC.RCV.BUF.PTR.

Note that the transmit and receive buffers are linear frame buffers, as opposed to circular ring buffers.  The received data must be extracted from the IIC.RCV.BUFFER before the next receive operation begins, and the data in the IIC.XMIT.BUFFER must be transmitted before writing a new frame into the transmit buffer.

IIC.MASTER.RECEIVER ( -- xaddr )

A system variable.  When executed, it returns the xaddr of a 16 bit variable that holds a flag used to control an IIC (Inter-IC 2-wire serial bus) serial transfer.  This flag is automatically set by IIC.RECEIVE and IIC.RECEIVE.FRAME, and is cleared by the IIC sending routines.  The application program typically does not have to access this low-level control flag.

IIC.NAK.ERROR ( -- n )

A constant equal to 3 which is logically OR’d together with any other error conditions encountered during an IIC (Inter-IC 2-wire serial bus) data transfer to indicate that No AcKnowlegement was received during a data transfer before a timeout occurred.  The resulting combined error result is placed into the IIC.ERROR variable and returned by the IIC send and receive functions.  An error value of zero means that no error occurred.  To analyze and respond to a nonzero error condition, the application program can perform a logical AND of the error result with this IIC.NAK.ERROR constant; a result equal to IIC.NAK.ERROR means that a timeout occurred without any acknowlegement during the IIC data exchange.  This typically results from a non-responsive slave or a multi-master conflict.

See also IIC.ERROR

IIC.NUM.BYTES.TO.RCV ( -- xaddr )

A system variable.  When executed, it returns the xaddr of a 16 bit variable that holds the number of bytes to be received by a master on the IIC (Inter-IC 2-wire serial) bus during the next data reception.  This variable is automatically initialized by IIC.RECEIVE and IIC.RECEIVE.FRAME.  The application program typically does not have to access this low-level control variable.

IIC.NUM.BYTES.TO.XMIT ( -- xaddr )

A system variable.  When executed, it returns the xaddr of a 16 bit variable that holds the number of bytes to be transmitted by a master on the IIC (Inter-IC 2-wire serial) bus.  This variable is automatically initialized by IIC.SEND, IIC.SEND.FRAME, and IIC.SEND.NEXT.FRAME.  The application program typically does not have to access this low-level control variable.

IIC.RCV.BUF.FULL ( -- xaddr )

A system variable.  When executed, it returns the xaddr of a 16 bit variable that holds a flag.  A true flag indicates that the master’s receive buffer is full based on the expected number of incoming bytes passed to the IIC.RECEIVE or IIC.RECEIVE.FRAME functions.  This variable is automatically set by the background IIC (Inter-IC 2-wire serial bus) interrupt service routine running in the master.  If you have used the IIC.RECEIVE function to initiate the master’s reception, the application program must monitor the IIC.RCV.BUF.FULL variable and, when it becomes true (non-zero), fetch the expected number of bytes out of the IIC.RCV.BUFFER starting at offset 0. To automate the process, use the IIC.RECEIVE.FRAME function to initiate the reception; in this case, the function waits until the IIC.RCV.BUF.FULL flag is true, clears the flag, copies the received data to a private buffer, and exits.  By calling IIC.RECEIVE.FRAME, you can access the received data without the need to monitor the IIC.RCV.BUF.FULL flag.

IIC.RCV.BUF.OFFSET ( -- xaddr )

A system variable.  When executed, it returns the xaddr of a 16 bit variable that holds the zero-based offset into the IIC.RCV.BUFFER, pointing to the next available byte.  This variable is automatically incremented by the IIC (Inter-IC 2-wire serial bus) interrupt service routine during the reception of a frame by the IIC master or slave.  This variable is typically not used during reception by the IIC master, but it is very useful for managing data reception in the IIC slave.  The application program of a slave IIC receiver should monitor the contents of IIC.RCV.BUF.OFFSET until it equals the expected number of incoming bytes, then copy the received bytes out of the receive buffer starting at buffer offset 0 (in other words, starting at the xaddress returned by IIC.RCV.BUFFER).

IIC.RCV.BUF.OVERFLOW ( -- n )

A constant equal to 0x10 which is logically OR’d together with any other error conditions encountered during an IIC (Inter-IC 2-wire serial bus) data reception to indicate that the number of bytes received exceeded the contents of IIC.RCV.BUF.SIZE, which specifies the size of the IIC.RCV.BUFFER.  The default receive buffer size after executing IIC.INIT is decimal 32 bytes; See the glossary entry for IIC.INIT if you want to declare a larger buffer.  The resulting combined error result is placed into the IIC.ERROR variable and returned by the IIC send and receive functions.  An error value of zero means that no error occurred.  To analyze and respond to a nonzero error condition, the application program can perform a logical AND of the error result with this IIC.RCV.BUF.OVERFLOW constant; a nonzero result means that a buffer overflow occurred during the IIC data reception.

See also IIC.ERROR

IIC.RCV.BUF.PTR ( -- xaddr )

A system variable.  When executed, it returns an xaddress that contains the 16-bit address of the IIC.RCV.BUFFER in common RAM.  IIC.INIT initializes this variable to point to the default 32 byte IIC receive buffer in reserved system RAM.  If a 32 byte receive buffer is adequate, you never have to use the IIC.RCV.BUF.PTR.  If, however, you need to declare a larger receive buffer, allocate the buffer in common RAM, call the IIC.INIT routine, then write the buffer size into IIC.RCV.BUF.SIZE, and write the 16-bit buffer base address into IIC.RCV.BUF.PTR.

Example of use: After calling IIC.INIT with the required two input parameters, the statement:

IIC.RCV.BUF.PTR @  COMMON.PAGE

returns the same value as:

IIC.RCV.BUFFER

IIC.RCV.BUFFER ( -- xaddr )

Returns the extended address of the IIC (Inter-IC 2-wire serial bus) receive buffer by fetching the contents of IIC.RCV.BUF.PTR and converting it to a 32-bit xaddress (with page = 0, the COMMON.PAGE).  By default, this buffer is decimal 32 bytes long after IIC.INIT is executed.  To create a larger receive buffer, See the glossary entry for IIC.RCV.BUF.PTR.  A master on the IIC bus should fetch received data out of the IIC.RCV.BUFFER starting at offset 0 after calling IIC.RECEIVE.  A slave on the IIC bus should fetch received data out of the IIC.RCV.BUFFER starting at offset 0 after monitoring the IIC.RCV.BUF.OFFSET variable until it equals the expected number of incoming bytes.

IIC.RCV.BUF.SIZE ( -- xaddr )

A system variable.  When executed, it returns an xaddress that contains the 16-bit size of the IIC.RCV.BUFFER.  IIC.INIT initializes this variable to 32. If a 32 byte receive buffer is adequate, you never have to use the IIC.RCV.BUF.SIZE variable.  If, however, you need to declare a larger receive buffer, allocate the buffer in common RAM, call the IIC.INIT routine, then write the buffer size into IIC.RCV.BUF.SIZE, and write the 16-bit buffer base address into IIC.RCV.BUF.PTR.

IIC.RECEIVE ( u\n1\n2 -- error | u = timeout_cnt, n1 = numbytes, n2 = slave_iic_address )

This routine receives n1 bytes of data from a remote slave on the IIC (Inter-IC 2-wire serial) bus having the specified slave_iic_address n2, and places the received data into the IIC.RCV.BUFFER.  IIC.RECEIVE sets up the control variables and registers, waits and pauses until the IIC bus is not busy, and, if the timeslicer is running, enforces a maximum waiting time of u1 (timeout_cnt) timeslice counts, where the default timeslice period is 1.024 milliseconds (see MSEC.TIMESLICE.PERIOD).  If a timeout occurs, the IIC.TIMEOUT.ERROR error flag is returned.  Note that if the timeslicer is not running (that is, if START.TIMESLICER was not executed), then no timeout is enforced, and if the slave is not responding for some reason, this routine will PAUSE indefinitely.  When the IIC bus becomes available, this routine initiates the reception by sending the slave_iic_address with its least significant bit set to indicate that we (the master) are reading.  This routine does not wait for the reception to end; rather, the calling routine should monitor the IIC.RCV.BUF.FULL system variable and, when it goes true (nonzero), get the data out of the IIC.RCV.BUFFER.  For a simpler way to receive data without monitoring the IIC.RCV.BUF.FULL variable, see IIC.RECEIVE.FRAME.  Note that there is a slight chance that the IIC bus will be busy when we start receiving (if someone else grabbed the bus just as we were about to grab it); this condition will be detected by the interrupt service routine and will result in an error code containing IIC.ARB.LOST.ERROR being returned by this function.  If the returned error flag is nonzero, the calling routine must test for and respond to the following error conditions: IIC.TIMEOUT.ERROR, IIC.ARB.LOST.ERROR, IIC.NAK.ERROR, and IIC.RCV.BUF.OVERFLOW.  Consult the glossary entries of these error constants and of IIC.ERROR for more details.

IIC.RECEIVE.FRAME ( u\xaddr\n1\n2 -- error | u= timeout_cnt, n1= numbytes, n2= slave_iic_addr )

This routine receives n1 bytes of data from a remote slave on the IIC (Inter-IC 2-wire serial) bus having the specified slave_iic_address n2, and places the received data into the IIC.RCV.BUFFER.

IIC.RECEIVE.FRAME sets up the control variables and registers, waits and PAUSEs until the IIC bus is not busy, and, if the timeslicer is running, enforces a maximum waiting time of u (timeout_cnt) timeslice counts, where the default timeslice period is 1.024 milliseconds; see MSEC.TIMESLICE.PERIOD.  If a timeout occurs, the IIC.TIMEOUT.ERROR error flag is returned.  When the IIC bus becomes available, this routine initiates the reception by sending the slave_iic_address with its least significant bit set to indicate that we (the master) are reading.  This routine then waits and pauses until the IIC.RCV.BUF.FULL flag is set, and, if the timeslicer is running, again enforces the u (timeout_cnt) timeslice counts maximum waiting period while waiting for the receive buffer to fill.  If there is no timeout, IIC.RECEIVE.FRAME moves the contents of the IIC.RCV.BUFFER to the buffer specified by the xaddr input parameter.

This routine retains control until the received bytes have been moved out of the IIC.RCV.BUFFER so the next requested reception can't corrupt prior data.  The specified timeslice count is used both while waiting for the IIC bus to be available, and again for the receive buffer to fill, so the maximum timeout is twice the specified timeout period.

Note that if the timeslicer is not running (that is, if START.TIMESLICER was not executed), then no timeout is enforced, and if the slave is not responding for some reason, this routine will PAUSE indefinitely.  Note also that there is a slight chance that the IIC bus will be busy when we start receiving (if someone else grabbed the bus just as we were about to grab it); this condition will be detected by the interrupt service routine and will result in an error code containing IIC.ARB.LOST.ERROR being returned.  If the returned error flag is nonzero, the calling routine must test for and respond to the following error conditions: IIC.TIMEOUT.ERROR, IIC.ARB.LOST.ERROR, IIC.NAK.ERROR, and IIC.RCV.BUF.OVERFLOW.  Consult the glossary entries of these error constants and of IIC.ERROR for more details.

See also IIC.RECEIVE

IIC.SEND ( u\n1\n2 -- error | u = timeout_cnt, n1 = numbytes, n2 = slave_iic_address )

This routine sends data to a remote slave on the IIC (Inter-IC 2-wire serial) bus having the specified slave_iic_address n2. IIC.SEND transmits n1 bytes of data that have been pre-loaded into the IIC.XMIT.BUFFER, sets up the control variables and registers, waits and PAUSEs until the IIC bus is not busy, and, if the timeslicer is running, enforces a maximum waiting time of u1 (timeout_cnt) timeslice counts, where the default timeslice period is 1.024 milliseconds; see MSEC.TIMESLICE.PERIOD.  If a timeout occurs, the IIC.TIMEOUT.ERROR error flag is returned.  Note that if the timeslicer is not running (that is, if START.TIMESLICER was not executed), then no timeout is enforced, and if the slave is not responding for some reason, this routine will PAUSE indefinitely.  If there is no timeout error, IIC.SEND initiates the transmission by sending the slave_iic_address with its least significant bit cleared to indicate that we (the master) are writing.  Note that, while this routine waits for the hardware IIC bus to be not-busy, this routine can still step on the control variables of a previous write by this processor which has not yet completed.  To avoid this problem, use IIC.SEND.NEXT.FRAME to wait until the prior frame transmission initiated by this (master) processor has completed before sending another one.  Note that there is a slight chance that the IIC bus will be busy when we start transmitting (if someone else grabbed the bus just as we were about to grab it); this condition will be detected by the interrupt service routine and will set the IIC.ARB.LOST.ERROR variable.  Also note that errors posted during the frame transmission by the background interrupt service routine may not be included in the error flag returned by this routine, as transmission may continue after this routine exits.  If the returned error flag is nonzero, the calling routine must test for and respond to the following error conditions: IIC.TIMEOUT.ERROR, IIC.ARB.LOST.ERROR, IIC.NAK.ERROR, and IIC.XMIT.BUF.OVERFLOW.  Consult the glossary entries of these error constants for more details.

See also IIC.SEND.FRAME and IIC.SEND.NEXT.FRAME

IIC.SEND.FRAME ( u\xaddr\n1\n2 -- error | u= timeout_cnt, n1= numbytes, n2= slave_iic_addr )

This routine copies n1 (numbytes) bytes of data from the specified xaddr buffer into the IIC.XMIT.BUFFER and calls IIC.SEND to send the data to the specified remote slave on the IIC bus.  The u parameter specifies the maximum time in timeslice counts (typically 1.024ms, see MSEC.TIMESLICE.PERIOD) to wait for the IIC (Inter-IC 2-wire serial) bus to become available.  Consult the glossary entries for IIC.SEND for a detailed description of operation.  For a more bullet-proof transmission function that returns only after the transmission has completed, see IIC.SEND.NEXT.FRAME.

IIC.SEND.NEXT.FRAME ( u\xaddr\n1\n2 -- error | u=timeout_cnt, n1=numbytes, n2=slave_iic_addr )

IIC.SEND.NEXT.FRAME first waits and PAUSEs until the IIC.XMIT.BUF.EMPTY flag is true to ensure that any prior transfer is complete.  If no timeout error occurred while waiting, copies n1 (numbytes) bytes of data from the specified buffer at xaddr into the IIC.XMIT.BUFFER and sends the data to the specified remote slave on the IIC (Inter-IC 2-wire serial) bus having slave address n2. The u parameter specifies the maximum time in timeslice counts (typically 1.024ms per count) to wait for the transmit buffer to empty, and for the IIC bus to become available.  The advantage of this routine is that it sends a new frame only after the prior transmission has ended, thereby avoiding contention between sequential transmissions and ensuring data integrity.  After waiting for any prior transmission to complete, IIC.SEND.NEXT.FRAME sets up the control variables and registers, waits and PAUSEs until the IIC bus is not busy, and, if the timeslicer is running, enforces a maximum waiting time of u1 (timeout_cnt) timeslice counts, where the default timeslice period is 1.024 milliseconds; see MSEC.TIMESLICE.PERIOD.  If a timeout occurs, the IIC.TIMEOUT.ERROR error flag is returned.  The specified timeslice count is used both while waiting for the xmit buffer to empty, and again for the IIC bus to become not-busy, so the maximum timeout is twice the specified timeout period.  Note that if the timeslicer is not running (that is, if START.TIMESLICER was not executed), then no timeout is enforced, and if the slave is not responding for some reason, this routine will PAUSE indefinitely.  If there is no timeout error, IIC.SEND.NEXT.FRAME initiates the transmission by sending the slave_iic_address with its least significant bit cleared to indicate that we the master are writing.  Note that there is a slight chance that the IIC bus will be busy when we start transmitting (if someone else grabbed the bus just as we were about to grab it); this condition will be detected by the interrupt service routine and will set the IIC.ARB.LOST.ERROR variable.  Also note that errors posted during the frame transmission by the background interrupt service routine may not be included in the error flag returned by this routine, as transmission may continue after this routine exits.  If the returned error flag is nonzero, the calling routine must test for and respond to the following error conditions: IIC.TIMEOUT.ERROR, IIC.ARB.LOST.ERROR, IIC.NAK.ERROR, and IIC.XMIT.BUF.OVERFLOW.  Consult the glossary entries of these error constants and of IIC.ERROR for more details.

See also IIC.SEND and IIC.SEND.FRAME

IIC.TIMEOUT.ERROR ( -- n )

A constant equal to 1 which is logically OR’d together with any other error conditions encountered during an IIC (Inter-IC 2-wire serial bus) data transfer to indicate that a timeout error occurred.  The resulting combined error result is placed into the IIC.ERROR variable and returned by the IIC send and receive functions.  An error value of zero means that no error occurred.  To analyze and respond to a nonzero error condition, the application program can perform a logical AND of the error result with this IIC.TIMEOUT.ERROR constant; a nonzero result means that a timeout occurred during the IIC data exchange.  This typically results from a non-responsive slave or a multi-master conflict.

See also IIC.ERROR

IIC.XMIT.BUF.EMPTY ( -- xaddr )

A system variable.  When executed, it returns the xaddr of a 16 bit variable that holds a flag.  A true flag indicates that the master’s transmit buffer is empty based on a comparison with the contents of the IIC.NUM.BYTES.TO.XMIT variable as initialized by IIC.SEND, IIC.SEND.FRAME, or IIC.SEND.NEXT.FRAME.  This variable is also set if the master was not properly acknowleged by the IIC (Inter-IC 2-wire serial bus) slave during the attempted data transmission.  This variable is not used by the slave in an IIC data transfer.  IIC.XMIT.BUF.EMPTY is a low level system variable that is typically not accessed by the application program.

IIC.XMIT.BUF.OFFSET ( -- xaddr )

A system variable.  When executed, it returns the xaddr of a 16 bit variable that holds a zero-based offset into the IIC.XMIT.BUFFER, pointing to the next byte to be transmitted by the IIC (Inter-IC 2-wire serial bus) master.  This variable is initialized by IIC.SEND, IIC.SEND.FRAME, and IIC.SEND.NEXT.FRAME and maintained by the IIC interrupt service routine; it is a low level system variable that is typically not accessed by the application program.

IIC.XMIT.BUF.OVERFLOW ( -- n )

A constant equal to 8 which is logically OR’d together with any other error conditions encountered during an IIC (Inter-IC 2-wire serial bus) data transmission to indicate that the offset to the next byte to be transmitted in the IIC.XMIT.BUFFER exceeds the allowed number of bytes in the buffer as indicated by the contents of the IIC.XMIT.BUF.SIZE variable.  The default transmit buffer size after executing IIC.INIT is decimal 32 bytes; See the glossary entry for IIC.XMIT.BUF.PTR if you want to declare a larger buffer.  The resulting combined error result is placed into the IIC.ERROR variable and returned by the IIC send functions.  An error value of zero means that no error occurred.  To analyze and respond to a nonzero error condition, the application program can perform a logical AND of the error result with this IIC.XMIT.BUF.OVERFLOW constant; a nonzero result means that a buffer overflow occurred during the IIC data transmission.

See also IIC.ERROR

IIC.XMIT.BUF.PTR ( -- xaddr )

A system variable.  When executed, it returns an xaddress that contains the 16-bit address of the IIC.XMIT.BUFFER in common RAM.  IIC.INIT initializes this variable to point to the default 32 byte IIC transmit buffer in reserved system RAM.  If a 32 byte transmit buffer is adequate, you never have to use the IIC.XMIT.BUF.PTR.  If, however, you need to declare a larger transmit buffer, allocate the buffer in common RAM, call the IIC.INIT routine, then write the buffer size into IIC.XMIT.BUF.SIZE, and write the 16-bit buffer base address into IIC.XMIT.BUF.PTR.

Example of use: After calling IIC.INIT with the required two input parameters, the statement:

IIC.XMIT.BUF.PTR @  COMMON.PAGE

returns the same value as:

IIC.XMIT.BUFFER

IIC.XMIT.BUFFER ( -- xaddr )

Returns the extended address of the IIC transmit buffer by fetching the contents of IIC.XMIT.BUF.PTR and converting it to a 32-bit xaddress (with page = 0, the COMMON.PAGE).  By default, this buffer is decimal 32 bytes long after IIC.INIT is executed.  To create a larger transmit buffer, See the glossary entry for IIC.XMIT.BUF.PTR.  An application program can perform an IIC (Inter-IC 2-wire serial bus) master transmission by writing the data to be transmitted into the IIC transmit buffer (starting at the xaddress returned by this IIC.XMIT.BUFFER function) and then calling IIC.SEND.  Alternatively, the data to be transmitted can reside in a buffer anywhere in memory, and this private buffer xaddress and the associated number of bytes to be transmitted can be passed to either IIC.SEND.FRAME or IIC.SEND.NEXT.FRAME; both of these functions automatically copy the data to be transmitted into the IIC.XMIT.BUFFER.  A slave on the IIC bus should place any data bytes to be transmitted to the master into the IIC transmit buffer (starting at the xaddress returned by this IIC.XMIT.BUFFER function) before they are demanded by the master, and then let the master retrieve them.

IIC.XMIT.BUF.SIZE ( -- xaddr )

A system variable.  When executed, it returns an xaddress that contains the 16-bit size of the IIC.XMIT.BUFFER.  IIC.INIT initializes this variable to 32. If a 32 byte transmit buffer is adequate, you never have to use the IIC.XMIT.BUF.SIZE variable.  If, however, you need to declare a larger transmit buffer, allocate the buffer in common RAM, call the IIC.INIT routine, then write the buffer size into IIC.XMIT.BUF.SIZE, and write the 16-bit buffer base address into IIC.XMIT.BUF.PTR.

IMMEDIATE ( -- )

Marks the header of the most recently defined word to indicate that it should be executed immediately even in compilation mode.  The command ?IMMEDIATE may be used to determine the status of the immediate bit for a given word.

IN.PLACE ( -- n )

A constant that specifies that a library or application segment should be built/dumped so that it reloads in the same place (that is, without relocation at load time).  IN.PLACE can be passed as a parameter to BUILD.APPLICATION, BUILD.LIBRARY, BUILD.SEGMENTS, COMPOSE.C.INSTALER, COMPOSE.C.INSTALLER.FOR, COMPOSE.FORTH.INSTALLER, COMPOSE.FORTH.INSTALLER.FOR, DUMP.SEGMENT, and DUMP.SEGMENTS; See their glossary entries.

INFINITY ( -- r )

Pushes the largest representable floating point number onto the data stack.

INIT.ELAPSED.TIME ( -- )

Initializes the system variable TIMESLICE.COUNT to 0\0.

INIT.IP.SPI ( -- )

Initializes SPI channels SPI1 and SPI2.  These SPI channels are used for inter-processor communications on custom parallel-processing systems.  If parallel processing is not required, the SPI1 and SPI2 channels may be used to communicate with other peripherals.  The SPI #2 jumper on the PDQ Board determines which port this routine designates as the master and which as the slave.  If the SPI #2 jumper cap is not installed, then SPI1 is the master and SPI2 is the slave.  If the SPI#2 jumper is installed, then SPI1 is the slave and SPI2 is the master.  After calling this word the SPI1 and SPI2 clocks idle low, data is sampled/valid on the falling/trailing clock edge, and data is transferred on the rising leading clock edge.  The default baud rate is set to 5 MHz.  This routine is not called upon power-up or restart, and must be explicitly called by a software application before calling SPI.CONFIG to change the communication parameters.
Pronunciation: init-i-p-S-P-I

INIT.SPI ( -- )

Configures and enables the serial peripheral interface channel SPI0 so that it can transfer data on the Wildcard bus stacks and to/from the on-board battery-backed real-time clock.  Initializes the 68HCS12 as the SPI master with 2 MHz data transfer, with clock idling low, valid data present/sampled on the falling trailing edge of the SPI clock, and data transferred on the rising/leading clock edge.  Also initializes the resource variable SPI.RESOURCE to zero.  This routine is called upon each power-up or reset.
Pronunciation: init-S-P-I

INIT.VITAL.IRQS.ON.COLD ( -- )

Undoes the effect of the NO.VITAL.IRQ.INIT command, and causes subsequent cold restarts to perform the default action of checking the interrupt vectors for the COP, clock monitor, illegal opcode trap and RTI (timeslicer) interrupts and initializing them if they do not contain the standard interrupt service vectors.
Pronunciation: init-vital-i-r-qs-on-cold

INPUT.CAPTURE ( channel_id -- )

For the specified channel_id in the range 0 to 7, configures the corresponding bit of the PORTT timer register as an input capture (as opposed to an output compare).  An input capture memorizes the value of the free-running TCNT counter at the instant of the triggering input transition in its associated timer/counter register TCx (TC0 through TC7); see OC.IC.REG.READ.  An input capture can also optionally cause an interrupt when the triggering input transition occurs.  After a power-up or hardware reset, all 8 PORTT pins are configured as input captures by default, with no triggering action.  To configure a trigger action, pass one of the action constants (TRIGGER.OFF, TRIGGER.ON.RISING.EDGE, TRIGGER.ON.FALLING.EDGE, or TRIGGER.ON.ANY.EDGE) and the specified channel_id to the TRIGGER.EDGE function.  To enable or disable an interrupt, pass the channel_id to ECT.INTERRUPT.ENABLE or ECT.INTERRUPT.DISABLE.

Pulse accumulator notes: For all pulse accumulators except the 16-bit PULSE_A, the pins associated with a pulse accumulator should be configured as input captures using this routine and the TRIGGER.EDGE routine, and then enabled for pulse counting using the PULSE.ENABLE function (for 8 bit pulse accumulators) or PULSE.B.SETUP function (for 16 bit pulse accumulators).  Use channel_id = 0 to 3 for the 8 bit accumulators PA0 through PA3, and channel_id = 0 (or pass the PULSE.B channel_id constant) for the 16-bit PULSE.B accumulator.  Do not pass PULSE.A as a channel_id input parameter to this INPUT.CAPTURE function.  See PULSE.A.SETUP for more details regarding the 16-bit PULSE.A accumulator.

Implementation detail: The INPUT.CAPTURE routine clears the bit of the specified channel in the TIOS register.

INPUT.STRING ( <text> -- x$addr | x$addr = PAD )

Inputs a character string <text> to the PAD buffer, terminating when CHARS/LINE characters are received or a carriage return is received, whichever comes first.  Leaves the address of the counted string on the stack.  Appends a blank (not included in the count) to the end of the string.

Attributes: M

INSTALL.MULTITASKER ( -- )

Installs the timeslice multitasker timer by initializing the interrupt vector of the real-time interrupt (RTI).  This command is automatically executed upon a COLD restart (unless the command NO.VITAL.IRQ.INIT has been executed) and by the command START.TIMESLICER.  Because the interrupt vector is in non-volatile EEPROM, it is usually not necessary to invoke this command unless the RTI interrupt vector has been modified.

INT-> ( u1 <name> -- u2 )

Adds a named member to the structure being defined and reserves room for a 16-bit field in the structure.  Removes <name> from the input stream and creates a structure field called <name>. u1 is the structure offset initialized by STRUCTURE.BEGIN:. u2 is the updated offset to be used by the next member defining word or by STRUCTURE.END.  When <name> is later executed, it adds its offset u1 to the extended address found on the data stack which is typically the start xaddress of an instance of the data structure; the result is the xaddress of the desired member in the structure.
Pronunciation: integer
Attributes: D

INT.FLOOR ( r -- n )

n is the greatest integer less than or equal to r.  OVERFLOW is set if needed.

Attributes: S

INT.PART ( r -- n )

n is the integer part of r.  OVERFLOW is set if needed.
Pronunciation: int-part
Attributes: S

INT.SIZE ( -- n )

Returns the constant value 2 which is the number of bytes in a parameter of type int that is passed to or returned by a C-callable function.  This size specifier is used in the PARAMS( statement that describes the input and output parameters of a C-callable function.

See also PARAMS(
Pronunciation: int-size

INTEGER: ( <name> -- )

Defines a 16-bit self-fetching variable.  Removes <name> from the input stream and creates a child word (a self-fetching variable) called <name> and VALLOTs 2 bytes in the variable area as the parameter field where the self-fetching variable's value is stored.  When <name> is executed it leaves its value (a 16-bit integer) on the stack.  Thus <name> behaves like a constant when executed.  Unlike a constant, its parameter field is in the variable area and so can always be modified.  The TO command is used to store a value into the self-fetching variable.  In general, code using self-fetching variables runs faster than does similar code that uses standard variables.  Use as:

INTEGER: <name>         <value>  TO  <name>

Pronunciation: integer-colon
Attributes: D

INTERPRET ( -- )

Interprets the input stream until the input stream is exhausted.  The input stream is taken from the terminal input buffer and INTERPRET interprets a single line of input which was read into the TIB by QUERY.  INTERPRET repeatedly calls WORD (which gets the next word from the input stream) until the input stream is exhausted at the end of the current line or block.

See also >IN, WORD, QUERY, and QUIT

INTS-> ( u1\u2 <name> -- u3 )

Adds a named member to the structure being defined and reserves room for u2 integers in the structure.  Removes <name> from the input stream and creates a structure field called <name>. u1 is the structure offset initialized by STRUCTURE.BEGIN:. u3 is the updated offset to be used by the next member defining word or by STRUCTURE.END.  When <name> is later executed, it adds its offset u1 to the extended address found on the data stack which is typically the start xaddress of an instance of the data structure; the result is the xaddress of the desired member in the structure.
Pronunciation: integers
Attributes: D

IO.! ( w\offset\module_num -- )

Stores the 16-bit number w at the specified offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  Also works for smart processor-carrying Wildcards.

Pronuciation: i-o-store

IO.2! ( d\offset\module_num -- )

Stores the 32-bit number d at the specified offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  Also works for smart processor-carrying Wildcards.

Pronuciation: i-o-two-store

IO.2@ ( offset\module_num -- d )

Fetches the 32-bit number d from the specified offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  Disables interrupts for an isolated period of 1.5 microseconds for each byte fetched.  To fetch from a smart processor-carrying Wildcard, use SMART.IO.2@

Pronuciation: i-o-two-fetch

IO.@ ( offset\module_num -- w )

Fetches the 16-bit number w from the specified offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  Disables interrupts for an isolated period of 1.5 microseconds for each byte fetched.  To fetch from a smart processor-carrying Wildcard, use SMART.IO.@

Pronuciation: i-o-fetch

IO.C! ( byte\offset\module_num -- )

Stores byte at the specified offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  Also works for smart processor-carrying Wildcards.

Pronuciation: i-o-c-store

IO.C@ ( offset\module_num -- byte )

Fetches byte from the specified offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  Disables interrupts for 1.5 .microseconds.  To fetch from a smart processor-carrying Wildcard, use SMART.IO.C@

Pronuciation: i-o-c-fetch

IO.CHANGE.BITS ( byte1\byte2\offset\module_num -- | byte1 = data; byte2 = mask )

At the byte specified by the offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, modifies the bits specified by 1's in byte2 to have the values indicated by the corresponding bits in byte1. In other words, byte2 serves as a mask which specifies the bits that are to be modified, and byte1 provides the data which is written to the modified bits.  module_num range 0-7 implements standard speed modules, and module_num range 8-15 implements slow-access-timing modules.  Disables interrupts for 2.7 microseconds to ensure an uninterrupted read/modify/write operation.  Does not work for smart processor-carrying Wildcards.

Pronuciation: i-o-change-bits

IO.CLEAR.BITS ( byte1\offset\module_num -- )

At the byte specified by the offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, clears the bits specified by 1's in byte1. module_num range 0-7 implements standard speed modules, and module_num range 8-15 implements slow-access-timing modules.  Disables interrupts for 2.35 microseconds to ensure an uninterrupted read/modify/write operation.  Does not work for smart processor-carrying Wildcards.

Pronuciation: i-o-clear-bits

IO.F! ( r\offset\module_num -- )

Stores the 32-bit floating point number r at the specified offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  A synonym for IO.2!. Also works for smart processor-carrying Wildcards.

Pronuciation: i-o-f-store

IO.F@ ( offset\module_num -- r )

Fetches the 32-bit floating point number r from the specified offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  A synonym for IO.2@. Disables interrupts for an isolated period of 1.5 microseconds for each byte fetched.  To fetch from a smart processor-carrying Wildcard, use SMART.IO.F@

Pronuciation: i-o-f-fetch

IO.SET.BITS ( byte1\offset\module_num -- )

At the byte specified by the offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, sets the bits specified by 1's in byte1. module_num range 0-7 implements standard speed modules, and module_num range 8-15 implements slow-access-timing modules.  Disables interrupts for 2.35 microseconds to ensure an uninterrupted read/modify/write operation.  Does not work for smart processor-carrying Wildcards.

Pronuciation: i-o-set-bits

IO.X! ( xaddr\offset\module_num -- )

Stores the 32-bit xaddr at the specified offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  A synonym for IO.2!. Also works for smart processor-carrying Wildcards.

Pronuciation: i-o-x-store

IO.X@ ( offset\module_num -- xaddr )

Fetches the 32-bit xaddr from the specified offset (0 ≤ offset ≤ 255) in the Wildcard module with hardware address module_num, where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  A synonym for IO.2@. Disables interrupts for an isolated period of 1.5 microseconds for each byte fetched.  To fetch from a smart processor-carrying Wildcard, use SMART.IO.X@

Pronuciation: i-o-x-fetch

IRQ.ID ( -- n )

Returns the interrupt identity code for the external interrupt request interrupt.  Used as an argument for ATTACH.
Pronunciation: i-r-q-i-d

IS.AUTOSTART ( xcfa -- )

Compiles a 6-byte sequence at 0xBFFA on page 0x37 in the HCS12 on-chip flash so that upon subsequent restarts and ABORTs, the function having the specified xcfa will be automatically executed.  This allows a finished application to be automatically entered upon power up and resets.  The autostart routine is invoked by ABORT which is called by the error handler and upon every reset or restart.  The autostart is executed after the processing of any valid boot vectors that have been posted by Mosaic’s kernel extensions, and after the PRIORITY.AUTOSTART vector is checked.  If no priority autostart or autostart routine is posted or if the specified autostart routine terminates, ABORT then invokes QUIT which is the QED-Forth interpreter.  To undo the effects of this command and return to the default startup action, call NO.AUTOSTART.  To recover from the installation of a buggy autostart routine, invoke the special cleanup mode by following the directions in the manual.

NOTE: For production systems, consider using the PRIORITY.AUTOSTART: or IS.PRIORITY.AUTOSTART routines which place the startup vector on page 0x0F in external RAM and shadow flash, making it easier to include the vector as part of the downloaded code.  See the examples in the glossary entries for DUMP.S2 and DUMP.MANY.S2

Implementation detail: At location 0xBFFA on page 0x37, AUTOSTART: writes the pattern 0x1357 followed by the specified 4-byte xcfa.

See also AUTOSTART:, PRIORITY.AUTOSTART: and IS.PRIORITY.AUTOSTART

IS.HEAP ( xaddr1\xaddr2 -- | xaddr1 = start, xaddr2 = end )

Initializes the heap control variables to set up a heap starting at xaddr1 and ending 1 byte below xaddr2. All of the bytes between xaddr1 and xaddr2 must be modifiable RAM.  The size of the heap and of individual heap items is limited only by available memory.  If the specified heap size (xaddr2 - xaddr1) is greater than or equal to 16 bytes, IS.HEAP initializes CURRENT.HEAP to xaddr2, initializes START.HEAP and HEAP.PTR to xaddr1, and initializes HANDLE.PTR and FREE.HANDLE to indicate that there are no allocated heap items.  If the specified heap size (xaddr2 - xaddr1) is less than 16 bytes, only the user variable CURRENT.HEAP is initialized, and the heap control variables that are stored in the heap itself (START.HEAP, HEAP.PTR, HANDLE.PTR and FREE.HANDLE) are not initialized.  This allows tasks to share a heap that has already been initialized without disturbing the values of the heap control variables.  The maximum size of a heap is limited only by the amount of available contiguous RAM.  A heap can flow over page boundaries.  Likewise, the size of a data structure in the heap is limited only by the available memory in the heap.  The only heap limitation is that the list of handles which is maintained near the top of the heap must be on the last page of the heap, and the handle list cannot flow over a page boundary.  Because each handle requires only 4 bytes, this poses very little limitation for most practical applications.

Caution: sharing a heap among tasks may lead to hard-to-diagnose multitasking failures.
Pronunciation: is-heap

IS.PRIORITY.AUTOSTART ( xcfa -- )

Compiles a 6-byte sequence at 0xBFFA on page 0x0F in the external RAM and corresponding shadow flash memory so that upon subsequent restarts and ABORTs, the function having the specified xcfa will be automatically executed.  This allows a finished application to be automatically entered upon power up and resets.  The priority autostart routine is invoked by ABORT which is called by the error handler and upon every reset or restart.  The priority autostart is executed after the processing of any valid boot vectors that have been posted by Mosaic’s kernel extensions, and before the AUTOSTART: vector is checked.  If no priority autostart or autostart routine is posted or if the specified autostart routine terminates, ABORT then invokes QUIT which is the QED-Forth interpreter.  To undo the effects of this command and return to the default startup action, call NO.AUTOSTART.  To recover from the installation of a buggy autostart routine, invoke the special cleanup mode by following the directions in the manual.  This priority autostart is ideal for production systems, because it places the startup vector on page 0x0F in external RAM and shadow flash, making it easier to include the vector as part of the downloaded code.  See the examples in the glossary entries for DUMP.S2 and DUMP.MANY.S2

Implementation detail: At location 0xBFFA on page 0x0F, writes the pattern 0x1357 followed by the specified 4-byte xcfa.

See also PRIORITY.AUTOSTART: and AUTOSTART:

IS.TRACE.ACTION ( xcfa -- )

Installs the action referenced by the extended code field address xcfa as the first action to be performed by the trace routine.  If a colon or code definition is compiled with TRACE ON, a call to the trace routine is compiled before each call to subsidiary words in the definition.  The first thing that the trace routine does is to execute the code whose xcfa has been stored in the headerless user variable TRACE.ACTION by IS.TRACE.ACTION.  The default action (set upon COLD restart) is NO.OP.  The action must have no net effect on the data or return stacks, and must be compiled while TRACE is OFF; if trace is ON while the trace action is being defined, an infinite loop of calls to the trace routine is initiated.  The word DEFAULT.TRACE.ACTION installs NO.OP (a do-nothing word) as the trace action.

See also BREAK, BREAK.ALL, DEBUG, DUMP.REGISTERS, and SINGLE.STEP

Example of use: assume that a complex program contains a mysterious bug, and the programmer is trying to locate it.  Further assume that the programmer knows that the bug causes a particular variable called THE.VARIABLE to be set equal to 0. One way to locate the problem would be to compile the program with TRACE ON and then execute the entire program with DEBUG ON.  The disadvantage of this is that a great deal of traced output must be examined.  A more efficient method is to write a word that tests the variable in question and, if it equals 0 (which signals that the bug has just occurred), turns DEBUG ON:

: CHECK.FOR.ERROR     THE.VARIABLE  @  0= IF  DEBUG  ON  THEN ;

This word is then installed as the trace action by executing:

CFA.FOR   CHECK.FOR.ERROR   IS.TRACE.ACTION

Now the program is compiled with TRACE ON, and executed with DEBUG initially OFF so that the program runs at near full speed and no traced output is written to the screen.  As soon as the bug manifests itself, however, the trace action word turns DEBUG ON which initiates the printout of all trace information.  This shows the programmer where the bug is occurring in the program.

IXN+ ( xaddr1 -- xaddr2 | xaddr2 = xaddr1 + I )
Return stack: ( R: w1 -- w1 )

Used inside a DO…LOOP or DO…+LOOP or FOR … NEXT structure.  Adds the current (innermost) loop index I, interpreted as a signed integer in the range -32,768 to +32,767, to xaddr1 and places the result xaddr2 on the data stack.  Cannot be used if additional items have been placed on the return stack (for example, using >R).  Typical use:

DO ... addr1  IXN+ ...  LOOP

See XN+
Pronunciation: i-x-n-plus
Attributes: C

IXN- ( xaddr1 -- xaddr2 | xaddr2 = xaddr1 - I )
Return stack: ( R: w1 -- w1 )

Used inside a DO…LOOP or DO…+LOOP or FOR … NEXT structure.  Subtracts the current (innermost) loop index I, interpreted as a signed integer in the range -32,768 to +32,767, from xaddr1 and places the result xaddr2 on the data stack.  Cannot be used if additional items have been placed on the return stack (for example, using >R).  Typical use:

DO ...xaddr1  IXN- ...  LOOP

See XN-
Pronunciation: i-x-n-minus
Attributes: C

IXU+ ( xaddr1 -- xaddr2 | xaddr2 = xaddr1 + I )
Return stack: ( R: w1 -- w1 )

Used inside a DO…LOOP or DO…+LOOP or FOR … NEXT structure.  Adds the current (innermost) loop index I, interpreted as an unsigned integer in the range 0 to +65,535, to xaddr1 and places the result xaddr2 on the data stack.  Cannot be used if additional items have been placed on the return stack (for example, using >R).  Typical use:

DO ... xaddr1  IXU+ ...  LOOP

See XU+
Pronunciation: i-x-u-plus
Attributes: C

IXU- ( xaddr1 -- xaddr2 | xaddr2 = xaddr1 - I )
Return stack: ( R: w1 -- w1 )

Used inside a DO…LOOP or DO…+LOOP or FOR … NEXT structure.  Subtracts the current (innermost) loop index I, interpreted as an unsigned integer in the range 0 to +65,535, from xaddr1 and places the result xaddr2 on the data stack.  Cannot be used if additional items have been placed on the return stack (for example, using >R).  Typical use:

DO ... xaddr1  IXU- ...  LOOP

See XU-
Pronunciation: i-x-u-minus
Attributes: C

J ( -- w1 )
Return stack: ( R: w2\w1\w3\w4 -- w2\w1\w3\w4 )

Used inside nested DO…LOOP or DO…+LOOP.  Places on the data stack a copy of the loop index for the next outer loop (i.e., the index of the loop nested 1 level below the loop in which J is invoked).  Cannot be used if additional items have been placed on the return stack (for example, using >R).  Cannot be used in FOR…NEXT loops.  Typical use:

DO
   DO  ... J ...
   LOOP
LOOP

Attributes: C

KEY ( -- char )

Waits (if necessary) for receipt of a character from the serial port and places the character on the data stack.  KEY is a vectored routine that executes the routine whose xcfa is stored in the headerless user variable UKEY.  The default installed routine called is KEY1 which receives the character from the primary serial port (supported by the processor’s SCI0 hardware UART).  KEY2 may be installed in UKEY by USE.SERIAL2 or SERIAL2.AT.STARTUP; KEY2 receives the character from the secondary serial port (supported by the processor’s SCI1 hardware UART).

See also KEY1 and KEY2

Attributes: M, U

KEY1 ( -- char )

Waits (if necessary) for receipt of a character from the primary serial port (serial1) and places the received character on the data stack.  KEY1 does not echo the character.  The serial1 port is associated with the processor’s SCI0 hardware UART.  KEY1 is the default KEY routine installed in the UKEY user variable if SERIAL1.AT.STARTUP has been executed (and after the special cleanup mode is invoked).  If the value in SERIAL.ACCESS is RELEASE.AFTER.LINE, KEY1 does not GET or RELEASE the SERIAL1.RESOURCE.  If SERIAL.ACCESS contains RELEASE.ALWAYS, KEY1 GETs and RELEASEs the SERIAL1.RESOURCE.  If SERIAL.ACCESS contains RELEASE.NEVER, KEY1 GETs but does not RELEASE the SERIAL1.RESOURCE.

See also KEY, UKEY, KEY2, and SERIAL.ACCESS
Pronunciation: key-one
Attributes: M

KEY2 ( -- char )

Waits (if necessary) for receipt of a character from the secondary serial (serial2) port and places the received character on the data stack.  The serial2 port is supported by the processor’s SCI1 hardware UART.  KEY2 does not echo the received character.  KEY2 can be made the default KEY routine installed in the UKEY user variable after each reset or restart by executing SERIAL2.AT.STARTUP.  If the value in SERIAL.ACCESS is RELEASE.AFTER.LINE, KEY2 does not GET or RELEASE the SERIAL2.RESOURCE.  If SERIAL.ACCESS contains RELEASE.ALWAYS, KEY2 GETs and RELEASEs the SERIAL2.RESOURCE.  If SERIAL.ACCESS contains RELEASE.NEVER, KEY2 GETs but doesn't RELEASE the SERIAL2.RESOURCE.  See KEY, UKEY, KEY1, and SERIAL.ACCESS.
Pronunciation: key-two
Attributes: M

KILL ( xtask.id -- )

Puts the task referenced by xtask.id ASLEEP and removes it from the round robin multitasking loop.  The task to be killed must be installed in the round robin loop.  If it isn't, or if a task attempts to KILL itself, the results are unpredictable.  Aborts if xtask.id is not in common ram.

LAST.DP.PAGE ( -- xaddr )

A 16-bit system variable that is used to enforce a maximum value of the dictionary pointer (DP) page when a new header is created.  This enforcement is enabled only if system variable DP.NOBUMP is OFF (its default state).  Because the default value of LAST.DP.PAGE is 0x3F, which is the top page in the HCS12 memory map, the error check is not effective until a lower value is stored into LAST.DP.PAGE.  To enable error checking, store the maximum allowed dictionary page into LAST.DP.PAGE so that CREATE and XCREATE will abort with an error message if DP is bumped (advanced) past the maximum page.

See also LAST.NP.PAGE

Example of use: After calling DEFAULT.MAP to set up a convenient memory map with dictionary at pages 0-0x0F and names at pages 0x10-0x13, you can enforce the dictionary and names area constraints as follows:

DEFAULT.MAP            \ set up memory map
0x0F LAST.DP.PAGE !         \ enforce DP page boundary
0x13 LAST.NP.PAGE !         \ enforce NP page boundary
DP.NOBUMP OFF  NP.NOBUMP OFF   \ let CREATE advance the pointers

LAST.NP.PAGE ( -- xaddr )

A 16-bit system variable that is used to enforce a maximum value of the names pointer (NP) page when a new header is created.  This enforcement is enabled only if system variable NP.NOBUMP is OFF (its default state).  Because the default value of LAST.NP.PAGE is 0x3F, which is the top page in the HCS12 memory map, the error check is not effective until a lower value is stored into LAST.NP.PAGE.  To enable error checking, store the maximum allowed names page into LAST.NP.PAGE so that CREATE, XCREATE, and (CREATE) will abort with an error message if NP is bumped (advanced) past the maximum page.

See also LAST.DP.PAGE

Example of use: After calling DEFAULT.MAP to set up a convenient memory map with dictionary at pages 0-0x0F and names at pages 0x10-0x13, you can enforce the dictionary and names area constraints as follows:

DEFAULT.MAP            \ set up memory map
0x0F LAST.DP.PAGE !         \ enforce DP page boundary
0x13 LAST.NP.PAGE !         \ enforce NP page boundary
DP.NOBUMP OFF  NP.NOBUMP OFF   \ let CREATE advance the pointers

LAST.SEGMENT ( -- xaddr )

A system variable that holds the segment index of the last valid segment that has been compiled or loaded.  This variable should never be directly modified by the programmer; its value is controlled by the segment management and operating system routines.

LATEST ( -- xnfa )

Returns the extended name field address of the last word defined in the CURRENT vocabulary.

Attributes: U

LCOUNT ( x$addr -- xaddr\count )

Unpacks a long string, returning xaddr = x$addr+2, under a 16-bit count that is fetched from x$addr.  The long string may cross page boundaries.

See also LPARSE and ${

LEAVE ( -- )
Return stack: ( R: w1\w2 -- | discards limit & index )

Forces the immediate termination of a DO…LOOP or DO…+LOOP structure.  Discards the loop control parameters from the return stack and transfers control to the word following LOOP or +LOOP.  An error is issued if LEAVE is used outside a DO…LOOP or DO…+LOOP structure.  LEAVE cannot be used inside a CASE statement which is inside a DO LOOP or DO +LOOP structure.  An unchecked error occurs if extra items are on the return stack when LEAVE executes (for example, items put on the return stack by >R).

Use as:

w1 w2    DO    ...
      flag  IF  LEAVE ENDIF
      ...
   LOOP

See also DO, LOOP and +LOOP

Attributes: C, I

LEFT.PLACES ( -- xaddr )

A 16-bit user variable that holds the number of digits to be displayed to the left of the decimal point when a floating point number is displayed in FIXED format.  The default value is 4.

See also F>FIXED$ and FP.DEFAULTS

Attributes: U

LIB2LIB.CFA.FOR ( <name> -- segment.xhandle\xcfa.offset&segment.index\flag )

Executes BL WORD to parse the next space-delimited word from the input stream, and then searches the dictionary for a match of the parsed word, returning the information needed by COMPILE.LIB2LIB.CALL to compile a handle-relative call to the found word if the word is defined in a different library than the library that is now compiling.  If a definition that includes the LOCALS{ statement is compiling, FIND.LIB2LIB first searches the VLOCALS vocabulary for a match to <name>. If no match is found, it searches the CONTEXT vocabulary.  Then, if the word is not found and if the CONTEXT and CURRENT vocabularies are different, it searches the CURRENT vocabulary.  Aborts if <name> is not found.  LIB2LIB.CFA.FOR leaves the word's segment.xhandle under its code field address offset under its code page offset (in the least significant byte) augmented by the segment index (in the most significant byte) under a flag on the stack.  If the word is in the kernel or the currently compiling segment (as indicated by THIS.SEGMENT), then the returned segment.xhandle is 0\0. For non-kernel non-local segments, the segment.xhandle is obtained by searching the current segment’s required.segment table for a match to the segment.index stored in the found word’s header, and returning the xaddress of the matching table entry.  This routine aborts if a matching segment entry is not found in required.segment table.  The code address- and page-offsets and the segment index are fetched directly from the found word’s header.  Note that the returned code field address parameters are offsets that must be added to the segment xbase.addr which is stored in the eeprom segment table indexed by the returned segment index.  A COLD restart will occur if more than 255 page changes are made during the search through either vocabulary.  This prevents the interpreter from going on an infinite search through a corrupted dictionary.  A COLD restart will also occur if POCKET is not in common memory.

See also FIND.LIB2LIB
Pronunciation: lib-to-lib-c-f-a-for

LIBRARY ( <name> -- )

Defines a new relocatable library segment.  The kernel supports relocatable code organized as program segments. Device drivers for Wildcards, Graphical User Interface Tools, and other software are distributed as pre-compiled segments that are accessible using Forth or C.  The two types of segments are libraries and applications.  A library is fully relocatable as long as it does not cross a page boundary.  Libraries that are longer than a page, and Application segments, can be relocated from page to parallel page.  The variables and EEPROM variables accessed by a library are offset-based, and can change based on the value of VP and EEP when the library is loaded.  The variables and EEPROM variables compiled into an application segment, on the other hand, have their addresses fixed at the time of compilation.  An library segment can be relocated to a parallel set of pages using RELOCATE: or RELOCATE.ONLY: (consult their glossary entries for details), or by storing the desired minimum starting address and page into DP and downloading the installer file to the board (see COMPOSE.FORTH.INSTALLER and COMPOSE.FORTH.INSTALLER.FOR).  This LIBRARY routine creates a non-executable full-width segment header <name>. Initializes system variables LIBRARY.IS.COMPILING (to true), THIS.SEGMENT.XBASE (to HERE), and THIS.SEGMENT.XNFA (points to the xnfa of <name>).  Assigns the next available segment index by incrementing the contents of LAST.SEGMENT, then stores the incremented value in THIS.SEGMENT.  Writes the 3-byte segment base xaddress (= HERE), 3-byte segment xnfa (points to <name>), 2-byte variable base address (= VHERE), and 2-byte EEPROM base address (= EEHERE) into the EEPROM segment table entry for the specified segment index.  ALLOTs the segment structure in the dictionary area.  The segment structure contains fields specifying the memory usage of the segment including the starting VP, variable area size, starting EEP, EEPROM area size, total segment size, starting compilation address, as well as a code area checksum and the required segment table.  Some of these fields are set by this function, while others are set by END.SEGMENT, REQUIRES.FIXED, or REQUIRES.RELATIVE.  Defining a new library or application also performs the ANEW action, which simplifies reloading and enforces the uniqueness of each segment name.  That is, this routine tries to FIND <name> and, if it already exists and is a segment header, FORGETs it and resets VP and EEP before re-defining <name>. This routine creates <name> using the maximum WIDTH (to assure clean segment dumping and loading) and modifies <name>’s header.type byte, setting the in.lib.mask bit and the segment.mask bit.  This routine zeros the 3-byte xcfa.offset field in <name>’s header to indicate that segment is compiling; this field is set by END.SEGMENT to contain the offset from the <name> xnfa to the xnfa of the last header defined in segment.  When a segment is forgotten, its EEPROM array entry is erased and LAST.SEGMENT is decremented; see FORGET.

WARNINGS: There is no executable code associated with the segment header, so it is illegal to execute a <name>, and CFA.FOR and ' (i.e., tick) do not work with the segment header.  Rather, <name> should should only be used as an argument to segment management routines such as LOAD.SEGMENT, COMPOSE.C.HEADERS.FOR, and BUILD.APPLICATION.  This routine aborts if too many segments have been declared (24 is the maximum, including the kernel which is segment 0).  Attempting to reload a segment whose definition is still in memory does not result in non-unique warnings; rather, it produces the aborting error message: Memory write failed during segment loading; try reloading all libraries. If this happens, do a COLD restart and reload the code.

Attributes: D

LIBRARY.IS.COMPILING ( -- xaddr )

A 16-bit system variable that holds a true flag is a library segment is compiling or loading; otherwise it holds a false flag.

See also LIBRARY

LINK ( xnfa1\xnfa2 -- )

Sets the link field in the name of the word referenced by name field address xnfa2 to point to the name referenced by xnfa1. In other words, it changes the way that backward-linked name list or vocabulary is searched so that the name associated with xnfa1 is encountered just after the name associated with xnfa2 (see FIND).  Because all names in the FORTH vocabulary are also linked via the hash table and hash links, this routine also adjusts all of the affected hash links and rebuilds the hash table if xnfa1 and xnfa2 are in the FORTH vocabulary.  LINK aborts if xnfa1 = xnfa2 and CURRENT points to the Forth vocabulary, as this would not only take away access to the kernel words, but would also corrupt the hash.  LINK can be used to exclude from the final names list a set of words that are needed during compilation.  The words to be excluded can be placed in a separate names area (say, on a separate page of RAM), and LINK can be used to link around (exclude) the names in the final published version.

LINK.HASH ( xnfa1\xnfa2 -- )

Sets the hash link field of xnfa2 to point to xnfa1. This low level utility is typically not used by the programmer.

LITERAL ( -- w )

Compile Time: ( w – )

If QED-Forth is in execution mode when LITERAL is invoked, LITERAL does nothing.  If QED-Forth is in compilation mode, LITERAL removes w from the stack and compiles it into the dictionary along with code that, when later executed, pushes w to the stack.  LITERAL can be used within a colon definition to compile a numeric value into the definition.  For example,

: <name>    ( -- n )
   [ CHARS/LINE @ ] LITERAL
;

This compiles as a literal the value of CHARS/LINE that exists when the definition is compiled.  When <name> is later executed, this value will be placed on the stack.

Attributes: I

LN(2) ( -- r )

Places the floating point representation of the natural logarithm of 2 (0.69314) on the stack.
Pronunciation: l-n-of-two

LOAD.APPLICATION ( xaddr\d1\u1\u2 <name> -- )

Creates the segment.header for the previously compiled application <name> and allots and initializes the segment structure at the specified code base xaddr to load it.

• d1 specifies the number of code bytes in the application segment,
• u1 specifies the number of variable area bytes, and
• u2 specifies the number of EEPROM area bytes.

This command is automatically generated by BUILD.APPLICATION and BUILD.SEGMENTS. 

When this command executes, the RECEIVE.HEX command has already initialized the code area including the segment structure.  If the specified segment base xaddr is in RAM, this routine writes over the segment structure to update it.  If the segment base xaddr is in flash, this routine writes into a segment struct buffer and then calls TO.FLASH to transfer the first part of the buffer (containing location-dependent values) to on-chip flash.  The remaining bytes of the segment structure are set by the REQUIRES statements, and an error is issued if we're loading to flash and the required segment indices don't match the values in the receive.hex dump; the error message is: Memory write failed during segment loading! Try reloading all libraries. Depending on the place parameter passed to COMPOSE.FORTH.INSTALLER, applications may reload IN.PLACE, TO.HERE, or with a USER.SPECIFIED load address. (See RELOCATE: and RELOCATE.ONLY: to move an application before calling BUILD.APPLICATION).

The code area dump as stored by RECEIVE.HEX must correspond to the declared code.xbase and code size; this is assured if the segment was dumped using BUILD.APPLICATION.  When loading a segment that was dumped using the TO.HERE mode, the dictionary pointer DP must be set to the appropriate starting xaddress before the installer file containing the LOAD.APPLIATION command is downloaded to the board.

If the declared code.xbase = HERE, then DP is advanced by the specified d.code.numbytes (recall that receiving an s-record of the code area does not modify DP).  For any other value of code.xbase, the DP is left unchanged, as this routine assumes you are trying to locate the application elsewhere in memory without using DP.  Starting at the current VP, EEP and NP, VP is advanced by u1 bytes, EEP is advanced by u2 bytes, and NP is advanced as <name> and subsequent public headers are declared.

Aborts if the 16-bit load-time starting addr does not equal the 16-bit compile-time starting address (an application segment must load at the same 16-bit address at which it compiled).  Note that loading a segment performs the ANEW <name> action to simplify reloading of source code.

See also RELOCATE:, RELOCATE.ONLY:, BUILD.APPLICATION, and BUILD.SEGMENTS

LOAD.LIBRARY ( xaddr\d1\u1\u2 <name> -- )

Creates the segment header for the previously compiled library <name> and allots and initializes the segment structure at the specified code base xaddr to load it.  d1 specifies the number of code bytes in the library, u1 specifies the number of variable area bytes, and u2 specifies the number of EEPROM area bytes.  This command is automatically generated by BUILD.LIBRARY and BUILD.SEGMENTS.  When this command executes, the RECEIVE.HEX command has already initialized the code area including the segment structure.  If the specified segment base xaddr is in RAM, this routine writes over the segment structure to update it.  If the segment base xaddr is in flash, this routine writes into a segment struct buffer and then calls TO.FLASH to transfer the first part of the buffer (containing location-dependent values) to on-chip flash.  The remaining bytes of the segment structure are set by the REQUIRES statements, and an error is issued if we're loading to flash and the required segment indices don't match the values in the RECEIVE.HEX dump; the error message is: Memory write failed during segment loading! Try reloading all libraries. The LOAD.LIBRARY command allows the caller to specify where code is; however, the code area dump as stored by RECEIVE.HEX must correspond to the declared code.xbase and code size; this is assured if the segment was dumped using BUILD.LIBRARY.  If the declared code.xbase = HERE, then the DP is advanced by the specified d.code.numbytes (recall that receiving an S-record of the code area does not modify DP).  For any other value of code.xbase, the DP is left unchanged, as this routine assumes you are trying to locate the library elsewhere in memory without using DP.  Starting at the current VP, EEP and NP, VP is advanced by u1 bytes, EEP is advanced by u2 bytes, and NP is advanced as <name> and subsequent public headers are declared.  Aborts if the library crosses a page boundary and the 16-bit load-time starting addr does not equal the 16-bit compile-time starting address (a multi-page library must load at the same 16-bit address at which it compiled).  Note that loading a library performs the ANEW <name> action to simplify the reloading of source code.

LOAD.MATRIX ( xpfa <text> -- | expects numbers in input stream )

Repeatedly calls NEXT.NUMBER to get as many numbers as needed to fill the matrix specified by xpfa.  The first row is filled first (starting at the left, i.e., at the first column), then the next row, etc.  Carriage returns and tabs can be used to format the numbers if desired.  The numbers can be valid integers or floating point numbers; NEXT.WORD automatically converts the integers to their floating point equivalents using FLOT.  Non-numeric text in the input is ignored until the matrix is filled, but be careful: any valid number encountered by LOAD.MATRIX will be converted and placed in the matrix, even if it is within parentheses or after a comment delimiter such as \ . Integers are converted according to the current number base.

See also MATRIX

Use as:

MATRIX: MAT.A 2 3 ' MAT.A DIMMED \ def & dimension

' MAT.A LOAD.MATRIX 99 3 4.2 5.3 8 3 \ init matrix

Attributes: M, S

LOAD.PAGE ( page1\page2 -- | page1 = src.flash.page; page2 = dest.ram.page )

Loads the 16 Kbyte contents of external flash memory from page1 into RAM memory at page2. No error checking is performed.  This routine can be used to read external flash pages 0x1E and 0x1F which have no parallel RAM pages.  To allow an effective load to RAM, the destination RAM pages must not be write protected.

See also WRITE.ENABLE and LOAD.PAGES

CAUTION: This routine disables interrupts for over half a millisecond during the read of each 1 Kbyte block from the external flash, corresponding to nearly 10 msec total disabled time.  Be sure to schedule the use of this routine so that it does not interfere with any interrupt-based runtime procedures.

LOAD.PAGES ( page1\n -- | page1 = starting.page; n = number of pages )

For the specified n-page range starting at page1, loads from each (virtual) page in external flash to the parallel page in external RAM.  All referenced pages must be in the range 00-0x1D; pages outside this range are ignored.  Pages 0x1E and 0x1F of RAM are not implemented in the memory map, and pages starting at 0x20 correspond to the on-chip flash on HCS12 processors with 512K of flash.  To simplify the load to RAM, the destination RAM pages are automatically write enabled before the load, and then the prior write protection status is restored after the load.

See also WRITE.ENABLE and LOAD.PAGES.AT.STARTUP

Example of use: To program all of the ram pages accessible by this routine, execute:

0  0x1E  LOAD.PAGES

Memory map summary:

XFlash Pages      RAM Pages         DEFAULT.MAP
@addr=0-3FFF   @addr=8000-BFFF   Typical Use; and write-protect (WP) area ID

   00-0F          00-0F       Typically code (DP);    WP region 1
   10-13          10-13       Typically names (NP);   WP region 2
   14-1D          14-1D       Always RAM,             not write-protectable
   1E-1F          --          RAM pages 1E, 1F are not implemented.

CAUTION: This routine disables interrupts for over half a millisecond during the read of each 1 Kbyte block from the external flash, corresponding to nearly 10 msec total disabled time per page.  Be sure to schedule the use of this routine so that it does not interfere with any interrupt-based runtime procedures.

LOAD.PAGES.AT.STARTUP ( page1\n1\n2 -- | page1= starting.page; n1= # pages; n2= area.id )

Stores a sequence into reserved system EEPROM that causes the specified n1 pages starting at page1 to be loaded from external flash to the parallel pages in RAM upon subsequent COLD restarts.  The n2 area.id can be 1, 2 or 3. Any valid set of RAM pages can be assigned to any of the 3 valid area.id’s.  This scheme allows flexibility in determining which pages are restored from the shadow flash to RAM upon each COLD powerup or restart.  At the time of the restart, COLD write-enables the affected RAM pages, invokes the LOAD.PAGES function to perform the memory load operation, and then establishes any write-protection that was configured using the WRITE.PROTECT function.  To undo the effect of this command for a given area.id, specify a valid starting page with n1 (#pages) equal to 0 for the specified area.id.  A factory cleanup clears all three area.id’s so that no pages are loaded.  All referenced pages must be in the range 00-0x1D; pages outside this range are ignored.  Pages 0x1E and 0x1F of RAM are not implemented in the memory map, and pages starting at 0x20 correspond to the on-chip flash on HCS12 processors with 512K of flash.

See also LOAD.PAGES

Memory map summary:

XFlash Pages      RAM Pages                DEFAULT.MAP
@addr=0-3FFF   @addr=8000-BFFF   Typical Use; and write-protect (WP) area ID

  00-0F            00-0F        Typically code (DP);  WP region 1
  10-13            10-13        Typically names (NP); WP region 2
  14-1D            14-1D        Always RAM;           not write-protectable
  1E-1F              --         RAM pages 1E, 1F are not implemented.

Example of use: Assume that a program has code on pages 0 through 3, and names on pages 0x10 through 0x11, and a PRIORITY.AUTOSTART vector has been installed at the top of page 0x0F.  After the program has been loaded (compiled) into RAM on the board, we can save it to the shadow external flash using these commands:

0     4  STORE.PAGES   \ store code pages 0-3 in shadow flash
0x10  2  STORE.PAGES   \ store names pages 10-11 in shadow flash
\ PRIORITY.AUTOSTART already wrote to flash; no need to store page F

We also want to write protect area 1 (pages 0-0xF containing the code) and area 2 (pages 0x10-0x13 containing the names) as follows:

1 WRITE.PROTECT      \ protect pages 0-0xF
2 WRITE.PROTECT      \ protect pages 0x10-0x13

Recall that the shadow flash is not directly readable by the processor as program memory, so we must transfer the needed pages from external flash to RAM at startup.  The following commands accomplish this:

0     4  1 LOAD.PAGES.AT.STARTUP   \ load code pages 0-3 to RAM
0x10  2  2 LOAD.PAGES.AT.STARTUP   \ load names pages 0x10-11 to RAM
0xF   1  3 LOAD.PAGES.AT.STARTUP   \ load page containing priority autostart

CAUTION: This routine disables interrupts while programming the EEPROM; See the (EE!) glossary entry for details.  Be sure to schedule the use of this routine so that it does not interfere with any interrupt-based runtime procedures.

LOCALS{ ( [...] -- | items are removed to initialize the local variables )
Return stack: ( R: -- [...] | stack frame is placed on return stack,removed by ; )

Used within a colon definition to begin a command sequence that defines from 1 to 16 local variables.  The syntax of the simplest type of local statement is:

LOCALS{ <name.1> <name.2>... <name.n> }

The names between LOCALS{ and the terminating } are given temporary headers that remain effective for the duration of the current definition.  If the first 2 characters in the name of a local are d& or D& (suggesting a 32-bit double number value) or f& or F& (suggesting a 32-bit floating point value) or x& or X& (suggesting a 32-bit extended address) then the local is defined as a 32-bit quantity.  All other local variables are defined as 16-bit quantities.  At runtime (when the definition containing the LOCALS{ command is executed) the code compiled by LOCALS{ initializes the values of each of the named local variables to a corresponding item on the data stack.  The top item is removed from the data stack and loaded into <name.1>, the next item on the data stack is removed and loaded into <name.2>, etc.  A single cell is removed from the stack for each 16-bit local, and two cells are removed from the stack for each 32-bit local.  Each local variable behaves just like a self-fetching variable.  When executed, the local leaves its value on the stack.  Its value can be initialized or modified by placing the desired value on the stack and invoking the TO operator followed by the name of the local variable.

An alternative syntax for the locals declaration is:

LOCALS{ <name.1> <name.2> ... | <name.a> <name.b> ... }

where the locals defined between LOCALS{ and the | (bar) are initialized to the values on the data stack as explained above, and the locals defined between the | and the terminating } are left uninitialized.  If certain local variables are to be initialized by a TO statement later in the definition, it is better to define them as uninitialized locals to save execution time.  If none of the locals need to be initialized, the syntax:

LOCALS{  | <name.a> <name.b> ... }

is acceptable.  Locals can be used in recursive definitions; each execution of the word allocates a new frame on the return stack where the values of the locals are kept.

Usage rules: The locals command sequence,

LOCALS{ ... | ... }

may occupy multiple lines in the source code; however, no comments may appear between LOCALS{ and }. To avoid problems with non-uniquely named local variables the convention of using names beginning with & is recommended.  Only one

LOCALS{ ... | ... }

command sequence is allowed per definition and within the declaration only one | is allowed.  The LOCALS{ declaration must not be inside a conditional structure such as an IF … ELSE … ENDIF structure.  The number of local variables defined must be greater than 0 and less than or equal to 16. The local variable names defined in the body of a word are forgotten after the definition is finished.  Colon definitions using locals should not call CREATE or other defining words and should not manipulate CURRENT.
Pronunciation: locals-start
Attributes: C, D, I

LOG10(2) ( -- r )

Pushes the base-10 logarithm of 2 onto the data stack.
Pronunciation: log-ten-of-two

LOG2 ( u -- n )

n is the integer part of the base 2 logarithm of u.
Pronunciation: log-two

LONG.LINE.MSG ( -- xaddr )

A user variable that contains a 16-bit flag.  If the flag is true (the default condition), BEEP is executed and a warning message is printed each time a line is received by the interpreter that includes CHARS/LINE characters without being terminated by a carriage return.  If the flag is false, no warning is issued a too-long line is received by the Forth interpreter.  In response to this warning, the programmer can shorten the offending line in the source program to avoid compilation errors that can happen when undetected lines of excessive length are interpreted.

LONG.SIZE ( -- n )

Returns the constant value 4 which is the number of bytes in a parameter of type long that is passed to or returned by a C-callable function.  This size specifier is used in the PARAMS( statement that describes the input and output parameters of a C-callable function.

See also PARAMS(

LOOP ( -- )

Return Stack: ( R: w1\w2 – [w1\w2] or [] | drops w1,w2 when loop terminates )

LOOP increments the loop index on the return stack by one. If the index then equals the loop limit, the loop parameters are removed from the return stack and execution continues at the word following LOOP. Otherwise, execution continues at the word following DO. See DO for examples.

Use as:

w1 w2    DO    words to be executed (w1 - w2) times
   LOOP

An error is issued if DO and LOOP are not paired within a definition.

See also DO  +LOOP  I  J  I'  K  LEAVE

Attributes: C, I

LPARSE ( xhandle\ u1\n1\n2 -- x$addr | u1=max#chars, n1= EOL sequence, n2 = delimiter )

Parses one or more lines from the input stream, terminating when either the specified max#chars u1 have been parsed, or when the 1- or 2-byte delimiter n2 has been encountered in the input stream.  If the most significant byte of n1 is zero, n1 is treated as a 1-byte delimiter; otherwise, n1 is treated as a 2-byte delimiter.  If the delimiter is a space, then the end of the input line is also treated as a valid delimiter.  Leading spaces are not skipped.  LPARSE moves the parsed characters from the TIB to the memory area pointed to by the xhandle; after parsing, this pointer is updated to point to the byte after the string (i.e., the byte after the terminating null).  Each time the input line is parsed without encountering the specified delimiter, LPARSE emplaces the specified 1- or 2-byte EOL (end-of-line) sequence n1 into the string and executes QUERY to acquire the next input line.  However, if the specified EOL parameter is -1, then no extra characters are emplaced at the end of each line; this allows definition of long strings without extra embedded CR or LF or BL chars.  LPARSE returns the xaddr of the packed long-string comprising a 2-byte count followed by the parsed string, followed by the null character (not included in the count).  x$addr is equal to the original 32-bit contents of the xhandle input parameter, and LPARSE increments the contents of xhandle by the total size of the parsed string in memory (= parsed_count + 3 bytes) using XU+. Typically, the xhandle is DP (to emplace the long string in the dictionary area) or NP (to emplace the long string in the names area).  If DP is the specified xhandle, then the automatic increment of its contents is equivalent to ALLOTing space for the parsed string in the code space, which is parallel to the action of ,” for standard byte-counted strings.  The input stream is the terminal input buffer TIB, and the contents of >IN specify the offset from the start of the input stream to the first character to be parsed.  Parsing starts after the required space that follows LPARSE (or the routine that calls LPARSE).  This routine leaves >IN pointing 1 byte past the terminating delimiter.  NOTE: If parsing has been terminated by reaching the specified max#chars limit u1, then the remainder of the input line on which the termination occurred will not be interpreted by the compiler; these remaining characters are effectively removed from the input stream.  The maximum allowed number of characters to be parsed is 65533 = 0xFFFD; this ensures that the maximum size of the parsed string plus its 2-byte count can be represented as a 16-bit value.  The stored output string can cross page boundaries.  Note that, for strings containing 255 characters or fewer, you can simply add 1 to the output x$addr using 1XN+ if you want to treat the string as a standard byte-counted string.  To unpack a long string, use LCOUNT.

See also ${
Pronunciation: parse-l-string
Attributes: M

LTYPE ( xaddr\u -- )

Types a long string.  If u is greater than zero, emits u characters beginning at location xaddr.  xaddr is typically the beginning of a long string created by LPARSE or ${ and u is the long string's character count.  The string may cross page boundaries.  This routine calls PAUSE.ON.KEY every 128 characters.

See also TYPE
Pronuciation: l-type
Attributes: M

M* ( n1\n2 -- d )

Multiplies signed single precision integers n1 and n2, producing the signed double precision product d.
Pronunciation: m-star

M. ( matrix.xpfa -- )

Prints the contents of the matrix specified by matrix.xpfa using the default printing format (FIXED, FLOATING, or SCIENTIFIC).  The print is performed with FILL.FIELD ON so that tabular format (constant field width, decimal alignment) is maintained.  Printed elements are delimited with spaces and with carriage returns and continuance marks (…).  Output line length is limited to 6 characters less than the contents of the user variable CHARS/LINE.  M. calls the word PAUSE.ON.KEY, so the print responds to XON/XOFF handshaking and can be aborted by typing a carriage return; see PAUSE.ON.KEY.
Pronunciation: m-dot
Attributes: M, S

M.. ( matrix.xpfa -- )

Prints the name of the matrix specified by matrix.xpfa followed by a display of its contents as performed by M.

See also M.
Pronunciation: m-dot-dot
Attributes: M, S

M.PARTIAL ( low.row#\high.row#\low.col#\high.col#\matrix.xpfa -- )

Prints a portion of the matrix specified by low.row# through high.row#, inclusive and low.col# through high.col#, inclusive, using the default print format (FIXED, FLOATING, or SCIENTIFIC).  The print is performed with FILL.FIELD ON so that tabular format (constant field width, decimal alignment) is maintained.  Printed elements are delimited with spaces and with carriage returns and continuance marks (…).  Output line length is limited to 6 characters less than the contents of the user variable CHARS/LINE.

Typical use: Assume that MAT.A is dimensioned to have 8 rows and 9 columns.  The following command prints the last 5 elements in each of the first 3 rows:

0 2  4 8  ' MAT.A   M.PARTIAL

M.PARTIAL calls the word PAUSE.ON.KEY, so the print responds to XON/XOFF handshaking and can be aborted by typing a carriage return.
Pronunciation: m-dot-partial
Attributes: M, S

M/MOD ( d1\n1 -- n2\d2 | n2 = remainder, d2 = quotient )

Divides double number d1 by integer n1 giving integer remainder n2 and double number quotient d2. Uses signed math.  Division by zero (n1 = 0) yields n2 = 0xFFFF and d2 = 0xFFFFFFFF.
Pronunciation: m-slash-mod

MAILBOX: ( <name> -- )

Removes the next <name> from the input stream, defines a child word called <name>, and VALLOTs 2 cells in the variable area.  When <name> is executed, it leaves the extended address xaddr of the reserved cells that hold the mailbox's contents. <name> is referred to as a mailbox. Use as:

MAILBOX: <name>

Mailboxes are used in multitasked systems to share information between tasks and to synchronize tasks to one another.  If the mailbox's contents equal 0\0, the mailbox is empty; it contains a message if its contents are non-zero.  Before its first use, the mailbox must be initialized to 0\0. After initialization to 0\0, the only operators that should access the mailbox are SEND ?SEND RECEIVE and ?RECEIVE.

Attributes: D

MAKE.HEADER ( width\segment\fn&header.type\cfa.os\cfa.page.os\#input\input.bitfield <name> -- )

A low-level primitive that creates a header for <name> with the specified parameters.  This command is generated by the library and segment BUILD and COMPOSE.FORTH.INSTALLER routines to build a library or application installation file.  The top two parameters on the stack are ignored if the header is not c-callable as indicated by the header.type input.

Attributes: D

MANTISSA.PLACES ( -- xaddr )

A 16-bit user variable that holds the number of digits to be displayed in the mantissa when a floating point number is displayed in SCIENTIFIC format.  The default value is 4.

See also F>FLOATING$ and FP.DEFAULTS

Attributes: U

MASTER2 ( -- flag )

Leaves a true (-1) flag on the stack if jumper cap is installed on the SPI #2 jumper of the PDQ Board, indicating that this board is master of SPI2, and a slave on SPI1. If the jumper cap is not installed, returns a false flag, indicating that this board is master of SPI1 and a slave on SPI2. This low-level utility is typically not used by the end programmer.

MATRIX ( <text> -- | expects name and numbers in input stream )

Expects the first word in the input stream following MATRIX to be the name of a dimensioned matrix.  Skips the word following the matrix name (typically =) and then repeatedly calls NEXT.NUMBER to get as many numbers as needed to fill the matrix.  The first row is filled first (starting at the left, i.e., at the first column), then the next row, etc.  Carriage returns and tabs can be used to format the numbers if desired.  The numbers can be valid integers or floating point numbers; NEXT.WORD automatically converts the integers to their floating point equivalents using FLOT.  Non-numeric text in the input is ignored until the matrix is filled, but be careful: any valid number encountered by MATRIX will be converted and placed in the matrix, even if it is within parentheses or after a comment delimiter such as \ . Integers are converted according to the current number base.

See also LOAD.MATRIX

Use as:

MATRIX: MAT.A    2 3 ' MAT.A DIMMED   \ define and dimension
MATRIX MAT.A  =  99  3  4.2  5.3  8   \ initialize matrix

Attributes: M, S

MATRIX.PF ( -- u | u = size of a matrix parameter field )

Places on the stack the number of bytes in a matrix parameter field (u = 14 bytes).  Typically used to define a stack-based temporary matrix within a definition; temporary matrices defined in this manner preserve re-entrancy (See the Manual).  For example:

: MATRIX.FUNCTION
   LOCALS{ .... | x&temp.matrix.pfa }
   MATRIX.PF PF.STACK.FRAME   TO  x&temp.matrix.pfa
   3 4 x&temp.matrix.pfa DIMMED   \ dimension as 3X4
   ....         \ use the temp matri
x   x&temp.matrix.pfa DELETED      \ delete from heap
   MATRIX.PF FRAME.DROP      \ drop temp pf off stack
;

See ARRAY.PF, PF.STACK.FRAME and FRAME.DROP.
Pronunciation: matrix-p-f

MATRIX: ( <name> -- )

Removes <name> from input stream and defines <name> as a matrix.  VALLOTs and clears a parameter field for <name> in the variable area; the size of the parameter field is MATRIX.PF bytes.  When executed, <name> returns the extended element address given the indices; its stack picture is:

( row#\col# -- xaddr )

The element address is also returned by the command

row# col# ' <name> M[]

MATRIX: does not allocate heap space; see DIMMED.
Pronunciation: matrix-colon
Attributes: D

MAX ( n1\n2 -- [n1] or [n2] )

Retains the greater of the two signed integers n1 and n2, and drops the other.  Also see UMAX.

MEMBER-> ( u1\u2 <name> -- u3 )

Adds a named member to the structure being defined and reserves room for u2 bytes in the structure.  Removes <name> from the input stream and creates a structure field called <name>. u1 is the structure offset initialized by STRUCTURE.BEGIN:. u3 is the updated offset to be used by the next member defining word or by STRUCTURE.END.  When <name> is later executed, it adds its offset u1 to the extended address found on the data stack which is typically the start xaddress of an instance of the data structure; the result is the xaddress of the desired member in the structure.
Pronunciation: member
Attributes: D

MICROSEC.DELAY ( u -- )

Enters a software timing loop for u microseconds.  This routine can time to a 1 microsecond resolution with an overhead of under 1 microsecond.  Note that the elapsed time will be increased by the duration of any interrupt routines that are serviced while MICROSEC.DELAY is running.  Consequently, this routine does not guarantee accurate timing when the timesliced multitasker is running.
Pronunciation: microsecond-delay

MIN ( n1\n2 -- [n1] or [n2] )

Retains the lesser of two signed integers n1 and n2, and drops the other.

See also UMIN

MOD ( n1\n2 -- n3 | n3 = remainder of n1/n2 )

Divides n1 by n2, giving the remainder n3. The sign of n3 is the same as that of n1. If n2 is zero the result is indeterminant.

See also UMOD

MOD.COUNTER.LOAD ( u -- )

Writes the value u to the MCCNT modulus down-counter count register associated with the Enhanced Capture Timer (ECT) system.  If the modulus down counter has been enabled by passing a true enable flag to MOD.COUNTER.SETUP (that is, if the MODMC bit in the MCCTL register is set), then the write of the value u is automaticaly directed by the hardware to the load counter associated with the 16-bit modulus down counter (as opposed to the modulus counter itself).  To force an immediate write of the counter, execute this routine, then call MOD.COUNTER.UPDATE.  If the input parameter u equals 0, the modulus counter will remain at 0 without setting the modulus underflow flag (MCZF in MCFLG).  If the holding and latch_mode flags passed to IC.PULSE.CONFIG are both true (that is, if the LATQ and BUFEN bits in the ICSYS register are set), the input capture and pulse accumulator registers will be latched when the modulus counter count equals zero.

MOD.COUNTER.READ ( -- u )

Reads the 16-bit modulus down counter and returns its value.  The modulus counter is associated with the Enhanced Capture Timer (ECT) system.  If the read_load_val flag passed to MOD.COUNTER.SETUP was false (that is, if the RDMCL bit in the MCCTL register = 0), then this routine returns the present value of the modulus down counter; otherwise, this routine returns the contents of the modulus counter load register.

MOD.COUNTER.SETUP ( underflow_irq\modulus_mode\read_load_val\enable\scaler -- )

Writes to the MCCTL register to configure the modulus down counter according to the five integer input parameters which have been given names in the stack picture for convenience.  The modulus counter is associated with the Enhanced Capture Timer (ECT) system.  Allowed values for the scaler parameter are 1,4, 8 or 16; the modulus down-counter is clocked at 20 MHz (the E-clock frequency) divided by the specified scaler.  The enable flag parameter enables the modulus down counter if true, and disables it if false.  If true, the read_load_val flag parameter configures MOD.COUNTER.READ to return the contents of the modulus load counter; if read_load_val is false, MOD.COUNTER.READ returns the down counter contents.  A true modulus_mode flag means that when the counter reaches 0 it is loaded with the latest value written by MOD.COUNTER.LOAD; if modulus_mode is false, the counter counts down once and stops at 0x0000. If true, the underflow_irq flag enables an interrupt whenever the modulus counter equals 0. After a power-up or hardware reset, the default condition is all flags false and the scaler equal to 1 (this corresponds to the MCCTL register = 0).

MOD.COUNTER.UPDATE ( -- )

To force an immediate write of the modulus down counter, execute MOD.COUNTER.LOAD, then invoke this MOD.COUNTER.UPDATE routine.  The modulus counter is associated with the Enhanced Capture Timer (ECT) system; see MOD.COUNTER.SETUP.

Implementation detail: sets the FLMC bit in the MCCTL register.

MODULUS.UNDERFLOW ( -- n )

A constant that identifies the interrupt flag associated with the modulus down-counter underflow condition (that is, when the counter reaches 0).  This constant can be passed to ECT.INTERRUPT.ENABLE (to enable an interrupt when the modulus counter underflows), ECT.INTERRUPT.DISABLE (to disable interrupt generation when the modulus counter underflows) or ECT.CLEAR.INTERRUPT.FLAG (to clear the flag bit associated with the modulus counter underflow).  The modulus counter is associated with the Enhanced Capture Timer (ECT) system; see MOD.COUNTER.SETUP.

MOVE ( xaddr1\xaddr2\u -- | xaddr1=src, xaddr2=dest, u = count )

If u is greater than 0, copies u consecutive 16-bit cells (i.e., 2*u consecutive bytes) from addresses starting at xaddr1 to addresses starting at xaddr2. The source and destination extended addresses may be located on different pages and the move may cross page boundaries.  If the source and destination regions overlap and xaddr1 < xaddr2, MOVE starts at high memory and moves toward low memory to avoid propagation of the moved contents.  MOVE always moves the contents in such a way as to avoid memory propagation, except that attempts to perform an overlapping-region copy to or from the kernel flash starting at the precise address 0xC000 may result in propagation.  Speed is approximately 4.6 microseconds per cell.

See also MOVE.MANY

MOVE.HEADERS ( dest.page <first.name.to.be.moved> -- )

Moves all headers from <first.name.to.be.moved> through LATEST (inclusive) to the memory region starting on the specified dest.page.  Each header is moved to a parallel location on the new page (that is, only its page, not its 16-bit address, is changed).  The page of <first.name.to.be.moved> must be less than or equal to the page of LATEST, and LATEST must be the last xnfa on the current names page.  That is, the source region of the move must be a monotonically increasing names area.  MOVE.HEADERS calls FIND to locate <first.name.to.be.moved> in the CURRENT vocabulary, and aborts if it is not found.  For each header to be moved, both the standard (chronological) and hash links are checked and updated if necessary.  If a segment header is encountered, the segment.xnfa field in that segment’s EEPROM segment array is updated to point to the new page.  MOVE.HEADERS then calls CMOVE or TO.FLASH to copy the headers to the destination region, then updates LATEST.  MOVE.HEADERS checks whether the contents of SECTION$.XADDR point into the name region being moved, and if so, offsets the page offset of the system variable to point to the new location in the relocated header list.

Restrictions on use: Do not execute this immediately after a PROTOTYPE: VPROTOTYPE: EEPROTOTYPE: or DATE/TIME: statement, as the associated string would then be in the names area after LATEST, and would not be moved to the new location.  In this situation, create a dummy name after the last PROTOTYPE: has been defined before calling MOVE.HEADERS.  Make sure that the destination page region occupies a single type of valid writeable memory, either RAM or onchip flash, never both.  If this routine aborts with an error message, all code should be reloaded, as the segment control system variables and structures may be corrupted.  MOVE.HEADERS is not compatible with non-Forth vocabularies defined using VOCABULARY.  If you need to move the headers of a library or application segment, use the default Forth vocabulary for all definitions.

MOVE.IN.PAGE ( addr1\addr2\u\page -- | addr1=src, addr2=dest, u = count )

If u is greater than 0, copies u consecutive 16-bit cells (i.e., 2*u consecutive bytes) starting at addr1 to the destination addresses starting at addr2 on the specified page.  If the source and destination regions overlap and addr1 < addr2, MOVE.IN.PAGE starts at high memory and moves toward low memory to avoid propagation of the moved contents.  MOVE.IN.PAGE always moves the contents in such a way as to avoid memory propagation.  Speed is approximately 0.4 microseconds per cell.
Pronunciation: move-in-page

MOVE.MANY ( xaddr1\xaddr2\d -- | xaddr1=src, xaddr2=dest, d = count )

If 32-bit count d is greater than 0, copies d consecutive 16-bit cells (i.e., 2*d consecutive bytes) from addresses starting at xaddr1 to addresses starting at xaddr2. The source and destination extended addresses may be located on different pages and the move may cross page boundaries.  If the source and destination regions overlap and xaddr1 < xaddr2, MOVE.MANY starts at high memory and moves toward low memory to avoid propagation of the moved contents.  MOVE.MANY always moves the contents in such a way as to avoid memory propagation, except that attempts to perform an overlapping-region copy to or from the kernel flash starting at the precise address 0xC000 may result in propagation.  Speed is approximately 4.6 microseconds per cell.

MOVE.SEGMENT.TO.DEST.PAGE ( segment\dest.page -- )

A primitive called by RELOCATE.ONLY: and RELOCATE:. Moves the code associated with specified segment index from its current page to the parallel address starting at the specified destination page.  Updates the cfa.page stored in the segment’s entry in the EEPROM segment array.  Dest.page can be in RAM or on-chip flash.  Aborts with error if on-chip flash programming failed; no other error checking is performed.

See also SHIFT.SEGMENT.PAGE

MSEC.TIMESLICE.PERIOD ( u -- )

Sets u as the period of the timeslice clock (the RTI interrupt) in units of 1.024 milliseconds.  For example, to set the timeslice period to just over 5 msec, execute

5  MSEC.TIMESLICE.PERIOD

The allowed input range is from 1 to decimal 15. Note that the default timeslice increment set after a COLD restart is 1.024 msec.

Implementation detail: Writes to the RTICTL register to configure the time base of the real-time interrupt that is used by the timeslicer.  The period of the RTI timer determines the timeslice period and also the resolution of the elapsed time clock (see READ.ELAPSED.TIME and READ.ELAPSED.SECONDS).
Pronunciation: millisecond-timeslice-period

M[] ( row#\col#\matrix.xpfa -- xaddr )

Places on the stack the extended address xaddr of the element with the specified row# and column# in the matrix specified by matrix.xpfa.  When using matrices this is faster than []. ABORTs if the indices are invalid.  Use as:

row# column#  ' <matrix.name>  M[]

Pronunciation: m-brackets

M[]! ( r\row#\col#\matrix.xpfa -- )

Stores r to the element at row#, column# in the specified matrix.  Equivalent to M[] F!
Pronunciation: m-brackets-store

M[]@ ( row#\col#\matrix.xpfa -- r )

Fetches r from the element at row#, column# in the specified matrix.  Equivalent to M[] F@
Pronunciation: m-brackets-fetch

NDROP ( wn\...\w1\+n -- | 0 ≤ +n ≤ 127 )

Drops +n cells in addition to +n itself from the data stack. +n is a single cell value within the range 0…127. 1 NDROP is equivalent to DROP, 2 NDROP is equivalent to 2DROP.
Pronunciation: n-drop

NEEDED ( +n -- )

If DEBUG is true and there are fewer than +n cell units on the data stack (excluding +n), ABORTs the current word and issues a Data stack underflow error message.

NEGATE ( n1 -- n2 )

Replaces n1 with its two's complement n2. The two's complement of n1 is computed by inverting each of the bits in n1 and adding 1 to the result.

NEXT ( -- )
Return stack: ( R: u -- [u] or [] | drops index when loop terminates )

Used inside a colon definition to mark the end of a count-down loop structure that is begun by FOR.  If the current loop index is zero, discards the index and terminates the loop, continuing execution with the word following NEXT.  If the loop index is not 0, NEXT decrements the index by 1 and continues looping by transferring control to the word after FOR.  Use as:

u1     FOR  <words to be executed u1+1 times>
   NEXT

0 FOR…NEXT executes 1 time, 1 FOR…NEXT executes 2 times, 65,535 FOR…NEXT executes 65,536 times, etc.  FOR…NEXT loops may be nested as long as each FOR is matched with a corresponding NEXT in the same definition as FOR.  An error is issued if FOR is not properly paired with NEXT inside a definition.  FOR … NEXT loops execute faster than DO … LOOP constructs.  The word I may be used inside a FOR NEXT loop.  J I' and LEAVE may not be used in a FOR NEXT loop.

Attributes: C, I

NEXT.NUMBER ( <text> -- r )

Accepts text from the input stream, reading in new lines if necessary, until a space-delimited string representing a valid floating point or integer number is encountered.  The floating point representation r of the number is placed on the stack.  Integers are converted according to the current number BASE (unless the integer starts with 0x or 0X, in which case hexadecimal base is used).

See also ASK.FNUMBER and ASK.NUMBER

Attributes: M, S

NEXT.TASK ( -- xaddr )

User variable that contains the 16-bit task identifier (i.e., the base address of the task's user area) of the next task in the round-robin task list.

Attributes: U

NEXT.WORD ( <name> -- addr )

Removes <name> from the input stream, inputting a new line if necessary to get it, leaves the text string in POCKET, and returns the 16-bit address of POCKET (which is in common memory) on the stack.

NFA.FOR ( -- xnfa )

Compile Time: ( <name> – )

Removes <name> from the input stream and returns <name>'s extended name field address xnfa.  xnfa is the address of the count byte in <name>'s header.  If in execution mode, leaves the xnfa on the stack.  If in compilation mode, compiles the xnfa as a 2-cell literal in the current definition; the xnfa is pushed to the stack when the definition later executes.  An error occurs if no <name> is given or if <name> cannot be found in the dictionary.
Pronunciation: n-f-a-for
Attributes: I

NFA>CFA ( xnfa -- xcfa )

Given the extended name field address xnfa of a header in the dictionary, returns the xcfa (extended code field address) of the word.  xcfa is the first byte of executable machine code associated with the definition.  An unchecked error occurs if xnfa is not a valid name field address.

See also NFA.FOR
Pronunciation: n-f-a-to-c-f-a

NFA>L$ ( xnfa – x$addr\flag )

Given the extended name field address xnfa of an extended header in the dictionary, returns the x$addr of the long-string associated with the header under a validity flag.  The validity flag is true if a long string was created and a reference to it was stored in the designated header by PROTOTYPE: or C.HEADERS: or FORTH.HEADERS:.
Pronunciation: n-f-a-to-l-string

NFA>LFA ( xnfa -- xaddr )

Given the extended name field address xnfa of a header in the dictionary, returns the link field address which is the extended xaddr in the header that contains the 3-byte link offset.  The link offset consists of a page offset and an address offset which link the specified header to the previous header in the linked list of names.  The page offset is a single signed byte stored at xaddr and the address offset is a 16-bit signed offset stored at xaddr+1. Adding the signed address and page offsets to the xnfa yields the xnfa of the previous word in the linked name list.  Note that headers in the Forth vocabulary have an additional hash link field.

See also NFA.FOR, LINK and LINK.HASH
Pronunciation: n-f-a-to-l-f-a

NFA>PFA ( xnfa -- [xpfa] or [0\0] )

Given the extended name field address xnfa of a header in the dictionary, returns the extended parameter field address xpfa of the word.  Returns 0\0 if the word has no pfa (see ?HAS.PFA).  An unchecked error occurs if xnfa is not a valid name field address.

See also NFA.FOR
Pronunciation: n-f-a-to-p-f-a

NFA>PROPERTIES ( xnfa -- segment.xhandle\xcfa\xnfa\segment\flag )

For the specified xnfa, leaves the word's extended segment handle address, extended code field address, extended name field address, segment index and a flag on the stack.  If <name> is in the kernel or the currently compiling segment (as indicated by THIS.SEGMENT), then the returned segment.xhandle is 0\0. For non-kernel non-local segments, the segment.xhandle is obtained by searching the current segment’s required.segment table for a match to the segment.index stored in <name>’s header, and returning the xaddress of the matching table entry.  Aborts if a matching segment entry is not found in required.segment table.  Only the lower 6 bits of the segment index are matched.  The 2 msbits of the byte-sized entry in the required segment table byte encode additional information: bit6 is set if the target xcfa is in a non-local library (as opposed to an application segment), and bit7 is set if a page-relative call is required (e.g., if <name> is in the currently compiling segment).  These 2 msbits from the matching required.segment table entry are transferred to the ms.page.byte of the xcfa for use by the compiler.  The returned xcfa is the absolute code field address.  For kernel routines, this is the xcfa stored in the header of <name>, while for nonkernel routines, the returned xcfa is calculated as:

 {xcfa.offset from header} + {segment.xbase from eeprom segment table}

The returned segment.index is copied from the header, and bit6 of the segment index is set if <name> is in a library segment.  The returned flag at the top of the stack has an msbyte = 0xFF (to guarantee a nonzero flag) and the lsbyte equals the header.type field from the header of <name>. .
Pronunciation: n-f-a-to-properties

NHERE ( -- xaddr )

Places on the stack the xaddr of the next available location in the names area.  Equivalent to NP X@
Pronunciation: n-here
Attributes: U

NIP ( w1\w2 -- w2 )

Drops the cell below the top cell on the data stack.  NIP is equivalent to SWAP DROP.

NO.AUTOSTART ( -- )

Undoes the effect of the PRIORITY.AUTOSTART:, IS.PRIORITY.AUTOSTART, AUTOSTART:, and IS.AUTOSTART commands and attempts to ensure that the standard QED-Forth interpreter will be entered after subsequent resets.  Does not affect startup configurations set by CHECKSTART.ENABLE or SET.BOOT.VECTOR.  Implementation detail: Erases the 0x1357 pattern at location 0x0FBFFA in RAM and shadow flash put there by priority autostart, and erases the 0x1357 pattern at location 0x37BFFA in on-chip flash put there by autostart.  Note that the RAM-based priority autostart vector cannot be erased if the memory is write-protected (see WRITE.PROTECT and WRITE.ENABLE).  NO.AUTOSTART is invoked by the special cleanup mode.

NO.OP ( -- )

Does nothing.  Used for redefining forward reference words.  See REDEFINE.
Pronunciation: no-op

NO.SPACES ( -- xaddr )

A user variable that contains a 16-bit flag.  If the flag is true, leading and trailing spaces are not printed when a floating point number is displayed.  If true, the spaces are printed.  The default value is false.

See also F>$, F>FIXED$, F>FLOATING$, and F>SCIENTIFIC$

Attributes: U

NO.STATUS.AT.STARTUP ( -- )

Initializes a flag in EEPROM that suppresses the status report that is typically printed at each COLD and WARM restart.  Suppresses the REPORT.PAGES.LOADED printout at subsequent COLD restarts, and suppresses the .MAP printout at subsequent WARM and COLD restarts.  Note that these printouts are automatically suppressed if a (priority) autostart is installed.  To undo the effect of this routine, call STATUS.AT.STARTUP or do a factory clean.  To temporarily suppress the status printouts during a COLD restart, use QUIET.COLD.

NO.VITAL.IRQ.INIT ( -- )

Initializes a flag in EEPROM so that subsequent cold restarts will not initialize COP, clock monitor, illegal opcode trap and RTI (timeslicer) interrupt vectors.  This option is provided for programmers interested in installing their own interrupt service routines in any of these four vectors.  Can be undone by INIT.VITAL.IRQS.ON.COLD.
Pronunciation: no-vital-i-r-q-init

NOT ( w -- flag )

flag is the boolean inverse of w.  That is, if w = 0, the flag is TRUE.  If w is non-zero, the flag is FALSE.

NP ( -- xaddr )

User variable that contains the 32-bit pointer to the names area of the dictionary.  The contents of NP are placed on the stack by NHERE and are modified by NALLOT.  The command NP X@ is equivalent to NHERE; it yields the xaddr of the next available location in the names area.  The command NP @ is equivalent to NPAGE; it yields the page of the names area.
Pronunciation: n-p
Attributes: U

NP.NOBUMP ( -- xaddr )

A 16-bit system variable that is zeroed by COLD.  If the system variable NP.NOBUMP is in its default false state, CREATE and (CREATE) check to see if the names pointer NP is within 88 bytes of top of the names page, and if so bumps NP to the start of the next page.  This feature helps automatically manage the names pointer, typically avoiding an abort error due to a newly defined header crossing a page boundary.

See also LAST.NP.PAGE and DP.NOBUMP

NPAGE ( -- page )

Returns the page of the names area in the dictionary.  Equivalent to NP @
Pronunciation: n-page
Attributes: U

NUMBER ( x$addr -- [n\1] or [d\2] or [0] )

Converts the string whose first character is at x$addr+1 into an integer or double number in the current number base, unless the number starts with 0x or 0X, in which case hexadecimal base is used.  If the number can be represented as a 16 bit signed integer, leaves it on the stack under a 1 flag.  If it is convertible but cannot be represented as a 16 bit number, leaves its 32 bit representation on the stack under a 2 flag.  If a non-convertible character is encountered in the string or if the string does not end with a space, leaves a 0 on the stack.  x$addr must end with a space; its count is not used by NUMBER.  Except for a leading 0x or 0X or + or - character and isolated embedded commas, no other punctuation is allowed in the numeric string.  If a leading 0x or 0X is present, no + or – is allowed in the string.  Also see FNUMBER.

Attributes: S

OC.ACTION ( n\channel_id -- | n = oc_action_id )

Configures the output compare (OC) action of the PORTT timer bit specified by channel_id in the range 0 to 7. The allowed values for the oc_action_id are the constants OC.NO.ACTION (the default after a power-up or hardware reset), OC.TOGGLE.ACTION, OC.CLEAR.ACTION, and OC.SET.ACTION.  Consult the glossary entries for these constants for descriptions of their actions.  Briefly, each action constant specifies what happens to the specified PORTT pin when there is a match between the free-running TCNT register and the 16-bit value in the TC register associated with the specified channel_id (see OC.REG.WRITE, OC.IC.REG.READ, and TCNT.READ).  Note that the specified channel should be declared as an output compare by invoking the OUTPUT.COMPARE function; see its glossary entry.

Implementation detail: OC.ACTION writes the 2-bit field associated with the specified oc_action_id constant to the specified channel bits in the TCTL1 and TCTL2 registers.

OC.CLEAR.ACTION ( -- n )

A constant equal to 2 that is passed as an argument to the OC.ACTION function.  Configures the output compare action of the specified PORTT timer pin such that it clears to the zero state when there is a match between the free-running TCNT register and the 16-bit value in the TC register associated with the specified channel_id.  See OC.ACTION, OC.REG.WRITE, OC.IC.REG.READ, and TCNT.READ.  Note that the specified channel should be declared as an output compare by invoking the OUTPUT.COMPARE function; see its glossary entry.

See also OC.NO.ACTION, OC.TOGGLE.ACTION, and OC.SET.ACTION

OC.FORCE ( channel_id -- )

Forces the action configured by the OC.ACTION function to occur immediately on the PORTT pin specified by channel_id (0 ≤ channel_id ≤ 7).  Note that the specified channel must have been pre-configured by invoking the OUTPUT.COMPARE and OC.ACTION functions; See their glossary entries.

Implementation detail: writes a 1 to the bit of the specified channel in the CFORC register to force the programmed output compare action to occur immediately.  Note that a read of the CFORC register always returns 0, as the '1' is transient.  Forcing is disabled by default after a power-up or hardware reset.

OC.IC.REG.READ ( channel_id -- u )

For the specified PORTT timer channel_id in the range 0 to 7, reads and returns the 16-bit contents from the specified output compare/input capture register (TC0 - TC7).  This function reads the TCx register of both output compare (OC) and input capture (IC) channels; use the OUTPUT.COMPARE and INPUT.CAPTURE functions to configure the channels.  Do not use OC.IC.REG.READ to read pulse accumulator channels; see PULSE.REG.READ.

OC.NO.ACTION ( -- n )

A constant equal to 0 that is passed as an argument to the OC.ACTION function.  Configures the output compare action of specified the PORTT timer pin to take no action when there is a match between the free-running TCNT register and the 16-bit value in the TC register associated with the specified channel_id.  See OC.ACTION, OC.REG.WRITE, OC.IC.REG.READ, and TCNT.READ.  Note that the specified channel should be declared as an output compare by invoking the OUTPUT.COMPARE function; see its glossary entry.  The no-action state is the default after a power-up or hardware reset.

See also OC.TOGGLE.ACTION, OC.CLEAR.ACTION, and OC.SET.ACTION

OC.NO.TOGGLE.ON.OVERFLOW ( channel_id -- )

Configures the PORTT pin specified by channel_id (in the range 0 to 7) to not toggle when the free-running TCNT timer overflows from 0xFFFF to 0x0000. No toggle is the default at power-up or after a hardware reset.  Note that the specified channel should be declared as an output compare by invoking the OUTPUT.COMPARE function; see its glossary entry.  This function reverses the effect of OC.TOGGLE.ON.OVERFLOW.

Implementation detail: This function clears the bit of the specified OC channel in the TTOV register.

OC.REG.WRITE ( n\channel_id -- )

For the specified PORTT timer channel_id in the range 0 to 7, writes the specified value n to the corresponding output compare register (TC0 - TC7).  Writes to the TCx registers only have meaning if the channel has been configured as an output compare (OC); See the OUTPUT.COMPARE glossary entry.  Do not use this function for pulse accumulator channels; see PULSE.REG.WRITE.

OC.SET.ACTION ( -- n )

A constant equal to 3 that is passed as an argument to the OC.ACTION function.  Configures the output compare action of specified the PORTT timer pin to set to the high state when there is a match between the free-running TCNT register and the 16-bit value in the TC register associated with the specified channel_id (see OC.ACTION, OC.REG.WRITE, OC.IC.REG.READ, and TCNT.READ).  Note that the specified channel should be declared as an output compare by invoking the OUTPUT.COMPARE function; see its glossary entry.

See also OC.NO.ACTION, OC.TOGGLE.ACTION, and OC.CLEAR.ACTION

OC.TOGGLE.ACTION ( -- n )

A constant equal to 1 that is passed as an argument to the OC.ACTION function.  Configures the output compare action of specified the PORTT timer pin to toggle to the opposite state each there is a match between the free-running TCNT register and the 16-bit value in the TC register associated with the specified channel_id (see OC.ACTION, OC.REG.WRITE, OC.IC.REG.READ, and TCNT.READ).  Note that the specified channel should be declared as an output compare by invoking the OUTPUT.COMPARE function; see its glossary entry.  Using the toggle action is a simple way to create a 50% duty-cycle square wave on a PORTT output pin with no ongoing processor intervention required: the pin will toggle to the opposite state at the periodicity of the TCNT rollover (104.8ms if the default prescaler of 32 is retained; See the ECT.PRESCALER function to change the rollover period).  If the channel is also configured by OC.TOGGLE.ON.OVERFLOW, variable duty cycles can be synthesized with no ongoing processor intervention by modifying the value in the output compare register TCx (see OC.REG.WRITE).

See also OC.NO.ACTION, OC.SET.ACTION, and OC.CLEAR.ACTION

OC.TOGGLE.ON.OVERFLOW ( channel_id -- )

Configures the PORTT pin specified by channel_id (in the range 0 to 7) to toggle when the free-running TCNT timer overflows from 0xFFFF to 0x0000. Note that the specified channel should be declared as an output compare by invoking the OUTPUT.COMPARE function; see its glossary entry.  This function reverses the effect of OC.NO.TOGGLE.ON.OVERFLOW which is the default at power-up or after a hardware reset.  Using the toggle on overflow action is a simple way to create a 50% duty-cycle square wave on a PORTT output pin with no ongoing processor intervention required: the pin will toggle to the opposite state at the periodicity of the TCNT rollover (104.8ms if the default prescaler of 32 is retained; See the ECT.PRESCALER function to change the rollover period).  If the channel is also configured by passing OC.TOGGLE.ACTION to OC.SET.ACTION, variable duty cycles can be synthesized with no ongoing processor intervention by modifying the value in the output compare register TCx (see OC.REG.WRITE).

Implementation detail: This function sets the bit of the specified OC channel in the TTOV register.

OC7.CLEARS.IT ( channel_id -- )

For the PORTT timer bit specified by channel_id in the range 0 to 7, configures the pin to go low upon a successful output compare on the OC7 (output compare 7) channel.  Note that OC7 must be configured separately by passing the parameter 7 to the OUTPUT.COMPARE function.  The specified channel_id must either be configured as an output compare using OUTPUT.COMPARE (which automatically makes it an output), or explicitly declared as an output pin by writing a 1 to its bit in PORTT.DIRECTION.  After a power-up or hardware reset, OC7 is disconnected from the other PORTT pins by default.  A successful OC7 compare overrides any other compare action specified for the pin.

Implementation detail: This function sets the bit of the specified channel in the OC7M register and clears the corresponding bit in the OC7D register.

OC7.DISCONNECT ( channel_id -- )

For the PORTT timer bit specified by channel_id in the range 0 to 7, undoes the effect of the OC7.SETS.IT and OC7.CLEARS.IT functions, disconnecting the specified pin from an action resulting from a successful compare on output compare 7 (OC7).  After a power-up or hardware reset, OC7 is disconnected from the other PORTT pins by default.

Implementation detail: This function clears the bit of the specified channel in the OC7M register.

OC7.SETS.IT ( channel_id -- )

For the PORTT timer bit specified by channel_id in the range 0 to 7, configures the pin to go high upon a successful output compare on the OC7 (output compare 7) channel.  Note that OC7 must be configured separately by passing the parameter 7 to the OUTPUT.COMPARE function.  The specified channel_id must either be configured as an output compare using OUTPUT.COMPARE (which automatically makes it an output), or explicitly declared as an output pin by writing a 1 to its bit in PORTT.DIRECTION.  After a power-up or hardware reset, OC7 is disconnected from the other PORTT pins by default.  A successful OC7 compare overrides any other compare action specified for the pin.

Implementation detail: This function sets the bit of the specified channel in the OC7M register and sets the corresponding bit in the OC7D register.

OF ( n1\n2 -- [n1] or [] )

Used inside a CASE … ENDCASE structure to mark the beginning of a conditional statement.  If n1 = n2 then n1 and n2 are dropped and execution continues with the words between OF and ENDOF and then skips to the word after ENDCASE.  If n1 does not equal n2, then n2 is dropped and execution continues after the next ENDOF.  Use as:

n1 CASE
   n2 OF    words to be executed if n1 = n2    ENDOF
   n3 OF    words to be executed if n1 = n3    ENDOF
   words to be executed if n1 doesn't equal n2 or n3
ENDCASE

An error is issued if OF and ENDOF are not properly paired.

Attributes: C, I

OFF ( xaddr -- )

Stores 0 (FALSE) at xaddr.

OK ( -- )

A do-nothing function.  It is included in the kernel so that a file generated by the kernel that includes the standard ok response can be interpreted without generating an error.
Pronunciation: o-k

ON ( xaddr -- )

Stores -1 (TRUE) at xaddr.

ON.FORGET ( -- )

Any word named ON.FORGET is executed by FORGET or ANEW (or LIBRARY or APPLICATION) before being forgotten.  The programmer can define a word with the name ON.FORGET to de-allocate a heap item when the associated data structure is forgotten.  This prevents cluttering the heap with memory allocated to forgotten structures during debugging sessions.  Typical use:

MATRIX: MAT.A
: DIM.MATRICES  3 3 ' MAT.A  DIMMED ;
: ON.FORGET
   ' MAT.A  DELETED
   ...other cleanup code...
;

If this code is later forgotten, MAT.A is deleted, thus freeing its space in the heap.  If the ON.FORGET word had not been included, the definition of MAT.A would have been forgotten, but its heap space would still be allocated.  Note that when this definition is compiled, the message

ON.FORGET isn't unique

will be issued.  The non-uniqueness does not affect the performance of the word.

ONE ( -- r )

Pushes the floating point number 1.0 onto the data stack.

OPEN.LAST.SEGMENT ( -- )

Opens the last segment that was defined.  If no segments have been defined (that is, if the system variable LAST.SEGMENT = 0), this routine does nothing.  This routine performs the action:

LAST.SEGMENT  @  OPEN.SEGMENT

See the glossary entry for OPEN.SEGMENT.

This routine is useful for re-opening the last library or application segment to add routines to it during program development and debugging even when all the segments have been completed and relocated.  Typically only the last segment is opened, as it REQUIREs all the relevant preceeding libraries.

OPEN.SEGMENT ( segment -- )

Opens the segment specified by the segment index input parameter.  If the segment index = 0 (i.e., the kernel segment), this routine does nothing, as opening the kernel segment has no meaning.  For any valid non-zero segment index, this routine does the following: Sets the system variable THIS.SEGMENT to equal the specified segment index, and sets the system variables THIS.SEGMENT.XBASE, THIS.SEGMENT.XNFA, and LIBRARY.IS.COMPILING to correspond to the specified segment using data from the eeprom segment array.  Sets DP, NP, VP, and EEP to the values they had when END.SEGMENT was called.  Zeros the xcfa field in the segment header to indicate that the segment is in the process of being defined.  Leaves the segment code size, variable size and eesize fields in the segment structure as they were; they will be overwritten with correct values by END.SEGMENT.  This routine is useful for adding routines to a library or application segment during program development and debugging even when all the segments have been completed and relocated.  Typically only the last segment is opened, as it REQUIREs all the relevant preceeding libraries.  See OPEN.LAST.SEGMENT.  If the specified segment has been moved to flash, note that errors will result if you try to add code or names to the re-opened segment.  This routine aborts if either the code or names base address is not in the region 0x0800-0xBFFF which includes common ram and paged memory; this acts as a sanity check to help avoid setting up a completely un-initialized map.

OR ( w1\w2 -- w3 )

Performs a logical bit-wise inclusive-or of two 16-bit numbers w1 and w2 to produce the result w3.

OR.TYPE.OF: ( u1\u2\u3 -- u1\max{u2,u3}\u1 )

Used inside a variant field declaration started by TYPE.OF: and terminated by TYPE.END within a structure definition.  Indicates that the following structure fields are a variant of the fields that followed TYPE.OF: An OR.TYPE.OF: variant should be used for variant fields which are loosely typed; i.e., during the life of the structure, the field content may change type.  See also TYPE.OF: for an example of use.
Pronunciation: or-type-of
Attributes: D

OTHERWISE ( -- )

Marks the start of the else portion of a conditional structure that is used in execution mode.  Use as:

flag  IFTRUE .... OTHERWISE ....  ENDIFTRUE

If the flag passed to IFTRUE is true, the code between IFTRUE and OTHERWISE is executed, and the code between OTHERWISE and ENDIFTRUE is skipped.  If the flag is false, the code between IFTRUE and OTHERWISE is skipped and execution continues with the words following OTHERWISE.  OTHERWISE is analogous to ELSE but it is used outside of a colon definition.  The execution mode conditional structure can be used to conditionally compile portions of source code.  An unchecked error occurs if OTHERWISE is used outside of IFTRUE and ENDIFTRUE.  Note that IFTRUE/OTHERWISE/ENDIFTRUE statements can be nested.

OUTPUT.COMPARE ( channel_id -- )

For the specified channel_id in the range 0 to 7, configures the corresponding bit of the PORTT timer register as an output compare (as opposed to an input capture).  An output compare (OC) can trigger an interrupt and/or modify the associated pin’s state when the value of the free-running TCNT counter matches the value in the channel’s timer/counter register TCx (TC0 through TC7).  To configure a pin action, pass one of the action constants (OC.NO.ACTION, OC.TOGGLE.ACTION, OC.CLEAR.ACTION, or OC.SET.ACTION) and the specified channel_id to the OC.ACTION function.  Other pin control functions are OC.TOGGLE.ON.OVERFLOW, OC.NO.TOGGLE.ON.OVERFLOW, OC7.SETS.IT, OC7.CLEARS.IT, and OC7.DISCONNECT; See their glossary entries for details.  To enable or disable an interrupt, pass the channel_id to ECT.INTERRUPT.ENABLE or ECT.INTERRUPT.DISABLE.  Note that, after a power-up or hardware reset, all 8 PORTT pins are configured as input captures by default, with no triggering action.

Implementation detail: This routine sets the bit of the specified channel in the TIOS register.

OVER ( w1\w2 -- w1\w2\w1 )

Places a copy of w1 on top of the stack.

OVERFLOW ( -- )

Sets the user variable FP.ERROR to -1 to indicate an overflow error.