Forth v6 New Features

This page compares the Forth v6 language and operating system with the prior QED-Forth v4 firmware. The PDQ Board and PDQ Screen operating system firmware carries the version number V6.xx, where xx represents a numeric value.

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.

Programmers who are familiar with the prior V4.xx operating system software will notice that certain classes of functions have been removed from V6.xx. These include the hardware drivers for the 12-bit A/D, D/A, PIA, high current drivers, keypad, display, and stepper motors. The matrix math, matrix row/column operators, and vector math functions have also been removed from V6.xx.

The PDQ Controllers boot up at 115200 baud, compared to 9600 baud or 19200 baud on earlier products.

Many new Forth functions are present in the V6.xx kernel that were not present in the V4.xx kernels. These are briefly summarized here, and are fully described in the glossary. When a new class of functions has been added, please refer to the Categorized Word List to view the entire class of new functions.

Like Mosaic products based the prior 68HC11 processor, there is a native 16-bit 64 Kbyte memory space with part of the space dedicated to paged memory. The page architecture of the HCS12 processor, however, differs from that of the older HC11-based products. Pages are now 16 Kbytes long, extending from addresses 0x8000 to 0xBFFF on pages 0x00 through 0x3F. The upper pages represent the on-chip flash on the HCS12 processor. The on-chip flash resides on pages 0x20-3F. Page 0x1F is reserved for memory-mapped devices such as Wildcards and the shadow external flash (XFlash). Page 0x1E is remapped to implement a 16 KByte block of common RAM, and is not addressable as paged RAM. This leaves pages 0x00 through 0x1D, inclusive, as paged RAM available for compiled code, names, heap, and other dynamic data structures. The operating system reserves the top half of page 0x1D at 0xA000-BFFF for its data structures, and places the default DP (Forth dictionary pointer) and NP (Forth names pointer) after a COLD restart in the bottom half of page 0x1D.

The HCS12 processor’s registers are located at addresses 0x0000-0x03FF in the bottom 1K of the memory space. The next 1 Kbyte from 0x0400 to 0x07FF is EEPROM; the region from 0x0400 to 0x063F is reserved for the operating system, and the remaining decimal 384 EEPROM bytes at 0x0640 to 0x07FF are available for the application.

The processor’s 14 Kbytes of on-chip RAM occupy addresses 0x0800-0x3FFF; the operating system reserves the on-chip RAM at 0x1000-1FFF, leaving 2K RAM at 0x0800-0x0FFF and the RAM starting at 0x2000 available for the user. External common RAM occupies addresses 0x4000-0x7FFF. Common RAM can be accessed regardless of the contents of the page latch. Thus the programmer has access to 24 Kbytes of contiguous common RAM at addresses 0x2000 through 0x7FFF, plus the 2K block at 0x0800-0x0FFF, which is double the common RAM available on the earlier 6811-based controllers. When common memory is referred to using a 32-bit xaddress, we designate the page of the common memory as 0, represented by the constant COMMON.PAGE (the DEFAULT.PAGE constant from the prior kernel has been deleted). Using this scheme, an address in common memory is numerically the same whether it is represented as 16 bits or 32 bits.

To optimize the timing of certain stack operations, the programmer’s stacks and task areas should be allocated in the on-chip RAM at 0x0800-0x0FFF or 0x2000-0x3FFF. For all other purposes, the on-chip common RAM is equivalent to the off-chip common RAM at 0x4000-7FFF. The variable area pointed to by VP is typically located in common RAM.

Common flash at 0xC000-0xFFFF completes the 64K native memory space of the HCS12 processor. The operating system kernel occupies this area, as well as pages 0x38 through 0x3F of the on-chip flash. The kernel on-chip flash is write protected so it is very difficult to accidentally erase.

Upon a COLD restart, a usable memory map is established. It includes a 24 Kbyte variable area in common RAM starting at 0x2000 and extending to 0x7FFF, and a 384 byte EEPROM area starting at 0x0640 and extending to 0x07FF. An 80 Kbyte heap is established on pages 0x18 through 0x1C; this area is useful for large arrays that contain volatile data. The DP (dictionary pointer for code) and NP (names pointer) point to temporary locations on page 0x1D that are suitable for debugging and testing. The initial DP is set to 0x8000, and the NP is set to 0x9000, both on page 0x1D. The operating system reserves the top half of page 0x1D at 0xA000-0xBFFF. This initial memory map allows a 4 Kbyte dictionary (code) area and a 4 Kbyte names area.

Executing the recommended function DEFAULT.MAP directive at the top of your application program (before your ANEW or segment declarations) moves the DP to 0x8000 on page 0, and moves the NP to 0x8000 on page 0x10; the default locations for the variable area, EEPROM, and heap are the same as those established by a COLD restart. The DEFAULT.MAP allows up to sixteen pages (256 Kbytes) of compiled code on pages 0x00 through 0x0F, and up to 4 pages (64 KBytes) of function names on pages 0x10 through 0x13. This is in write-protectable RAM. Pages 0x00 through 0x17 are shadowed RAM, which is backed up (shadowed) by a flash chip on the board so that the compiled code is restored to the RAM upon each power-up or restart, and then pages 00-0x13 can be optionally write-protected.

A set of flash and memory map management functions is present in V6.xx kernels. Prior controllers implemented a page swapping memory architecture supported by routines named STANDARD.MAP, DOWNLOAD.MAP, WHICH.MAP, PAGE.TO.FLASH, and PAGE.TO.RAM; these functions have been deleted. The PDQ controllers compile memory into RAM, and allow it to be backed up to parallel pages of shadow flash memory. You can configure the code to be automatically restored to RAM from the non-volatile flash each time the board powers up or undergoes a COLD restart. This is similar to a desktop PC, which loads programs from disk to RAM at startup. The following routines assist in managing the program memory:

A typical program places DEFAULT.MAP at the top of the first source code file (before the file’s ANEW, LIBRARY, or APPLICATION statement), and a SAVE.ALL command at the bottom of the last file to handle backup to the shadow flash, as described above. The SAVE and RESTORE functions are also available to assist in re-establishing a prior saved memory map. The new functions WRITE.PROTECT and WP.ALL disallow writes to certain page ranges where the compiled code is typically stored, thereby helping to bullet-proof the runtime program in a production product. WRITE.ENABLE and WE.ALL allow writes to the specified page ranges.

Managing the shadowed RAM is easy. The LOAD.PAGES.AT.STARTUP function specifies which pages are restored from shadow flash to RAM at startup. The convenient SAVE.ALL function saves pages 0x00 through 0x17 to the shadow XFlash, and configures the system to automatically restore these pages upon subsequent power-ups or COLD restarts. SAVE.ALL also saves the current memory pointers (DP, NP, VP, EEP, segment information, etc.) in EEPROM so that it can be restored by invoking RESTORE or RESTORE.ALL. The RESTORE.ALL function forces an immediate restoration of pages 0x00-0x17 paged RAM from the shadow flash, and restores the memory pointers to the values they had when SAVE or SAVE.ALL was last executed. Because pages 0x00 through 0x17 include the code and names pages used by most application programs, these simple utility functions are perform the most often needed memory management capability.

Pages 0x00-0x0F can be write-protected by passing the parameter 1 to the WRITE.PROTECT function, and pages 0x10-0x13 can be write protected by passing 2 to WRITE.PROTECT. The complementary WRITE.ENABLE function restores write-ability to the specified page ranges. The WP.ALL function write protects pages 0x00-0x13, and WE.ALL write-enables pages 0x00 through 0x13.

Upon a COLD restart, the V6.xx kernel prints a status report that summarizes the memory map, write-protect (WP) status, pages loaded from the shadow flash into RAM, and the current library or application segment status. The .MAP and REPORT.PAGES.LOADED functions enable you to reproduce these reports at any time. To suppress the status report at every COLD restart, execute NO.STATUS.AT.STARTUP (which can be reversed by STATUS.AT.STARTUP). To suppress the status printout for a single COLD restart, use QUIET.COLD.

The V6.xx kernel supports relocatable code organized as program segments. Device drivers for Wildcards, Graphical User Interface Tools, and other software are distributed as pre-compiled segments that are accessible using Forth or C. The two types of segments are libraries and applications. A library is fully relocatable as long as it does not cross a page boundary. Libraries that are longer than a page, and Application segments, can be relocated from page to page. The variables and EEPROM variables accessed by a library are offset-based, and can change based on the value of VP and EEP when the library is loaded. The variables and EEPROM variables compiled into an application segment, on the other hand, have their addresses fixed at the time of compilation.

A comprehensive set of functions supporting these capabilities is summarized in the Library Management section of the Categorized Word List. These functions facilitate the creation of new segments via the LIBRARY, APPLICATION and END.SEGMENT directives, the relocation of segments, and the export and re-loading of segments via the various COMPOSE commands. The LIBRARY and APPLICATION directives also serve as ANEW statements in the code, simplifying the reloading of code during development. Consult the software manual for details regarding how to manage library and application segments. For experts, these tools enable the compilation of pre-compiled loadable libraries that can be invoked from either the C or the Forth programming environments.

The kernel automatically bumps the dictionary (code) pointer and the names pointer to the start of the next page when they get near to the upper boundary of a page. This works unless a fairly long definition happens to be compiling when the page boundary is encountered. In this case, simply insert a statement that advances the DP to the next page before the page boundary is reached. If you don’t want the auto-bump assistance, you can turn ON the variables DP.NOBUMP and NP.NOBUMP. If you want additional memory map assistance, you can initialize the variables LAST.DP.PAGE and LAST.NP.PAGE so that you will be warned when the code or names area goes outside the allowed boundaries.

To better support the available EEPROM, these functions have been added to the kernel:

Now eevariables can be declared in the EEPROM area, just as RAM-based variables can be declared in the variable area. These are read using the standard fetch operators, and written to using the ee-store operators such as (EEC!), (EE!), and (EE2!).

A Wildcard is a tiny I/O board that plugs into one of two Wildcard headers on the PDQ controller. A maximum of four Wildcards can be stacked on a single Wildcard header. Each Wildcard has a unique 2-bit address set by a pair of jumpers on the Wildcard. The combination of the Wildcard header number (0 or 1) and the 2-bit jumper address yields a 3-bit hardware address, or module number that identifies the Wildcard. Each Wildcard occupies a 256 byte region in memory, and individual bytes in this region are specified by an offset from the Wildcard’s base address.

To address the Wildcard memory you can use access primitives such as IO.C@, IO.C!, IO.@, IO.!, and IO.CHANGE.BITS that have been added to the kernel. For a complete list of these functions, see the table of "Device Drivers: Wildcard I/O Drivers" in the Categorized Word List.

Each of these IO function accepts an offset and module_num that specifies the byte location to be accessed. Full control of each Wildcard is facilitated by pre-coded device driver libraries that are available for each Wildcard. A Smart Wildcard carries its own HCS12 co-processor. Write operations are the same for standard and Smart Wildcards, but a special set of Smart I/O read operators (SMART.IO.C@, etc.) is required to read from these processor-carrying cards.

The names of the autostart configuration functions have changed. In the prior kernels they were named AUTOSTART and PRIORITY.AUTOSTART. In the new kernel, they are named:

The functions that end in a colon expect the name of the startup function to follow, while IS.AUTOSTART and IS.PRIORITY.AUTOSTART expect the xcfa (execution address) of the startup function to be on the stack. For example, to automatically execute a program function named MAIN each time the PDQ controller powers up or is reset, you could execute

PRIORITY.AUTOSTART: MAIN

or, equivalently,

CFA.FOR MAIN IS.PRIORITY.AUTOSTART

The new DUMP.AUTOSTARTS routine dumps a short S-record that includes the compiled autostart and priority autostart vectors at the top of pages 0x37 and 0x0F, respectively.

To support pre-coded Forth libraries that require special runtime initialization, a set of boot vectors is implemented using the SET.BOOT.VECTOR function. 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 associated with libraries. They are automatically installed when the 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. The DISABLE.BOOT.VECTORS function forces the boot vector processing to be skipped (for example, during debugging), and ENABLE.BOOT.VECTORS re-enables boot vector processing. An optional layer of checksum protection is provided for the boot vectors to ensure that corrupted or missing boot vectors are not executed. The checksum control functions are called CHECKSTART.ENABLE and CHECKSTART.DISABLE. This optional checksum protection is typically handled automatically by the kernel extension package.

A new ALLOCATE.TASK: routine is available that allocates a new 1 Kbyte task area in the variable area. This is cleaner than the old approach of designating fixed addresses for the tasks in the source code using the TASK: function. The BUILD.TASK routine has a new stack picture that includes the EEPROM pointer. Note that, to optimize the timing of stack-based instructions, tasks should be allocated in the on-chip RAM at 0x2000-0x3FFF. The variable and task area starts at 0x2000 and works towards higher memory, so the best way to accomplish this is to place the ALLOCATE.TASK: statements early in the program’s source code.

The HCS12 processor has a new and expanded set of interrupt vectors. The interrupt identifiers used with the ATTACH function have been renamed accordingly (ECT0.ID, ECT1.ID, etc.).

ACTIVATE now ensures that each activated task runs with interrupts globally enabled. In prior firmware versions, enabling of interrupts in all built tasks required START.TIMESLICER to be executed.

The timeslice multitasker is now supported by the Real-Time Interrupt (RTI) as opposed to the output compare 2 (OC2) interrupt as in prior HC11-based products. The timeslicer period can be set from 1 millisecond (the default) to 15 milliseconds by the MSEC.TIMESLICE.PERIOD routine which replaces the *100US=TIMESLICE.PERIOD function from prior kernels. The new COUNT.TO.MSEC function converts a timeslice count (or elapsed count difference) into the corresponding number of elapsed milliseconds. The new WAIT.TIL.MATCH function provides a way to wait and PAUSE until a specified condition is met at a memory location.

The Freescale 9S12 (HCS12) processor has an expanded assembly instruction set with many more addressing modes and assembly commands than the older HC11 processor. The new assembler mnemonics are summarized in the Assembler section of the categorized word list, and are documented in the Assembler glossary section of this document.

There are many new device driver functions to support the native I/O on the HCS12 processor. These are summarized in the Device drivers sub-sections in the Categorized Word List.

The new I/O includes:

• A built-in Analog-To-Digital (ATD) converter on pins AN0-15
• Pulse-Width Modulated (PWM) output signals on PORTP

• Enhanced Capture/Timer (ECT) subsystem on PORTT for timer-controlled I/O

  The ECT timer includes

  • Input captures (IC),
  • Output compares (OC),
  • Pulse accumulators,
  • A free-running 16-bit counter (TCNT), and,
  • A modulus down-counter.
• An Serial Peripheral Interface (SPI0) 3-wire serial port that is brought out to the Wildcard bus header,
• An Inter-IC (IIC) clocked 2-wire multi-drop serial bus available on PORTJ of the HCS12 processor. The IIC bus is sometimes referred to as the I-squared-C (I2C) bus.

A new SPI.EXCHANGE function and new SPI initializers are included in the V6.xx kernel. There are 3 SPI channels on the HCS12 processor. SPI0 is the default user-accessible channel that appears on the Wildcard bus and supports the battery-backed real-time clock. INIT.SPI initializes SPI0; it configures the SPI to sample data on the falling trailing edge of the SPI clock. This is consistent with the data transfer protocol of the on-board battery-backed real-time clock. The user may freely change the SPI configuration to meet the needs of the application program using the SPI.SAVE, SPI.CONFIG, and SPI.RESTORE functions. Each of the four clock specifiers is now a named constant (SPI.FALLING.TRAILING.EDGE, SPI.RISING.LEADING.EDGE, etc.) SPI1 and SPI2 are reserved for inter-processor (IP) communications, and are supported by the INIT.IP.SPI and MASTER2 functions.

The processor has two identical hardware UARTs named SCI0 and SCI1 (corresponding to Serial1 and Serial2, respectively). The BAUD function has a new stack picture that accepts the serial port ID (1 or 2) in addition to a parameter that specifies the baud rate. The new UARTs can support standard baud rates from 300 to 115200 bits per second; see the glossary entry for BAUD for more details. The RS485.INIT, RS485.RECEIVE, and RS485.TRANSMIT functions now accept a serial port ID parameter to specify the relevant serial channel. An RS485.TRANSMIT.DONE function has been added to improve the management of RS485 data transfers. The functions that implemented the software UART supporting the secondary serial port in prior products have been removed from the kernel.

The interpreter and its DIN, NEXT.NUMBER, and NUMBER functions now accept a leading 0x or 0X to indicate that hexadecimal base should be used when converting the number to binary. The new functions D>R$, HEXD>R$, and UD>R$ make it easy to convert a 32-bit integer to a formatted numeric string. Combined with the S>D and U>D utilities that convert 16-bit integers to 32-bit integers, these functions simplify the creation of numeric strings. The new functions

enable numbers to be printed in hexadecimal base with a leading 0x no matter what the current number base is.

Some new defining words have been added to make it easier to test bug fixes during program development. The functions R: and RCODE allow you to define a new version of a function that has already been compiled. The prior compiled definition is automatically revectored to point to the new version of the function. This allows you to fix a bug in a function and exercise the patched version without downloading all of the program code.

Arrays are now limited to 1 or 2 dimensions, and array address resolution is faster than in prior versions.

Array and matrix data is now stored in memory by rows (just like C does); prior QED-Forth versions stored array and matrix data by column.

The V6.xx floating point package adopts the ANSI standard floating point format which is the same as that used by C. While the size of each floating point number remains unchanged at 32 bits, the new format implements 23 bit mantissas, delivering greater precision than the previous 16-bit mantissa format. Thus the now unneeded routines FP_QToC and FP_CtoQ have been removed from the kernel. All of the floating point math, printing, and transcendental functions use the new format. The RANDOM function now returns a long instead of a 16-bit integer, and RANDOM# now returns the address of a 32-bit variable. The new F>$ routine performs a string conversion for floating point numbers in the current default format (fixed, floating, or scientific notation).

The interpreter has been made significantly faster through the use of a hash which is a sorted table that points to a set of short linked lists of names. Low level words such as BUILD.HASH.TABLE, LINK.HASH and VALID.HASH support this capability. While this results in significant performance advantages, the hash makes it very difficult to support the (now obsolete) AXE function that removed names from the linked names list in earlier kernels. The new function SMUDGE: allows the programmer to make a name un-findable in the linked names list. Moreover, LINK can be used to exclude from the final names list a set of words that are needed during compilation. The words to be excluded can be placed in a separate names area (say, on a separate page of RAM), and LINK can be used to link around (exclude) the names in the final published version.

The interpreter now prints a Line is too long warning message if an incoming line exceeds the contents of the CHARS/LINE user variable; the recommended default maximum line size is 95 characters. The new user variable LONG.LINE.MSG can be set to zero to suppress this warning.

The loop index primitives I\J, J\I, and K have been deleted from the kernel. Also, support for the obsolete blocks file interface has been deleted from the kernel.

The default value for the TAB.WIDTH user variable has been changed to 1 (its prior default was 4).

New long strings complement the standard Forth strings. Long strings store a 16-bit count followed by the string contents, followed by a null (0) character that is not included in the count. They are convenient for creating blocks of text, or for parsing strings that may include the " character that is used as the delimiter in standard strings. The format for a long string is

${ //text goes here//}$

You can also use the new function LPARSE to create a long string using any specified 1- or 2-character delimiter. The LCOUNT and LTYPE functions unpack and type the long strings. The new CAT function makes it easy to concatenate strings.

The compile-time conditional functions

can now be nested.

The VERSION function returns the address of a counted string that contains an ascii representation of the version number of the kernel.

Additional low-level routines available in this kernel include BREAK.ALL, CALC.CHECKSUM, CALC.CHECKSUM.MANY, CMOVE.MANY.CHECK, DUMP.BINARY, DUMP.MANY.S2 and RECEIVE.BINARY. See their glossary entries for more details. The CALC.CHECKSUM routine can handle memory regions that cross page boundaries.

The low-level utilities (#FIND), #FIND and (BENCHMARK:) have new stack pictures. A number of new find and compile routines support the interpreter/compiler’s ability to compile relocatable code; see the "Interpreter and Compiler" section of the Categorized Word List for a summary of these functions.

To avoid a redundant list of new device driver function names, please consult the Forth Function Summary for a categorized word list, and note that all of the functions in the following subsections are new for the V6.xx kernel:

In addition, all of the functions in the SPI Serial Bus Drivers category that start with the letters SPI are new to this kernel.

The following table lists the other functions that have been added to V6.xx that were not present in the V4.08 kernel.