Programming the PDQ Board Lite

The PDQ Board Lite is a low cost single board computer (SBC) and development board using the 9S1/HCS1 microcontroller. Like the PDQ Board, it contains an embedded RTOS in firmware and is programmed using a comprehensive GNU C integrated development environment (IDE). The IDE is far more extensive than that provided by Freescale's Code Warrior. Using the Mosaic IDE+ you can edit, compile, download, interactively debug, and run your multitasking application programs. You can also configure them to autostart on power-up.

The full-featured Mosaic IDE Plus handles programming on either the standard PDQ Board or the PDQ Board Lite. See the full documentation for the Mosaic IDE Plus for more information.

Before compiling your source code, go to the Project→ Project Compiler Options menu in the Mosaic IDE+ and in the top drop-down box select the kernel version number V6.02L (the L indicates the Lite version of the kernel). The IDE+ will clean and rebuild the libraries to ensure that there is synchrony between the generated *.dlf download file and the PDQ Board Lite firmware.

One difference between the PDQ Board and PDQ Board Lite is that the PDQ Board Lite provides only the on-chip memory of the microcontroller. So, while following the documentation for the PDQ Board, keep in mind the PDQ Board Lite's smaller memory footprint.

All of the memory on the PDQ Board Lite resides on the microcontroller chip, which has plenty of on-chip memory for programming, including:

• 320 KB Flash memory for your application program;
• 9 KB RAM for your variables and data; and,
• 384 bytes EEPROM so you can store status, modal, and calibration information.

The Mosaic IDE+ understands the memory map, and it will compile code into the available memory pages. Even so, if you have any questions about memory availability, please consult Memory Allocation.

Owing to the limited memory (255 bytes) allocated to the onboard Forth heap, the use of Forth arrays is not recommended on the PDQ Board Lite. The best approach is to use standard C variables, arrays and structs to code your C application on the PDQ Board Lite.

The Mosaic IDE+ development system includes an interactive debugging facility that is based on the onboard Forth language interpreter. The interactive debugger works by allowing the programmer to tag a function with the _Q keyword, or to tag a variable with the _qv keyword. Tagged names can then be interactively invoked at the terminal to execute a function or report the contents of a variable. These names are stored in the Forth names area when code is loaded onto the controller.

In addition, a range of driver software libraries is available to add functionality such as queued serial communications and additional software-based serial ports. Many of these drivers are implemented in Forth, and also create entries in the Forth names area for system use.

Because the PDQ Board Lite has a limited amount of RAM, the amount of memory reserved for the Forth interpreter is quite limited. Consequently, there is a limit of ten _Q or _qv declarations in any C application on the PDQ Board Lite if no drivers are being used. Exceeding this limit will cause a warning to be issued by the Mosaic IDE+. Each Forth-implemented driver consumes about 1.5 times as much space in the names area as a _Q or _qv definition, and including Forth-implemented drivers in your application reduces the threshold for Mosaic IDE+ (revisions above 1300) to generate this warning accordingly.

In revisions of Mosaic IDE+ above 1300, on loading code to the PDQ Board Lite a final definitive check is performed on whether the Forth names area has overflowed, and if so you will see a memory dump of the Forth names area followed by the message below, before the processor resets:

_Q NAMES OVERFLOW!

On loading an application including _Q or _qv definitions, you may see an error stating that one of the definitions isn't unique. Only the first nine characters of the defined name of a variable or function are stored in the Forth names area, along with the length of the name. This means that two definition names can share the same first 9 characters only if the total length of each name is different. If you see this error, the function or variable name in question has the same length and first nine characters as one of the other _Q or _qv definitions in your application, or one of the built in Forth words.

Depending on the particular drivers used and the names chosen for _Q functions and _qv variables, it is possible to breach the threshold for Mosaic IDE+ to generate the warning without actually overflowing the names area. The error produced on loading code is the definitive indication of whether the names area has overflowed or not.

If you wish to use additional _Q and _qv definitions, shortening the function and variable names defined may allow you to do so. In creating short variable names to use with _qv definitions, ensure that the variable name does not conflict with any built in Forth words, and that it contains at least one character that is not a hexadecimal digit (letters A-F plus numbers).

The Forth names area on the PDQ Board Lite is 256 bytes. Each _qv definition takes 14 bytes plus the length of the variable name, to a max total of 23 bytes. Each _Q definition takes 15 bytes plus the length of the function name, to a max total of 23 bytes. Each Forth-implemented driver that is loaded takes up 20 bytes of the Forth names area plus the length of the Forth segment name of the driver, which is generally the same as the driver's name in C. After loading code, you may view the contents of the Forth names area using the command below. If the names area has not overflowed, you should see the full name of every _qv variable, and every _Q function, plus a function called _cinit(, including a trailing open parenthesis on each one:

DIN 0x900 0x100 DUMP

A more direct way to verify that the Forth names area has not overflowed is to execute the following command, which prints a pointer to the end of the Forth names area, and check that the value printed is less than or equal to 0xA00:

NHERE HEXD.

If you wish to write a program that can be loaded on either a standard PDQ Board (with extra _Q and _qv debugging statements) or the PDQ Board Lite (where the _Q and _qv tags are suppressed), you can use the pre-processor directives #ifdef _MOSAIC_LITE or #ifndef _MOSAIC_LITE to remove all Forth-callable variables and functions as follows:

#ifdef _MOSAIC_LITE
#undef _Q
#undef _qv
#define _Q
#define _qv
#endif

The above code after the line #include <mosaic\allqed.h> will remove the existing _Q and _qv macros and then redefine them as null operations within that file, so that when compiling for the PDQ Board Lite no Forth debugging routines are generated.

If you'd like to define only some functions or variables as Forth-callable on the PDQ Board Lite but not others, or selectively remove some functionality for the PDQ Board Lite such as use of Forth arrays, see below for examples.

#ifdef _MOSAIC_LITE
static uint radius = 0;
#else
_qv static uint radius = 0;
#endif
 
 
 
#ifndef _MOSAIC_LITE
 
FORTH_ARRAY Last10Voltages;
 
_Q void CalcStats( void )
{
    mean = RowMean( 0, &Last10Voltages );
    standard_deviation = RowStandardDeviation( 0, &Last10Voltages, mean );
}
 
#endif
 
 
 
#ifdef _MOSAIC_LITE
void Wakeup( void )
#else
_Q void Wakeup( void )
#endif
{
    CalculationTask.USER_AREA.user_status = AWAKE;
}

The QSerial library converts one or both of the serial ports on PDQ Single Board Computer (SBC) to use interrupt-based queued operation instead of the standard polled operation to process incoming and outgoing characters. A queue is a first-in/first-out buffer that holds outgoing characters waiting to be sent, or incoming characters that have been received by the processor's serial hardware but have not yet been processed by the application program. The output and input queues are managed by interrupt routines, thus decoupling the rate of serial data exchange from the response speed of the C-language application program. Compared to polled serial, which requires that the application program service the serial port often enough to ensure that no characters are missed, these interrupt-based serial drivers can increase the reliable throughput of serial transactions. This chapter describes how to use the pre-compiled queued serial library. It's as easy as including a file from your application source code and then invoking an installation function. All of the standard serial routines (such as putchar, getchar, printf and scanf in C) will then operate using the queued serial drivers.

The queued serial capability for the PDQ Board is described here: Using Queued Serial

The restrictions for the PDQ Board Lite are as follows:

1. The queue buffers on the PDQ Board Lite are 64 bytes long, compared to 128 bytes each on the standard PDQ Board.
2. RS485 is not supported on the PDQ Board Lite.

A C demo programs is provided to illustrate how to use the queued serial channels.

The comments in the source code file present an explanation of the program. Simply load the program and run the top level routine to see the queued serial ports in action.

From the Mosaic IDE+ C environment, C programmers can invoke the queued serial library by including the following line in their source code file:

#include <qserial.h>