Chapter 8. Software Tools

Two sets of software tools are provided in the MuP21 Development System, which allows a user to evaluate the MuP21 chip and develop new applications. However, as MuP21 is a very new product, the tools are still undergoing frequent changes. We will be updating the tools as new features are included.

The first set of tools is that developed and used by Chuck Moore. The code was discussed in details in Chapter 6. The code generated from this system is what loaded into the MuP21 Development System. All parts except the OKCAD system have been verified and proven to work.

The second set of tools is provided by Jeff Fox of Ultra Technology. This package includes more conventional tools like cross assembler and emulator for MuP21. The tools were developed according to the original specifications of MuP21. As the prototype MuP21 has a problem with the data stack and the instruction OVER, this set of tools has to be used with caution. Jeff is working on a version which will take into account of the peculiar behavior of the prototype MuP21. It will be released in the near future.

8.1. OK Software Package

The OK4.1 package is supplied on a 5.25" floppy disketteand is distributed with the P21A2 board. It contains two files:

F.EXE FPC, a public domain Forth system for PC running under MSDOS.

OK.SEQ Tools to develop MuP21 applications.

FPC is a public domain Forth system optimized for PC computers. Its principal authors were Tom Zimmer and Robert L.Smith. Extensive documentation's were provided by C. H. Ting. The complete FPC system, documentation's, and application programs donated by users are available from Offete Enterprises.

The process to invoke FPC and OK.SEQ is the following:

1. Insert OK disk into drive A.

2. C> md MUP21 Make a new directory MuP21 on the hard disk C.

3. C> cd MUP21 Enter the new directory

4. C> copy A:*.* Copy F.EXE and OK.SEQ to the directory

5. C> F Invoke FPC

6. open ok.seq Open OK tools file

7. e Enter FPC editor to examine OK source code

8. Editor is intuitive and self-documented

Very easy to navigate and edit

9. F10 Exit editor, save changes

10. ok Compile the entire OK package with sample code

11. send Download compiled OK code to SRAM card

12. check Compare OK code with that in SRAM

If CHECK reveals no error, the SRAM card can be removed from the PCMCIA interface and inserted into the MuP21 Development System. Apply 4.75 volts to the MuP21 System, and the big 'OK' sign-on message will appear on the TV monitor screen.

If 'OK' does not appear right away, push the reset button to reset MuP21. Prototype MuP21 resets best at 4.75 volts. However, you may change the voltage to find the best reset condition for your chip. Once MuP21 resets successfully, the voltage can be changed. The system runs between 4.5 to 5.0 volts. MuP21 will run at 3.0 volts, but the SRAM card will shut down at 4.3 volts.

To develop new applications, write your own code following the examples provided by Chuck. You have to study his code carefully and observed closely how he developed various modules. Use the menu system he set up and attach your modules to keys so that you can test them using the keypad.

On the DEMO16 disk distributed with P21A5 board, there is a ZIP'ed file EMO16.ZIP. There are four files in it:

OK16C.SEQ Assembler, utility, boot code, and Chuck Moore's OK demo.

OKCHAR16.SEQ Text utilities and demo by C. H. Ting.

OKPICT16.SEQ 320x200 16 color picture decompression and demo by C. H. Ting

DEMO16C.BLK Binary image of P21DEMO in the P21c16 EPROM.

F.EXE FPC Forth system by Tom Zimmer.

From DOS, load FPC by:

C>f

Load demonstration files by:

include OK16C

You will see a list of names and compiled addresses scrolling on the screen. To write the compiled P21 code to a 128KB PCMCIA SRAM card, type:

send check

'Send' shipped 12KB of code to SRAM card. 'Check' compares the code in SRAM card with the compiled code in memory It reports any discrepancy. The PCMCIA interface is described in MuP21 Programming Manual.

If you want to burn the compiled code into a EPROM, save the compiled code to a file:

writeROMfile demo16c.blk

If demo16c.blk does not exit, such file will be created and 12KB of code copies into it. If it already exists, the lower 12KB of this file is updated.

Consult MuP21 Programming Manual for the detailed description of the P21 assembler and the demo programs. For the exact functionality, study the source code in OK16c, OPCHAR16, and OKPICT16.

To learn and to use the FPC Forth system, there are two manuals from Offete Enterprises:

FPC User's Manual ($20)

FPC Technical Reference Manual ($30)

A complete FPC Forth system with source listings, help files, and a hypertext referencing system can also be order from Offete for $25.

MuP21 system is still undergoing modifications and enhancements. Check with Offete for latest updates.

8.2 Rober Patten's Advanced P21 Assembler

The P21asm is an Target Macro assembler for the MuP21 microprocessor that is hosted on F-pc running on a IBM-PC. It is contributed by Robert Patten at Turlock, CA. It is supplied on a diskette which contains the following files:

MAKE BAT Make p21asm.exe from p21asm.seq

F-PC EXE Used in make.bat to create P21asm.exe from p21asm.seq

BOOT SEQ Source file for Mup21 creates object: boot.p21

P21ASM EXE Mup21 Target assembler >P21ASM BOOT.SEQ OK

P21ASM TST Test structures >P21ASM p21asm.tst ok

P21ASM HLP Help file for MmuP21 target assembler.

P21ASM SEQ Source for P21asm.exe

BOOT P21 MuP21 Memory image created by: >p21asm boot ok

OKCHAR SEQ Text extentsion included in boot.seq

README SEQ File directory

P21ASM DOC DOCUMENT of MuP21 assembler.

To assemble the test program in BOOT.SEQ, type the following DOS commands:

>MAKE

>P21ASM BOOT OK

The P21asm 8-bit assembler: creates MuP21 code that runs out of eight bit wide memory. Usually

it is used to boot the MuP21.

The P21asm 20-bit assembler creates a MuP21 Memory image file from ASCII source files. It maintains separate assembly pointers and symbol vocabularies for each 1024 word sheet of memory. It also maintains a Global symbol table available to all sheets of memory. This assembler aborts on off page jump or call, preventing the user to address off-page memory accidentally. It reports on MuP21 data or return stack underflow. Optionally it warns on data or return stack overflow. It reports stack change on execution flow structures, and also start and closure of flow structures. Finally it aborts on unmatched flow structure words.

P21asm provides much user friendly environment and helps first time user of MuP21 to avoid many pitfalls which may not be obvious by could be fatal.

8.3 Jeff Fox's P21Forth

P21Forth 1.0 is an ANS Forth system for the MuP21 microprocessor. It provides the use with a portable and easy to use programming environment that complies with American National Standard X3.215-1994 Forth language specification. P21Forth uses only 16 kilowords of MuP21 memory, but provides boot code, a text interpretter, a Forth compiler, an MuP21 assembler, metacompiler, and over 500 easy to access Forth words.

P21Forth supports colored text and graphics output to a video display, and it also supports a serial or parallel terminal or both. The user may select the type of input and output that they want to use. A terminal or at least a keyboard must be attached to the MuP21 system to use P21Forth.

When P21Forth starts it puts the message 'P21Forth 1.0' on the video screen and looks for a parallel or serial keyboard on the input port. If a serial terminal or keyboard is being used P21Forth will try to determine the speed of the attached device. P21Forth reads a 'b' character from the serial device and initializes the serial input output routine. To start P21Forth with a serial keyboard or terminal the user must send a 'b' character to the MuP21 system. If all of the bits on the parallel port are set when P21Forth boots it will assume that a parallel keyboard or terminal is attached and start in that mode.

After P21Forth displays the boot message and begins reading the keyboard it will respond to an Enter or Return with the familiar Forth 'ok' prompt. This is an indication that the text interpreter has processed a line of text and is ready for a new command. Press Enter several times and P21Forth should respond with several ok.

The P21Forth language consists of a list of over 500 words that are commands in the language and most can be executed if they are typed on the command line. A user can 'extend' the language by creating new words. The Forth word WORDS will display the names of all of the words in the Forth dictionary. Type WORDS and press Enter for P21Forth to display the list of defined words. If you press a key while the list is being displayed it will pause. If you then press the Enter key the display will stop, any other key will restart the list display.

P21Forth uses two dictionaries to store the names of the Forth words, and the code and data associated with those words. There are Forth words to manipulate the name and code dictionaries.

The operation and syntax of Forth is very simple. The syntax is simply that Forth words are separated by spaces. The operation is that words are looked up and found in the dictionary, or are interpreted as a number, or are an error. If you enter a word into the Forth interpreter it will try to look it up and execute the associated code in the dictionary. If the word is not in the dictionary it will then see if it is a number that can be put on the data stack. If it is not in the dictionary and is not a number then it is an error and an error message is generated.

If you type 1 2 3 and press Enter you will place the numbers 1, 2, and 3 on the data stack. The number 3 will be on the top of the stack. If you type a period and press Enter P21 will print the number on the top of the stack. If you type a period again and press Enter again it will print out the next item on the stack. If you attempt to print out more items that you have placed on the stack P21Forth will produce an error message.

The word : (pronounced Colon) is used to define new words in Forth. If you type

: XDEMO 1 . ;

and press Enter, this will define a new Forth word called XDEMO that will place a 1 on the data stack and then print out the value on the stack. The word XDEMO can now by typed on the command line or used in other definitions.

P21Forth will begin using the HEX number base. All numbers will be interpreted and displayed as HEX numbers. The word DECIMAL will change the number base to base 10 numbers. If you type HEX 1234 DECIMAL . Forth will interpret 1234 as a hex number, place it on the stack, and then remove it and print it as a decimal number.

The ANS Forth standard provides a new widely accepted portable standard for Forth programs. The standard specifices in detail the operation of standard words and also specifies the things that must be documented in order for a system to declare that it is an ANS Forth compliant implementation. The ANS Forth standard provides information that will be true of all ANS Forth compliant systems. The details of the implementation are provided in some utility words, the user manual, and the source for P21Forth 1.0.

In order to write portable ANS Forth programs one needs to maintain several programming habits. The most important has to do with addressing units. In ANS Forth memory is addressed in CELLS. A CELL is a unit of memory containing an item the size of one item on the stack. The MuP21 has a 21 bit ALU and a 20 bit memory bus. P21Forth is a 20 bit word implementation of ANS Forth. The items on the data and return stacks and in memory CELLS are 20 bits wide in P21Forth. MuP21 is a CELL addressing machine, that is each address of memory contains a 20 bit number or CELL. On a machine with byte addressing a 16 bit Forth would use two bytes per CELL, and a 32 bit Forth would use four bytes per CELL. Forth programmers who have used 16 bit Forths on byte addressing machines have a habit of using 2* to convert between the number of 16 bit items and the number of addressing units (or bytes) to hold them. The problem with this is that on a byte addressing machine a 32 bit Forth would need 4 * to convert between the number of items and the number of byte address units. ANS Forth uses CELL addressing, so it will support portable code. The word CELLS converts a count of items into the addressing number that a system uses. On a 32 bit Forth on a byte addressing machine CELLS would multiply by 4, and on a 16 bit Forth on a byte addressing machine CELLS would multipy by 2. In P21Forth CELLS does nothing. This is because on a word addressing machine CELLS is the same as 1 * which does nothing.

If a program is to be portable one must consider the correct use of the ANS Forth words CELL+, CELL-, and CELLS when dealing with the addresses of stack items stored in memory. Just as 2+ would properly move from the address of one stack item in memory on a byte addressing 16 bit Forth the word 1+ will properly move to the next stack item in memory on a word addressing machine and 4 + would work properly on a byte addressing machine with a 32 bit Forth. This type of code would not be portable on all machines. The correct use of CELL+ rather than 1+ or 2+ or 4 + or whatever can make a program portable on any ANS Forth implementation that also provides for all the specific environmental dependencies of a given program.

Consult the ANS Document for more information on portability issues. There are words in P21Forth that are standard ANS Forth words. If a user sticks to the proper use of these words programs can be portable accross ANS Forth systems. There are also words in P21Forth that are common to implementations of Forth. Finally there are words in the P21Forth implementation that are unique to P21Forth. If you write code that uses words specific to P21Forth then the code will not be portable unless these same words are provided on some different platform.