Changes from the Prior C IDE

Software development in C now uses the Codeblocks-based Mosaic IDE Plus Integrated Development Environment. The IDE Plus provides a full-featured text editor, GNU C (GCC) compiler, and customized terminal for rapid code downloads and interactive debugging sessions with the 9S12 (HCS12) processor on the controller board. This page compares the Mosaic IDE Plus operating system (the Forth v6 OS) with the prior Mosaic IDE operating system (using Forth v4 firmware). The PDQ Board and PDQ Screen operating system firmware carries the version number V6.xx, where xx represents a numeric value.

Customers 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 that were present on prior boards.

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

A number of new 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.

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 Forth DP (dictionary pointer for code compilation) and NP (names pointer for function names) 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. 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, so 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. This is handled by the C compiler. All common RAM (onchip and off-chip) is suitable for C variables and RAM-based arrays and structures.

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 useable 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 FORTH_ARRAYs that contain volatile data. The DP (Forth dictionary pointer for code) and NP (Forth names pointer) point to temporary locations on page 0x1D that are suitable for debugging and testing. The initial Forth DP is set to 0x8000, and the NP is set to 0x9000, both on page 0x1D.

The C compiler configures the memory map so that code loads into memory starting at page 0 RAM; the default locations for the variable area, EEPROM, and heap are the same as those established by a COLD restart. A compiled program can occupy up to 384K of paged memory at pages 0x00 through 0x17. This is 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 0x00 through 0x13 can be optionally write-protected.

The LoadPagesAtStartup function specifies which pages are restored from shadow flash to RAM at startup. The handy interactive function SAVE.ALL (typed at the terminal) 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.

The complementary interactive function RESTORE.ALL forces an immediate restore of the saved image from XFlash into the working paged RAM. You can write protect RAM using the WriteProtect function. Pages 0x00-0x0F are write-protected using WriteProtect(1), and pages 0x10-0x13 are write protected by calling WriteProtect(2). The interactive function WP.ALL protects all pages from 0x00-0x13, and the interactive function WE.ALL write-enables these pages.

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 interactive 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 interactive routines assist in managing the program memory:

These functions are documented in the Interactive Debugger glossary. Consult the MEMORY.h table of functions in the Categorized Function List for the matching C functions available for some of these functions.

The V6.xx kernel includes a segment management system that enables Mosaic to create device drivers for Wildcards, Graphical User Interfaces, and other devices, and distribute them as a set of files that can be installed using either the C or Forth programming environments. The SEGMENTS.h file contains structure and macro definitions that allow the C environment to compile and locate these pre-compiled library and application segments.

Interactive management of the download and copying of the application code to flash is now streamlined, and the C compiler tool chain automates the process so you don’t have to manage the details. The compiler tools typically place a SAVE.ALL directive at the bottom of the download file. This 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. Most programs place all non-volatile code and data in this page region, so the system provides an automated means of managing the paged RAM and shadow flash. If you ever need to force an immediate restore of the saved image from XFlash into the working paged RAM, you can type the complementary function RESTORE.ALL at the terminal prompt. The SAVE and RESTORE functions are available to assist in re-establishing a prior saved memory map. The new function WriteProtect (WRITE.PROTECT in interactive Forth) disallows writes to certain page ranges where the compiled code is typically stored, thereby helping to bullet-proof the runtime program in a production product. WriteEnable (WRITE.ENABLE in interactive Forth) allows writes to these page ranges.

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

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, and there are two headers per controller board, for a total of 8 allowable Wildcards per system. 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 IOFetchChar, IOStoreChar, IOFetchInt, IOStoreInt, and IOChangeBits which have been added to the kernel. For a complete list of these functions, see the table in the IOAccess.h section in the Categorized Function List. Each I/O 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 (SmartIOFetchChar, 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 PriorityAutostart (AUTOSTART and PRIORITY.AUTOSTART in Forth). In the new kernel, they are named IsAutostart and IsPriorityAutostart in C, and AUTOSTART:, PRIORITY.AUTOSTART:, IS.AUTOSTART, and IS.PRIORITY.AUTOSTART in interactive Forth. The functions that end in a colon expect the name of the startup function to follow, while the others 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 interactively type at the terminal,

PRIORITY.AUTOSTART: MAIN

or, equivalently,

CFA.FOR MAIN IS.PRIORITY.AUTOSTART

To support pre-coded libraries that require special runtime initialization, a set of boot vectors is implemented using the SetBootVector (SET.BOOT.VECTOR in Forth) 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 specialized device-driver libraries. They are automatically installed when the libaray is loaded onto the board. They can be removed by interactively executing CLEAR.BOOT.VECTORS, or invoking the factory cleanup procedure described in the manual. The interactive DISABLE.BOOT.VECTORS function forces the boot vector processing to be skipped (for example, during debugging), and interactively typing DISABLE.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 CheckstartEnable and CheckstartDisable. This optional checksum protection is typically handled automatically by the kernel extension package. In most cases you do not have to worry about these low level functions.

The BuildTask routine has a new stack picture that includes the EEPROM pointer. 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. This is handled by the C compiler.

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 StartTimeslicer 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 MsecTimeslicePeriod routine which replaces the ChangeTaskerPeriod function from prior kernels. The new CountToMsec function converts a timeslice count (or elapsed count difference) into the corresponding number of elapsed milliseconds. The new WaitTilMatch function provides a way to wait and Pause until a specified condition is met at a memory location.

The HCS12 processor has a different complement of I/O ports and registers compared to the prior HC11 processor, so many of the register names in the HCS12Regs.h file are new.

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 SPI0 (Serial Peripheral Interface) 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.

In the Categorized Word List all of the functions in the SERIAL.h file that start with the letters IIC are new; they support the 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. All of the functions in SERIAL.h that start with the letters SPI (Serial Peripheral Interface) are new. All of the functions in the ANALOG.h, PWM.h, and TIMERIO.h header files in the \INCLUDE\MOSAIC directory are new. These files support the HCS12 processor’s built-in Analog To Digital (ATD) converter, Pulse-Width-Modulated (PWM) outputs, and Enhanced Capture/Timer (ECT) subsystems, respectively. The ECT timer includes input captures (IC), output compares (OC), pulse accumulators, a free-running 16-bit counter (TCNT), and a modulus down-counter.

A new SPIExchange 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. InitSPI 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 SPISave, SPIConfig, and SPIRestore 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 InitIPSPI function.

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 baud rates from 300 to 115200 bits per second; see the glossary entry for Baud for more details. The RS485Init, RS485Receive, and RS485Transmit functions now accept a serial port ID parameter to specify the relevant serial channel. The functions that implemented the software UART supporting the secondary serial port in prior products have been removed from the kernel.

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 Forth 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 function Random now returns a long instead of a 16-bit integer, and RANDOM_SEED now returns the address of a 32-bit variable. The newly available C function FRandom returns a floating point random number.

Additional low-level routines available in this kernel include,

See their glossary entries for more details. The CalcChecksum routine can handle memory regions that cross page boundaries.

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

All of the functions in the ANALOG.h, PWM.h, TIMERIO.h, and SEGMENTS.h header files in the \INCLUDE\MOSAIC directory are new. All of the functions in the SERIAL.h file that start with the letters IIC are new; they support the Inter-IC (IIC) clocked 2-wire multi-drop serial bus available on PORTJ of the HCS12 processor. All of the functions in SERIAL.h that start with the letters SPI (Serial Peripheral Interface) are new. For each of these header files, please consult the Categorized Function List for a list of the new device driver functions.

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

The following table lists the interactively callable (Forth) debugger functions that have been added to V6.xx that were not present in the V4.08 kernel.