Forth v6 Function Glossary (P-Z-})

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:

PAD ( -- xaddr | xaddr = start of scratchpad area )

Returns the xaddr of the start of the PAD scratchpad area.  The 32 bytes below PAD are used for floating point and integer string/number conversion, and the area above PAD is available as scratchpad memory for the programmer (but note that the kernel routines ASK.NUMBER, ASK.FNUMBER, INPUT.STRING, and RECEIVE.HEX write text strings into the PAD).  Equivalent to

UPAD X@

PAD must point to modifiable RAM, and there must be at least 32 bytes of RAM below PAD for number/string conversion.  PAD may be on any page, but may not cross a page boundary.

Attributes: U

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

Adds a named member to the structure being defined and reserves room for a 1-cell (16-bit) page 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: page
Attributes: D

PAGE.SIZE ( -- n )

Returns the constant value 2 which is the number of bytes in a parameter of type page 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(

PARAMS( ( n <iparam.size.list> <c-callable_fn_name> -- | n = return.param.size )

Declares the return parameter size, the number of input parameters, and the input parameter sizes of the specified <c-callable_fn_name>, and stores them in the name header for use in exporting C wrapper function that can call the function from C.  Parses a single- or multi-line comma-delimited list of input parameter sizes, terminated by the ) character, and sets the 1byte +NUM.INPUT.PARAMS field and 2byte +INPUT.PARAMS bitfield in the header of the specified <c-callable_fn_name>. No comments are allowed inside the PARAMS( ) list or before <c-callable_fn_name>.

Examples of allowed syntax:

VOID.SIZE PARAMS( CHAR.SIZE, XADDR.SIZE )  C!
CHAR.SIZE PARAMS( XADDR.SIZE )  C@
VOID PARAMS( VOID )  PAUSE
VOID PARAMS( )  PAUSE

Note that simple integers can be substituted for char.size, void.size, etc.  Each specified parameter size must evaluate to an integer number of bytes between 0 and 4, and MUST be represented by a single word (for example, you can't say 2 2 * for 4.) Note that parameter sizes = 1 are promoted to 2bytes to match the promotion done by the C compiler.  Valid parameter sizes are 0, 1, 2 or 4 bytes.  C.CALLABLE must be true when c-callable_fn_name is originally defined; use X: XCREATE or XCODE, or turn C.CALLABLE ON when defining it.  The PARAMS( keyword must be followed by a space.
Pronunciation: params-open-paren

PARSE ( n1 -- xaddr\cnt | n1 is the terminating delimiter )

Parses a string delimited by the specified 1- or 2-byte delimiter n1 from the input stream, and returns the xaddr\cnt of the parsed string, where xaddr is the address of the first character and cnt is the number of characters in the parsed string (the string may cross a page boundary).  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.  Unlike WORD, which also parses strings from the input stream, PARSE does not move the parsed string to POCKET.  Thus it is suitable for parsing strings longer than 63 bytes (see WORD).  If the specified delimiter char1 is a space, then leading spaces are ignored.  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.  PARSE leaves >IN pointing 1 byte past the terminating delimiter unless the input stream is exhausted, in which case >IN is left pointing 1 byte past the last valid location in the input stream.

Attributes: M

PARSE.BUFFER ( xaddr1\u1\u2\n1—xaddr2\cnt\n2 )

Parses a string with the 1- or 2-byte delimiter n1, located in the buffer starting at xaddr1 with buffer size u1. Parsing starts at buffer-offset u2. In other words, the first byte examined is at xaddr1+u2. Returns the xaddress of the parsed string xaddr2, its 1- or 2-byte count cnt, and the number of skipped leading spaces n2 (leading spaces are skipped only if the delimiter n1 is a space).  The delimiter is not included in the returned count.  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.  The string is parsed in place.  The specified buffer at xaddr1 with size u1 is allowed to cross page boundaries only if the specified delimiter is a single byte.

PAUSE ( -- )

Stacks the state of the current task and passes control to the next AWAKE task in the round-robin task list.  You can embed calls to PAUSE in any task when you wish to give other tasks a chance to run.  PAUSE may be used in multitasked systems whether or not the timeslicer is active.  PAUSE switches tasks in 6 + 0.5n microseconds, where n is the number of ASLEEP tasks encountered in the round robin task list.  Interrupts are disabled for most of the task switch time.

Attributes: M

PAUSE.ON.KEY ( -- )

Suspends execution of the calling word when a character is received and, with the exceptions noted below, resumes execution of the calling word when a second character is received.  Typically coded into a loop structure to allow control of execution during debugging, or to control a data dump.  PAUSE.ON.KEY checks whether a character has been received.  If no character has been received, it does nothing.  If a character has been received and it is a carriage return, executes ABORT which clears the stacks and returns to the interpreter.  If the character received is a . (dot) executes QUIT which returns to the interpreter without clearing the data stack.  If any other character is received, suspends execution until another character other than carriage return or . is received.  This word effectively responds to XON/XOFF from a host terminal; a QED-Forth word that dumps data and calls PAUSE.ON.KEY repeatedly will pause when the XOFF is received by QED-FORTH, and resume when XON is received.  The word does not know that the characters are special; it just stops when receiving the first and resumes after the second.  The kernel words that call call PAUSE.ON.KEY include DUMP, DUMP.INTEL, DUMP.S1, DUMP.S2, DUMP.MANY.S2, DUMP.BINARY, .HANDLES, LTYPE, M.PARTIAL, M., M.., WORDS, and the segment export routines whose names start with BUILD, COMPOSE or DUMP.

Attributes: M

PF.STACK.FRAME ( +n -- [+n bytes]\xaddr )

First performs the operation of STACK.FRAME, reserving +n bytes of room on the data stack and leaving xaddr that points to the top (lowest in memory) reserved byte in the data stack frame.  PF.STACK.FRAME then zeros the first 4 bytes (lowest in memory, nearest top of stack) of the allocated stack frame.  See STACK.FRAME and FRAME.DROP.  PF.STACK.FRAME should be used when creating a temporary array or matrix parameter field within a definition; See the glossary entries of ARRAY.PF and MATRIX.PF for examples of use.  The first 4 bytes of a parameter field contain an xhandle to the heap, and the xhandle should always be initialized to 0\0 before the array or matrix is dimensioned.  PF.STACK.FRAME performs this initialization on the temporary stack-based parameter field.  There is an unchecked error if +n is less than 4.
Pronunciation: p-f-stack-frame

PFA>NAME ( xpfa -- )

Prints the name of the word associated with the specified extended parameter field address xpfa.  Useful for error diagnostics to print the name of an array, matrix or other data structure given its xpfa.  The name is printed as ?NAME? if no name corresponding to xpfa is found in the dictionary.
Pronunciation: p-f-a-to-name
Attributes: M

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

Given the extended parameter field address xpfa of a word in the dictionary, searches the dictionary and returns the extended name field address xnfa of the word.  If the name associated with xpfa cannot be found in the dictionary, returns 0\0.

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

PI ( -- r )

Places the floating point value pi (= 3.1416) on the stack.

PI/2 ( -- r )

Places the floating point representation of pi/2 (= 1.5708) on the stack.
Pronunciation: pi-over-two

PICK ( wn\...\w1\w0\+n -- wn\...\w1\w0\wn | 0 ≤ +n ≤ 255 )

Copies the +nth item (not including n) to the top of the stack, where the top stack item is item#0, the next is item#1, etc.  An unchecked error occurs if there are fewer than n+1 items on the data stack. 0 PICK is equivalent to DUP, 1 PICK is equivalent to OVER.

PLL.LOCK.ID ( -- n )

Returns the interrupt identity code for the PLL (phase-locked-loop) lock interrupt.  Used as an argument for ATTACH.
Pronunciation: p-l-l-lock-i-d

POCKET ( -- xaddr | xaddr is the start of the pocket buffer )

Returns the xaddress of the start of the POCKET buffer.  POCKET is a 64-byte (minimum) scratch area used by WORD.  Equivalent to

UPOCKET  @  DEFAULT.PAGE

FIND executes COLD if POCKET is not in the common RAM.

Attributes: U

PORTAD0 ( -- xaddr )

Returns the extended address (0x008F\0) of the 8 bit PortAD0 register in the 68HCS12. This is a read-only port that returns the bit-wise digital equivalents of the each of the inputs on the AN0-AN7 lines that have been configured in digital mode by writing to PORTAD0.MODE.  Note: After a reset or power-up, the PORTAD0 inputs are in analog mode, and can not be read as digital inputs until the corresponding bits are set to 1 by writing to PORTAD0.MODE.
Pronunciation: port-a-d-zero

PORTAD0.MODE ( -- xaddr )

Returns the extended address (0x008D\0) of the 8 bit PortAD0-digital-input-enable register in the 68HCS12. Writing a 1 to a bit in this port configures the corresponding PORTAD0 signal on the AN0-AN7 lines as a digital input, while writing a 0 configures the corresponding PORTAD0 bit as an analog input.  Any bits in PORTAD0 corresponding to 0’s in this port will be read as a digital 1. This port is cleared by a reset or power-up, placing the PORTAD0 inputs in analog mode.  Note that enabling digital reads on analog input channels can cause high current draw, as the input pin buffer may operate in linear mode.

Example of use: To use AN0-3 as digital inputs while using AN4-7 as analog inputs, write 0x0F to this port as:

0x0F PORTAD0.MODE C!

The digital inputs can be read as:

PORTAD0 C@

In this example, only the lower 4 bits of the result are valid digital inputs.
Pronunciation: port-a-d-zero-mode

PORTAD1 ( -- xaddr )

Returns the extended address (0x012F\0) of the 8 bit PortAD1 register in the 68HCS12. This is a read-only port that returns the bit-wise digital equivalents of the each of the inputs on the AN8-AN15 lines that have been configured in digital mode by writing to PORTAD1.MODE.  Note: After a reset or power-up, the PORTAD1 inputs are in analog mode, and can not be read as digital inputs until the corresponding bits are set to 1 by writing to PORTAD1.MODE.
Pronunciation: port-a-d-one

PORTAD1.MODE ( -- xaddr )

Returns the extended address (0x0012D\0) of the 8 bit PortAD1-digital-input-enable register in the 68HCS12. Writing a 1 to a bit in this port configures the corresponding PORTAD1 signal on the AN8-AN15 lines as a digital input, while writing a 0 configures the corresponding PORTAD0 signal as an analog input.  Any bits in PORTAD1 corresponding to 0’s in this port will be read as a digital 1. This port is cleared by a reset or power-up, placing the PORTAD1 inputs in analog mode.  Note that enabling digital reads on analog input channels can cause high current draw, as the input pin buffer may operate in linear mode.

Example of use: To use AN8-11 as digital inputs while using AN12-15 as analog inputs, write 0x0F to this port as:

0x0F PORTAD1.MODE C!

The digital inputs can be read as:

PORTAD1 C@

In this example, only the lower 4 bits of the result are valid digital inputs.
Pronunciation: port-a-d-one-mode

PORTH.ID ( -- n )

Returns the interrupt identity code for PortH on the 68HCS12. Used as an argument for ATTACH.
Pronunciation: port-h-i-d

PORTJ ( -- xaddr )

Returns the extended address (0x0268\0) of the 8 bit PortJ register in the 68HCS12. On most hardware implementations, only the upper 2 bits (bits 6 and 7) are available: bit6 is SDA.IIC and bit 7 is SCL.IIC.  If the IIC bus is not being used, these pins can be used as general purpose I/O with direction controlled by the PORTJ.DIRECTION register.  Note that each of these signals is conditioned by a pull-up to +5V and a series resistor.  Make sure that you do not change the values of any other PORTJ pins when writing to this port, as the other pins may be dedicated to other hardware functions.
Pronunciation: port-j

PORTJ.DIRECTION ( -- xaddr )

Returns the extended address (0x026A\0) of the 8 bit PortJ direction control register in the 68HCS12. Setting a bit to 1 configures the corresponding signal as an output, and setting it to 0 configures the corresponding signal as an input.  On most hardware implementations, only the upper 2 bits (bits 6 and 7) are available: bit6 is SDA.IIC and bit 7 is SCL.IIC.  If the IIC bus is not being used, these pins can be used as general purpose I/O with direction controlled by the PORTJ.DIRECTION register.  Note that each of these signals is conditioned by a pull-up to +5V and a series resistor.  Make sure that you do not change the values of any other PORTJ pins when writing to this port, as the other pins may be dedicated to other hardware functions.
Pronunciation: port-j-direction

PORTJ.ID ( -- n )

Returns the interrupt identity code for PortJ on the 68HCS12. Used as an argument for ATTACH.
Pronunciation: port-j-i-d

PORTM ( -- xaddr )

Returns the extended address (0x0250\0) of the 8 bit general purpose digital I/O PortM register in the 68HCS12 whose direction is controlled by the PORTM.DIRECTION register.
Pronunciation: port-m

PORTM.DIRECTION ( -- xaddr )

Returns the extended address (0x0252\0) of the 8 bit PortM direction control register in the 68HCS12. Setting a bit to 1 configures the corresponding signal as an output, and setting it to 0 configures the corresponding signal as an input.
Pronunciation: port-m-direction

PORTP ( -- xaddr )

Returns the extended address (0x0258\0) of the 8 bit PWM (pulse-width modulation) and general purpose digital I/O PortP register in the 68HCS12 whose direction is controlled by the PORTP.DIRECTION register.  For any pins that have been configured as outputs by writing a 1 to the corresponding bit position in PORTP.DIRECTION, a read of the PORTP register returns the last value written to the register, not the actual signal level on the pin.  If the pin is under the control of the PWM subsystem, reads of this PORTP register can be misleading, and the PORTP.IN register should be read instead (see its glossary entry).
Pronunciation: port-p

PORTP.DIRECTION ( -- xaddr )

Returns the extended address (0x025A\0) of the 8 bit PortP direction control register in the 68HCS12. Setting a bit to 1 configures the corresponding signal as an output, and setting it to 0 configures the corresponding signal as an input.
Pronunciation: port-p-direction

PORTP.ID ( -- n )

Returns the interrupt identity code for PortP on the 68HCS12. Used as an argument for ATTACH.
Pronunciation: port-p-i-d

PORTP.IN ( -- xaddr )

Returns the extended address (0x0259\0) of the 8-bit input register of the PWM (pulse-width modulation) and general purpose digital I/O PortP in the 68HCS12 whose direction is controlled by the PORTP.DIRECTION register.  For any pins that have been configured as outputs by writing a 1 to the corresponding bit position in PORTP.DIRECTION, a read of the associated PORTP register (see its glossary entry) returns the last value written to PORTP, not the actual signal level on the pin.  If the pin is under the control of the PWM subsystem, reads of the PORTP register can be misleading, and this PORTP.IN register should be read instead to ascertain the actual logic level at the pin.

PORTT ( -- xaddr )

Returns the extended address (0x0240\0) of the 8 bit ECT (Enhanced Capture Timer) and general purpose digital I/O PortT register in the 68HCS12 whose direction is controlled by the PORTT.DIRECTION register.  For any pins that have been configured as outputs by writing a 1 to the corresponding bit position in PORTT.DIRECTION, a read of the PORTT register returns the last value written to the register, not the actual signal level on the pin.  If the pin is under the control of the ECT subsystem, reads of this PORTT register can be misleading, and the PORTT.IN register should be read instead (see its glossary entry).
Pronunciation: port-t

PORTT.DIRECTION ( -- xaddr )

Returns the extended address (0x0242\0) of the 8 bit PortT direction control register in the 68HCS12. Setting a bit to 1 configures the corresponding signal as an output, and setting it to 0 configures the corresponding signal as an input.
Pronunciation: port-t-direction

PORTT.IN ( -- xaddr )

Returns the extended address (0x0241\0) of the 8 bit input register of the ECT (Enhanced Capture Timer) and general purpose digital I/O PortT in the 68HCS12 whose direction is controlled by the PORTT.DIRECTION register.  For any pins that have been configured as outputs by writing a 1 to the corresponding bit position in PORTT.DIRECTION, a read of the associated PORTT register returns the last value written to PORTT, not the actual signal level on the pin.  If the pin is under the control of the ECT (Enhanced Capture Timer) subsystem, reads of the PORTT register can be misleading, and this PORTT.IN register should be read instead to ascertain the actual logic level at the pin.

PRIORITY.AUTOSTART: ( <name> -- )

Removes <name> from the input stream and 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.  You'll find 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 IS.PRIORITY.AUTOSTART and AUTOSTART:
Attributes: I

PRIVATE ( -- xaddr )

A system variable whose contents at the time of function definition are stored in the newly created function’s header.  If PRIVATE is true when a function is created, the function is not exported by the routines that BUILD and COMPOSE (export) library and application segments.  This variable has no effect on C.CALLABLE functions.  The default value of PRIVATE after a COLD restart is zero.  To create a Forth function that is not exported as part of a segment, simply set PRIVATE ON before creating the function, and set PRIVATE OFF to re-establish the default after the function is defined.

PROTOTYPE: ( <forth.fn.name> <${prototype.string}$> -- )

For the specified <forth.fn.name>, declares and saves a C prototype equal to the contents of the specified prototype.string which is delimited by a stating ${ and an ending }$ delimiter.  The C prototype string is exported by the routines that BUILD and COMPOSE (export) library and application segments.

PROTOTYPE: 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.fn.name> must be C-callable; that is, it must be defined using use X: or XCODE, or the C.CALLABLE system variable must be true when forth.fn.name is originally defined.  In the prototype string, the C function name and the ( must be separated by at least one space.  The <forth.fn.name> and ${ must be on the same line as PROTOTYPE:.

A single-word return type specifier such as void or char* must be used in the prototype string.  The C function 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.

During the segment export process, the 'extern' keyword will be automatically inserted in front of each prototype.  The __attribute__((far)) specifier will be inserted between the return type specifier and the C function name to indicate that a paged call is required (all C-callable functions are invoked by C/assembly wrapper functions that use a paged call).  The PROTOTYPE: statement is for functions only; for variable and EEPROM variable declarations, use the VPROTOTYPE: and EEPROTOTYPE: statements, respectively.  Some examples of proper syntax are as follows:

PROTOTYPE: C! ${void StoreChar (char val, xaddr address);  }$
PROTOTYPE: C@ ${char FetchChar (xaddr address);  }$
PROTOTYPE: FPtoString ${char* FPtoString (float ansi_fp_num); }$

PULSE.A ( -- n )

A constant equal to 0x100 used to identify the PULSE.A 16-bit accumulator on PORTT pin 7. This constant is used as an input parameter to PULSE.REG.READ and PULSE.REG.WRITE.  The PULSE.A accumulator is configured by the PULSE.A.SETUP function.  When PULSE.A is in use, the associated 8-bit pulse accumulators 2 (forming the least significant byte of PULSE.A) and 3 (forming the most significant byte of PULSE.A) on PORTT pins 2 and 3 are not available.

See also PULSE.A.SETUP and PULSE.B

PULSE.A.EDGE ( -- n )

A channel identifier constant that can be passed to ECT.CLEAR.INTERRUPT.FLAG, ECT.INTERRUPT.ENABLE, or ECT.INTERRUPT.DISABLE to manipulate the interrupt and/or flag bits associated with the PULSE.A 16-bit accumulator edge detector.  The PULSE.A accumulator is part of the Enhanced Capture Timer (ECT) system and is available on pin 7 of PORTT.

See also PULSE.A and PULSE.A.SETUP

PULSE.A.EDGE.ID ( -- n )

Returns the interrupt identity code for the 16-bit pulse accumulator A input edge detector on pin 7 of PORTT. . Used as an argument for ATTACH.
Pronunciation: pulse-a-edge-i-d

PULSE.A.FALLING.EDGE ( -- n )

A constant that identifies the desired trigger edge for the 16-bit PULSE.A pulse accumulator as a falling edge present on PORTT pin 7. The pulse accumulator is incremented each time the qualifying edge occurs.  This constant can be passed as the pulse_mode parameter to the PULSE.A.SETUP function (see its glossary entry).  This constant must not be used as an argument to the TRIGGER.EDGE function.

PULSE.A.GATED.HIGH ( -- n )

A constant that identifies the operational mode for the 16-bit PULSE.A pulse accumulator on PORTT pin 7. The pulse accumulator is incremented by a constant-period clock every 3.2 microseconds (= 64 * E-clock-period) whenever a high (gating) signal is present at the input pin.  This constant can be passed as the pulse_mode parameter to the PULSE.A.SETUP function (see its glossary entry).  This constant must not be used as an argument to the TRIGGER.EDGE function.

PULSE.A.GATED.LOW ( -- n )

A constant that identifies the operational mode for the 16-bit PULSE.A pulse accumulator on PORTT pin 7. The pulse accumulator is incremented by a constant-period clock every 3.2 microseconds (= 64 * E-clock-period) whenever a low (gating) signal is present at the input pin.  This constant can be passed as the pulse_mode parameter to the PULSE.A.SETUP function (see its glossary entry).  This constant must not be used as an argument to the TRIGGER.EDGE function.

PULSE.A.OVERFLOW ( -- n )

A channel identifier constant that can be passed to ECT.INTERRUPT.ENABLE (to enable an interrupt when the 16-bit PULSE.A accumulator overflows), ECT.INTERRUPT.DISABLE (to disable interrupt generation when PULSE.A overflows) or ECT.CLEAR.INTERRUPT.FLAG (to clear the flag bit associated with the PULSE.A overflow).  The PULSE.A accumulator is part of the Enhanced Capture Timer (ECT) system on the HCS12 processor.

See also PULSE.A and PULSE.A.SETUP

PULSE.A.OVERFLOW.ID ( -- n )

Returns the interrupt identity code for the pulse accumulator A overflow.  Used as an argument for ATTACH.
Pronunciation: pulse-a-overflow-i-d

PULSE.A.RISING.EDGE ( -- n )

A constant that identifies the desired trigger edge for the 16-bit PULSE.A pulse accumulator as a rising edge present on PORTT pin 7. The pulse accumulator is incremented each time the qualifying edge occurs.  This constant can be passed as the pulse_mode parameter to the PULSE.A.SETUP function (see its glossary entry).  This constant must not be used as an argument to the TRIGGER.EDGE function.

PULSE.A.SETUP ( edge_irq\overflow_irq\pulse_mode\16bit_pulse_enable -- )

This function writes to the PACTL register to configure the 16-bit PULSE.A pulse accumulator on pin 7 of PORTT.  Each input parameter is a 16-bit flag that is named in the stack picture for convenience.  If the 16bit_pulse_enable flag is true, the 16-bit PULSE.A pulse accumulator on pin 7 of PORTT is enabled.  If the 16bit_pulse_enable flag is false, then PULSE.A is disabled and the two component 8-bit pulse accumulators PA2 (forming the least significant byte of PULSE.A) and PA3 (forming the most significant byte of PULSE.A) on PORTT pins 2 and 3 are available.  The pulse_mode input paramter is one of the following four constants: PULSE.A.FALLING.EDGE, PULSE.A.RISING.EDGE, PULSE.A.GATED.HIGH, or PULSE.A.GATED.LOW; See their glossary entries.  The former 2 modes increment the accumulator on the specified edge, while the latter modes enable the ECLK/64 clock to increment the pulse count every 3.2 microseconds while the input is in the specified gating state.  If the overflow_irq flag is true, an interrupt occurs every time the pulse accumulator overflows from 0xFFFF to 0x0000. If the edge_irq flag is true, an interrupt is generated upon each qualifying input edge as configured by the pulse_mode parameter.  The default state after a power-up or hardware reset is interrupts disabled and the 16-bit PULSE.A accumulator disabled.

Implementation note: To operate PULSE.A accumulator independently of the input capture/output compare channel IC7/OC7, set IOS7=1 in TIOS and set OM7=OL7= 0 in TCTL1/2 to disconnect the timer from pin PT7. You can accomplish this by executing:

7  OUTPUT.COMPARE
OC.NO.ACTION  7  OC.ACTION

Also, 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 these two 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 functions relies on TCNT for software timing; rather, the multitasking operating system uses the RTI (real-time interrupt) as a time base.

PULSE.B ( -- n )

A constant equal to 0x101 used to identify the PULSE.B 16-bit accumulator on PORTT pin 0. This constant is used as an input parameter to PULSE.REG.READ and PULSE.REG.WRITE.  The PULSE.B accumulator is configured by the PULSE.B.SETUP function.  When PULSE.B is in use, the associated 8-bit pulse accumulators 0 (forming the least significant byte of PULSE.B) and 1 (forming the most significant byte of PULSE.B) on PORTT pins 0 and 1 are not available.

See also PULSE.A

PULSE.B.OVERFLOW ( -- n )

A channel identifier constant that can be passed to ECT.INTERRUPT.ENABLE (to enable an interrupt when the 16-bit PULSE.B accumulator overflows), ECT.INTERRUPT.DISABLE (to disable interrupt generation when PULSE.B overflows) or ECT.CLEAR.INTERRUPT.FLAG (to clear the flag bit associated with the PULSE.B overflow).  The PULSE.B accumulator is part of the Enhanced Capture Timer (ECT) system on the HCS12 processor.

See also PULSE.B and PULSE.B.SETUP

PULSE.B.OVERFLOW.ID ( -- n )

Returns the interrupt identity code for the pulse accumulator B overflow.  Used as an argument for ATTACH.
Pronunciation: pulse-b-overflow-i-d

PULSE.B.SETUP ( flag1\flag2 -- | flag1 = overflow_irq?; flag2 = 16bit_pulse_enable? )

This function writes to the PBCTL register to configure the 16-bit PULSE.B pulse accumulator on pin 0 of PORTT.  If the 16bit_pulse_enable (flag2) parameter is true, the 16-bit PULSE.B pulse accumulator on pin 0 of PORTT is enabled.  If the 16bit_pulse_enable flag is false, then PULSE.B is disabled and the two component 8-bit pulse accumulators PA0 (forming the least significant byte of PULSE.B) and PA1 (forming the most significant byte of PULSE.B) on PORTT pins 0 and 1 are available.  If the overflow_irq (flag1) parameter is true, an interrupt occurs every time the pulse accumulator overflows from 0xFFFF to 0x0000. To configure the PULSE.B trigger edge, make sure that channel 0 is an input capture by executing 0 INPUT.CAPTURE or PULSE.B INPUT.CAPTURE, and call TRIGGER.EDGE with channel_id = 0. For example, to count rising-edge pulses without generating interrupts, execute:

TRIGGER.ON.RISING.EDGE  PULSE.B  TRIGGER.EDGE
PULSE.B  INPUT.CAPTURE
FALSE TRUE PULSE.B.SETUP

The PULSE.B 16-bit accumulator and its interrupt are disabled by default after a power-up or hardware reset.

PULSE.DISABLE ( channel_id -- )

Disables the 8-bit pulse accumulator specified by channel_id in the range 0 to 3 on corresponding bits 0 to 3 of the PORTT timer port.

Implementation detail: Clears the specified bit in the ICPAR register.  Pulse accumulators are disabled by default after a power-up or harddware reset.

PULSE.ENABLE ( channel_id -- )

Enables the 8-bit pulse accumulator specified by channel_id in the range 0 to 3 on corresponding bits 0 to 3 of the PORTT timer port.  Do not pass PULSE.A or PULSE.B as a channel_id input parameter to this function; rather, use PULSE.A.SETUP and PULSE.B.SETUP to configure the 16-bit accumulators.  For all 8-bit pulse accumulators, the associated pins should be configured as input captures by leaving the pin in the default input capture state after a reset, or by invoking the INPUT.CAPTURE function.  The pulse accumulator trigger edge is configured using TRIGGER.EDGE, and the pulse accumulator channel is enabled using the PULSE.ENABLE function; See their glossary entries.  Use channel_id = 0 to 3 for the 8 bit accumulators PA0 through PA.  See PULSE.A.SETUP and PULSE.B.SETUP for more details regarding the 16-bit pulse accumulators.

Example of use: To configure the 8-bit pulse accumulator 1 on PORTT pin 1 to count rising edges, execute:

TRIGGER.ON.RISING.EDGE  1  TRIGGER.EDGE
1  INPUT.CAPTURE
1  PULSE.ENABLE

Implementation detail: Sets the specified bit in the ICPAR register.  Pulse accumulators are disabled by default after a power-up or hardware reset.

PULSE.HOLDING.READ ( channel_id -- n )

For the specified pulse accumulator channel_id in the range 0 to 3, reads and returns the value n from the corresponding 8-bit pulse accumulator holding register PA0H, PA1H, PA2H, or PA3H.  The channel_id cannot be PULSE.A or PULSE.B, as these do not have holding registers.  The specified channel must be configured as an input capture (as opposed to an output compare) by leaving the pin in the default input capture state after a reset, or by invoking the INPUT.CAPTURE function.  The pulse accumulator trigger edge is configured using TRIGGER.EDGE, and the pulse accumulator channel is enabled using the PULSE.ENABLE function; See the PULSE.ENABLE glossary entry for an example.  See the glossary entries for IC.PULSE.CONFIG for more information about the IC and pulse accumulator 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 associated pulse accumulator register upon each read of the holding register.  Do not use this function for input capture holding registers; See the glossary entry for IC.HOLDING.READ.

PULSE.REG.READ ( channel_id -- u )

For the specified pulse accumulator channel_id, reads and returns the value u from the corresponding 8-bit or 16-bit pulse accumulator count register (or register pair) PACN0-3. The channel_id can be the numeric value 0, 1, 2, or 3 to identify the 8-bit accumulators, or PULSE.A or PULSE.B to identify the 16-bit pulse accumulators.  See the glossary entries for PULSE.ENABLE, IC.PULSE.CONFIG, PULSE.A.SETUP, and PULSE.B.SETUP for details on how to configure the pulse accumulators.  To access the holding registers, see PULSE.HOLDING.READ.  Do not use this function for input capture or output compare channels; See the glossary entry for OC.IC.REG.READ.

PULSE.REG.WRITE ( u\channel_id -- )

For the specified pulse accumulator channel_id, writes the value u to the corresponding 8-bit or 16-bit pulse accumulator count register (or register pair) PACN0-3. The channel_id can be the numeric value 0, 1, 2, or 3 to identify the 8-bit accumulators, or PULSE.A or PULSE.B to identify the 16-bit pulse accumulators.  See the glossary entries for PULSE.ENABLE, IC.PULSE.CONFIG, PULSE.A.SETUP, and PULSE.B.SETUP for details on how to configure the pulse accumulators.  Do not use this function for output compare channels; See the glossary entry for OC.REG.WRITE.

PUSH.FORTH.PARAMS ( -- )

This is a low-level utility function that is never directly used by the programmer.  It is used by the operating system to generate C wrapper (calling) functions that enable Forth functions to be called from C.  This function is not invoked by name, but its calling address in common memory is invoked in the code generated by COMPOSE.C.ASM.CODE and COMPOSE.C.ASM.CODE.FOR.  The calling wrapper function {typically defined in a C assembly code *.s file} must be called via a paged call; this is why every C-callable function is automatically tagged as a 'far' function when C headers are composed.  This ensures that both the return address and return page of the calling wrapper function will be on the return stack when this routine is called.  The call to this routine is compiled {typically in GCC assembly code} as:

jsr *push.forth.params <params.size{2}> <output.param.size&#input.params{1}>
   <segment.array.addr{2}> <callee.pg.offset{1}> <callee.addr.offset{2}> RTC

Thus there are 8 bytes of inline information and an RTC instruction after the call to this routine.  The compiled <callee.pg.offset> and <callee.addr.offset> parameters are offsets with respect to the code base page and address stored in the 3 bytes at <segment.array.addr>. Thus, the wrapper functions are tolerate of segment relocation.  The C calling paradigm is as follows: if a routine has input parameters P1, P2, … Pn, then C pushes the parameters last-to-second, and passes the first param in the X:D registers.  The PUSH.FORTH.PARAMS routine points the Y register to the Forth data stack by reading the contents of a special system variable, pushes the parameters in (Forth-style) forward order to the dstack, decrementing Y as they are pushed, calls the forth-callee function, places the return value in X:D {depending on output.param.size), and returns.  This routine executes in approximately 3.75us + 1.5us per input parameter.  The system variable that references the Forth data stack is initialized to S0 by ABORT, so C-callable Forth functions use the same data stack that Forth would use for foreground functions.  If an interrupt service routine is in progress, code compiled by ATTACH points the system variable to a reserved interrupt data stack in system RAM, ensuring a valid data stack that does not interfere with foreground operations.  The Y register is not cleaned up at the end of the call; it is left pointing somewhere into the dstack area, and this has no ill effects.  Note that nesting of C-invoked forth functions is not allowed, as corruption of the data stack would occur.

PWM.ACTIVE.HIGH ( channel_id -- )

Configures the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id to start in the active high state.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must be configured by invoking PWM.SETUP, PWM.ENABLE or PWM.ENABLE.MULTIPLE; See the PWM.SETUP glossary entry for a list of useful PWM configuration functions and a code example.

Implementation detail: Writes a 1 to the bit of the specified channel in the PWMPOL register.  After a power-up or hardware reset, the contents of PWMPOL is zero, causing the PWM outputs to be active low by default.

PWM.ACTIVE.LOW ( channel_id -- )

Configures the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id to start in the active low state.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must be configured by invoking PWM.SETUP, PWM.ENABLE or PWM.ENABLE.MULTIPLE; See the PWM.SETUP glossary entry for a list of useful PWM configuration functions and a code example.

Implementation detail: Writes a 0 to the bit of the specified channel in the PWMPOL register.  After a power-up or hardware reset, the contents of PWMPOL is zero, causing the PWM outputs to be active low by default.

PWM.CENTER.ALIGN ( channel_id -- )

Configures the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id to to be center aligned (as opposed to left aligned).  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  Center alignment causes the output period to be double the value set by PWM.PERIOD.WRITE, for the following reason.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must be configured by invoking PWM.SETUP, PWM.ENABLE or PWM.ENABLE.MULTIPLE; See the PWM.SETUP glossary entry for a list of useful PWM configuration functions and a code example.

Implementation detail: Writes a 1 to the bit of the specified channel in the PWMCAE register.  After a power-up or hardware reset, the contents of PWMCAE is zero and the signals are left aligned.

PWM.CLOCKA ( -- n )

A constant clock identifier (clock_id) that is passed to the PWM.SCALER or PWM.PRESCALER functions to identify the CLOCKA clock source; See the glossary entries of these functions. 8-bit PWM (pulse-width modulated) channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM.CLOCKA or a scaled version of PWM.CLOCKA; See the glossary entries for PWM.SCALED.CLOCK and PWM.UNSCALED.CLOCK.

PWM.CLOCKB ( -- n )

A constant clock identifier (clock_id) that is passed to the PWM.SCALER or PWM.PRESCALER functions to identify the CLOCKB clock source; See the glossary entries of these functions. 8-bit PWM (pulse-width modulated) channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM.CLOCKB or a scaled version of PWM.CLOCKB; See the glossary entries for PWM.SCALED.CLOCK and PWM.UNSCALED.CLOCK.

PWM.CONCATENATE ( channel_id -- )

Creates a 16-bit PWM (pulse-width modulated) channel by concatenating two 8-bit PWM channels.  Valid channel_id input parameters are PWM01 (combines PWM0 and PWM1, present on PORTP pin 1); PWM23 (combines PWM2 and PWM3, present on PORTP pin 3); PWM45 (combines PWM4 and PWM5, present on PORTP pin 5); and PWM67 (combines PWM6 and PWM7, present on PORTP pin 7).  You can also use PWM.SETUP to create a concatenated channel; see its glossary entry.  To undo the effect of PWM.CONCATENATE, use PWM.SEPARATE.  While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution.

Note: Make sure that both PWM channels associated with the concatenation are disabled before calling this routine.  If the relevant channels are active, they can be disabled using PWM.DISABLE or PWM.DISABLE.MULTIPLE.

Implementation detail: This function sets the relevant bit in the PWMCTL register to create a concatenated 16bit PWM channel.  After a power-up or hardware reset, the contents of PWMCTL equal zero and the signals are separated (not concatenated).  For each channel_id, the second (numerically higher) channel mentioned in the name is the least significant byte of the 16-bit PWM, its register bits control the signal, and its associated PORTP pin is the output pin for the concatenated channel.  For example, if you execute

PWM01 PWM.CONCATENATE

then the 16-bit PWM output is available on PORTP pin 1, the control register bits associated with PWM1 configure the output, and all 16-bit configuration quantities use the associated PWM0 register as the most significant byte, and the associated PWM1 register as the least significant byte.

PWM.COUNTER.READ ( channel_id -- u )

Returns the contents of the specified PWM (pulse-width modulated) counter register.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  This function returns an 8-bit count if the specified channel is a single PWM channel, and returns a 16-bit value if the channel_id specifies a concatenated channel.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must have be configured by invoking PWM.SETUP, PWM.ENABLE or PWM.ENABLE.MULTIPLE; See the PWM.SETUP glossary entry for a list of useful PWM configuration functions and a code example.

PWM.COUNTER.WRITE ( u\channel_id -- )

Writes the value u to the specified PWM (pulse-width modulated) counter register.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  This function stores an 8-bit count if the specified channel is a single PWM channel, and stores a 16-bit value if the channel_id specifies a concatenated channel.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must have be configured by invoking PWM.SETUP, PWM.ENABLE or PWM.ENABLE.MULTIPLE; See the PWM.SETUP glossary entry for a list of useful PWM configuration functions and a code example.

PWM.DISABLE ( channel_id -- )

Disables the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  If a concatenated channel_id is passed to this function, both associated 8-bit PWM channels are disabled.  See PWM.ENABLE.

Implementation detail: Clears the relevant bit(s) in the PWME register.  After a power-up or hardware reset, the PWM channels are disabled by default.

PWM.DISABLE.MULTIPLE ( n -- )

Expects an 8-bit bitmask input parameter, where bit0 corresponds to PWM0, bit 1 corresponds to PWM1, and bit7 corresponds to PWM7. For each 1 bit in the input bitmask, this function clears the specified bits in the PWME register to disable the corresponding PWM (pulse-width modulated) channels.  Channels associated with 0 bits in the bitmask are not modified.  This function is useful for simultaneously disabling a number of PWM channels.  For concatenated channels, it is typically best to disable both subsidiary PWM channels, but note that only the bit corresponding to the numerically higher member of the pair has an effect on the concatenated pair.

See also PWM.ENABLE.MULTIPLE

PWM.DUTY.READ ( channel_id -- u )

Returns the contents of the specified PWM (pulse-width modulated) duty register.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  This function returns an 8-bit duty value if the specified channel is a single PWM channel, and returns a 16-bit duty value if the channel_id specifies a concatenated channel.  When the counter value matches the duty value, the output changes state.  See PWM.ACTIVE.HIGH and PWM.ACTIVE.LOW to configure the starting polarity of the PWM output.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  Note that the specified channel must have be configured by invoking PWM.SETUP, PWM.ENABLE or PWM.ENABLE.MULTIPLE; See the PWM.SETUP glossary entry for a list of useful PWM configuration functions and a code example.

PWM.DUTY.WRITE ( u\channel_id -- )

Writes the value u to the specified PWM (pulse-width modulated) duty register.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  This function writes an 8-bit duty value if the specified channel is a single PWM channel, and writes a 16-bit duty value if the channel_id specifies a concatenated channel.  When the counter value matches the duty value, the output changes state.  See PWM.ACTIVE.HIGH and PWM.ACTIVE.LOW to configure the starting polarity of the PWM output.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  Note that the specified channel must have be configured by invoking PWM.SETUP, PWM.ENABLE or PWM.ENABLE.MULTIPLE; See the PWM.SETUP glossary entry for a list of useful PWM configuration functions and a code example.

PWM.ENABLE ( channel_id -- )

Enables the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  See PWM.DISABLE and PWM.SETUP; the latter’s glossary entry describes a set of useful PWM configuration utiltities and provides an example of use.  To enable multiple channels at once, use PWM.ENABLE.MULTIPLE.

Implementation detail: Sets the relevant bit(s) in the PWME register.  If a concatenated channel_id is passed to this function, only the numerically higher bit in the PWME register is set, as this controls the concatenated channel.  After a power-up or hardware reset, the PWM channels are disabled by default.

PWM.ENABLE.MULTIPLE ( n -- )

Expects an 8-bit bitmask input parameter, where bit0 corresponds to PWM0, bit 1 corresponds to PWM1, and bit7 corresponds to PWM7. For each 1 bit in the input bitmask, this function sets the specified bits in the PWME register to enable the corresponding PWM (pulse-width modulated) channels.  Channels associated with 0 bits in the bitmask are not modified.  For concatenated channels, note that only the bit corresponding to the numerically higher member of the pair has an effect on the concatenated pair.  This function is useful for simultaneously enabling a number of PWM channels.  See PWM.DISABLE.MULTIPLE and PWM.SETUP; the latter’s glossary entry describes a set of useful PWM configuration utiltities and provides a code example.  To enable a single PWM channel identified by its channel_id, use PWM.ENABLE.

Implementation detail: Sets the specified bit(s) in the PWME register.  After a power-up or hardware reset, the PWM channels are disabled by default.

PWM.LEFT.ALIGN ( channel_id -- )

Configures the PWM (pulse-width modulated) signal on the PORTP pin specified by channel_id to to be left aligned (as opposed to center aligned).  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must be configured by invoking PWM.SETUP, PWM.ENABLE or PWM.ENABLE.MULTIPLE; See the PWM.SETUP glossary entry for a list of useful PWM configuration functions and a code example.

Implementation detail: Clears the bit of the specified channel in the PWMCAE register.  After a power-up or hardware reset, the contents of PWMCAE is zero and the signals are left aligned.

PWM.PERIOD.READ ( channel_id -- u )

Returns the contents of the specified PWM (pulse-width modulated) period register.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  This function returns an 8-bit period if the specified channel is a single PWM channel, and returns a 16-bit period value if the channel_id specifies a concatenated channel.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must be configured by invoking PWM.SETUP, PWM.ENABLE or PWM.ENABLE.MULTIPLE; See the PWM.SETUP glossary entry for a list of useful PWM configuration functions and a code example.

PWM.PERIOD.WRITE ( u\channel_id -- )

Writes the value u to the specified PWM (pulse-width modulated) period register.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  This function writes an 8-bit period value if the specified channel is a single PWM channel, and writes a 16-bit period value if the channel_id specifies a concatenated channel.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle; as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  Note that the specified channel must be configured by invoking PWM.SETUP, PWM.ENABLE or PWM.ENABLE.MULTIPLE; See the PWM.SETUP glossary entry for a list of useful PWM configuration functions and a code example.

PWM.PRESCALER ( n1\n2 -- | n1 = clock_id; n2 = prescaler )

Sets n2 as the prescale factor for the clock specified by clock_id n1 = PWM.CLOCKA or PWM.CLOCKB (See the PWM.CLOCKA and PWM.CLOCKB glossary entries).  The prescale factor n2 is applied to both the scaled and unscaled versions of the specified clock in the PWM (pulse-width modulated) subsystem.  Allowed values of the n2 factor are : 1, 2, 4, 8, 16, 32, 64, and 128. The fundamental clock is the bus clock E, running at 20MHz, and the frequency is reduced (the period is increased) by the prescale factor to create the specified PWM.CLOCKA or PWM.CLOCKB.  For a slower clock, use the scaled clock source for a given PWM channel; See the glossary entries for PWM.SCALER, PWM.SCALED.CLOCK, and PWM.UNSCALED.CLOCK. 8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM.CLOCKA or a scaled version of PWM.CLOCKA. 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM.CLOCKB or a scaled version of PWM.CLOCKB.

Example of use: The bus clock (E clock) has a period of 0.05 microseconds (us).  To configure PWM.CLOCKA to have a period of 1.6 us, and PWM.CLOCKB to have a period of 6.4 us, execute:

DECIMAL
PWM.CLOCKA  32  PWM.PRESCALER      \ clockA period = 1.6us
PWM.CLOCKB 128  PWM.PRESCALER   \ clockB period = 6.4us

As stated above, each PWM channel can also use the slower scaled clocks; see PWM.SCALED.CLOCK.

PWM.SCALED.CLOCK ( channel_id -- )

Configures the specified PWM (pulse-width modulated) channel to use the slower (longer period) scaled clock source.

Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  The 8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM.CLOCKA or a scaled version of PWM.CLOCKA.  The 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM.CLOCKB or a scaled version of PWM.CLOCKB.  If this routine is called for channel_id 0, 1, 4, 5, PWM01, or PWM45, that channel will use the scaled PWM.CLOCKA (SA).  If this routine is called for channel_id 2, 3, 6, 7 PWM23, or PWM67, that channel will use scaled PWM.CLOCKB (SB).  The period of the unscaled PWM.CLOCKA is equal to the E-clock period (0.05 us) multiplied by a prescaler set by PWM.PRESCALER.  Allowed values of the prescaler are 1, 2, 4, 8, 16, 32, 64, and 128. The period of the scaled version of PWM.CLOCKA is equal to the unscaled PWM.CLOCKA period times the scaler set by PWM.SCALER, where the scaler can be any even integer between 2 and 512. The clock B sources are exactly parallel, and have their own unique prescaler and scaler values as set by PWM.PRESCALER and PWM.SCALER.  Note that the default scale factor for the scaled PWM.CLOCKA and scaled PWM.CLOCKB clocks after a power-up or hardware reset is 512.

Example of use: The bus clock (E clock) has a period of 0.05 microseconds (us).  To configure PWM channel 0 to have a 1.6 us clock (unscaled PWM.CLOCKA), PWM channel 1 to have a 64 us clock (scaled PWM.CLOCKA), PWM channel 2 to have a 6.4 us clock (unscaled PWM.CLOCKB), and PWM channels 3 and PWM67 to have a 512 us clock (scaled PWM.CLOCKB), execute:

DECIMAL                         \ first set the clock periods…
PWM.CLOCKA  32  PWM.PRESCALER   \ clockA period = 1.6us
PWM.CLOCKA  40  PWM.SCALER      \ scaled clockA = 40 * 1.6 = 64us
PWM.CLOCKB 128  PWM.PRESCALER   \ clockB period = 6.4us
PWM.CLOCKB  80  PWM.SCALER      \ scaled clockB = 75 * 6.4 = 512us
0 PWM.UNSCALED.CLOCK            \ pwm0 uses clockA @ 1.6us
1 PWM.SCALED.CLOCK              \ pwm1 uses SA @ 64us
2 PWM.UNSCALED.CLOCK            \ pwm2 uses clockB @ 6.4us
3 PWM.SCALED.CLOCK              \ pwm3 uses SB @ 512us
PWM67 PWM.SCALED.CLOCK          \ pwm67 uses SB @ 512us

Implementation detail: Sets the bit corresponding to the specified PWM channel in the PWMCLK register to select the scaled (slower) clock source.  To undo the effect of this function see PWM.UNSCALED.CLOCK.

PWM.SCALER ( n1\n2 -- | n1 = clock_id; n2 = scaler )

Sets n2 (2 ≤ n2 ≤ 512, n2 is even) as the scale factor for the clock specified by clock_id n1, where n1 = PWM.CLOCKA or PWM.CLOCKB (See the PWM.CLOCKA and PWM.CLOCKB glossary entries).  The fundamental clock is the bus clock E, running at 20MHz, and its frequency is reduced (the period is increased) by the prescale factor to create the two unscaled PWM clocks.  The prescale factor set by PWM.PRESCALER (see its glossary entry) is applied to both the scaled and unscaled versions of the specified clock.  This PWM.SCALER function applies a second scale factor to create a longer-period scaled PWM.CLOCKA (SA) and/or scaled PWM.CLOCKB (SB).  Allowed values of the scaler n2 are even integers in the range 2 to 512. For a slower clock, use the scaled clock source for a given PWM channel; See the glossary entries for PWM.PRESCALER, PWM.SCALED.CLOCK, and PWM.UNSCALED.CLOCK. 8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM.CLOCKA or a scaled version of PWM.CLOCKA (SA). 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM.CLOCKB or a scaled version of PWM.CLOCKB (SB).  See the glossary entry for PWM.SCALED.CLOCK for an example of use.

Implementation detail: If clock_id = PWM.CLOCKA, this routine writes to the PWMSCLA register.  If clock_id = PWM.CLOCKB, this routine writes to the PWMSCLB register.  Note that a value of 0 in the register corresponds to a scale factor of 512; this is the default scale factor for the scaled PWM.CLOCKA and scaled PWM.CLOCKB clocks after a power-up or hardware reset.

PWM.SEPARATE ( channel_id -- )

Undoes the concatenation of a 16-bit PWM (pulse-width modulated) channel to yield two 8-bit PWM channels.  Valid channel_id input parameters are PWM01 (combines PWM0 and PWM1, present on PORTP pin 1); PWM23 (combines PWM2 and PWM3, present on PORTP pin 3); PWM45 (combines PWM4 and PWM5, present on PORTP pin 5); and PWM67 (combines PWM6 and PWM7, present on PORTP pin 7).  You can also use PWM.SETUP to configure a PWM channel; see its glossary entry.  To undo the effect of PWM.SEPARATE, use PWM.CONCATENATE.  While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution.

Note: Make sure that both of the PWM channels associated with the concatenation are disabled before calling this routine.  If the relevant channels are active, they can be disabled using PWM.DISABLE or PWM.DISABLE.MULTIPLE.

Implementation detail: This function clears the relevant bit in the PWMCTL register.  After a power-up or hardware reset, the contents of PWMCTL equal zero and the signals are separated (not concatenated).  For each channel_id, the second (numerically higher) channel mentioned in the name is the least significant byte of the 16-bit PWM, its register bits control the signal, and its associated PORTP pin is the output pin for the concatenated channel.

PWM.SETUP ( active_high\scaled_clock\centered\period\duty\channel_id -- )

Sets up the PWM subsystem for automated waveform generation on output pins.  The six 16-bit integer input parameters to this routine have been given descriptive names in the stack picture for convenience.  Valid channel_id parameters for 8-bit PWM (pulse width modulated) channels are in the range 0 to 7, and the PWM output on the corresponding PORTP pins.  Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher PORTP channel pin mentioned in each named constant.

While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution.  If the PWM channel is enabled when this routine is invoked, the channel is disabled during configuration to prevent anomalous transient behavior.  Then the specified parameters are written to the registers, and the specified PWM channel’s enable bit is restored to the state it was in before this routine was called.

If the active_high flag is true, the signal is configured to start in the (active) high state; see PWM.ACTIVE.HIGH.  If active_high is false (the default after a hardware reset), the signal is configured to start in the (active) low state; see PWM.ACTIVE.LOW.  If the scaled_clock flag is true, the channel is configured to use the (slower, longer-period) scaled clock; see PWM.SCALED.CLOCK.  If the scaled_clock flag is false (the default after a hardware reset), the channel is configured to use the unscaled clock; see PWM.UNSCALED.CLOCK.

8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM.CLOCKA or a scaled version of PWM.CLOCKA. 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM.CLOCKB or a scaled version of PWM.CLOCKB; See the glossary entries for PWM.PRESCALER and PWM.SCALER.  If the centered flag input parameter is true, the PWM channel is configured to be center aligned; see PWM.CENTER.ALIGNED.  If the centered flag is false (the default after a hardware reset), the PWM channel is configured to be left-aligned; see PWM.LEFT.ALIGNED.  For standard left aligned outputs, the PWM counter starts at 0 and counts up to the value stored in the period register(s) - 1, and then resets to zero to start the next cycle – as a result, the period equals the value in the period register(s) for standard left aligned signals.  For center aligned outputs, the counter starts at 0 and counts up to the value stored in the period register(s), and then counts down to zero.  This symmetrical up/down counting approach ensures a center aligned signal, and it also results in an output period that is twice the value stored in the period register(s).  In each case, when the counter value matches the duty value, the output changes state.  This function’s period input parameter is passed to the PWM.PERIOD.WRITE function which stores the parameter into the period register (if the channel_id is an 8-bit PWM) or register pair (if the channel_id is a 16-bit PWM).  Recall that the actual period will be double the specified period if the centered flag is true.  This functions’s duty input parameter is passed to the PWM.DUTY.WRITE function which stores the parameter into the duty register (if the channel_id is an 8-bit PWM) or register pair (if the channel_id is a 16-bit PWM).

Example of use:

The clock(s) should be configured before the specified channels are enabled.  Typically, clocks are configured using the PWM.PRESCALER and PWM.SCALER functions, then PWM.SETUP is called for each channel or channel pair, and then PWM.ENABLE or PWM.ENABLE.MULTIPLE is called to start the PWM signal(s).  For example, assume we want to simultaneously enable the two 8-bit channels PWM0 and PWM1. Both are to be left aligned active high signals.  PWM0 is to have a 40% duty cycle with a 16 microsecond (us) period.  PWM1 is to have a 60% duty cycle with a 640 us period.  Since both PWM0 and PWM1 use the A clocks (unscaled or scaled PWM.CLOCKA), we must first configure these to facilitate the design.  We’ll use the unscaled PWM.CLOCKA as the source for channel PWM0, and the scaled PWM.CLOCKA source for channel PWM1. The fundamental clock source is the E-clock with a period of 0.05 us.  Referring to the example in the glossary entry of PWM.SCALED.CLOCK, we choose a prescaler of 32, resulting in an unscaled period of 1.6 us for PWM.CLOCKA; this sets the minimum time resolution of a PWM channel using this clock at 1.6 microseconds.  For the slower PWM1 channel, we use the scaled PWM.CLOCKA (SA) with a period of 64 us.  We’ll specify the period of each channel as 10 counts; thus the PWM0 period is 10 * 1.6us = 16 us, and the PWM1 period is 10 * 6.4us = 64 us, as desired.  The required duty cycle of PWM0 is 40%, so we specify a duty parameter of 4 (4/10 = 40%).  The required duty cycle of PWM1 is 60%, so we specify a duty parameter of 6 (4/10 = 60%).  Finally, to simultaneously enable the two PWM channels we note that the bitmask for the combination of channels 0 and 1 equals decimal 3; that is, a bitmask with bits 0 and 1 set has a value of 3, and this is the parameter we will pass to PWM.ENABLE.MULTIPLE to simultaneously enable PWM0 and PWM1 after PWM.SETUP has executed.  We assume that this example starts after a power-up or hardware reset, with all of the PWM channels initially disabled.  Here is the code that fulfills the requirements of this example:

DECIMAL                         \ first set the clock periods…
PWM.CLOCKA  32  PWM.PRESCALER   \ clockA period = 1.6us
PWM.CLOCKA  40  PWM.SCALER      \ scaled clockA = 40 * 1.6 = 64us
0 PWM.UNSCALED.CLOCK            \ pwm0 uses clockA @ 1.6us
1 PWM.SCALED.CLOCK              \ pwm1 uses SA @ 64us
\ now call PWM.SETUP for PWM0:
TRUE    \ active high
FALSE   \ use unscaled clock
FALSE   \ left aligned (not centered)
10      \ period is ten
4       \ duty = 4, duty cycle = 40%
0       \ channel_id = 0
( active_high\scaled_clock\centered\period\duty\channel_id -- )
PWM.SETUP  \ setup but don’t enable PWM0
\ now call PWM.SETUP for PWM1:
TRUE       \ active high
TRUE       \ use scaled clock
FALSE      \ left aligned (not centered)
10         \ period is ten
6          \ duty = 6, duty cycle = 60%
1          \ channel_id = 1
( active_high\scaled_clock\centered\period\duty\channel_id -- )
PWM.SETUP  \ setup but don’t enable PWM1
3 PWM.ENABLE.MULTIPLE \ simultaneously enable PWM0 and PWM1

This glossary entry and example show how the PWM control functions work together to facilitate the configuration of pulse-width modulated signals.

PWM.SHUTDOWN.ID ( -- n )

Returns the interrupt identity code for the pulse width modulator shutdown.  Used as an argument for ATTACH.
Pronunciation: p-w-m-shutdown-i-d

PWM.UNSCALED.CLOCK ( channel_id -- )

Configures the specified PWM (pulse-width modulated) channel to use the faster (shorter period) unscaled clock source.  Valid channel_id parameters for 8-bit PWM channels are in the range 0 to 7. Valid 16-bit (concatenated) channel_id constants are PWM01, PWM23, PWM45, and PWM67; concatenated outputs are available on the numerically higher channel pin mentioned in each named constant.  The 8-bit PWM channels 0, 1, 4, 5, and 16-bit channels PWM01 and PWM45 can be clocked by either PWM.CLOCKA or a scaled version of PWM.CLOCKA (SA).  The 8-bit PWM channels 2, 3, 6, 7, and 16-bit channels PWM23 and PWM67 can be clocked by either PWM.CLOCKB or a scaled version of PWM.CLOCKB (SB).  If this PWM.UNSCALED.CLOCK routine is called for channel_id 0, 1, 4, 5, PWM01, or PWM45, that channel will use the unscaled PWM.CLOCKA.  If this routine is called for channel_id 2, 3, 6, 7 PWM23, or PWM67, that channel will use unscaled PWM.CLOCKB.  The period of the unscaled PWM.CLOCKA is equal to the E-clock period (0.05 us) multiplied by a prescaler set by PWM.PRESCALER; allowed values of the prescaler are 1, 2, 4, 8, 16, 32, 64, and 128. The period of the scaled version of PWM.CLOCKA is equal to the unscaled PWM.CLOCKA period times the scaler set by PWM.SCALER, where the scaler can be any even integer between 2 and 512. The clock B sources are exactly parallel, and have their own unique prescaler and scaler values as set by PWM.PRESCALER and PWM.SCALER.  See the glossary entry of PWM.SCALED.CLOCK for an example of use.

PWM01 ( -- channel_id )

A 16-bit constant that returns the channel_id representing a concatenated PWM (pulse width modulated) channel.  This channel_id can be passed as a parameter to many of the PWM configuration functions.  While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution.  The 16-bit PWM01 channel combines 8-bit PWM channels PWM0 and PWM1, and is present on PORTP pin 1. See the glossary entries for PWM.CONCATENATE and PWM.SETUP to configure a concatenated channel.  For the PWM01 channel_id, the second (numerically higher) channel mentioned in the name (channel 1) is the least significant byte of the 16-bit PWM, its register bits control the signal, and its associated PORTP pin is the output pin for the concatenated channel.  For example, if you execute

PWM01 PWM.CONCATENATE

then the 16-bit PWM output is available on PORTP pin 1, the control register bits associated with PWM1 configure the output, and all 16-bit configuration quantities use the associated PWM0 register as the most significant byte, and the associated PWM1 register as the least significant byte.  The associated 8-bit PWM channels 0 and 1 are not available when the PWM01 channel is in use.  PWM01 uses the PWM.CLOCKA or scaled PWM.CLOCKA clock source.

PWM23 ( -- channel_id )

A 16-bit constant that returns the channel_id representing a concatenated PWM (pulse width modulated) channel.  This channel_id can be passed as a parameter to many of the PWM configuration functions.  While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution.  The 16-bit PWM23 channel combines 8-bit PWM channels PWM2 and PWM3, and is present on PORTP pin 3. See the glossary entries for PWM.CONCATENATE and PWM.SETUP to configure a concatenated channel.  For the PWM23 channel_id, the second (numerically higher) channel mentioned in the name (channel 3) is the least significant byte of the 16-bit PWM, its register bits control the signal, and its associated PORTP pin is the output pin for the concatenated channel.  For example, if you execute

PWM23 PWM.CONCATENATE

then the 16-bit PWM output is available on PORTP pin 3, the control register bits associated with PWM3 configure the output, and all 16-bit configuration quantities use the associated PWM2 register as the most significant byte, and the associated PWM3 register as the least significant byte.  The associated 8-bit PWM channels 2 and 3 are not available when the PWM23 channel is in use.  PWM23 uses the PWM.CLOCKB or scaled PWM.CLOCKB clock source.

PWM45 ( -- channel_id )

A 16-bit constant that returns the channel_id representing a concatenated PWM (pulse-width modulated) channel.  This channel_id can be passed as a parameter to many of the PWM configuration functions.  While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution.  The 16-bit PWM45 channel combines 8-bit PWM channels PWM4 and PWM5, and is present on PORTP pin 5. See the glossary entries for PWM.CONCATENATE and PWM.SETUP to configure a concatenated channel.  For the PWM45 channel_id, the second (numerically higher) channel mentioned in the name (channel 5) is the least significant byte of the 16-bit PWM, its register bits control the signal, and its associated PORTP pin is the output pin for the concatenated channel.  For example, if you execute

PWM45 PWM.CONCATENATE

then the 16-bit PWM output is available on PORTP pin 5, the control register bits associated with PWM5 configure the output, and all 16-bit configuration quantities use the associated PWM4 register as the most significant byte, and the associated PWM5 register as the least significant byte.  The associated 8-bit PWM channels 4 and 5 are not available when the PWM45 channel is in use.  PWM45 uses the PWM.CLOCKA or scaled PWM.CLOCKA clock source.

PWM67 ( -- channel_id )

A 16-bit constant that returns the channel_id representing a concatenated PWM (pulse-width modulated) channel.  This channel_id can be passed as a parameter to many of the PWM configuration functions.  While the period and duty cycle of an 8-bit PWM can be specified in the range 1 to 255, the period and duty cycle of a 16-bit PWM can be specified in the range 1 to 65,535, and this allows much greater resolution.  The 16-bit PWM23 channel combines 8-bit PWM channels PWM6 and PWM7, and is present on PORTP pin 7. See the glossary entries for PWM.CONCATENATE and PWM.SETUP to configure a concatenated channel.  For the PWM67 channel_id, the second (numerically higher) channel mentioned in the name (channel 7) is the least significant byte of the 16-bit PWM, its register bits control the signal, and its associated PORTP pin is the output pin for the concatenated channel.  For example, if you execute

PWM67 PWM.CONCATENATE

then the 16-bit PWM output is available on PORTP pin 7, the control register bits associated with PWM7 configure the output, and all 16-bit configuration quantities use the associated PWM6 register as the most significant byte, and the associated PWM7register as the least significant byte.  The associated 8-bit PWM channels 6 and 7 are not available when the PWM67 channel is in use.  PWM67 uses the PWM.CLOCKB or scaled PWM.CLOCKB clock source.

QUERY ( -- )

Executes

TIB CHARS/LINE @ EXPECT

to accept a line of up to CHARS/LINE characters from the serial port and store them in the terminal input buffer.  Saves the number of characters actually received in the user variable #TIB.  Sets >IN to 0 so that the next execution of WORD will parse the received line of input starting at the first character received.  This is the main serial input word in the QED-Forth interpreter.  Note that the terminal input buffer may be on any page, but may not cross a page boundary.

Attributes: M

QUIET ( -- xaddr )

A user variable that holds a flag that controls the word BEEP.  BEEP is called when an error is detected.  If the flag in QUIET is false, BEEP EMITs the bell character when executed to give an audible warning.  If the flag is true, BEEP does nothing.  BEEP is called by the system error routine, so QUIET controls whether system errors emit an audible beep.

Attributes: U

QUIET.COLD ( -- )

Performs a COLD restart while suppressing the status report that is typically printed at each COLD restart.  Suppresses the REPORT.PAGES.LOADED and .MAP printouts.  This is often useful during a download to avoid confusing the terminal with extra carriage return/linefeed sequences, as the linefeed character is used for handshaking during the terminal download.  Unlike NO.STATUS.AT.STARTUP, this routine does not affect the behavior of subsequent restarts.

QUIT ( -- )

Enters execution mode and begins an infinite loop (terminated by errors) that repeatedly executes QUERY INTERPRET to read in a new line of input and interpret it.  The return stack is cleared after each line of input is interpreted while in execution mode.  This is the top level word in the QED-Forth interpreter.

Attributes: M

R0 ( -- xaddr )

User variable that contains the 16-bit address which is used by RP! to initialize the return stack pointer.  The first cell on the return stack occupies the 2 bytes below the address contained in R0, and the stack grows downward in memory.  After changing the contents of R0, the next ABORT or restart loads the value into the return stack pointer (the S register) to change the position of the stack.  The return stack is allocated in a 768 byte region in common memory after each COLD restart.  See RP!.
Pronunciation: r-zero
Attributes: U

R: ( <name> -- )

A version of the function-defining routine : that is useful during debugging.  R: removes <name> from the input stream and starts a new definition.  The words between R: and ; form the body of the definition.  If <name> has not yet been defined (that is, if <name> is not found in the dictionary), then R: behaves exactly the same as :. If <name> has already been defined, then R: prints the message “Redefining non-unique name” and REDEFINEs the prior definition of <name> to point to the code of the new instance of <name>. This provides an easy way to patch a bug in a function without reloading all of the code defined after the buggy routine.  The prior version of <name> must be in writeable RAM.
Pronunciation: r-colon
Attributes: D

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

Transfers the top cell on the return stack to the data stack.
Pronunciation: r-from
Attributes: C

R>DROP ( -- )
Return stack: ( R: w -- )

Drops the top cell from the return stack.
Pronunciation: r-from-drop
Attributes: C

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

Copies the top cell on the return stack to the data stack.
Pronunciation: r-fetch
Attributes: C

RANDOM ( -- d )

Generates d, a pseudo-random 23-bit double integer.  A pseudo-random sequence traverses every possible bit sequence (with the possible exception of all zeros) once and only once before repeating.

See also RANDOM#

RANDOM# ( -- xaddr )

A 32-bit user variable that holds the last 23-bit number generated by RANDOM, or the 23-bit mantissa of the last floating point random number generated by FRANDOM.  Storing a specific non-zero double integer (a seed) into RANDOM# leads to the generation of a reproducible series of pseudo-random numbers by repeated calls to FRANDOM or RANDOM.  This may be useful for debugging words that use random numbers.
Pronunciation: random-number
Attributes: U

RANDOM.GAUSSIAN ( -- r )

r is a random number drawn from a Gaussian distribution with unity standard deviation and zero mean.  Uses the Box-Muller method.

Attributes: S

RANGE ( n1\n2\n3 -- n1\flag )

Flag is TRUE if n1 is greater than or equal to n2 and less than or equal to n3. Otherwise flag is FALSE.

See also URANGE

RANGE.OF ( n1\n2\n3 -- [n1] or [] )

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

n1 CASE
n2 n3 RANGE.OF  executed if n1 in range (n2,n3)    ENDOF
n4 n5 RANGE.OF  executed if n1 in range (n4,n5)    ENDOF
      words to be executed if not in range (n2,n3) or (n4,n5)
ENDCASE

An error is issued if RANGE.OF and ENDOF are not properly paired.  See OF.
Pronunciation: range-of
Attributes: C, I

RCODE ( <name> -- )

A version of the assembly-code-defining routine CODE that is useful during debugging.  RCODE removes <name> from the input stream and starts a new definition.  Executes ASSEMBLER so that the assembler mnemonics can be found by the interpreter.  The assembly mnemonics between CODE and END.CODE form the body of the definition.  If <name> has not yet been defined (that is, if <name> is not found in the dictionary), then RCODE behaves exactly the same as CODE.  If <name> has already been defined, then RCODE prints the message “Redefining non-unique name” and REDEFINEs the prior definition of <name> to point to the code of the new instance of <name>. This provides an easy way to patch a bug in a function without reloading all of the code defined after the buggy routine.  The prior version of <name> must be in writeable RAM.
Pronunciation: r-code
Attributes: D

READ.ELAPSED.SECONDS ( -- u\ud | u = #msec, ud = #sec )

Returns the elapsed time on the timeslice clock since it was initialized to 0\0 by INIT.ELAPSED.TIME.  ud is the number of elapsed seconds, and u is the number of milliseconds since the last integral second on the timeslice clock.  The resolution equals the period of the timeslice clock (the default is approximately 1 msec).  Even though the timeslice clock has a period that is a multiple of 1.024 msec, this routine mathematically compensates for the non-integer period, reducing the reported error to 1 part in 5000, equivalent to reporting 17 too few seconds per day.  The maximum time that the clock can represent is proportional to the timeslice period; the clock can represent times to over 49 days if the default 1 msec timeslice period is used.  This routine disables interrupts for 0.55 microseconds.  See READ.ELAPSED.TIME, COUNT.TO.MSEC, TIMESLICE.COUNT, START.TIMESLICER, and MSEC.TIMESLICE.PERIOD.

READ.ELAPSED.TIME ( -- u1\u2\u3\u4\u5 | u1 msec, u2 sec, u3 min, u4 hrs, u5 days )

Returns the number of milliseconds, seconds, minutes, hours, and days that the timeslice clock (supported by the RTI real-time interrupt) has run since it was initialized to 0\0 by INIT.ELAPSED.TIME.  u5 is the number of days, u4 is the number of hours since the last integral day on the clock, u3 is the number of minutes since the last integral hour on the clock, u2 is the number of seconds since the last integral minute on the clock, and u1 is the number of milliseconds since the last integral second on the clock.  The resolution equals the period of the timeslice clock (the default is approximately 1 msec).  Even though the timeslice clock has a period that is a multiple of 1.024 msec, this routine mathematically compensates for the non-integer period, reducing the reported error to 1 part in 5000, equivalent to reporting 17 too few seconds per day.  This routine disables interrupts for 0.55 microseconds.  The maximum time that the clock can represent is proportional to the timeslice period; the clock can represent times to over 49 days if the default 1 msec timeslice period is used.

See also READ.ELAPSED.SECONDS, COUNT.TO.MSEC, TIMESLICE.COUNT, START.TIMESLICER, and MSEC.TIMESLICE.PERIOD

READ.WATCH ( -- u1\u2\u3\u4\u5\u6\u7\u8 )

meaning: ( – 100ths.sec\sec\min\hr\day\date\month\yr )

Reads the battery-operated real-time clock (if present), returning the time, day, and date specified by u1 through u8. The stack items and their allowed ranges are:

item description         range (decimal)
 u8    year                     0 - 99
 u7    month                    1 - 12
 u6    date                     1 - 31
 u5    day of week              1 -  7
 u4    hour of day              0 - 23
 u3    minute after the hour    0 - 59
 u2    seconds after the minute 0 - 59
 u1    hundredths of seconds    0

Due to a hardware limitation, the hundredths of second parameter always reads as 0; it is included in the stack picture to maintain backward compatibility with prior code.  Once correctly set, the watch handles the differing numbers of days in each month, and correctly handles leap years.  This routine also stores the results in the structure at WATCH.RESULTS.

See also SET.WATCH

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

Adds a named member to the structure being defined and reserves room for a real (floating point) number 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: real
Attributes: D

REAL: ( <name> -- )

REAL: is a synonym for DOUBLE: ; see its glossary entry.  REAL: defines a 32-bit self-fetching variable which holds a 32-bit floating point value (a real number).  Use as:

REAL: <name>

See also: DOUBLE:
Pronunciation: real-colon
Attributes: D

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

Adds a named member to the structure being defined and reserves room for u2 real (floating point) numbers 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: reals
Attributes: D

RECEIVE ( xmailbox -- wd | wd is the received message )

If xmailbox is empty (i.e., if it contains 0\0), executes PAUSE until the mailbox contains a message.  If xmailbox contains a message (i.e., if it does not contain 0\0), fetches the contents of xmailbox and stores a 0\0 into xmailbox to indicate that the message has been received and that the mailbox is now empty.  To ensure that the state of the mailbox is correctly determined, RECEIVE disables interrupts for 0.55 to 1.5 microseconds.

See also SEND, ?RECEIVE and MAILBOX:

Attributes: M

RECEIVE.BINARY ( xaddr\u1 <binary_stream> -- u2 | u2 = number of unreceived bytes )

Accepts a stream of up to u1 binary (not ascii!) bytes and initializes the RAM memory locations starting at the specified xaddr accordingly.  This function terminates at the earlier of: u bytes received, or, a 1-second timeout AFTER the first character is detected.  That is, the user can wait a long time before starting to send the binary stream, but once started, a delay of 1 second or more will terminate the load.  This function returns the difference between the input parameter u1 and the actual number of binary bytes received.  There can be no extra ascii characters sent by the terminal after the CRLF that terminates the line on which RECEIVE.BINARY resides (assuming that this command is issued interactively).  In other words, this routine immediately starts running KEY in a loop and interprets all incoming bytes as part of the binary data stream.  As usual, this function uses contiguous memory, so the byte after 0xBFFF on a given page is at 0x8000 on the following page.  This function does not GET the serial resource if SERIAL.ACCESS contains RELEASE.AFTER.LINE.

Attributes: M

RECEIVE.HEX ( xaddr1 <text> -- )

Accepts a download in standard Intel hex or Motorola S1 or S2 or S3 hex formats and initializes the RAM and/or onchip flash memory locations starting at the specified xaddr1 accordingly.  The first address specified in the <text> hex dump is stored in memory at xaddr1, and all subsequent bytes are stored in memory preserving the relative spacing of data specified in the <text> hex dump.  If the specified xaddr1 is 0xFFFFFFFF (that is, a 32-bit -1), the memory storage addresses are as specified in the hex dump itself.  The paged memory is treated as a contiguous memory space; recall that the location following 0xBFFF on a given page is location 0x8000 on the following page.  There is an unchecked error if the specified xaddr input parameter is in paged memory and the address embedded in the hex dump is in unpaged (common) memory, or vis versa.  Accepts empty lines.  If a format or checksum error is detected, emits an 'X' character to signal the error, but does not abort.  Aborts with a Missing delimiter message if the first character on a line is not a : or S character.  Terminates when an end-of-file record is received; the final line of an Intel hex dump is

:00000001FF

and the standard final line of a Motorola hex dump is

S9030000FC

although any S7, S8, or S9 termination record will terminate reception.  Motorola S0 header records are accepted and ignored.  Each input text line is temporarily stored at PAD.  Be sure that the PAD buffer is large enough to accommodate a full line (decimal 80 bytes or more is safe).  See the glossary entries for DUMP.INTEL, DUMP.S1, and DUMP.S2 for descriptions of Intel and Motorola hex formats.  Intel records must have a record type of 00.

Implementation detail: RECEIVE.HEX calculates an offset as the specified xaddr1 minus the first address specified in the <text> file.  This offset is then added to every byte's file address (specified in the <text> file) to calculate the destination address.  This scheme allows the data in a <text> hex dump file with arbitrary reported addresses to be loaded starting at any desired location in the memory space.

If the target memory is in onchip flash and a flash sector programming error occurs, this routine emits the ascii BELL character as a warning.
Pronunciation: receive-hex
Attributes: M

RECOVER.HANDLE ( xaddr -- [xhandle] or [0\0] )

Searches through the handle list for a handle that contains the specified base address xaddr.  If found, returns the heap item's xhandle; otherwise, returns 0\0. Useful for debugging.

RECURSE ( -- )

Compiles into the current definition a call to the word currently being defined.

Attributes: C, I

REDEFINE ( xcfa1\xcfa2 -- | xcfa1 = operational word, xcfa2 = null word )

Resolves a forward reference or redefines a word by writing a call to xcfa1, the extended code field address of an operational word, into the code field specified by xcfa2. Up to ten bytes are written into the code field of xcfa2.

To implement a forward reference (that is, to use a word before its action or operation has been defined), first define a null definition as:

: <null.definition.name>
   NO.OP ;

Then define words which call <null.definition.name> .

Then define the operational word as

: <operational.definition.name>
   words defining the operation   ;

Then execute

CFA.FOR <operational.definition.name>
CFA.FOR <null.definition.name>
REDEFINE

Now, all the words that were compiled with calls to <null.definition.name> will execute <operational.definition.name>. Of course, when REDEFINE is executed, xcfa2 must be in modifiable RAM.

REDEFINE may also be used during debugging.  If xcfa2 is the code field address of a word that is found to be buggy, a bug-free version with code field address xcfa1 can be defined, and a REDEFINE command will cause all compiled calls to the buggy routine to execute the debugged version instead:

CFA.FOR <debugged.definition.name>
CFA.FOR <buggy.definition.name>
REDEFINE

Two requirements must be met: xcfa2 must be in modifiable RAM, and the code field of xcfa2 must be at least ten bytes long so that the redefinition will not overwrite other words in the dictionary.  If you are compiling a library, you cannot REDEFINE a function in a different library.  There is no error checking.  See R: and RCODE for a more convenient way to redefine buggy functions.  For another (though less efficient) way to implement forward references, see EVALUATE.

REDIMMED ( #rows\#cols\matrix.xpfa -- )

Re-writes the contents of the parameter field of the specified dimensioned matrix.  Modifies the number of rows and columns in the parameter field to have the specified values without changing any data in the matrix.  Thus the data in the matrix is effectively reconfigured into the new number of rows and columns.  Error if the previous product of #rows times #columns is not equal to the product of the specified #rows times #cols.

REGISTER: ( addr <name> -- )

Typically used to define names for the HCS12's hardware registers, REGISTER: removes the next <name> from the input stream and defines an XCONSTANT called <name> which when executed leaves the specified register address under a 0 (designating the default page) on the data stack.  REGISTER: enforces a minimum WIDTH of 6 in the saved name to minimize non-unique names when defining registers.
Pronunciation: register-colon
Attributes: D

RELEASE ( xresource -- )

If the current task owns the resource variable referenced by xresource (i.e., if xresource contains the current task's xtask.id), releases the resource by storing 0\0 in xresource.  Otherwise, does nothing; this prevents a task from RELEASEing a resource controlled by another task.  Interrupts are not disabled and PAUSE is not executed.

See also GET and RESOURCE.VARIABLE:

RELEASE.AFTER.LINE ( -- n )

A constant which is the default value stored into the SERIAL.ACCESS user variable.  If stored into the SERIAL.ACCESS user variable of a task that is running the QED-Forth interpreter, prevents the low level I/O words KEY EMIT and ?KEY from executing GET or RELEASE on the active serial resource variable.  Rather, the interpreter (that is, QUIT) GETs the serial resource before each line is received and RELEASEs the serial resource after each line is interpreted.  This virtually eliminates the overhead required to GET and RELEASE during downloads.  CAUTION: In multitasking systems using both serial ports SERIAL1 and SERIAL2, the application code should include the command

RELEASE.ALWAYS     SERIAL.ACCESS !

or RELEASE.NEVER SERIAL.ACCESS !

before building the tasks.  This prevents contention that can occur if the default RELEASE.AFTER.LINE option is installed in the SERIAL.ACCESS user variable.

See also SERIAL.ACCESS, RELEASE.NEVER, and RELEASE.ALWAYS

RELEASE.ALWAYS ( -- n )

A constant.  Returns a value that, when stored into the SERIAL.ACCESS user variable, causes the low level I/O words KEY EMIT and ?KEY to always RELEASE the serial resource variable after each I/O operation.  This is useful if the task that has control over the serial line (for example, the task running the QED-Forth interpreter) wants to share access to the serial port.

See also SERIAL.ACCESS, RELEASE.NEVER, and RELEASE.AFTER.LINE

CAUTION: Depending on which terminal program you use, you may find that storing RELEASE.ALWAYS into the QED-Forth task's SERIAL.ACCESS variable decreases the sustainable download baud rate.  To assure the highest sustainable download baud rate, it is recommended that RELEASE.AFTER.LINE be stored in the QED-Forth task's SERIAL.ACCESS variable during program development.

CAUTION: In multitasking systems using both serial ports SERIAL1 and SERIAL2, the application code should include the command

RELEASE.ALWAYS     SERIAL.ACCESS !

or RELEASE.NEVER SERIAL.ACCESS !

before building the tasks.  This prevents contention that can occur if the default RELEASE.AFTER.LINE option is installed in the SERIAL.ACCESS user variable.

RELEASE.NEVER ( -- n )

A constant.  Returns a value that, when stored into the SERIAL.ACCESS user variable, prevents the low level I/O words KEY EMIT and ?KEY from executing the command SERIAL RELEASE.  This is useful if the task that has control over the serial line (for example, the task running the QED-Forth interpreter) does not want to share access to the serial port.

See also SERIAL.ACCESS, RELEASE.ALWAYS, and RELEASE.AFTER.LINE

CAUTION: Depending on which terminal program you use, you may find that storing RELEASE.NEVER into the QED-Forth task's SERIAL.ACCESS variable decreases the sustainable download baud rate.  To assure the highest sustainable download baud rate, it is recommended that RELEASE.AFTER.LINE be stored in the QED-Forth task's SERIAL.ACCESS variable during program development.

CAUTION: In multitasking systems using both serial ports SERIAL1 and SERIAL2, the application code should include the command

RELEASE.ALWAYS     SERIAL.ACCESS !

or RELEASE.NEVER SERIAL.ACCESS !

before building the tasks.  This prevents contention that can occur if the default RELEASE.AFTER.LINE option is installed in the SERIAL.ACCESS user variable.

RELOCATE.ONLY: ( page <segment.name> -- success? )

Relocates the code of the specified named segment to a parallel address starting at the specified page, and updates the segment’s entry in the eeprom segment array to point to the new code base page.  This routine does not relocate the required libraries of <segment.name>; see RELOCATE:. This routine does not relocate headers; see MOVE.HEADERS.

RELOCATE: ( page.offset <segment.name> -- success? )

Relocates the code of the specified named segment plus its REQUIRED.RELATIVE antecedents (plus their REQUIRED.RELATIVE antecedents, …) by moving them by page.offset pages, where page.offset is a 16bit signed offset.  Updates the eeprom segment array entry for each moved segment to point to the new code base page.  The user must make sure that the specified page.offset will be appropriate for all of the moved segments.  See RELOCATE.ONLY:. This routine does not relocate headers; see MOVE.HEADERS.

REPEAT ( -- )

Used inside a colon definition to mark the end of a BEGIN … WHILE … REPEAT loop structure.  Use as:

BEGIN    ...
flag WHILE    ...
REPEAT

See BEGIN and WHILE.

Attributes: C, I

REPORT.PAGES.LOADED ( -- )

Prints a single-line report of the pages loaded from external shadow flash to the parallel RAM pages upon a COLD restart, and summarizes the write-protect status of write protect region 1 (pages 0-0x0F) and write protect region 2 (pages 0x10-13).  The user can designate any valid pages in the range 00-0x1D for each of three areas using LOAD.PAGES.AT.STARTUP (see its glossary entry), and these designated page ranges are reported by this function.  For example, if the user has executed the commands:

0x00  5  1 LOAD.PAGES.AT.STARTUP
0x10  3  3 LOAD.PAGES.AT.STARTUP
1  WRITE.PROTECT   2 WRITE.ENABLE

then the next COLD restart or invocation of REPORT.PAGES.LOADED would print:

XFlash->RAM pages loaded: Area 1: 0x00-0x04  2: None  3: 0x10-0x12
WP1: ON  WP2: OFF

(The printout appears on a single line).

Attributes: M, S

REQUIRES.FIXED ( <segment.name> -- )

Writes the segment index obtained from the header of the specified <segment.name> segment into the required_segment table at the base of the currently compiling segment.  Clears bit 7 of the segment index to indicate that this required segment is fixed, meaning that if the requiring segment moves via a RELOCATE: command, then this segment does not move.  Sets bit 6 of the segment index if the <segment.name> corresponds to a library segment.  The information stored by this routine is used by the operating system to compile proper calls to the functions in the referenced segment.

REQUIRES.RELATIVE ( <segment.name> -- )

Writes the segment index obtained from the header of the specified <segment.name> segment into the required_segment table at the base of the currently compiling segment.  Sets bit 7 of the segment index to indicate that this required segment is relative, meaning that if the requiring segment moves via a RELOCATE: command, then this segment moves too.  Sets bit 6 of the segment index if the <segment.name> corresponds to a library segment.  The information stored by this routine is used by the operating system to compile proper calls to the functions in the referenced segment.

RESERVED ( u1\u2 -- u3 )

Used during definition of a structure to reserve an unnamed space equal to u2 bytes within the structure.  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.

Attributes: D

RESIZE.HANDLE ( xhandle\d -- flag )

Attempts to resize the heap item associated with xhandle so that it has a new size of d bytes.  Retains as much data as possible in the heap item.  The heap must have enough space to copy the heap item to be successful.  A true flag is returned if the heap item is successfully resized.  A false flag indicates failure (due to an invalid xhandle or inadequate heap space) and the original heap item is left unchanged.

RESOURCE.VARIABLE: ( <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 the resource variable's contents. <name> is referred to as a resource variable. Use as:

RESOURCE.VARIABLE: <name>

Resource variables are used in multitasked systems to control access to shared resources (for example, an A/D converter, serial port, block of memory, etc.) When the resource associated with <name> is available, <name> contains 0\0. When it is controlled by a task (and hence unavailable to other tasks), it contains the task id of the controlling task.  Before its first use, the resource variable must be initialized to 0\0. After initialization to 0\0, the only operators that should access the resource variable are GET ?GET and RELEASE.  The following resource variables are pre-defined in the QED-Forth kernel:

SERIAL            SPI.RESOURCE
SERIAL1.RESOURCE  SERIAL2.RESOURCE

Attributes: D

RESTORE ( -- )

Restores the memory map user variables stored by the last execution of SAVE to their respective user variables.  Restores DP, NP, VP, EEP, last xnfa in the FORTH vocabulary, CURRENT.HEAP, THIS.SEGMENT, and LAST.SEGMENT from a reserved area in EEPROM to the values stored by SAVE.  Useful for dictionary management and for recovery from crashes.

See also SAVE

RESTORE.ALL ( -- )

This handy utility function is typically typed at the terminal to restore the memory state that was saved using the SAVE.ALL function.  RESTORE.ALL is equivalent to:

0x00  0x18  LOAD.PAGES
RESTORE

The LOAD.PAGES operation write-enables pages 0x00 through 0x13, reads the saved contents of the external flash (put there by SAVE.ALL) into RAM pages 0x00 through 0x17, and restores the write-protect status to the state it was in before RESTORE.ALL was executed.  The RESTORE operation then loads all of the memory map pointers so that they have the values they had when the last SAVE or SAVE.ALL was executed.  Because the application code and names typically reside in pages 0x00 through 0x17, this SAVE.ALL and RESTORE.ALL pair provides a handy tool for managing the development process.  After downloading a program from the terminal into the RAM on the board, SAVE.ALL can be executed to back up the RAM contents to the shadow flash.  If the memory is corrupted by a software bug during development, the RAM and memory pointers can be restored by simply typing RESTORE.ALL at the terminal.  If the board’s power is cycled after SAVE.ALL has been executed, the RAM will be automatically restored from the shadow flash upon power-up; in this case simply executing RESTORE will complete the restoration process.  For additional information, See the glossary entries for RESTORE, SAVE.ALL, LOAD.PAGES, and LOAD.PAGES.AT.STARTUP.

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 memory page.  Be sure to schedule the use of this routine so that it does not interfere with any interrupt-based runtime procedures.

RESTORE.SEGMENT.NAMES ( segment.index -- )

Stores the last xnfa of specified segment into VFORTH and calls BUILD.HASH.TABLE; does nothing if specified segment = 0. There is an unchecked error if the specified segment has not been compiled.  This function is tolerant of the relocation, and is typically used in conjuction with segments that are relocated to flash memory.

See also COMPOSE.FLASH.INSTALLER

NOTE: The input parameter is a literal constant; do not use LAST.SEGMENT @ as this system variable contains zero after a COLD restart.

RIGHT.PLACES ( -- xaddr )

A user variable that holds the number of digits to be displayed to the right of the decimal point when a floating point number is printed in FIXED format.  The default value is 3.

See also F>FIXED$ and FP.DEFAULTS

Attributes: U

ROLL ( wn\wn-1\...\w0\+n -- wn-1\...\w0\wn | 0 ≤ +n ≤ 127 )

Transfers the +nth item (not including +n) on the data stack to the top of the data stack, where +n must be less than or equal to 127. The top stack item is item#0, the next is item#1, etc. 0 ROLL does nothing, 1 ROLL is equivalent to SWAP, and 2 ROLL is equivalent to ROT.  An unchecked error occurs if there are less than +n items on the data stack.

ROOM ( -- d )

d is the number of bytes available in the HEAP.

ROT ( w1\w2\w3 -- w2\w3\w1 )

Rotates the top three stack cells.
Pronunciation: rote

RP! ( -- )
Return stack: ( R: [...] -- )

Initializes the return stack pointer to be equal to the value in the user variable R0, thus clearing the return stack.  The first return stack item will be stored in the two bytes below the value in R0, and the stack grows downward in memory.  For example, if R0 = 0x1900, the first stack item is at memory locations 0x18FE and 0x18FF.  Forces a COLD restart if R0 is not in common RAM.
Pronunciation: r-p-store

RS485.INIT ( -- )

Initializes the bits that control the RS485 direction for both serial channels 1 and 2 as outputs, with the default starting states of the RS485 links set to the receive mode.  This routine is automatically called at each COLD or WARM restart or powerup.  Make sure that the onboard RS485 jumper for the specified RS485 channel is properly configured before attempting to use the RS485 interface.

RS485.RECEIVE ( n -- | n = 1 or 2 )

Places the RS485 transceiver for serial channel n in the receive mode, where n designates either the serial1 or serial2 channel.  Make sure that the onboard RS485 jumper for the specified RS485 channel is properly configured before attempting to use the RS485 interface.  Use care not to call this function while a character transmission is in progress, as the transmission will be corrupted; see RS485.TRANSMIT.DONE.

See also RS485.TRANSMIT

RS485.TRANSMIT ( n -- | n = 1 or 2 )

Places the RS485 transceiver for serial channel n in the transmit mode, where n designates either the serial1 or serial2 channel.  Make sure that the onboard RS485 jumper for the specified RS485 channel is properly configured before attempting to use the RS485 interface.

See also RS485.RECEIVE

RS485.TRANSMIT.DONE ( n -- flag | n = 1 or 2 )

Returns a true flag when the specified serial channel n has completed its transmission.  This function can be used to ensure that RS485.RECEIVE is not called while a character transmission is in progress.

RTI.ID ( -- n )

Returns the interrupt identity code for the real time interrupt.  Used as an argument for ATTACH.  Note that this interrupt is used by the multitasker.
Pronunciation: r-t-i-i-d

S0 ( -- xaddr )

User variable that contains the 16-bit address which is used by SP! to initialize the data stack pointer.  The first cell on the data stack occupies the 2 bytes below the address contained in S0, and the stack grows downward in memory.  After changing the contents of S0, the next ABORT or restart loads the value into the stack pointer (the Y register) to change the position of the stack.  The data stack is allocated in a 768 byte region in common memory after each COLD restart.  See SP!.
Pronunciation: s-zero
Attributes: U

S>D ( n -- d )

Sign-extends a single precision integer to a double precision equivalent.
Pronunciation: s-to-d

SAVE ( -- )

Saves the current memory map so that it may be restored later.  Saves DP, NP, VP, EEP, last xnfa in the FORTH vocabulary, CURRENT.HEAP, THIS.SEGMENT, and LAST.SEGMENT in a reserved area in EEPROM.  RESTORE fetches these quantities and places them in the appropriate user variables to restore the saved state.  Useful for dictionary management and for recovery from crashes.

SAVE.ALL ( -- flag | flag is true if operation was successful )

This handy utility function is typically typed at the terminal to save the current RAM contents and memory state so that it can be restored by simply typing RESTORE.ALL at the terminal.  SAVE.ALL is equivalent to:

0 18 STORE.PAGES   ( -- success? )   \ store pages 0-1x17->Xflash, takes 11 sec
0 18 1 LOAD.PAGES.AT.STARTUP   \ restore on subsequent COLD startups
SAVE               \ save memory pointers

The STORE.PAGES operation takes about eleven seconds to back up pages 0x00 through 0x17 to shadow flash.  The LOAD.PAGES.AT.STARTUP operation ensures that the saved contents will be automatically copied to pages 0x00-0x17 RAM upon subsequent power-ups and COLD restarts, and the SAVE operation writes the current memory pointers (DP, NP, VP, pointer to LATEST, segment control variables, etc.) to the EEPROM so they can be restored by RESTORE or RESTORE.ALL.  Because the application code and names typically reside in pages 0x00 through 0x17, this SAVE.ALL and RESTORE.ALL pair provides a convenient tool for managing the development process.  After loading a program from the terminal into the RAM on the board, SAVE.ALL can be executed to back up the RAM contents to the shadow flash.  If the board is turned off, or if the memory is corrupted by a software bug during development, the RAM and memory pointers can be restored by simply typing RESTORE.ALL at the terminal.  If the board’s power is cycled after SAVE.ALL has been executed, the RAM will be automatically restored from the shadow flash upon power-up; in this case simply executing RESTORE will complete the restoration process.  For more information, See the glossary entries for SAVE, RESTORE, STORE.PAGES, LOAD.PAGES.AT.STARTUP, and RESTORE.ALL.

CAUTION: This routine takes approximately 11 seconds to execute and disables interrupts for significant time periods while writing to the onboard shadow flash.  It is meant for use during program development.  If for some reason you choose to use this function in a program, be sure to schedule it so that it does not interfere with any interrupt-based runtime procedures.

SCALE ( n1\n2 -- n3 )

Arithmetically (i.e., preserving sign) shifts n1 by n2 bit places to yield signed result n3. If n2 is positive, n1 is shifted left; if n2 is negative, n1 is shifted right.  The absolute value of n2 determines the number of bits of shifting.  For example, 1 SCALE is equivalent to 2* and -1 SCALE is equivalent to 2/ . There is an unchecked error if the absolute value of n2 is greater than 15.

SCAN ( xaddr1\n1\n -- xaddr2\n2 )

xaddr2 is the extended address of the first instance of the specified 1- or 2-byte delimiter n in the n1 bytes following xaddr1. n2 is the count remaining in the string after the first non-char bytes have been skipped:

 n2 = n1 - (xaddr2 - xaddr1)

n1 and n2 are signed 16 bit counts; a negative value for n1 causes an unchecked error.  The string may cross a page boundary if a single-byte delimiter is specified (i.e., if the most significant byte of n = 0).  SCAN is used by WORD to locate the trailing delimiter of the next word in the input stream.

SCI0.ID ( -- n )

Returns the interrupt identity code for the asynchronous SCI0 serial communications interface, corresponding to the Serial1 port.  Used as an argument for ATTACH.
Pronunciation: s-c-i-zero-i-d

SCI1.ID ( -- n )

Returns the interrupt identity code for the asynchronous SCI1 serial communications interface, corresponding to the Serial2 port.  Used as an argument for ATTACH.
Pronunciation: s-c-i-one-i-d

SCIENTIFIC ( -- )

Sets the default printing format used by PrintFP, F.  and F>$ to scientific.

See also F>SCIENTIFIC$

SCIENTIFIC. ( r -- )

Prints r using SCIENTIFIC format.

See also F>SCIENTIFIC$
Pronunciation: scientific-dot
Attributes: M, S

SECTION$.XADDR ( -- xaddr )

A system variable that holds either zero or the 32-bit xaddress of a counted string that is set by SECTION: (see its glossary entry).  This default contents of this variable equal zero after a COLD restart.
Pronunciation: section-string-xaddress

SECTION: ( <.section_name> -- )

Declares a section name to be used when exporting C/assembly code via COMPOSE.C.ASM.CODE or COMPOSE.C.ASM.CODE.FOR.  This section name tells the C compiler where to locate the compiled definitions (wrapper functions) in the controller’s memory space.  The specified section name must begin with a . (dot) character.  SECTION: removes the next word <.section_name> from the input stream and, if it begins with the required . (dot) character, emplaces it as a counted string in the names area, and then stores the x$addr (address of the count) in the system variable SECTION$ADDR.  This routine aborts with a not found error if <.section_name> is not found on the same line as SECTION:, and aborts with an invalid parameter error if the section_name doesn't start with a dot.
Pronunciation: section-colon

SEGMENT.ARRAY.ADDR ( n -- addr )

Returns the eeprom segment array addr for the specified segment index n.  Aborts if the segment index is out of the allowed range 0 to 23. Information about the memory location of the segment is stored in a ten-byte structure at the SEGMENT.ARRAY.ADDR.  The contents are: a 3-byte code base page and address, followed by a 3-byte segment header page and address, followed by a 2-byte variable area base address, followed by a 2-byte EEPROM variable area base address.  The end user should never modify the contents of this array; the array is managed by the operating system.

SEGMENT.BUMP ( xaddr1\d\addr\flag -- xaddr2 )

Enforces the segment relocation rules to assist in automated segment loading.  xaddr1 is the proposed starting code xaddress for a loading segment, d is the code size, addr is the compile-time-start-address at which the segment was initially compiled, and the flag is true if the segment is a library, or false if the segment is an application.  Based on the input parameters, this routine decides if the xaddr1 needs to be bumped to the compile-time-start-addr on the next available page, and returns the (perhaps adjusted) xaddr2. This allows the TO.HERE mode to be used for smart segment loading. The SEGMENT.BUMP directive is automatically placed in the output file by COMPOSE.FORTH.INSTALLER, COMPOSE.FORTH.INSTALLER.FOR, and the BUILD segment routines; See their glossary entries.

SEGMENT.PRESENT ( n <segname> "timestamp" -- )

Verifies whether the segment named <segname> with specified index n and date/time string timestamp has already been loaded, and if so, prints the bell character (ascii 7) followed by the string:

#AlreadyLoaded

If the segment verification fails, nothing is printed.  The <segname> and timestamp must be on same line as the SEGMENT.PRESENT command.  There are no extra spaces between the “ marks in timestamp, and the timestamp string comparison is case sensitive (although the <segname> comparison is not case sensitive).

Example of use and description of operation:

Assume that a library segment named MYLIB has been loaded as segment number 1, and that the following DATE/TIME: command was included in the segment installer file:

DATE/TIME: ${Mon 11/23/05 12:05:32 PST}$

We now want to download either the full Forth installer file named MYLIB.fin, or the quick Forth installer file named MYLIB.qfin; the latter file does not include the S-record dump, and thus will load into the board more quickly.  We issue the command:

1 SEGMENT.PRESENT MYLIB "Mon 11/23/05 12:05:32 PST"

To verify whether the specified segment has been loaded, SEGMENT.PRESENT looks up the segment.xnfa corresponding to segment.index, compares it to the <segname> passed on the command line, then performs a case-sensitive comparison of the stored date/time string as set by the prior DATE/TIME: directive to the timestamp on the command line, and verifies that the checksum stored in the segment structure matches the calculated checksum of the code area.  If all of these comparisons match, then the bell character followed by the #AlreadyLoaded string is emitted to the serial port.  The terminal program traps this response, and implements logic to send the quick version of the install file to the board.  If no response is received, the full install file including the S-record code image is sent.  This approach optimizes download time by avoiding redundant S-record loads of code that already resides in memory.

Attributes: M, S

SELF.CLOCK.ID ( -- n )

Returns the interrupt identity code for the self-clock module on the HCS12. Used as an argument for ATTACH.
Pronunciation: self-clock-i-d

SEND ( wd\xmailbox -- )

PAUSEs until the mailbox with extended address xmailbox is empty (i.e., contains 0\0) and then stores the 32-bit message wd in xmailbox.  The message wd can be any 32-bit quantity except 0\0. For example, the message can be an xaddress that points to a block of data.  To ensure that the state of the mailbox is correctly determined, SEND disables interrupts for 0.75 to 1.55 microseconds.

See also ?SEND, RECEIVE, ?RECEIVE, and MAILBOX:

Attributes: M

SERIAL ( -- xresource )

A resource variable associated with the primary serial I/O port.  A synonym for SERIAL1.RESOURCE; see its glossary entry.

SERIAL.ACCESS ( -- xaddr )

A user variable containing a flag that controls when a task GETs and RELEASEs access to the serial resource.  If more than one task needs access to the serial I/O port, this flag can help specify which task (if any) gets priority use.  If SERIAL.ACCESS contains the value RELEASE.ALWAYS, then each I/O operation by KEY EMIT or ?KEY GETs the active serial resource before each I/O operation and RELEASEs the active serial resource after each character I/O operation is complete.  If SERIAL.ACCESS contains the value RELEASE.NEVER, then I/O operations called by the task always GET but never RELEASE the serial resource variable.  If SERIAL.ACCESS contains the value RELEASE.AFTER.LINE, then KEY EMIT and ?KEY never GET or RELEASE the serial resource.  Rather, the QED-Forth interpreter (that is, QUIT) GETs the serial resource before each line is received and RELEASEs the serial resource after each line is interpreted.  This virtually eliminates the overhead required to GET and RELEASE during downloads.  The default value stored in SERIAL.ACCESS after a COLD restart is RELEASE.AFTER.LINE.

CAUTION: In multitasking systems using both serial ports SERIAL1 and SERIAL2, the application code should include the command

RELEASE.ALWAYS  SERIAL.ACCESS !

or RELEASE.NEVER SERIAL.ACCESS !

before building the tasks.  This prevents contention that can occur if the default RELEASE.AFTER.LINE option is installed in the SERIAL.ACCESS user variable.

See also SERIAL1.RESOURCE, SERIAL2.RESOURCE, GET, RELEASE, KEY, EMIT, ?KEY, and QUIT

Attributes: U

SERIAL1.AT.STARTUP ( -- )

Initializes a flag in EEPROM which installs the primary serial port (serial1) as the default serial port used by the QED-Forth interpreter after each reset or restart.  The serial1 port is supported by the processor’s SCI0 hardware UART.

See also USE.SERIAL1 and SERIAL2.AT.STARTUP
Pronunciation: serial-one-at-startup

SERIAL1.RESOURCE ( -- xaddr )

A resource variable that mediates access to the primary serial port (serial1) supported by the processor’s SCI0 hardware UART.  Should be accessed only by the words GET ?GET and RELEASE.  Initialized to 0\0 by USE.SERIAL1 and at each reset or restart.  A synonym for SERIAL.

See also RESOURCE.VARIABLE:
Pronunciation: serial-one-resource

SERIAL2.AT.STARTUP ( -- )

Initializes a flag in EEPROM which installs the secondary serial port (serial2) as the default serial port used by the QED-Forth interpreter after each reset or restart.  The serial2 port is supported by the processor’s SCI1 hardware UART.

See also USE.SERIAL2 and SERIAL1.AT.STARTUP
Pronunciation: serial-two-at-startup

SERIAL2.RESOURCE ( -- xaddr )

A resource variable that mediates access to the secondary serial port (serial2).  The serial2 port is supported by the processor’s SCI1 hardware UART.  Should be accessed only by the words GET ?GET and RELEASE.  Initialized to 0\0 by USE.SERIAL2 and at each reset or restart.

See also RESOURCE.VARIABLE:
Pronunciation: serial-two-resource

SET.BITS ( byte1\xaddr -- )

For each bit of byte1 that is set, sets the corresponding bit of the 8 bit value at xaddr.  Disables interrupts for 0.5 microseconds to ensure an uninterrupted read/modify/write operation.

See also CLEAR.BITS

SET.BOOT.VECTOR ( xcfa\n -- )

Configures the function specified by xcfa as a boot vector with index n (0 ≤ n ≤ 15).  To support pre-coded “kernel extensions”, a set of “boot vectors” is implemented.  These vectors allow the posting of up to sixteen functions that are executed before the autostart program is run.  Typically, the boot vector programs are initializers that are automatically installed when a kernel extension is loaded onto the board.  They can be removed by executing CLEAR.BOOT.VECTORS or invoking the “factory cleanup” procedure described in the manual.  They can be disabled using ENABLE.BOOT.VECTORS, whose effect is reversable using DISABLE.BOOT.VECTORS.  An optional layer of checksum protection is provided for the boot vectors to ensure that corrupted or missing boot vectors are not executed; see CHECKSTART.ENABLE.

SET.WATCH ( u1\u2\u3\u4\u5\u6\u7\u8 -- )

meaning: ( 100ths.sec\sec\min\hr\day\date\month\yr – )

Sets the battery-operated real-time clock (if present) to the time, day, and date specified by u1 through u8. The stack items and their allowed ranges are:

item   description         range (decimal)
u8   year            0 - 99
u7   month              1 - 12
u6   date              1 - 31
u5   day of week         1 -  7
u4   hour of day           0 - 23
u3   minute after the hour      0 - 59
u2   seconds after the minute   0 - 59
u1   hundredths of seconds      0 - 99

Due to a hardware limitation, the hundredths of second parameter is ignored; it is included in the stack picture to maintain backward compatibility with prior code.  Once correctly set, the watch handles the differing numbers of days in each month, and correctly handles leap years.

See also READ.WATCH

SHIFT.SEGMENT.PAGE ( segment.index\page.offset -- )

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 segment’s current starting page plus the signed 16-bit page.offset.  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.  This routine does not move the segment’s headers; see MOVE.HEADERS.

See also MOVE.SEGMENT.TO.DEST.PAGE

SIGN ( n -- )

If n is negative, inserts a minus sign into the pictured output to the left of the previous character.  Used between <# and #>.

Attributes: S

SIGNED.D>S ( d -- n )

n is the signed 16-bit representation of 32-bit double number d.  FP.ERROR is set if d cannot be represented as a 16-bit signed integer.
Pronunciation: signed-d-to-s
Attributes: S

SINGLE.STEP ( -- xaddr )

A user variable that holds a 16-bit flag.  If the flag is true, a definition that has been compiled with TRACE ON stops and enters a special BREAK interpreter before each instruction during the trace.  If the flag is false, the BREAK interpreter is not automatically entered before each instruction during the trace. (Even if the flag is false, a keystroke from the terminal may still be used to enter the BREAK mode while the trace is in progress.)

See also BREAK and BREAK.ALL

Attributes: U

SIZE.OF ( -- u )

Compile Time: ( <name> – )

Removes <name> from the input stream, where <name> is a heap structure instance defined using D.INSTANCE: or H.INSTANCE: or V.INSTANCE: (an unchecked error occurs if <name> was not created by one of these three defining words).  SIZE.OF returns the size in bytes of <name>. If executing, leaves u on the stack.  If compiling, SIZE.OF compiles u as a literal in the current definition.

Attributes: I

SKIP ( xaddr1\n1\char -- xaddr2\n2 )

Skips the leading specified chars in the string whose first character is at xaddr1 and whose count is n1, returning the string specification xaddr2\n2. xaddr2 is the address of the first byte not equal to char found after searching from xaddr1 to at most xaddr1+n1 . n2 is the count remaining after the leading chars have been skipped:

n2 = n1 - ( xaddr2  - xaddr1 )

n1 and n2 are signed 16 bit counts; a negative value for n1 causes an unchecked error.  The string may cross a page boundary.  This routine is used by WORD to skip leading spaces when parsing the input stream.

SKIP> ( xaddr\u1\char -- xaddr\u2 )

Strips the trailing characters specified by char from the string located at xaddr by adjusting the count of the string.  Returns the new character count, u2, of the text string with trailing chars removed.  The string may cross a page boundary.
Pronunciation: skip-back

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

Fetches the 32-bit number d from the specified offset (0 ≤ offset ≤ 255) in the smart processor-carrying 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 5.8 microseconds for each byte fetched, with an access time of approximately 10 microseconds per byte.

Pronuciation: smart-i-o-two-fetch

SMART.IO.@ ( offset\module_num -- w )

Fetches the 16-bit number w from the specified offset (0 ≤ offset ≤ 255) in the smart processor-carrying 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 5.8 microseconds for each byte fetched, with an access time of approximately 10 microseconds per byte.

Pronuciation: smart-i-o-fetch

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

Fetches byte from the specified offset (0 ≤ offset ≤ 255) in the smart processor-carrying 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 5.8 microseconds, with an access time of approximately 11.5 microseconds.

Pronuciation: smart-i-o-c-fetch

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

Fetches the 32-bit floating point number r from the specified offset (0 ≤ offset ≤ 255) in the smart processor-carrying 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 5.8 microseconds for each byte fetched, with an access time of approximately 10 microseconds per byte.

Pronuciation: smart-i-o-f-fetch

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

Fetches the 32-bit xaddr from the specified offset (0 ≤ offset ≤ 255) in the smart processor-carrying 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 5.8 microseconds for each byte fetched, with an access time of approximately 10 microseconds per byte.

Pronuciation: smart-i-o-x-fetch

SMUDGE ( -- )

Toggles (i.e., reverses the state of) the smudge bit in the header of the most recently defined word in the CURRENT vocabulary.  If the smudge bit is set, the word cannot be found during a search of the dictionary.  The smudge bit is used to prevent execution of incomplete definitions, or to exclude headers from the dictionary list.  Used by : ; CODE and END.CODE.

See also SMUDGE:

SMUDGE: ( <name> -- )

Toggles (i.e., reverses the state of) the smudge bit in the header of <name>. If the smudge bit is set, the word cannot be found during a search of the dictionary, and is not printed by WORDS.  This routine is useful when “cleaning up” the dictionary to make unfindable headers that are not needed by the end user.

See also SMUDGE

Pronuciation: smudge-colon

SP! ( [...] -- )

Initializes the data stack pointer to be equal to the value in the user variable S0, thus clearing all items off the data stack.  The first stack item will be stored in the two bytes below the value in S0, and the stack grows downward in memory.  For example, if S0 = 0x1600, the first stack item will be at memory locations 0x15FE and 0x15FF.  Forces a COLD restart if S0 is not in common RAM.
Pronunciation: s-p-store

SPACE ( -- )

Emits one space character.  Equivalent to BL EMIT

Attributes: M

SPACES ( +byte -- )

Emits +byte spaces.  Does nothing if +byte is negative.

Attributes: M

SPAN ( -- xaddr )

A 16-bit user variable that contains the number of characters received by the last execution of EXPECT.

Attributes: U

SPI.CONFIG ( n1\n2\n3 -- | n1 = clock_edge_specifier; n2 = spibr_contents; n3 = spi_channel )

Configures the specified spi_channel (= 0, 1 or 2) based on the specified clock and baud rate input parameters.  The clock_edge_specifier is one of the constants SPI.FALLING.TRAILING.EDGE (the default after a power-up or restart for all 3 SPI channels), SPI.RISING.LEADING.EDGE, SPI.FALLING.LEADING.EDGE, or SPI.RISING.TRAILING.EDGE; See their glossary entries.  The clock idles in the low state for the first two of these clock_edge_specifiers, and idles in the logic high state for the latter two.  Each named constant describes the clock edge at which the data is sampled and valid; the data is typically transferred on the SPI bus one half cycle before the specified edge.  The spibr_contents input parameter is the baud rate specifier.  All other configuration parameters (master/slave, mode fault enable, SPI interrupt enable, bit order, /SS direction) are unchanged by this routine, and typically retain the state set by INIT.SPI for the SPI0 channel, or INIT.IP.SPI for the SPI1 and SPI2 channels.  INIT.SPI is called upon each reset and restart, but INIT.IP.SPI is not, and must be explicitly called by application code before calling SPI.CONFIG; See their glossary entries for configuration details.  The SPI0 channel’s default baud register contents equal 0x40 after a power-up or restart, corresponding to a 2 Mhz SPI clock frequency.  The default SPI.FALLING.TRAILING.EDGE with a 2 MHz baud rate is a common configuration, and is proper for the on-chip battery-backed Real-Time Clock which shares the SPI0 channel.  The SPI0 bus is brought out to the Wildcard bus and is available for communication with various peripherals, provided that each peripheral is selected by a unique chip select signal.  The processor’s SPI1 and SPI2 buses are reserved for interprocessor communications, and come up at a default baud rate of 5 MHz.  To select a configuration for a given SPI peripheral, consult the peripheral’s data sheet to discover the proper data-valid clock edge and baud rate.  Execute the interactive SPI.FREQUENCIES function from the terminal to obtain a printout summarizing the available baud rates and corresponding SPIBR baud register contents.

Example of use: Let’s assume that we are interfacing to an SPI peripheral that samples data on the SPI.RISING.TRAILING.EDGE of a clock that idles high, and can run at up to 4 MHz SPI clock frequencies.  Using SPI.FREQUENCIES, we note that the fastest attainable baud rate under 4 MHz is 3.33 MHz, corresponding to an spibr_contents parameter of 0x20. To interact with this peripheral device, we save the current SPI configuration state using SPI.SAVE, set the new configuration parameters using SPI.CONFIG, communicate with the peripheral by strobing its unique chip select signal and exchanging data using the SPI.EXCHANGE function, and restore the prior SPI configuration using SPI.RESTORE.  To implement this example, execute:

SPI.SAVE      ( d -- ) \ d = prior SPI configuration state; also does GET
SPI.RISING.TRAILING.EDGE 0x20 0 SPI.CONFIG
\ assert the unique chip select for the specific SPI peripheral here and
\ call SPI.EXCHANGE as needed to talk to the peripheral
\ de-assert the unique chip select for the specific SPI peripheral here
( d -- ) \ the prior SPI configuration data is still on stack
SPI.RESTORE ( -- ) \ restore prior configuration; also does RELEASE

This approach enables polite reconfiguration of the clock edge and baud rate for various slaves on the spi bus, and also prevents contention on the SPI bus because SPI.SAVE and SPI.RESTORE correctly GET and RELEASE the SPI.RESOURCE.

Implementation detail: Writes to the SPIxCR1 and SPIxBR registers.

SPI.EXCHANGE ( xaddr\+n1\flag\n2 -- | xaddr = buf, +n1 = #bytes, flag = readback?, n2 = spi.id )

Writes to the specified SPI channel n2 (= 0, 1 or 2) the contents of the buffer specified by xaddr and +n, where xaddr is the starting address, and +n is the number of bytes (0 ≤ +n < 32,768).  The buffer may cross page boundaries.  If the input flag is true, then a simultaneous readback from the specified remote SPI is performed, and the incoming bytes are written into the buffer (replacing the transmitted bytes).  Of course, if flag is true, the buffer at xaddr must be in RAM.  This routine does not GET or RELEASE the SPI.RESOURCE, nor does it modify the configuration of the SPI or activate any chip selects; the calling program must do these things.  This routine can operate at any SPI frequency that is supported by the hardware.  Recall that the default SPI channel that is used on the Wildcard bus is SPI0 (i.e., n2 = 0); SPI1 and SPI2 are reserved for inter-processor communications in multiprocessor systems.  This routine runs at approximately 7 microseconds per byte with a 2MHz SPI clock.
Pronunciation: s-p-i-exchange

SPI.FALLING.LEADING.EDGE ( -- n )

A constant that returns a clock edge specifier to be passed to the SPI.CONFIG function to specify the SPI (serial peripheral interface) data-valid clock edge.  SPI.FALLING.LEADING.EDGE specifies a clock that idles in the logic high state, with data valid and sampled on the falling leading edge transition of the clock.

Implementation detail: When passed to SPI.CONFIG, results in CPOL = 1 and CPHA = 0 in the SPI0CR1 register of the SPI0 channel.

SPI.FALLING.TRAILING.EDGE ( -- n )

A constant that returns a clock edge specifier to be passed to the SPI.CONFIG function to specify the SPI (serial peripheral interface) data-valid clock edge.  SPI.FALLING.LEADING.EDGE specifies a clock that idles in the logic low state, with data valid and sampled on the falling trailing edge transition of the clock.  Data is transferred on the rising leading clock edge so that it is stable and ready to be sampled at the falling trailing edge.  This is the default clock edge specifier established after a power-up or restart, and it is the proper configuration for communications with the onboard battery-backed Real-Time clock that is performed by the operating system’s SET.WATCH and READ.WATCH functions.

Implementation detail: When passed to SPI.CONFIG, results in CPOL = 0 and CPHA = 1 in the SPI0CR1 register of the SPI0 channel.

SPI.FREQUENCIES ( -- )

This function prints a formatted table of all 64 possible contents of the SPIBR register (serial peripheral interface baud rate) register in both hex and decimal, followed by the corresponding decimal SPI bus frequency.  Units are kHz, and the result is rounded to the nearest kHz.  To use, type this routine interactively at the terminal and examine the resulting data table to select the SPIBR register contents that yield the desired SPI bus clock frequency, and pass the selected value to SPI.CONFIG (see its glossary entry).  After a power-up or restart, the default SPI0 baud rate register contents equals 0x40, yielding a 2000 kHz (2MHz) baud rate which is the default for the SPI link on the Wildcard bus.  When executed, the first few lines of the resulting printout look like this:

Pass the selected SPIBR constant to SPIConfig (or to SPI.CONFIG in Forth).
0xSPIBR  SPIBR  BAUD.KHZ  (decimal)
  0x0     0      10000
  0x1     1       5000
  0x2     2       2500
  0x3     3       1250
   …

Attributes: M, S

SPI.RESOURCE ( -- xaddr )

A resource variable associated with the serial peripheral interface (SPI0) which is used for data transfer to and from the battery-backed real-time clock (also called the watch) and optionally for communications on the Wildcard bus.  Should be accessed only by the words GET ?GET and RELEASE.  Initialized to 0\0 by INIT.SPI and at each reset or restart.  SPI.RESOURCE is automatically invoked by the real-time clock device driver routines.

See also RESOURCE.VARIABLE:
Pronunciation: S-P-I-resource

SPI.RESTORE ( d -- )

Stores the specified 4-byte quantity d into the 4 sequential configuration registers of the SPI0 channel, and then executes SPI.RESOURCE RELEASE to make the SPI0 (serial peripheral interface 0) bus available to other tasks.  The input parameter d is typically the parameter returned by the SPI.SAVE function, and this SPI.RESTORE function re-saves the register contents to restore the prior SPI clock edge and baud rate specifications.  SPI0 is brought out to the Wildcard bus and is available for communication with various peripherals, provided that each peripheral is selected by a unique chip select signal.  See the glossary entries for SPI.SAVE and SPI.CONFIG for examples of use.

Note: This function cannot be used with SPI channels 1 and 2.

Implementation detail: Stores the 4-byte input parameter d into the four sequential SPI0 configuration registers SPI0CR1, SPI0CR2, SPI0BR, and SPI0SR, then executes SPI.RESOURCE RELEASE.

Attributes: M

SPI.RISING.LEADING.EDGE ( -- n )

A constant that returns a clock edge specifier to be passed to the SPI.CONFIG function to specify the SPI (serial peripheral interface) data-valid clock edge.  SPI.RISING.LEADING.EDGE specifies a clock that idles in the logic low state, with data valid and sampled on the rising leading edge transition of the clock.

Implementation detail: When passed to SPI.CONFIG, results in CPOL = 0 and CPHA = 0 in the SPI0CR1 register of the SPI0 channel.

SPI.RISING.TRAILING.EDGE ( -- n )

A constant that returns a clock edge specifier to be passed to the SPI.CONFIG function to specify the SPI (serial peripheral interface) data-valid clock edge.  SPI.RISING.TRAILING.EDGE specifies a clock that idles in the logic high state, with data valid and sampled on the rising trailing edge transition of the clock.  Data is transferred on the falling leading clock edge so that it is stable and ready to be sampled at the rising trailing edge.

Implementation detail: When passed to SPI.CONFIG, results in CPOL = 1 and CPHA = 1 in the SPI0CR1 register of the SPI0 channel.

SPI.SAVE ( -- d )

GETs the SPI.RESOURCE, then fetches and returns as a 32-bit quantity d the contents of the four configuration registers of the SPI0 (serial peripheral interface 0) channel.  After calling SPI.CONFIG to configure the SPI link and SPI.EXCHANGE to talk to the specified peripheral, the output parameter d should be passed by the application program as the input to SPI.RESTORE which restores the prior configuration and calls SPI.RESOURCE RELEASE to make the resource available to other tasks.  SPI0 is brought out to the Wildcard bus and is available for communication with various peripherals, provided that each peripheral is selected by a unique chip select signal.

Example of use: Let’s assume that we are interfacing to an SPI peripheral that samples data on the SPI.RISING.TRAILING.EDGE of a clock that idles high, and can run at up to 4 MHz.  Using SPI.FREQUENCIES, we note that the fastest attainable baud rate under 4 MHz is 3.33 MHz, corresponding to an spibr_contents parameter of 0x20. To interact with this peripheral device, we save the current SPI configuration state using SPI.SAVE, set the new configuration parameters using SPI.CONFIG, communicate with the peripheral by strobing its unique chip select signal and exchanging data using the SPI.EXCHANGE function, and restore the prior SPI configuration using SPI.RESTORE.  To implement this example, execute:

SPI.SAVE      ( d -- ) \ d = prior SPI configuration state; also does GET
SPI.RISING.TRAILING.EDGE 0x20 0 SPI.CONFIG
\ assert the unique chip select for the specific SPI peripheral here and
\ call SPI.EXCHANGE as needed to talk to the peripheral
\ de-assert the unique chip select for the specific SPI peripheral here
 ( d -- ) \ the prior SPI configuration data is still on stack
SPI.RESTORE ( -- ) \ restore prior configuration; also does RELEASE

This approach enables polite reconfiguration of the clock edge and baud rate for various slaves on the spi bus, and also prevents contention on the SPI bus because SPI.SAVE and SPI.RESTORE correctly GET and RELEASE the SPI.RESOURCE.

Implementation detail: GETs the SPI.RESOURCE variable, then fetches the four sequential SPI0 configuration registers SPI0CR1, SPI0CR2, SPI0BR, and SPI0SR and returns them as a 32-bit long.

Note: This function cannot be used with SPI channels 1 and 2..

Attributes: M

SPI0.ID ( -- n )

Returns the interrupt identity code for the synchronous serial peripheral interface channel 0 (SPI0).  Used as an argument for ATTACH.  SPI0 is used for data transfer to and from the battery-backed real-time clock (also called the watch) and optionally for communications on the Wildcard bus.
Pronunciation: s-p-i-zero-i-d

SPI1.ID ( -- n )

Returns the interrupt identity code for the synchronous serial peripheral interface channel 1 (SPI1).  Used as an argument for ATTACH.  SPI1 is reserved for inter-processor communications on multi-processor systems.
Pronunciation: s-p-i-one-i-d

SPI2.ID ( -- n )

Returns the interrupt identity code for the synchronous serial peripheral interface channel 1 (SPI2).  Used as an argument for ATTACH.  SPI2 is reserved for inter-processor communications on multi-processor systems.
Pronunciation: s-p-i-two-i-d

SQRT(2) ( -- r )

Places the floating point representation of the square root of 2 (1.41421) on the stack.
Pronunciation: square-root-of-two

STACK.FRAME ( +n -- [+n bytes]\xaddr )

Reserves +n bytes of room on the data stack and leaves xaddr that points to the top (lowest in memory) reserved byte of the data stack frame.  xaddr is equal to the stack pointer before the xaddr is placed on the stack.  xaddr is the base address of the stack frame.  If +n is odd it is incremented to reserve an integer number of cells (of two bytes each) on the stack.  STACK.FRAME is typically used to create a temporary variable space within colon definitions so that re-entrant code may be written.  FRAME.DROP is used to drop the stack frame off the data stack.

See also PF.STACK.FRAME

STANDARD.RESET ( -- )

Undoes the effect of the COLD.ON.RESET command so that subsequent resets will result in the standard warm-or-cold startup sequence.

START.HEAP ( -- xaddr )

A variable that holds the extended address of the start of the current heap.  The xaddr left on the stack by START.HEAP is equal to CURRENT.HEAP - 4. Initialized by IS.HEAP.

START.TIMESLICER ( -- )

Starts the timeslice clock and begins timeslice multitasking.  Initializes the RTI real-time interrupt vector (if it wasn't already initialized) so that the multitasking executive/elapsed-time clock routine services the interrupt.  Enables the RTI interrupt mask and globally enables interrupts by clearing the I bit in the condition code register of each built task.

Notes:

1. The default timeslice clock period of 1.024 msec can be changed with the command MSEC.TIMESLICE.PERIOD.

2. START.TIMESLICER does not initialize the value in TIMESLICE.COUNT; execute INIT.ELAPSED.TIME if you wish to initialize the clock count to 0\0.

3. After a restart, the system is configured so that timeslice multitasking can begin at any time; if no other tasks have been built, the main QED-Forth task is the only task in the task loop.

4. The timeslice clock must be running to use the BENCHMARK: function.

5. The timeslicer's interrupt service routine disables interrupts for the duration of a task switch which requires 5 microseconds plus 0.5 microseconds for each ASLEEP task encountered in the task list.

STATE ( -- xaddr )

A user variable that indicates the compilation state.  If the contents of STATE equal 0, the system is in execution mode.  If the contents are non-zero, the system is in compilation mode.  STATE is modified by the commands [ and ].

Attributes: U

STATUS ( -- xaddr | xaddr is also the task's xtask.id )

A user variable that contains the status of a task.  Typically contains one of the 16-bit constants AWAKE or ASLEEP.  An ASLEEP task does not run as the multitasking executive goes around the round robin task list.  STATUS is the first user variable in the user area, so the extended address returned by executing STATUS is also the base address of the user area.  This base address is also referred to as the task identifier or task id; it is the address in common memory used to identify a particular task.

See also (STATUS)

Attributes: U

STATUS.AT.STARTUP ( -- )

Initializes a flag in EEPROM that enables the status report that is typically printed at each COLD and WARM restart.  The status print is enabled by default after a factory cleanup.  Enables the REPORT.PAGES.LOADED printout at subsequent COLD restarts, and enables 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 NO.STATUS.AT.STARTUP or do a factory clean.  To temporarily suppress the status printouts during a COLD restart, use QUIET.COLD.

STOP.TIMESLICER ( -- )

Stops the multitasker's timeslice clock by disabling the local RTI interrupt mask.  Cooperative (PAUSE-invoked) task switching is not affected.  Note that this command also stops QED-Forth's elapsed-time clock, and that the timing feature of the BENCHMARK: command cannot be used unless the timeslice clock is running.

See also START.TIMESLICER

STORE.PAGES ( page1\n -- flag | page1 = starting.page; n = number of pages; flag = success? )

For the specified n-page range starting at page1, stores the contents from each page in external RAM to the parallel (virtual) page in external flash, returning a true flag if the flash was programmed successfully.  All referenced pages must be in the range 00-0x1D; pages outside this range are ignored and result in the return of a false flag.  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.

Example of use: To back up all of the ram pages accessible by this routine and store them in the nonvolative shadow flash, execute:

0  0x1E  STORE.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 a significant period during the write of each 1 Kbyte block to the external flash.  Be sure to schedule the use of this routine so that it does not interfere with any interrupt-based runtime procedures.

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

STRING-> ( u1\u2 -- u3 )

Adds a named member to the structure being defined and reserves room for a counted string in the structure.  u2 is the number of characters in the string; u2+1 bytes are reserved to allow room for the string's count byte.  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: string
Attributes: D

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

Adds a named member to the structure being defined and reserves room for a (sub)structure of size u2 bytes in the structure being defined.  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: struct
Attributes: D

STRUCTS-> ( u1\u2\u3 <name> -- u4 )

Adds a named member to the structure being defined and reserves room for u2 (sub)structures 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 size of the (sub)structure, and u4 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: structs
Attributes: D

STRUCTURE.BEGIN: ( <name> -- xpfa\0 )

Begins a structure definition and creates a named constant <name> which, when executed, returns the size of the structure in bytes.

Implementation detail: <name>'s parameter field is at xpfa, and its initial contents equal 0. STRUCTURE.BEGIN: leaves the xpfa and the initial size on the stack.  The size is incremented throughout the structure's definition.  STRUCTURE.END stores the total size of the structure into the xpfa of the structure constant <name>.
Pronunciation: structure-begin
Attributes: D

STRUCTURE.END ( xpfa\u -- | u is the structure's size )

Marks the end of a structure definition.  Stores u, the total number of bytes in the structure being defined, into the xpfa of the structure constant created by STRUCTURE.BEGIN:.

See also STRUCTURE.BEGIN:

Attributes: D

SWAP ( w1\w2 -- w2\w1 )

Exchanges the top two stack cells.

SWAP.ARRAYS ( array.xpfa1\array.xpfa2 -- )

Interchanges the contents of the parameter fields of the two specified arrays and leaves the heap undisturbed, thus rapidly swapping the two arrays.

SWAP.MATRIX ( matrix.xpfa1\matrix.xpfa2 -- )

Interchanges the contents of the parameter fields of the two specified matrices and leaves the heap undisturbed, thus rapidly swapping the two matrices.

SWI.ID ( -- n )

Returns the interrupt identity code for the software interrupt (SWI).  Used as an argument for ATTACH.  See the SWI instruction in the assembler glossary.
Pronunciation: s-w-i-i-d

TAB.WIDTH ( -- xaddr )

A 16-bit user variable that contains the number of spaces that EXPECT places in the TIB to replace each incoming TAB character (ascii 09).  Replacing tabs with spaces ensures that tab-delimited words can be interpreted.  The default value is 1.

See also EXPECT

Attributes: U

TALK.TO.MASTER ( -- )

A marker used to end the datastream started by TALK.TO.SLAVE.  This routine is legal only after TALK.TO.SLAVE has been executed, and functions only on hardware that includes a slave HCS12 coprocessor.

TALK.TO.SLAVE ( -- )

A utiltity function that allows communications with the slave HCS12 processor via the master's RS232 serial port.  This function may be used only on hardware that includes a slave HCS12 coprocessor.  This routine is typically used to download PDQScreen image data to the slave's flash through the master's serial port.  Note that this function changes the configuration of PortH, PortH_Dir, and SPI1 and SPI2; these are reserved for the interprocessor bus and are not available for general purpose use.  The data exchange terminates when TALK.TO.MASTER appears as first word on a line from the PC to the master; after this normal serial communications resume via the master RS232 port.

TASK'S.USER.VAR ( xaddr1\xtask.id -- xaddr2 )

Converts the xaddress of a specified user variable xaddr1 in the current task to the xaddress of the equivalent user variable xaddr2 in the task specified by xtask.id.  Facilitates the modification of user variables in other tasks.  Use with care.  For example, to put a task named OTHER.TASK asleep, execute

ASLEEP  STATUS  OTHER.TASK  TASK'S.USER.VAR  !

Pronunciation: task's-user-variable

TASK: ( xtask.id <name> -- )

Removes the next <name> from the input stream and creates an XCONSTANT that, when executed, leaves the task identifier xtask.id on the stack.  xtask.id is the base xaddress of the user area of the new task being defined.  An error is issued if xtask.id is not in common RAM.  xtask.id is also referred to as the task's STATUS address.

See also ALLOCATE.TASK: and STATUS

NOTE: To optimize stack timing on the 68HCS12 processor, all task user areas should be located in the on-chip RAM at addresses below 0x4000 (available on-chip RAM starts at 0x2000).  Tasks allocated in the off-chip common RAM at 0x4000-0x7FFF will exhibit a slight increase in the number of processor cycles required for stack accesses to odd addresses.

Attributes: D

TCNT.OVERFLOW ( -- n )

A channel identifier constant that can be passed to ECT.INTERRUPT.ENABLE (to enable an interrupt when TCNT overflows), ECT.INTERRUPT.DISABLE (to disable interrupt generation when TCNT overflows) or ECT.CLEAR.INTERRUPT.FLAG (to clear the flag bit associated with the TCNT overflow).  TCNT is a free-running 16-bit counter that provides the time base for the Enhanced Capture Timer (ECT) resources including the input capture (IC), output compare (OC) and other timer-controlled channels.  TCNT is readable using the TCNT.READ function.  TCNT overflow occurs when the counter transitions from 0xFFFF to 0x0000. The overflow can generate an interrupt and/or toggle output compare (OC) lines; see OC.TOGGLE.ON.OVERFLOW and OC.NO.TOGGLE.ON.OVERFLOW.  The glossary entry for ECT.PRESCALER includes a discussion of the TCNT period and overflow times.

TCNT.READ ( -- u )

Returns the contents of the free-running TCNT timer, a read-only 16-bit register that continously counts from 0x0000 to 0xFFFF without stopping.  TCNT provides the time base for the Enhanced Capture Timer (ECT) including the input capture (IC), output compare (OC) and other timer-controlled channels.  See also TCNT.OVERFLOW, ECT.PRESCALER, OC.TOGGLE.ON.OVERFLOW, and OC.NO.TOGGLE.ON.OVERFLOW.  The glossary entry for ECT.PRESCALER presents a discussion of the TCNT period and overflow times, and includes some important notes regarding maintenance of the free-running counter.

TEN ( -- r )

Pushes the floating point number 10. onto the data stack.

THEN ( -- )

Synonym for ENDIF . Used inside a colon definition to mark the end of an IF … ELSE … THEN or IF … THEN conditional structure.  The word following THEN is executed after the IF or ELSE (if present) part of the conditional executes.  An error is issued if THEN is not paired with IF or ELSE in a colon definition.

See also IF and ELSE

Attributes: C, I

THIS.PAGE ( -- byte )

Returns the contents of the page latch which indicates the current page.  THIS.PAGE is equivalent to (PAGE.LATCH) (C@)

THIS.SEGMENT ( -- xaddr )

A system variable that holds the 16-bit segment index of the currently open segment.  This variable should never be directly modified by the programmer; its value is controlled by the segment management and operating system routines.  Its value is printed in the ID: field by .MAP and is typically reported upon each COLD and WARM restart.  The kernel is assigned the segment index 0, which is the default after a COLD restart.  A maximum of 23 additional segments (libraries and applications) can be defined.

THIS.SEGMENT.XBASE ( -- xaddr )

A system variable that holds the 32-bit code base xaddress of the currently open segment, which is also the xaddress of the segment structure that contains memory allocation information and the required_segment table.  This variable should never be directly modified by the programmer; its value is controlled by the segment management and operating system routines.  Its value is printed in the Code Base: field by .MAP and is typically reported upon each COLD and WARM restart.  The kernel is assigned the segment xbase 0\0, which is the default after a COLD restart.
Pronunciation: this-segment-x-base

THIS.SEGMENT.XNFA ( -- xaddr )

A system variable that holds the 32-bit extended name field address of the segment header corresponding to the currently open segment.  This variable should never be directly modified by the programmer; its value is controlled by the segment management and operating system routines.  The default contents after a COLD restart equal 0\0.
Pronunciation: this-segment-x-n-f-a

TIB ( -- xaddr | xaddr is the start of the terminal input buffer )

Returns the starting xaddr of the terminal input buffer.  Equivalent to UTIB X@. The terminal input buffer may be on any page, but may not cross a page boundary.  The default size of the terminal input buffer is 96 bytes.

See also QUERY

Attributes: U

TIMESLICE.COUNT ( -- xaddr )

Returns the extended address of the system variable TIMESLICE.COUNT.  It contains a 32-bit count of the number of clock ticks on the timeslicer clock.  The period of the clock is set by MSEC.TIMESLICE.PERIOD.  TIMESLICE.COUNT must only be read using the atomic read word |2@|, i.e.

TIMESLICE.COUNT |2@|

See READ.ELAPSED.SECONDS and READ.ELAPSED.TIME.

TO ( [n] or [r] or [xaddr] or [d] -- | depends on type of self fetchers or locals )

Compile Time: ( <name> – )

Stores a value into the named self-fetching or local variable.  Removes <name> from the input stream.  If in compilation mode, compiles code that, when later executed, will store the value on top of the stack into the self-fetching or local variable.  If in execution mode, stores the value on top of the stack into the self-fetching or local variable.  If <name> represents a 32-bit self-fetching variable (i.e., created by REAL: DOUBLE: or XADDR:) or a 32-bit local variable (i.e., one whose name begins with D& or d& or F& or f& or X& or x&), then a 32-bit value is removed from the stack and stored; otherwise, a 16-bit value is removed from the stack and stored.

Attributes: I

TO.EEPROM ( xaddr1\addr2\u -- flag | xaddr1=src, addr2=dest, u = byte count )

Transfers the specified number of bytes u (0 ≤ u ≤ 65,535) starting at the specified source extended address xaddr1, to the specified destination 16-bit address addr2 in on-chip eeprom, and returns a success flag.  This routine programs only on-chip eeprom.  The source xaddr1 may be anywhere in memory; it may even be in the eeprom which is being programmed.  This routine returns a flag equal to -1 if the programming was successful, or 0 if the programming failed. (If any locations in the EEPROM are programmed more than 10,000 times, the cell may wear out causing a failure flag to be returned).  Caution: This routine disables interrupts for 30 msec per 4-byte eeprom segment.  The prolonged disabling of interrupts by TO.EEPROM can adversely affect real-time servicing of interrupts.  This routine is not re-entrant, as it uses a fixed content buffer.  The buffer is shared by on-chip and off-chip flash programming.  If multitasking access to this routine is required, define a resource variable and use GET and RELEASE to manage access to these flash programming routines.

TO.FLASH ( xaddr1\xaddr2\u -- flag | xaddr1=src, xaddr2=dest, u = byte count )

Transfers the specified number of bytes u (0 ≤ u ≤ 65,535) starting at the specified source extended address xaddr1, to the specified destination extended address xaddr2 in on-chip flash, and returns a success/failure flag.

This routine programs only on-chip flash pages (0x30-3F for 256K processors, or 0x20-3F for 512K processors), but note that pages 0x38-3F are write protected and reserved for the operating system.  To program external flash, see TO.XFLASH.

The source xaddr1 may be anywhere in memory; it may even be in the flash which is being programmed.  This routine returns a flag equal to -1 if the programming was successful, or 0 if the programming failed.  Reasons for failure include trying to program a page that is not a writeable on-chip flash page. (If any locations in the flash are programmed more than 1,000 times, the cell may wear out causing a failure flag to be returned).

Caution: This routine disables interrupts for 35 milliseconds per segment (there are 512 bytes/segment for the 256K HCS12, or 1024 bytes/segment for the 512K HCS12).  The prolonged disabling of interrupts by TO.FLASH can adversely affect real-time servicing of interrupts.  This routine is not re-entrant, as it uses a fixed content buffer.  The buffer is shared by on-chip and off-chip flash programming.  If multitasking access to this routine is required, define a resource variable and use GET and RELEASE to manage access to the flash programming routines.

TO.FLASH.MANY ( xaddr1\xaddr2\ud -- flag | xaddr1=src, xaddr2=dest, ud = byte count )

Transfers the specified number of bytes ud starting at the specified source extended address xaddr1, to the specified destination extended address xaddr2 in on-chip flash, and returns a success/failure flag.

This routine programs only on-chip flash pages (0x30-3F for 256K processors, or 0x20-3F for 512K processors), but note that pages 0x38-3F are write protected and reserved for the operating system.  To program external flash, see TO.XFLASH.  The source xaddr1 may be anywhere in memory; it may even be in the flash which is being programmed.

This routine returns a flag equal to -1 if the programming was successful, or 0 if the programming failed.  Reasons for failure include trying to program a page that is not a writeable on-chip flash page. (If any locations in the flash are programmed more than 1,000 times, the cell may wear out causing a failure flag to be returned).

Caution: This routine disables interrupts for 35 msec per segment (there are 512 bytes/segment for the 256K HCS12, or 1024 bytes/segment for the 512K HCS12).  The prolonged disabling of interrupts by TO.FLASH can adversely affect real-time servicing of interrupts.  This routine is not re-entrant, as it uses a fixed content buffer.  The buffer is shared by on-chip and off-chip flash programming.  If multitasking access to this routine is required, define a resource variable and use GET and RELEASE to manage access to the flash programming routines.

TO.HEAP ( xhandle -- flag )

If xhandle is a valid 32-bit handle in the current heap, the heap item associated with the xhandle is returned to the heap (de-allocated), the heap is compacted, and a true flag is returned.  If xhandle is not a valid handle in the current heap, no action is taken and a false flag is returned.

TO.HERE ( -- n )

A constant that specifies that a library should be built/dumped so that it loads at the load time dictionary HERE xaddress, as modified by SEGMENT.BUMP (see its glossary entry).  TO.HERE 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.

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

Transfers +n bytes starting at the specified xaddr in memory, to the Wildcard with hardware address module_num starting at an address specified by offset (0 ≤ offset ≤ 255), where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  Also works for smart processor-carrying Wildcards.

See also TO.IO.REGISTER and FROM.IO
Pronunciation: to-i-o

TO.IO.REGISTER ( xaddr\offset\module_num\+n -- )

Transfers +n bytes starting at the specified xaddr in memory, to the Wildcard with hardware address module_num at a fixed address specified by offset (0 ≤ offset ≤ 255), where modules 0-7 implement standard speed modules, and modules 8-15 implement slow-access-timing modules.  The destination Wildcard address is not incremented as the transfer proceeds.  Also works for smart processor-carrying Wildcards.

See also TO.IO
Pronunciation: to-i-o-register

TO.MEMORY ( xaddr1\xaddr2\u -- | xaddr1=src, xaddr2=dest, u = byte count )

This routine is an onchip-flash-smart version of CMOVE.  It transfers the specified number of bytes u (0 ≤ u ≤ 65,535) starting at the specified source extended address xaddr1, to the specified destination extended address xaddr2. The destination can be in on-chip RAM, external RAM, or on-chip flash.  Unlike TO.FLASH, this routine does not report a programming error (such as trying to program a write-protected region of on-chip flash), so the flash programming is unverified.

Restrictions on use: The destination region must be either entirely in onchip flash or entirely in ram.  If both the source and destination are in on-chip flash and the source and destination regions overlap, memory propagation will occur if xaddr2 > xaddr1. If the destination is in flash, this routine not re-entrant and it disables interrupts, as described in the glossary entries of TO.FLASH and TO.XFLASH.  The prolonged disabling of interrupts by this routine can adversely affect real-time servicing of interrupts.

TO.XFLASH ( xaddr1\xaddr2\u -- flag | xaddr1=src, xaddr2=dest, u = byte count )

Transfers the specified number of bytes u (0 ≤ u ≤ 65,535) starting at the specified source extended address xaddr1, to the specified destination extended address xaddr2 in eXternal (shadow) flash, and returns a success flag.  This routine programs only the external flash at virtual shadow pages 0x00-0x1F.  To program the processor’s on-chip flash, see TO.FLASH.  The source is typically in the external RAM mapped as 16 Kbyte pages at addresses 0x8000-BFFF on pages 0x00-0x1D (RAM pages 0x1E and 0x1F are not accessible).  The external flash is mapped as a virtual paged device with 16 Kbyte pages at addresses 0x0000-0x3FFF on pages 0x00-0x1F; thus the destination xaddress must be in this range.  This routine returns a flag equal to -1 if the programming was successful, or 0 if the programming failed.  Reasons for failure include trying to program a region that includes an invalid xaddress. (If any locations in the flash are programmed more than 1,000 times, the cell may wear out causing a failure flag to be returned).  Caution: This routine disables interrupts for 12 msec per sector.  The default sector size is 256 bytes; the sector size is read from the external flash chip’s ID byte and stored in EEPROM at each factory cleanup.  The prolonged disabling of interrupts by TO.XFLASH can adversely affect real-time servicing of interrupts.  This routine is not re-entrant, as it uses a fixed content buffer.  The buffer is shared by on-chip and off-chip flash programming.  If multitasking access to this routine is required, define a resource variable and use GET and RELEASE to manage access to the flash programming routines.

Pronunication: to-x-flash

TOGGLE.BITS ( byte1\xaddr -- )

For each bit of byte1 that is set, reverses the state of the corresponding bit of the 8 bit value at xaddr.  Disables interrupts for 0.5 microseconds to ensure an uninterrupted read/modify/write operation.

TRACE ( -- xaddr )

A user variable that contains a 16-bit flag.  If true, this flag causes a call to a trace routine to be compiled before each compiled word in a colon or code definition.  The trace instruction (a headerless routine called DO.TRACE) can facilitate debugging.  If a definition has been compiled while TRACE is ON, then when the word is executed (if DEBUG is ON) the compiled trace routine prints out the name of each called subroutine in the definition as it executes, along with the stack picture after that step in the definition.  If DUMP.REGISTERS is ON, the contents of the 68HC12's registers are printed; this aids in the debugging of assembly coded routines.  If SINGLE.STEP is ON, the BREAK mode is entered after each step in the definition.  The BREAK mode is also entered if any character is received by QED-Forth while a trace is in progress.  To add even more flexibility and power to the debugger, the first thing that DO.TRACE does is to execute the code whose xcfa is stored in the user variable TRACE.ACTION.  The default action is NO.OP, but the programmer can define any action and install it using IS.TRACE.ACTION; see IS.TRACE.ACTION for further details.

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

Attributes: U

TRAILING.ZEROS ( -- xaddr )

A user variable that contains a 16-bit flag.  If the flag is false, trailing zeroes are not printed when a floating point number is displayed in fixed or floating format.  If true, trailing zeros are displayed.  The default value is false.  See F>FIXED$ and F>FLOATING$.

Attributes: U

TRANSFER.HEAP.ITEM ( xhandle1\xaddr -- [xhandle2] or [0\0] )

Copies the heap item specified by xhandle1 in the current heap into the heap whose CURRENT.HEAP is equal to xaddr.  If the operation is successful, returns the 32-bit handle xhandle2 of the new heap item; if unsuccessful, does nothing and returns 0\0. To copy a heap item within a single heap, use DUP.HEAP.ITEM.

TRAP.ID ( -- n )

Returns the interrupt identity code for the illegal opcode trap.  Used as an argument for ATTACH
Pronunciation: trap-i-d

TRIGGER.EDGE ( n\channel_id -- | n = edge_identifier )

Based on the trigger edge_identifier n, configures the trigger edge for the input capture or pulse-accumulator specified by channel_id.  Valid edge identifier inputs are the named constants TRIGGER.OFF (the default after a power-up or hardware reset), TRIGGER.ON.RISING.EDGE, TRIGGER.ON.FALLING.EDGE, or TRIGGER.ON.ANY.EDGE.  Valid channel_id’s are input capture (IC) channels 0 through 7, 8-bit pulse accumulator channels 0 through 3, or the named 16-bit PULSE.B accumulator.  Do not use this function to configure PULSE.A.  The arguments PULSE.A, PULSE.A.FALLING.EDGE, PULSE.A.RISING.EDGE, or PULSE.A.GATED.HIGH PULSE.A.GATED.LOW are not valid inputs for this TRIGGER.EDGE function; see PULSE.A.SETUP.

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 the INPUT.CAPTURE routine and this TRIGGER.EDGE routine, and then enabled for pulse counting using the PULSE.ENABLE function (for 8 bit pulse accumulators) or the PULSE.B.SETUP function (for 16 bit pulse accumulators).  To configure the PULSE.B trigger edge, make sure that channel 0 is an input capture by executing 0 INPUT.CAPTURE or PULSE.B INPUT.CAPTURE, and call TRIGGER.EDGE with channel_id = 0 or PULSE.B.

Examples of use: To count rising-edge pulses on the 16-bit PULSE.B accumulator without generating interrupts, execute:

PULSE.B  INPUT.CAPTURE
TRIGGER.ON.RISING.EDGE  PULSE.B  TRIGGER.EDGE
FALSE TRUE PULSE.B.SETUP

To configure input capture 4 to record the value of TCNT on any rising or falling edge, execute:

TRIGGER.ON.ANY.EDGE 4 TRIGGER.EDGE
4 INPUT.CAPTURE

Implementation detail: Writes a 2-bit field associated with specified channel in TCTL3/4 registers to configure the specified input compare or pulse accumulator edge trigger.

TRIGGER.OFF ( -- n )

A 16-bit constant that returns an edge_identifier that can be passed as an argument to TRIGGER.EDGE.  TRIGGER.OFF disables the triggering of the specified input capture or pulse accumulator channel; this is the default after a power-up or hardware reset.

TRIGGER.ON.ANY.EDGE ( -- n )

A 16-bit constant that returns an edge_identifier that can be passed as an argument to TRIGGER.EDGE.  TRIGGER.ON.ANY.EDGE enables triggering on both rising (low-to-high) and falling (high-to-low) edges for the specified input capture or pulse accumulator channel.

TRIGGER.ON.FALLING.EDGE ( -- n )

A 16-bit constant that returns an edge_identifier that can be passed as an argument to TRIGGER.EDGE.  TRIGGER.ON.FALLING.EDGE enables triggering on falling (high-to-low) edges for the specified input capture or pulse accumulator channel.

TRIGGER.ON.RISING.EDGE ( -- n )

A 16-bit constant that returns an edge_identifier that can be passed as an argument to TRIGGER.EDGE.  TRIGGER.ON.RISING.EDGE enables triggering on rising (low-to-high) edges for the specified input capture or pulse accumulator channel.

TRUE ( -- flag | flag = -1 )

Puts a boolean true flag equal to -1 on the data stack.

TUCK ( w1\w2 -- w2\w1\w2 )

Copies the top data stack cell to below the next data stack cell.  TUCK is equivalent to SWAP OVER.

TYPE ( xaddr\cnt -- )

If cnt is greater than zero, emits cnt (0 < cnt ≤ 255) characters beginning at location xaddr.  xaddr is typically the beginning of a text string and cnt is the text string's character count.  There is an unchecked error if cnt is outside the range 0 to 255. The string may cross a page boundary.

See also COUNT.TYPE and LTYPE

Attributes: M

TYPE.END ( u1\u2\u3 -- max{u1,u2,u3} )

Marks the end of a TYPE.OF: construct within a structure definition.

See also TYPE.OF: and OR.TYPE.OF:
Attributes: D

TYPE.OF: ( u -- u\u\u )

Marks the beginning of a TYPE.OF: construct within a structure definition.  This allows fields to be defined for variant data types.  Each variant type is designated by an OR.TYPE.OF: declaration, and the TYPE.OF: construct is terminated by TYPE.END.  For example, the following structure allows a member to be referred to either as a 32-bit xhandle or as a separate handle and page:

STRUCTURE.BEGIN: HEAP.STRUCTURE.PF
   TYPE.OF:
      XHNDL->   +XHANDLE
   OR.TYPE.OF:
      PAGE->   +HNDL.PAGE
      ADDR->   +HNDL.ADDR
   TYPE.END
      ADDR->   +END.HEAP
STRUCTURE.END

Pronunciation: type-of
Attributes: D

U*/MOD ( u1\u2\u3 -- u4\u5 | do u1*u2/u3; u4 = remainder; u5 = quotient )

Multiplies two unsigned integers u1 and u2 producing an intermediate unsigned double number result which is divided by unsigned integer u3 to yield an integer remainder u4 and quotient u5. An unchecked error occurs on overflow.  Division by zero (u2=0) yields u4 = u5 = -1 .

See also */MOD
Pronunciation: u-star-slash-mod

U. ( u -- )

Prints unsigned integer u with no leading spaces and 1 trailing space.
Pronunciation: u-dot
Attributes: M, S

U/ ( u1\u2 -- u3 | u3 = u1/u2 )

Divides unsigned integer u1 by unsigned integer u2, giving the unsigned integer quotient u3. Division by 0 (u2 = 0) results in a quotient of –1.

See also /
Pronunciation: u-slash

U/MOD ( u1\u2 -- u3\u4 | u3 = remainder, u4 = quotient )

Divides unsigned integer u1 by u2, giving the unsigned integer quotient u4 and remainder u3. Division by 0 (u2 = 0) results in a quotient of -1 and an indeterminant remainder.

See also /MOD
Pronunciation: u-slash-mod

U2/ ( u1 -- u2 | u2 = u1 / 2 )

Divides the unsigned number u1 by 2 giving u2.

See also 2/
Pronunciation: u-two-slash

U< ( u1\u2 -- flag )

Flag is TRUE if unsigned integer u1 is less than unsigned integer u2 and FALSE otherwise.
Pronunciation: u-less-than

U> ( u1\u2 -- flag )

Flag is TRUE if unsigned integer u1 is greater than unsigned integer u2 and FALSE otherwise.
Pronunciation: u-greater-than

U>D ( u -- ud )

Converts unsigned integer u to its double number equivalent ud by placing a 0 on the data stack above u.
Pronunciation: u-to-d

U?KEY ( -- xaddr )

A user variable that contains the extended code field address of the ?KEY routine.

See also ?KEY
Pronunciation: u-question-key
Attributes: U

UABORT ( -- xaddr )

A user variable that contains the extended code field address of the user-supplied abort routine that is executed if the CUSTOM.ABORT flag is TRUE.  If CUSTOM.ABORT is FALSE, ABORT executes the default (ABORT) routine.  UABORT is initialized by COLD to contain the xcfa of (ABORT).

See also (ABORT) and CUSTOM.ABORT
Pronunciation: u-abort
Attributes: U

UD*S ( ud1\u -- ud2 | ud2 = ud1 * u )

Multiplies unsigned double number ud1 by unsigned single precision number u giving the unsigned double number result ud2. An unchecked error occurs on overflow.
Pronunciation: u-d-star-s

UD.R ( ud\+byte -- | +byte = width )

Prints the unsigned double number ud right-justified in a field of +byte characters.  If +byte is less than or equal to the number of characters to be printed, the number is printed with no extra spaces.

See also D.R and HEX.D.R
Pronunciation: u-d-dot-r
Attributes: M, S

UD>R$ ( ud\+b -- xaddr\cnt | +b = width )

Converts the unsigned 32-bit number ud to a counted string right justified in a field of minimum width +b.  The string is built below PAD, and the count is stored at xaddr-1.

See also D>R$

Attributes: S

UEMIT ( -- xaddr )

A user variable that contains the extended code field address of the EMIT routine.

See also EMIT
Pronunciation: u-emit
Attributes: U

UERROR ( -- xaddr )

A user variable that contains the extended code field address of the error routine that is executed if the CUSTOM.ERROR flag is TRUE.  If CUSTOM.ERROR is FALSE, all system errors call the default (ERROR) routine which prints descriptive error messages. UERROR is initialized by COLD to contain the xcfa of a simple default error handler that prints the hexadecimal system error number and executes ABORT.

See also ((ERROR)), (ERROR), CUSTOM.ERROR, and ABORT
Pronunciation: u-error
Attributes: U

UFIXX ( r -- u )

Rounds the positive floating point number r to the nearest unsigned integer u.  Equivalent to DFIXX D>S.  Overflow errors are not checked.

See also DFIXX

Attributes: S

UFLOT ( u -- r )

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

See also DFLOT and FLOT
Pronunciation: u-float
Attributes: S

UKEY ( -- xaddr )

A user variable that contains the extended code field address of the KEY routine.

See also KEY
Pronunciation: u-key
Attributes: U

UM* ( u1\u2 -- ud | ud = u1 * u2 )

Multiplies unsigned integers u1 and u2 giving the unsigned double precision product ud.
Pronunciation: u-m-star

UM/MOD ( ud1\u1 -- u2\ud2 | u2 = remainder, ud2 = quotient )

Divides unsigned double number ud1 by unsigned integer u1 to give an unsigned single-precision remainder u2 and an unsigned double number quotient ud2. Division by 0 (u1=0) yields u2 = -1 and ud2 = -1.
Pronunciation: u-m-slash-mod

UMAX ( u1\u2 -- [u1] or [u2] )

Retains the greater of two unsigned integers and drops the other.

See also MAX
Pronunciation: u-max

UMIN ( u1\u2 -- [u1] or [u2] )

Retains the lesser of two unsigned integers and drops the other.

See also MIN
Pronunciation: u-min

UMOD ( u1\u2 -- u3 | u3 = remainder of u1/u2 )

Divides unsigned integer u1 by unsigned integer u2, giving the unsigned remainder u3. Division by zero results in an indeterminant remainder.

See also MOD
Pronunciation: u-mod

UNDERFLOW ( -- )

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

UNIQUE.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 word is defined that already exists in the CURRENT or CONTEXT vocabularies.  If the flag is false, no warning is issued when non-unique words are added to the dictionary.
Pronunciation: unique-message

UNLOOP ( -- )
Return stack: ( R: w1\w2 -- | discards the loop limit and index )

Removes the top two cells from the return stack.  If you need to immediately EXIT a word definition from inside a DO…LOOP, call UNLOOP to discard the loop index and limit before executing EXIT to exit the definition.  To exit a definition from within nested do loops, execute one UNLOOP for each level of nesting.  Make sure that there are no additional items on the return stack (e.g., resulting from a >R command).  UNLOOP is a synonym for XR>DROP which drops two cells from the return stack.

Attributes: C

UNSAVE.ALL ( -- )

This function provides a “partial undo” operation after SAVE.ALL has been executed.  UNSAVE.ALL undoes the SAVE.PAGES.AT.STARTUP action that was performed by SAVE.ALL so that no pages will be restored on subsequent power-ups or COLD restarts.  Note that the memory pointer SAVE operation that was performed by SAVE.ALL is unchanged and still valid until SAVE or SAVE.ALL is executed again.

Implementation detail: UNSAVE.ALL is equivalent to:

0 0 1 LOAD.PAGES.AT.STARTUP

In other words, for area_id 1, it specifies that no pages are to be loaded from shadow flash to RAM upon subsequent COLD restarts.

UNTIL ( flag -- )

Used inside a colon definition to mark the end of a BEGIN … UNTIL loop structure which terminates based on the value of flag.  If flag is true, the loop terminates and execution continues with the word following UNTIL.  If flag is false, looping continues and execution passes to the word following BEGIN.  Use as:

BEGIN    ... words to be executed ...
flag UNTIL

An error is issued if BEGIN and UNTIL are not properly paired within a definition.

Attributes: C, I

UP ( -- xhandle | xhandle contains 16-bit user pointer )

Places on the stack the 32-bit extended address that contains the 16-bit base address of the current task's user area.  Executing UP @ is equivalent to executing (STATUS) ; both return the 16-bit base address (in common memory) of the current task.
Pronunciation: u-p

UPAD ( -- xaddr )

User variable that holds the 32 bit xaddr of PAD.  The contents of UPAD must point to modifiable RAM, and there must be at least 32 bytes of RAM below PAD for number/string conversion.  PAD may be on any page, but may not cross a page boundary.  To change the location of PAD, store the new xaddress into UPAD using X!.

See also PAD
Pronunciation: u-pad
Attributes: U

UPOCKET ( -- xaddr )

User variable that holds the 16-bit addr of POCKET which is in common memory.  To change the location of POCKET, store the new xaddress into UPOCKET using !. Note that FIND executes COLD if POCKET is not in common RAM.
Pronunciation: u-pocket
Attributes: U

UPPER.CASE ( x$addr -- x$addr )

Converts all of the characters in the counted string at x$addr to upper case letters.  The string may not cross a page boundary.

URANGE ( u1\u2\u3 -- u1\flag )

Flag is TRUE if u1 is greater than or equal to u2 and less than or equal to u3. Otherwise flag is FALSE.  Uses unsigned comparison.

See also RANGE
Pronunciation: u-range

URANGE.OF ( u1\u2\u3 -- [u1] or [] )

Used inside a CASE … ENDCASE structure to mark the beginning of a conditional statement.  If u2 ≤ u1 ≤ u3 (using unsigned math) then u1, u2, and u3 are dropped and execution continues with the words between URANGE.OF and ENDOF and then skips to the word after ENDCASE.  Otherwise, u2 and u3 are dropped and execution continues after the next ENDOF.  Use as:

n1 CASE
u2 u3 URANGE.OF executed if n1 in range (u2,u3)    ENDOF
u4 u5 URANGE.OF executed if n1 in range (u4,u5)   ENDOF
words to be executed if not in range (u2,u3) or (u4,u5)
ENDCASE

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

See also CASE, OF, RANGE.OF
Pronunciation: u-range-of
Attributes: C, I

USE.SERIAL1 ( -- )

Installs the primary serial port (serial1) as the serial link used by the QED-Forth interpreter and called by EMIT, ?KEY, and KEY.  The serial1 port is associated with the processor’s SCI0 on-chip hardware UART.  Stores the xcfa of KEY1 in UKEY, the xcfa of ?KEY1 in U?KEY, and the xcfa of EMIT1 in UEMIT.  Thus the vectored routines KEY, ?KEY, and EMIT will automatically execute the serial1 routines KEY1, ?KEY1, and EMIT1 respectively.  Initializes the resource variable SERIAL1.RESOURCE (also called SERIAL) to 0\0, and initializes the resource variable associated with the prior serial channel in use (typically either SERIAL1.RESOURCE or SERIAL2.RESOURCE) to 0\0. Does not disable the serial2 port.

See also BAUD
Pronunciation: use-serial-one

USE.SERIAL2 ( -- )

Installs the secondary serial port (serial2) as the serial link used by the QED-Forth interpreter and called by EMIT, ?KEY, and KEY.  The serial2 port is supported by the processor’s SCI1 hardware UART.  USE.SERIAL2 stores the xcfa of KEY2 in UKEY, the xcfa of ?KEY2 in U?KEY, and the xcfa of EMIT2 in UEMIT.  Thus the vectored routines KEY, ?KEY, and EMIT will automatically execute the serial2 routines KEY2, ?KEY2, and EMIT2 respectively.  Initializes the resource variable SERIAL2.RESOURCE to 0\0, and initializes the resource variable associated with the prior serial channel in use (typically either SERIAL1.RESOURCE or SERIAL2.RESOURCE) to 0\0. Does not disable the serial1 port.

See also BAUD
Pronunciation: use-serial-two

USER ( +byte <name> -- | +byte = offset from user area base address )

Removes the next <name> from the input stream and creates a user variable called <name> which when executed places on the stack an extended address equal to the user base address (i.e., the value in UP) plus the specified offset +byte.  Use as:

+byte USER <name>

The user area holds system variables.  The kernel word #USER.BYTES returns the number of bytes in the user area that are already used by the kernel.  Thus when defining a new user variable, +byte should be greater than or equal to #USER.BYTES and less than 255 (the maximum size of the user area).

Attributes: D

USER.SPECIFIED ( -- n )

A constant that specifies that a library should be built/dumped so that it loads at a user-specified xaddress that is explicitly typed into the exported library file by the user.  USER.SPECIFIED 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.  Use of this constant is not recommended except in special cases; see IN.PLACE and TO.HERE.

UTIB ( -- xaddr )

User variable that holds the 32 bit xaddr of the TIB (terminal input buffer).  To change the location of TIB, store the new xaddress into UTIB using X!. The terminal input buffer may be on any page, but may not cross a page boundary.
Pronunciation: u-t-i-b
Attributes: U

V, ( w -- )

Stores w at the next available location in the variable area and increments the variable pointer VP by 2. An error occurs if w is not correctly stored; e.g.  if VP does not point to RAM.  An error occurs if the V, operation causes VP to be incremented across the boundary between 0xBFFF (the last valid address in a given page) and 0xC000 (the start of the common kernel area).
Pronunciation: v-comma

V.INSTANCE: ( u <name> -- | u is the size of the structure )

Removes <name> from the input stream, creates a structure instance called <name>, and allocates u bytes in the variable area starting at VHERE for the structure instance.  The V in V.INSTANCE: refers to the Variable area where the instance is allocated.  Compare with D.INSTANCE:.  When <name> is executed, the base address of the allocated structure instance is placed on the data stack.  Typical use:

<structure.name>  V.INSTANCE:  <name>

where <structure.name> was defined using

STRUCTURE.BEGIN: <structure.name> ... STRUCTURE.END

Executing <structure.name> leaves the structure size n on the stack, and V.INSTANCE: <name> allocates and names the instance.  Executing

SIZE.OF <name>

places the allocated size of the instance on the stack.  The instance may not cross a page boundary.  V.INSTANCE: is segment-relocation-smart, and returns the correct result even when defined inside a library or application segment that is relocated to a location that is different from its initial compilation address.
Pronunciation: v-instance
Attributes: D

VALID.HASH ( -- xaddr )

A system variable that whose contents are set to 0x1357 by BUILD.HASH.TABLE upon each restart.  The hash is a linked list; a hash link is stored in each header in the Forth vocabulary to enable fast compilation.  If for some reason the hash needed to be disabled, this could be accomplished by executing VALID.HASH OFF after each restart.

VALLOT ( n -- )

Reserves n bytes in the variable area by incrementing the variable pointer VP by n.  An error occurs if the VALLOT operation causes VP to be incremented across the boundary between 0xBFFF (the last valid address in a given page) and 0xC000 (the start of the common kernel area).
Pronunciation: v-allot

VARIABLE ( <name> -- )

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

VARIABLE <name>

VARIABLE is segment-relocation-smart, and 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.

Attributes: D

VC, ( byte -- )

Stores byte at the next available location in the variable area and increments the variable pointer VP by 1. An error occurs if byte is not correctly stored; e.g.  if VP does not point to RAM.  An error occurs if the VC, operation causes VP to be incremented across the boundary between 0xBFFF (the last valid address in a given page) and 0xC000 (the start of the common kernel area).
Pronunciation: v-c-comma

VERSION ( -- x$addr )

Returns the xaddress of a packed counted ascii string that contains the version number of the kernel.  This string is part of the prompt that is printed at cold and warm startup.  To print the contents, execute VERSION COUNT.TYPE

VFORTH ( -- xaddr )

A user variable that contains the xnfa (extended name field address) of the top word in the FORTH vocabulary, which is the default vocabulary to which the programmer's definitions are typically appended.  In turnkeyed (autostarted) applications that require the interpreter to run in the final application, the autostart word should initialize VFORTH to contain the xnfa of the last word defined.  For example:

: LAST.WORD    [ LATEST ] 2LITERAL VFORTH X!
<other code goes here>
;
PRIORITY.AUTOSTART:  LAST.WORD

See LATEST, CONTEXT, CURRENT, FIND, and NFA.FOR.
Pronunciation: v-forth
Attributes: U

VHERE ( -- xaddr )

Places on the stack the xaddr of the next available location in the variable area.  Equivalent to VP X@.
Pronunciation: v-here
Attributes: U

VOCABULARY ( <name> -- )

Creates and initializes to LATEST a 32 bit xhandle in the variable area.  When <name> executes, this xhandle is stored into the user variable CONTEXT so that the <name> vocabulary branch is searched first during dictionary searches.

See also FIND

Restrictions on use: VOCABULARY is not compatible with MOVE.HEADERS.  If you need to move the headers of a library or application segment, use the default Forth vocabulary for all definitions.

Attributes: D

VOID ( -- n )

Returns the constant value 0 which is the number of bytes in a parameter of type void 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.  This is a synonym for VOID.SIZE.

See also PARAMS(

VOID.SIZE ( -- n )

Returns the constant value 0 which is the number of bytes in a parameter of type void 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.  This is a synonym for VOID.

See also PARAMS(

VP ( -- xaddr )

User variable that contains the 32-bit Variable Pointer.  The contents of VP are placed on the stack by VHERE and are modified by VALLOT.  The command VP X@ is equivalent to VHERE; it yields the xaddr of the next available location in the variable area.  The command VP @ is equivalent to VPAGE; it yields the page of the variable area.
Pronunciation: v-p
Attributes: U

VPROTOTYPE: ( <forth.variable.name> <${prototype.string}$> -- )

For the specified <forth.variable.name> corresponding to a variable 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 printed 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 variable in the *.h file. VPROTOTYPE: 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.variable.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.variable.name> and ${ must be on the same line as VPROTOTYPE:.  A single-word return type specifier such as void or char* must be used in the prototype string.  The variable 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
FVARIABLE LIBVAR1
VPROTOTYPE: LIBVAR1 ${ float libvar1 }$  \ no ; in var prototype!
VARIABLE LIBVAR2
VPROTOTYPE: LIBVAR2 ${ int libvar2 }$     \ no ; in var prototype!
C.CALLABLE OFF   \ revert to default non-c-callable

WAIT.TIL.MATCH ( mask\match_value\xaddr\u -- flag | u = max_timeslice_counts; flag = timeout )

The 16-bit mask and match_value parameters have been named in the stack picture for convenience.  This timing routine loops and PAUSEs until the following equation is true:

[{mask} AND {16bit_contents_of_xaddr}] = match_value

In other words, on each pass through the loop, WAIT.TIL.MATCH fetches the 16-bit contents of the specified xaddr, performs the logical AND operation with the specified 16-bit mask parameter, and compares the result to the specified 16-bit match_value parameter.  If they are equal, the wait loop terminates; otherwise, the looping continues.  In addition, if START.TIMESLICER has been executed and interrupts are globally enabled, this routine loops and PAUSEs for a maximum of the specified max_timeslice_counts (a 16-bit unsigned value) and returns a true flag if a timeout occurred without the specified match occurring.  If the specified match occurs before the timeout, this function returns a zero flag.  The default timeslice count period is 1.024 milliseconds; see MSEC.TIMESLICE.PERIOD.

Example of use: Assume that the variable at xaddress 0x8000 on page 0x0C is being updated by an interrupt routine, and we want to wait until it has the value 0x1234. To test for this equality condition, we will pass the mask equal to 0xFFFF (so we examine all 16 bits at xaddr), and we specify the match_value as 0x1234. Assuming we want to enforce a timeout of approximately 9 milliseconds (9 timeslice counts), we would execute:

DECIMAL
START.TIMESLICER   \ this also globally enables interrupts
0xFFFF 0x1234 0x8000 0x0C 9  WAIT.TIL.MATCH   ( -- timeout? )

The WAIT.TIL.MATCH function will exit at the earlier one of the following two conditions: 1. the match is found (in which case the returned timeout flag is false), or, 2. the timeout occurred after 9 ms (in which case the returned timeout flag is true).

Attributes: M

WARM ( -- )

Restarts the QED-Forth system, initializes key hardware registers (as listed in the COLD glossary entry), and clears the data and return stacks and executes ABORT.  Unlike COLD, WARM does not initialize all of the user variables to their default values.  Upon a restart caused by a power-up or reset, the operating system checks a 16 bit location in the user area and, if it contains the pattern 0x1357, the operating system assumes that RAM has already been initialized and a WARM (instead of a COLD) restart can be performed.  To force every restart to be a COLD restart, execute COLD.ON.RESET, which can be reversed by STANDARD.RESET.

WATCH.RESULTS ( -- xaddr )

Returns the xaddr of an 8-byte buffer that is loaded with the current time and date information each time READ.WATCH executes.  The contents of the buffer are as follows:

offset   description               range (decimal)
  0      hundredths of seconds     always reads as 0
  1      seconds after the minute   0 - 59
  2      minute after the hour      0 - 59
  3      hour of day                0 - 23
  4      day of week                1 -  7
  5      date                       1 - 31
  6      month                      1 - 12
  7      year                       0 - 99

WE.ALL ( -- )

This handy function write enables the RAM pages 0x00 through 0x13, undoing the effect of a prior execution of WP.ALL.  WE.ALL is equivalent to:

1 WRITE.ENABLE   \ write enables pages 0x00-0x0F
2 WRITE.ENABLE   \ write enables pages 0x10-0x13

Write protected RAM cannot be corrupted, even by a program crash that tries to overwrite memory.  During program development, the programmer can type

WP.ALL
SAVE.ALL

to protect the program and back it up to shadow flash so that it is automatically reloaded on subsequent power-ups, COLD restarts, or by executing RESTORE.ALL.  After invoking WP.ALL, and before attempting to download a new version of your program, execute WE.ALL to write-enable the RAM so the board will accept the download into RAM.

WHILE ( flag -- )

Used inside a colon definition to mark the beginning of the while true portion of a BEGIN … WHILE … REPEAT loop.  If flag is TRUE, the loop continues and the words between WHILE and REPEAT are executed, after which control is transferred to the word following BEGIN.  If flag is FALSE, the loop terminates and execution continues with the word following REPEAT.  Use as:

BEGIN
      words to be iteratively executed
flag WHILE    words to be iteratively executed
REPEAT

An error is issued if BEGIN WHILE and REPEAT are not properly paired inside a colon definition.

Attributes: C, I

WIDTH ( -- xaddr )

A 16-bit user variable that contains the number of characters saved in a name entry by CREATE.  Minimum value is 2, maximum is 63.

Attributes: U

WORD ( n1 -- xaddr | n1 is delimiter, xaddr = POCKET )

Parses the next word delimited by the specified 1- or 2-byte delimiter n1 from 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.  Moves the parsed word as a counted string to the buffer at POCKET in common memory, and places the xaddr of POCKET on the data stack.  If the word has more than 63 characters, only the first 63 characters are moved and the count is clamped to 63. WORD appends a space to the counted string in POCKET; the space is not included in the string's count.  If the input stream is exhausted when WORD executes, the count left at POCKET equals 0. If the specified delimiter n1 is a space, then leading spaces are ignored.  The input stream is the terminal input buffer TIB, and the value of >IN specifies the offset from the start of the input stream to the first character to be parsed.  WORD leaves >IN pointing 1 byte past the terminating delimiter unless the input stream is exhausted, in which case >IN is left pointing 1 byte past the last valid location in the input stream.  The interpreter executes BL WORD to parse input commands, and then calls (#FIND) to search for the parsed command in the dictionary.  To parse strings longer than 63 characters, use PARSE, PARSE.BUFFER, or LPARSE.

Attributes: M

WORD.IN.BUFFER ( xaddr\cnt -- addr )

A primitive called by WORD.  This routine moves the lesser of cnt or 63 characters from xaddr, storing the moved characters as a counted string at POCKET.  Adds a terminating BL (not included in cnt) after the string in pocket.  Returns the addr of POCKET (which is in common RAM) on the data stack.

WORDS ( -- )

Prints all un-smudged words in the CURRENT vocabulary.  WORDS incorporates PAUSE.ON.KEY, so the printout can be terminated by typing a carriage return or . (dot); it can be suspended and resumed by typing other characters, and it responds to XON/XOFF handshaking (see PAUSE.ON.KEY).  Each word is printed left justified in a field of 16 or 32 characters, 3 names per line.  Characters that are not saved in the headers are represented by the appropriate number of _ characters.

Attributes: M

WP.ALL ( -- )

This handy function write protects RAM pages 0x00 through 0x13. It is equivalent to:

1 WRITE.PROTECT   \ write protects pages 0x00-0x0F
2 WRITE.PROTECT   \ write protects pages 0x10-0x13

Write protected RAM cannot be corrupted, even by a program crash that tries to overwrite memory.  During program development, the programmer can type

WP.ALL
SAVE.ALL

to protect the program and back it up to shadow flash so that it is automatically reloaded on subsequent power-ups, COLD restarts, or by executing RESTORE.ALL.

NOTE: After invoking WP.ALL, and before attempting to download a new version of your program, execute WE.ALL to write-enable the RAM so the board will accept the download into RAM.

WRITE.ENABLE ( n -- | n = 1 or 2 )

Undoes the effect of WRITE.PROTECT for the specified region n.  If n = 1, this routine allows writes to external RAM pages 0x00-0x0F, and if n = 2 this routine write enables external RAM pages 0x10-0x13.

Implementation detail: Sets a bit in reserved system EEPROM; this information is written to the on-board logic upon each restart to configure the writeability of the specified memory pages.

WRITE.PROTECT ( n -- | n = 1 or 2 )

Disallows writes for the specified region n.  If n = 1, this routine disallows writes to external RAM pages 0x00-0x0F, and if n = 2 this routine disallows writes to external RAM pages 0x10-0x13.

Implementation detail: Clears a bit in reserved system EEPROM; this information is written to the on-board logic upon each restart to configure the write protection of the specified memory pages.  See WRITE.ENABLE.

X! ( xaddr1\xaddr2 -- | xaddr1 is stored at xaddr2 )

Stores the extended address xaddr1 at xaddr2. A synonym for 2!.

Caution: Make sure that the xaddress that you are storing is not subject to relocation.  See the glossary entry for XCONSTANT.REL for more details.
Pronunciation: x-store

X.OVER.N ( xaddr\w -- xaddr\w\xaddr )

Copies the extended address located under the top data stack cell to the top of the data stack.
Pronunciation: x-over-n

X1-X2>D ( xaddr1\xaddr2 -- d )

Subtracts xaddr2 from xaddr1 to yield the signed double number result d.  There is an unchecked error if one of the xaddresses is in common memory (addr ≤ 0x7FFF or addr ≥ 0xC000) and the other is in paged memory (0x8000 ≤ addr ≤ 0xBFFF).  Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.
Pronunciation: x-one-minus-x-two-to-d

X1-X2>N ( xaddr1\xaddr2 -- n )

Subtracts xaddr2 from xaddr1 to yield the signed integer result n.  There is an unchecked error if one of the xaddresses is in common memory (addr ≤ 0x7FFF or addr ≥ 0xC000) and the other is in paged memory (0x8000 ≤ addr ≤ 0xBFFF), or if the difference cannot be represented as a signed 16-bit integer.  Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.
Pronunciation: x-one-minus-x-two-to-n

X2DROP ( xaddr1\xaddr2 -- )

Drops two extended addresses (4 cells) from the data stack.
Pronunciation: x-two-drop

X2DUP ( xaddr1\xaddr2 -- xaddr1\xaddr2\xaddr1\xaddr2 )

Duplicates the top two extended addresses on the data stack.
Pronunciation: x-two-dupe

X: ( < name> -- )

Starts the compilation of a new C-callable definition with an eXtended header.  Removes <name> from the input stream and creates an extended header for <name> in the dictionary.  The header is SMUDGEd so that it cannot be found until ; executes to successfully terminate the definition.  Enters the compile mode so that words following X: are compiled into the code field of <name> (but IMMEDIATE words are executed immediately instead of being compiled).  A <name> isn't unique warning is issued if <name> already exists in the dictionary.  The contents of CONTEXT and CURRENT are not modified.  X: sets the system variable C.CALLABLE true before creating the header to ensure that a C-callable extended header is formed, and then restores C.CALLABLE it to its prior value after the new header is created.  See the : glossary entry.  Use as

X: <name>
   ...body of new definition...
;

Pronunciation: x-colon
Attributes: D

X<> ( xaddr1\xaddr2 -- flag )

Flag is TRUE if the two extended addresses are not equal and FALSE otherwise.
Pronunciation: x-not-equal

X= ( xaddr1\xaddr2 -- flag )

Flag is TRUE if the two extended addresses are equal and FALSE otherwise.
Pronunciation: x-equals

X>R ( xaddr -- )
Return stack: ( R: -- xaddr )

Transfers the top extended address on the data stack to the return stack.
Pronunciation: x-to-r
Attributes: C

X@ ( xaddr1 -- xaddr2 )

Fetches an extended address xaddr2 from memory location xaddr1. A synonym for 2@.
Pronunciation: x-fetch

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

Adds a named member to the structure being defined and reserves room for a 32-bit extended address 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: x-address
Attributes: D

XADDR.SIZE ( -- n )

Returns the constant value 4 which is the number of bytes in a parameter of type xaddr 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(

XADDR: ( <name> -- )

It defines a 32-bit self-fetching variable called <name> which holds a 32-bit extended address.  Use as:

XADDR:  <name>

Defines a 32-bit self-fetching variable.  Removes <name> from the input stream and creates a child word (a self-fetching variable) called <name> and allots 4 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 32-bit number) on the stack.  Thus <name> behaves like an XCONSTANT when executed.  Unlike an XCONSTANT, 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 because the fetch and store operations are integrated into the action of the variable. XADDR: is a synonym for DOUBLE:.  Use as:

XADDR: <name>

See also DOUBLE:
Pronunciation: x-address-colon
Attributes: D

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

Adds a named member to the structure being defined and reserves room for u2 extended addresses 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: x-addresses
Attributes: D

XALIGN ( xaddr1 -- xaddr2 )

If xaddr1 is not an even multiple of 4 bytes, increases xaddr1 by 1, 2, or 3 bytes to yield xaddr2 which is an even multiple of 4 bytes.  The heap manager and DIM.CONSTANT.MATRIX: and DIM.CONSTANT.ARRAY: use XALIGN to ensure that heap items, arrays, and matrices are 4-byte aligned.
Pronunciation: x-align

XCODE ( <name> -- )

Begins a C-callable assembly coded definition.  Removes <name> from the input stream and creates an eXtended header for <name> that cannot be found in the dictionary until END.CODE executes.  Executes ASSEMBLER so that the assembler mnemonics can be found by the interpreter.  The assembly mnemonics between XCODE and END.CODE form the body of the definition.  XCODE sets the system variable C.CALLABLE true before creating the header to ensure that a C-callable extended header is formed, and then restores C.CALLABLE it to its prior value after the new header is created.

See also CODE and END.CODE
Pronunciation: x-code
Attributes: D

XCONSTANT ( xaddr <name> -- )

Removes the next <name> from the input stream and defines a child word called <name> which when executed leaves the specified extended address xaddr on the data stack.  xaddr is stored in the definitions area of the dictionary. <name> is referred to as an xconstant. Use as:

xaddr XCONSTANT <name>

NOTE: If you need to create a constant that stores the code address that is in a relocatable application segment, use XCONSTANT.REL (see its glossary entry).
Pronunciation: x-constant
Attributes: D

XCONSTANT.REL ( xaddr <name> -- )

Creates a page-relative xconstant.  Removes the next <name> from the input stream and defines a child word called <name> which when executed returns the specified extended address xaddr, or, if the segment containing the xconstant.rel definition has moved, a page-shifted version of xaddr.  xaddr is stored in the definitions area of the dictionary. <name> is referred to as a page-relative xconstant. Use as:

xaddr XCONSTANT.REL <name>

The returned address is the same as specified when the constant is created, but the returned page is relative to DP.PAGE.  For example, if you are compiling on page 1 and specify

0x8234 4 XCONSTANT.REL MYCON

you are saying that you want to remember addr 0x8234 on a page 3 pages greater than the code page.  If you then relocate the segment containing MYCON +5 pages to code page 6, executing MYCON returns ( 8234\9 – ) which is 3 pages greater than the runtime code page.

Restrictions on use: XCONSTANT.REL cannot be used to store an explicit reference to a code xaddress in a relocatable LIBRARY that fits on a single page; such a library is subject to relocation within a page, which is not handled by this routine.  Similarly, do not attempt to use XCONSTANT.REL to define an xaddress in a relocatable segment’s variable or EEPROM area, as the base addresses of these regions can change during relocation.  Whenever possible, try to avoid explicitly capturing and storing pointers as constants in programs that are relocatable.
Pronunciation: x-constant-rel
Attributes: D

XCREATE ( <name> -- )

Adds a new C-callable eXtended header for <name> to the names area.  XCREATE sets the system variable C.CALLABLE true, calls CREATE to create a C-callable extended header, and then restores C.CALLABLE it to its prior value after the new header is created.  For a complete description, See the glossary entry for CREATE.
Pronunciation: x-create
Attributes: D

XD+ ( xaddr1\d -- xaddr2 )

Adds signed double number d to xaddr1 to yield xaddr2. Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.
Pronunciation: x-d-plus

XD- ( xaddr1\d -- xaddr2 )

Subtracts signed double number d from xaddr1 to yield xaddr2. Note that in paged memory, the address immediately preceding 0x8000 is address 0xBFFF on the preceding page.
Pronunciation: x-d-minus

XDROP ( xaddr -- )

Drops an extended address (two cells) from the data stack.
Pronunciation: x-drop

XDUP ( xaddr -- xaddr\xaddr )

Duplicates the top extended address (two cells) on the data stack.
Pronunciation: x-dupe

XDUP>R ( xaddr -- xaddr )
Return stack: ( R: -- xaddr )

Copies the top extended address on the data stack to the return stack.
Pronunciation: x-dup-to-r
Attributes: C

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

Adds a named member to the structure being defined and reserves room for a 32-bit extended handle 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: x-handle
Attributes: D

XIRQ.ID ( -- n )

Returns the interrupt identity code for the external non-maskable interrupt called XIRQ.  Used as an argument for ATTACH.  The XIRQ interrupt is activated by an active-low signal on the XIRQ input pin and is enabled by the X bit in the condition code register.

CAUTION: Because the XIRQ interrupt can occur while another interrupt is in progress, the XIRQ service routine must not use the standard interrupt data stack.  If a Forth function is called from inside the XIRQ service routine, the Y register (data stack pointer) must be saved, Y must be pointed to a reserved area of common RAM, the Forth function(s) called, and then Y must be restored before the service routine exits.
Pronunciation: x-i-r-q-i-d

XMIT.DISABLE ( -- xaddr )

A user variable that contains a 16-bit flag that is set each time that EXPECT receives an XOFF character (ascii 19) and is cleared upon startup and each time EXPECT receives the XON character (ascii 17).  XON and XOFF are standard handshaking characters used to control the flow of data between computers.  The XMIT.DISABLE flag is not used by the operating system; it is provided in case the programmer needs to implement an XON/XOFF handshaking protocol.  Note that inserting PAUSE.ON.KEY in the inner loop of a data dump word provides a very easy way to emulate XON/XOFF control of data dumps.

See also EXPECT and PAUSE.ON.KEY
Pronunciation: transmit-disable
Attributes: U

XN+ ( xaddr1\n -- xaddr2 )

Adds signed integer n to xaddr1 to yield xaddr2. Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.
Pronunciation: x-n-plus

XN- ( xaddr1\n -- xaddr2 )

Subtracts signed integer n from xaddr1 to yield xaddr2. Note that in paged memory, the address immediately preceding 0x8000 is address 0xBFFF on the preceding page.
Pronunciation: x-n-minus

XOR ( w1\w2 -- w3 )

w3 is the result of a logical bit-by-bit exclusive-or of w1 and w2.
Pronunciation: x-or

XOVER ( xaddr1\xaddr2 -- xaddr1\xaddr2\xaddr1 )

Places a copy of xaddr1 on top of the data stack.
Pronunciation: x-over

XPICK ( xaddr\wn-1\...w1\w0\+n -- xaddr\wn-1\...\w1\w0\xaddr )

Copies to the top of the stack the extended address whose most significant cell is the +nth item on the stack (0-based, not including +n).  An unchecked error occurs if there are fewer than +n+2 cells on the data stack or if +n is outside the range 0 to 255, inclusive. 0 XPICK is equivalent to XDUP, 1 XPICK is equivalent to X.OVER.N, 2 XPICK is equivalent to XOVER.
Pronunciation: x-pick

XR> ( -- xaddr )
Return stack: ( R: xaddr -- )

Transfers the top extended address on the return stack to the data stack.
Pronunciation: x-r-from
Attributes: C

XR>DROP ( -- )
Return stack: ( R: xaddr -- )

Removes the top extended address from the return stack.
Pronunciation: x-r-from-drop
Attributes: C

XR@ ( -- xaddr )
Return stack: ( R: xaddr -- xaddr )

Copies the top extended address on the return stack to the data stack.
Pronunciation: x-r-fetch
Attributes: C

XRANGE ( xaddr1\xaddr2\xaddr3 -- xaddr1\flag )

Flag is TRUE if xaddr1 is greater than or equal to xaddr2 and less than or equal to xaddr3. Otherwise flag is FALSE.  There is an unchecked error if one or two of the xaddresses is in common memory (addr ≤ 0x7FFF or addr ≥ 0xC000) and other(s) are in paged memory (0x8000 ≤ addr ≤ 0xBFFF).  In other words, XRANGE works properly only if all three xaddresses are in paged memory, or if all three are in common memory.  Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.
Pronunciation: x-range

XROT ( xaddr1\xaddr2\xaddr3 -- xaddr2\xaddr3\xaddr1 )

Rotates the top three extended addresses on the data stack.
Pronunciation: x-rote

XSWAP ( xaddr1\xaddr2 -- xaddr2\xaddr1 )

Exchanges the top two extended addresses on the data stack.
Pronunciation: x-swap

XU+ ( xaddr1\u -- xaddr2 )

Adds unsigned integer u to xaddr1 to yield xaddr2. Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.
Pronunciation: x-u-plus

XU- ( xaddr1\u -- xaddr2 )

Subtracts unsigned integer u from xaddr1 to yield xaddr2. Note that in paged memory, the address immediately preceding 0x8000 is address 0xBFFF on the preceding page.
Pronunciation: x-u-minus

XU< ( xaddr1\xaddr2 -- flag )

Flag is TRUE if xaddr1 is less than xaddr2. Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.
Pronunciation: x-u-less-than

XU> ( xaddr1\xaddr2 -- flag )

Flag is TRUE if xaddr1 is greater than xaddr2. Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.
Pronunciation: x-u-greater-than

XVARIABLE ( <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 xvariable. XVARIABLE is segment-relocation-smart, and 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.

Use as:

XVARIABLE <name>

Pronunciation: x-variable
Attributes: D

ZERO ( -- r | r = 0.0 )

Puts the floating point representation for zero (= 0\0) on the data stack.

ZERO.ARRAY ( array.xpfa -- )

Stores 0 into each byte of the specified array.

ZERO.MATRIX ( matrix.xpfa -- )

Stores 0.0 into each element of the specified matrix.

[ ( -- )

Sets STATE equal to 0 and enters the execution mode so that subsequent text from the input stream is executed.

See also ] and STATE
Pronunciation: left-bracket
Attributes: I

[0] ( array.xpfa -- [xaddr] or [0\0] | xaddr is array base address )

Returns the base address (that is, the address of the first element) of the array or matrix indicated by array.xpfa.  Returns 0\0 if the array or matrix is undimensioned.  No error checking is performed.
Pronunciation: bracket-zero

[COMPILE] ( <word> -- )

Removes the next <name> from the input stream and compiles a call to <name> into the current definition.  Use as:

: <namex>
   ... [COMPILE] <name> ...
;

where <namex> is typically not immediate and <name> is typically immediate. [COMPILE] forces the immediate word <name> to be compiled into the definition of <namex> instead if executing while <namex> is being defined.

See also COMPILE
Pronunciation: bracket-compile
Attributes: C, I

[] ( n1\[n2]\array.xpfa -- xaddr | n1...nn = indices )

Returns the extended address xaddr of the element whose indices are n1 (if it’s a 1-dimensional array) or n2\n2 (if it’s a 2-dimensional array) in the array specified by array.xpfa.  ABORTs if the indices are invalid.  Typical use:

<indices> ' <array.name> []

Pronunciation: brackets

\ ( -- )

Ignores all remaining input on the current line.  Very useful for inserting descriptive comments into QED-Forth source code.

See also ( and //
Pronunciation: back-slash
Attributes: I

] ( -- )

Sets STATE to a non-zero value and enters the compilation mode so that subsequent text from the input stream is compiled instead of being executed.

See also [ and STATE
Pronunciation: right-bracket
Attributes: I

|2!| ( w1\w2\xaddr -- | [xaddr] gets w2, [xaddr+2] gets w1 )

Stores two 16 bit integers at xaddr.  Disables interrupts during the store to ensure that an interrupting routine or task will read valid data.  w2 is stored at xaddr and w1 is stored at xaddr+2. Can also be used to store a double number at xaddr.  Disables interrupts for 0.5 microseconds unless the specified 4 bytes straddle a page boundary, in which case interrupts are disabled for approximately 5.4 microseconds.  Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.
Pronunciation: bar-two-store

|2@| ( xaddr -- w1\w2 )

Fetches two 16 bit integers from xaddr.  Disables interrupts during the fetch to ensure that an interrupting routine or task does not modify the contents while the fetch is in process.  w2 is taken from xaddr and w1 is from xaddr+2. Can also be used to fetch a double number from xaddr.  Disables interrupts for 0.55 microseconds unless the specified 4 bytes straddle a page boundary, in which case interrupts are disabled for approximately 5.4 microseconds.  Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.
Pronunciation: bar-two-fetch

|F!| ( r\xaddr -- )

Stores a floating point number at xaddr.  Disables interrupts during the store to ensure that an interrupting routine or task will read valid data.  Disables interrupts for 0.5 microseconds unless the specified 4 bytes straddle a page boundary, in which case interrupts are disabled for approximately 5.4 microseconds.  A synonym for |2!|.
Pronunciation: bar-f-store

|F@| ( xaddr -- r )

Fetches a floating point number from xaddr.  Disables interrupts during the fetch to ensure that an interrupting routine or task does not modify the contents while the fetch is in process.  Disables interrupts for 0.55 microseconds unless the specified 4 bytes straddle a page boundary, in which case interrupts are disabled for approximately 5.4 microseconds.  A synonym for |2@|.
Pronunciation: bar-f-fetch

|X!| ( xaddr1\xaddr2 -- )

Stores the extended address xaddr1 at xaddr2. Disables interrupts to ensure that an interrupting routine or task will read valid contents.  Disables interrupts for 0.5 microseconds unless the specified 4 bytes straddle a page boundary, in which case interrupts are disabled for approximately 5.4 microseconds.  A synonym for |2!|.
Pronunciation: bar-x-store

|X1-X2|>U ( xaddr1\xaddr2 -- n )

Subtracts xaddr2 from xaddr1 and takes the absolute value of the result to yield the unsigned integer difference u.  There is an unchecked error if one of the xaddresses is in common memory (addr ≤ 0x7FFF or addr ≥ 0xC000) and the other is in paged memory (0x8000 ≤ addr ≤ 0xBFFF).  Note that in paged memory, the address immediately following 0xBFFF is address 0x8000 on the following page.
Pronunciation: abs-of-x-one-minus-x-two-to-u

|X@| ( xaddr1 -- xaddr2 )

Fetches an extended address xaddr2 from memory location xaddr1. Disables interrupts during the fetch to ensure that an interrupting routine or task does not modify the contents while the fetch is in process.  Disables interrupts for 0.55 microseconds unless the specified 4 bytes straddle a page boundary, in which case interrupts are disabled for approximately 5.4 microseconds.  A synonym for |2@|.
Pronunciation: bar-x-fetch

Closing delimiter for ${

See also ${