amrlogo


amrFORTH V6

Table of Contents

 Shortcut to Windows files Shortcut to Linux/BSD files
Introduction
Why Basic? Basic offers one major advantage to precompiled langauges such as Assembler or 'C', it allows the programmer to incrementally and interpretatively test work in progress. This encourages small modules of tested, trusted, code. These modules are then linked together as subroutines.    Unlike Assembler and 'C' BASIC doesn't require large, expensive, bulky support equipment such as in-circuit-emulators or single-step debuggers.

Another advantage is that BASIC is a “High Level Language” allowing the programmer to accomplish more in a single command making the program more comprehensible and much shorter. C did have advantages but at the same time brought about it's own set of problems; mainly C was arcane, difficult to learn, and expensive for usable implementations. Being deveopled for large systems, C is overkill for most embedded projects...

BASIC's major advantage is that it isolates us from much of the underlying structure permiting the programmer to focus directly upon the problem at hand rather than on their tools.
Why FORTH? amrFORTH Is a new species of the machine-control language FORTH, a high level language with a kernel of about half a kilobyte while remaining fully interactive, able to interpret keyboard commands. amrFORTH contains a full slate of functions including editor, compiler, serial communications to the host terminal, an assembler, and soon a disassembler, decompiler and single-step source level debugger. All in as little as 582 bytes of memory on the target microcontroller.

Our Gadget series complements current technology amr51, amr451, amr537, amr552 and amr6811 products in a classification called "Tethered Microcontrollers". In this class much of the overhead not needed in embedded applications is relegated to the Host/File server for two reasons, first moving the compiler and interpreter to the host dramatically reduces the ROM requirements of the Target system and, secondly, the Host has more horsepower and is able to reduce the compilation time significantly.

As application engineers ourselves, we need a complete development system wherein we can remain within a friendly environment, any environment would do if only we could work within one command set. We, too, suffered the vicious time wasting cycle of editing the program in a word processor or a commercial assembler, compiling with another set of commands, spitting the result to disk and exiting to DOS where we would have to copy the file to a ROM burner directory, move to that directory and enter the ROM burner program, find and fry the EPROM, exit back to DOS or switch to an In-Circuit-Emulator to debug in yet another language. Ugh! Then, when the inevitable bug was found we would have to repeat this terribly time consuming process.

Now, with amrFORTH and amrBASIC, we are free to develop applications with a fully interpretive language where debugging is quick and simple, compilation is essentially instantaneous, the editor, ROM emulator, ROM burner, decompiler and disassembler are all available within a unified framework. Read on and go where your interest takes you, this manual has been written in a modular manner with each chapter complete in itself Some of the examples and code are better understood if you have a Target system functioning at your fingertips. Within a very short time it is reasonable to expect a productivity improvement factor of 10 or more over assembler, basic or 'C' languages while obtaining an improvement of 2 to 20 times in execution speed.

Why Assembler?
Assembler has a number of uses:
  • When you want absolute control over your code without the compiler getting in the way.
  • Some things are just easer to do in assembler than in high level Forth or Basic.
  • For dinosaur programmers who refuse to use modern tools.
  • Adding features that are otherwise unavailable.

Why AM Research Gadgets are better than stamps

  • They're faster. Not just a bit faster. Not twice as fast. In some cases our Gadgets are 2,500 times faster than stamps!
  • They use a higher level of integration. Standard features included which are unavailable on stamps.
  • Standard core processing unit. Based upon the 8051 which has been tested by professionals for 30 years.
  • More features. Timer/counters, A/D's, multiple UART's, D/A's.

Install
Installation is similar in both Windows and Linux/BSD.    Just choose Windows or Linux, then from CD or from the Web:
Windows Install
  • Installing From CD
    • Install Tcl/TK
         Using File Explorer, or any GUI file browser, find the \windows directory on the CD.    Hold down the control key on your keyboard, click on the ActiveTcl8.4.2.0-win32-ix86.exe icon drag and drop it onto your desktop.  This copies the install file rather than making a shortcut.  Now run the installer by double clicking on the icon on your desktop.  Follow instructions and accept the default directory paths.  When the installer has finished you may delete the icon from your desktop. Tcl/Tk will not install directly from the CD, you must copy it to your workstation and install from there.
    • Install Gforth
         From the CD execute: "gforth-0.5.0.exe"  (or newer revision) and follow the instructions. Use all suggested folders and directories.
    • Install amrFORTH
         From the CD execute amr-install.bat to complete the installation.
    • Run amrFORTH
         Now, to launch and execute amrFORTH or amrBASIC go to Startup

  • Installing From the Web
    • Install Tcl/TK
         Download and execute:   Tcl/Tk   follow the instructions, use default folders and directories.
    • Install Gforth
         Download and execute newest revision of   Gforth   , follow the instructions.    Use default folders and directories.
    • Install amrFORTH
         Download and install the latest version of amrforth Grab all three files, the most recent version of amrforth-v6-windows-xxxxxxx.zip, amr-install.bat, and unzip.exe. Be sure to have all three files downloaded into the same directory then execute amr-install.bat to complete the installation.
    • Run amrFORTH
         Now, to launch and execute amrFORTH or amrBASIC go to Startup

  • Upgrading From the Web
    • Tcl/tk
         Before installing the latest version, you should uninstall the previous version. Go to the start menu, choose Programs/ActiveStateActiveTcl8.4.4.0/UninstallActiveTcl8.4.4.0 and follow instructions, remembering that the version number may change. Now simply install the latest version of Tcl/Tk from the CD or from the Web as detailed above.
    • Gforth
         Uninstall the previous version before upgrading to a new version. Go to the start menu, choose Programs/Gforth/Uninstall Gforth, and follow instructions. Now you may install the new version of Gforth from CD or the Web as detailed above.
    • amrFORTH
         To uninstall amrFORTH simply delete the \amrforth folder using your filemanager. Then install the new version from CD or from the Web as detailed above.
    • Run amrFORTH
         Now, to launch and execute amrFORTH or amrBASIC go to Startup

Linux/BSD Install
  • Installing From CD
    • Install Tcl/TK
         If you already have Tcl/Tk installed then don't reinstall.    It is unlikely that your default installation included Tcl/Tk however you will find Tcl/Tk on your installation CD's.    First confirm that Tcl/Tk is not installed. If that is the case then install from your Linux distribution.    The chances that your Linux distribution does not include Tcl/Tk are so slight that we have not included Tcl/Tk on our CD.

         If you cannot get Tcl/Tk from your Linux distribution then install from the Web.

    • Install Gforth
         If you already have Gforth installed then do not reinstall.    It is probable that your default ation included Gforth.    If not then first consult and install from your Linux distribution if available otherwise install from the amrFORTH CD by moving to your home directory and executing "tar -xvzf /path/gforth-0.5.0-i386-pc-linux-gnu.tar.gz"   where "/path/" is the path to your CD drive and may be similar to "/mnt/cdrom/linux/".
    • Decompressing the .tar file will create the subdirectory "gforth-0.5.0" off your home directory. To finally install Gforth, cd to ~/gforth-0.5.0, su to root, execute './configure' then 'make install'.
    • Gforth may be a newer, higher, revision in future releases, so the version number may change.

    • Install amrFORTH
         From the CD execute 'amr-install' to complete the installation. The batch file will create the ~/amrforth/v6/ path and untar the files there.

    • Run amrFORTH
         Now, to launch and execute amrFORTH or amrBASIC go to Startup

  • Installing From the Web

    • Install Tcl/TK
         ActiveTcl for Linux is available at:   Tcl/Tk   follow the instructions, use default folders and directories.    You will probably not need to get Tcl/Tk from the Web.

    • Install Gforth
         Download newest revision of   Gforth   into your home directory. Move to your home directory and execute "tar -xvzf gforth-0.5.0-i386-pc-linux-gnu.tar.gz"  Decompressing the .tar file will create the subdirectory "gforth-0.5.0" off your home directory. To finally install Gforth, cd to ~/gforth-0.5.0, su to root, execute './configure' then 'make install'.

    • Gforth may be a newer, higher, revision in future releases, so the version number may change.

    • Install amrFORTH
      Download and install the latest version of amrforth    Be sure to grab both files, the most recent version of amrforth-v6-windows-xxxxxxx.zip, and amr-install. Be sure to have both files downloaded into the same directory, then execute amr-install to complete the installation.

    • Run amrFORTH
      Now, to launch and execute amrFORTH or amrBASIC go to Startup

  • Upgrading From the Web

    • Tcl/tk
      There really is no reason to upgrade your Tcl/Tk from the Web. Simply use the version that comes with your distribution of Linux/BSD.

    • Gforth
      If you have already installed Gforth there is probably not a good reason to upgrade. We are not using any cutting edge features of Gforth. In fact, we have no experience upgrading Gforth. We believe that a new version can be installed over an old version without uninstalling.    Simply follow instructions above for installing from the Web.

    • amrFORTH
      To uninstall amrFORTH simply delete the ~/amrforth directory with rm -r ./amrforth. Then install the new version from CD or from the Web as detailed above.

    • Run amrFORTH
      Now, to launch and execute amrFORTH or amrBASIC go to Startup

Startup
Index
Overview

The installation disk includes source code for the serial bootloaders for a number of Cygnal C8051Fxxx chips as well as the f300-hosted JTAG loader along with some simple test code.

For Windows and MS-DOS users, this source is contained in the amrForth\V6\300 , amrForth\V6\310 , amrForth\V6\061 and \amrForth\V6\017 directories. For Linux users, this source is in the ~/amrforth/V6/300 , ~/amrforth/V6/310 , ~/amrforth/V6/061 and ~/amrforth/V6/017 directories.

Windows Startup
  • Use Explorer to create a desktop shortcut for the "\amrforth\v6\300\example\amrf.bat" batch file, for example. Clicking on this shortcut the amrFORTH GUI will startup in the ...\300\example\ directory.
  • From an MS-DOS Prompt, "cd" to the C:\amrForth\v6\300\example directory and run the amrf.bat script. This should bring up the amrForth V6 GUI, ready for you to configure.
Linux Startup
  • From a shell prompt, "cd" to ~/amrforth/v6/300/example and run the ./amrf script.
Options
  • After starting amrFORTH you absolutely must set system options before communicating with a Gadget. In the title bar you will see "amrForth V6".    Below the Title Bar is a menu row, pull down the "Configure" choice then "Configure: Processor/C8051F0xx".    A list of choices will be offered, set the appropriate comm port, your choice of font size and colors and save when finished. Now you're ready to communicate with your Gadget and develop a project.
Projects
  • After starting amrFORTH, you can create your own project directories. Pull down the FILE menu and choose NEW PROJECT. You will get a file browser dialog that lets you choose (or create) a directory for your next project. The necessary batch or script files are placed in that directory automatically when you click on OK. Configure your project by pulling down the OPTIONS menu and choosing CONFIGURE, then choosing the correct processor and comm ports. Finally, if you are using Windows, you may want to create an icon for this project as detailed above.
Compiling

Two methods of compiling exist, GUI clicking and command line.

GUI Compilation. You can compile by entering c at the GUI command line as well as by pulling down the Compiler/Compile menu. To turnkey your application, use the TURNKEY option on the COMPILE menu or just enter t at the GUI command line. The compiler automatically loads the file named job.fs in the current directory. This file should either contain your program, or load other files that do contain your program.    The example directories show how this can be done. In order to turnkey your program, the word go must be defined and it must first perform any initialization and then fall into an endless loop.

Command Line Compilation

Windows/DOS

Three batch files are used that you should be familiar with, amrf.bat, c.bat, and t.bat.
  • "c.bat"   is short for "compile" which translates your high level Forth and Basic instructions to machine instructions the Gadget understands. The entry point is "quit" which is the interactive forth/BASIC interpreter.

  • "t.bat"   is short for "turnkey" which compiles your high level Forth or Basic instructions just as "compile" does, except that the entry point will be the word "go", which should be the name of your main program loop.

  • "amrf.bat" launches the amrFORTH GUI. This GUI has menus as well as a command line to make configuring, compiling, downloading, and interpreting easy, all in one environment.

  • Note: You may wish to use your favorite editor. This is fine as long as the output is straight ascii, Micro$oft Notepad will not suffice because it installs footers inline with your code.

Linux/BSD
  • In the V6 directory are the script files ./c and ./t as well as ./amrf. If you want to work from a Linux shell, edit your files with your favorite editor and compile with ./c (or ./t for Turnkey) and then run ./amrf to test interactively once you have compiled successfully. You can use your own editor and still compile and download from within the ./amrf GUI. Just be sure the output is straight ascii.

Downloading

As you will see, there are various ways to download code, depending on environment, destination and usage. However, there is seldom a need to worry about download modes. Because the serial bootloader is installed on all Target chips at the factory, you may never need to use the JTAG or C2 downloaders.

Once the serial bootloader is installed on the Target Board (by the factory or by the JTAG Loader), you will usually want to download code either via the COMPILE/DOWNLOAD_RS232 menu sequence from the GUI Menu bar or from the command line in the GUI.

Sometimes mousing becomes inconvenient. To save hand movement you can use the amrForth command line on the amrFORTH GUI for many oft used functions. For example type c at the GUI command line prompt to compile your application.    Similarly, you can turnkey your application by typing t and you can download code by entering d.

MS-DOS users can also compile or turnkey code by typing c or t at the MS-DOS command line prompt using the same single-letter commands. They will still need to run amrf.bat, the amrFORTH GUI, and change to forth or BASIC mode, in order to download and test their code.

Linux users can do the same operations from a shell by entering ./c and ./t.    Interactive testing occurs in the amrFORTH GUI in the forth or the basic mode.

Note: Executing the serial downloader is driven by screen prompt. Whether the GUI menu choice "Compile/Download_RS232" or the command line (by typing "d ") is used, amrFORTH will prompt you through the process. This process is: first press the reset button on the Gadget Motherboard. Hold the reset button. down then tap the spacebar then release the reset button. On the Host screen download progress will be displayed.

JTAG/C2 Loader

We are simply explaining the process here for your information, in case you find a need to create a JTAG Loader. You may skip this explanation without missing anything of critical importance.

An f300 Target Board with the JTAG and C2 loaders programmed into its f300 chip is called a JTAG Loader Board (or just a JTAG Loader). You can use the JTAG Loader to directly download programs to f017 Target Board and the C2 Loader to download programs to the f300 or f310 Target Board.

Normally, the JTAG/C2 Loader is used to load a serial downloader program (serial bootloader) into your Target Board. After the serial bootloader is loaded into the Target, you can use it to program the Target's flash memory. To make a JTAG Loader, first install an f300 Target Board in the JTAG slot located near the right hand edge of the Development Board. Also connect the serial cable to the JTAG jack. This jack is the one to the right of the serial development jack and is labeled "JTAG"../ on the printed circuit board.

Note: To download the JTAG program in the following way, the f300 Target must have a serial bootloader programmed into it -- all f300 Target boards have this program installed on the chip when they are shipped from the factory.

Load the JTAG program into the f300 Target Board by first selecting the \V6\f300\JTAG directory using the FILE/OPEN_PROJECT menu sequence. Make sure that you have set the processor to f300, and saved this configuration, in this directory, using the SAVE button in the Configure dialog.

Compile the JTAG Loader program by selecting the Turnkey option on the Compile Menu. Finally, select the Download RS-232 option on the Compile Menu to download the JTAG loader program.

Note: If you try to download your own program via C2 or JTAG, you must patch a jump to COLD at address 0 as follows:

    romHERE ( *) 0 org

    in-assembler COLD jump c;

    ( *) org


Normally the amr serial bootloader resides at address 0, the reset vector. If you just use the amr serial bootloader you will not need to worry about any of this.

Checking the JTAG Loader

To check the JTAG Loader, install either an f017 or an f300 in the appropriate slot in the motherboard.

Note:Do not install two Target boards at the same time!

Test the JTAG Loader by choosing the PROGRAMMER/JTAG/DUMP menu sequence for the f017 or the PROGRAMMER/C2/DUMP sequence for the f300. You should see a hex dump of the lowest page in memory on the target. The JTAG dump is 512 bytes and the C2 dump is 256 bytes. To see more dump pages, select the PROGRAMMER/JTAG/NEXT or PROGRAMMER/C2/NEXT menu sequences.  For command line users, type jtag or c2 to change to the appropriate mode.  The prompt will show what mode you are in.  Then type dump to see the first page and next or n to see subsequent pages.

If the dump works, you can install the serial bootloader by choosing JTAG/DOWNLOAD for the f017 or C2/DOWNLOAD for the f300. Use the DUMP and NEXT options to verify that the download occurred.

Now you should be able to switch from the jtag serial port to the target serial port and download programs via the serial bootloader.

Version 6 Features
Version 6 is a big change from version 5.    If you have familiarity with Version 5 then please study these differences carefully.

Index

Interpreter
Loops and For/Next
Goodbye to Old Friends
Switching Between Forth and Assembler
Target Heads
System Portability
Comments and Suggestions


Interpreter

  Actually there are five different modes of interpretation each with a corresponding prompt:

   - "host" which give you the "host>" prompt.  For communicating with Tcl/Tk on the workstation. Rarely needed except for changing modes of operation.

   - "forth" which gives the "forth>" prompt.  for communicating with the Gadget using the amrFORTH language.

   - "basic" which gives the "basic>" prompt.  For communicating with the Gadget using the amrBASIC language.

   - "jtag" which gives the "jtag>" prompt.  For communicating with the Gadget using amrFORTH with only JTAG words compiled.  Needed only to install the boot loader into the C8051F310, 017 and 061 Gadgets.

   - "c2" which gives the "c2>" prompt.  For communicating with the Gadget using amrFORTH but with only JTAG2 words compiled.  Needed only to install the boot loader into the C8051F300 Gadget.

The amrFORTH target interpreter has changed from a direct threaded inner interpreter in V3-5 to native machine code or call threading in Version6 providing an 8-fold speed improvement in NEXT. The new compiler tries to be smart enough to change redundant calls to jumps in the word "exit" for efficient tail recursion.

Most 'words' now end in a jump to the last word instead of a call followed by a return. Also if you use exit inside a definition, it will change a preceding call into a jump. This is a thinly disguised goto.

These changes were inspired by Chuck Moore's ColorForth. We have also added the words push and pop which are aliases for >R and R>.


Here are links to specific vocabulary definitions for each interpretative mode:

Host Words
Host JTAG Interface Words
Host JTAG C2 Interface Words
Gadget Basic Mode
Gadget Forth Mode

HOST WORDS
(Words that execute on the host, when not in communication with the Gadget.)

jtag Change the current, working, vocabulary to the standard, 4-wire, JTAG vocabulary. Command line control of the JTAG interface.
forth Change the current, working, vocabulary to the target Forth vocabulary for interactive testing.
c2 Change the current, working, vocabulary to the C2 JTAG vocabulary, command line control of the C2 interface.
basic Change the current, working, vocabulary to the target BASIC vocabulary.
words Show the words of the current vocabulary.
bye Exit amrForth.
edit Start editing the file whose name follows on the command line.
c Compile the current project as defined within job.fs in the current project directory. For interactive testing, does not install an autostart vector..
t Turnkey compile the current project as defined within job.fs in the current project directory, for turnkey installation.
d Download the object code from the file rom.bin to the target via RS232.

JTAG Interface Words
(Words used to install a boot kernel into the Gadgets through a special JTAG interface. Very rarely used.)

host Change to the Host vocabulary, your starting point.
forth Change to the target Forth vocabulary, for interactive testing.
c2

 Change to the C2 vocabulary, command line control of the C2 interface.
basic Change to the target BASIC vocabulary, for interactive testing.
words Show the words in the JTAG vocabulary, these words.
suspend Issue the JTAG suspend command.
run Issue the JTAG run command.
reset Issue the JTAG reset command.
next Dump the next page of target memory via JTAG interface.
n Alias for Next, easier to type.
halt Issue the JTAG halt command.
erase Erase all of target memory via the JTAG interface.
dump Dump the first page, 512 bytes, of target memory via the JTAG interface.
download Download the object code in the file rom.bin to the target via the JTAG interface.

JTAG C2 Interface Words
(Words used to install a boot kernel into the Gadgets through a special JTAG interface. Very rarely used.)

jtag Change to the JTAG vocabulary, command line control of the JTAG interface.
host Change to the Host vocabulary, your starting point.
forth Change to the target Forth vocabulary, for interactive testing.
basic Change to the target BASIC vocabulary, for interactive testing.
words Show the words in the C2 vocabulary, these words.
bye Exit amrForth or amrBASIC.
next Dump the next page of target memory via C2 interface.
n Alias for Next, easier to type.
erase Erase all of target memory via the C2 interface.
dump Dump the first page, 256 bytes, of target memory via the C2 interface.
download Download the object code in the file rom.bin to the target via the C2 interface.

Gadget Basic Mode
(Words that execute on the Host and Gadget when in Basic mode)


Host Words
(Words that execute on the host, when not in communication with the Gadget.)

jtag Change to the JTAG vocabulary, command line control of the JTAG interface.
host Change to the Host vocabulary, your starting point.
c2 Change to the C2 vocabulary, command line control of the C2 interface.
forth Change to the target FORTH vocabulary, for interactive testing.
words Show the words in the Forth vocabulary, both host and target.
t Turnkey compile job.fs in the current project directory, for turnkey installation.
d Download the object code from the file rom.bin to the target via RS232.
c Compile job.fs in the current project directory. For interactive testing.
bye Exit amrForth.
edit Start editing the file whose name follows on the command line.
BASIC OPERATORS
(Arithmetic and logic, logical operators return numbers, -1 for true and 0 for false)
(operators are evaluated left to right, no precedence, no parentheses)

<> 'not equal' e.g. print b0 <> 0 ; let b1 = b0 <> 0
>= 'greater or equal' e.g. print b0 >= 10 ; let b1 = b0 >= 10
<= 'less than or equal' e.g. print b0 <= 10 ; let b1 = b0 <= 10
|/ 'bit or logical not' e.g. print b0 |/ b1
^/ 'bit xor logical not' e.g. print b0 ^/ b1
&/ 'bit and logical not'
// 'remainder'e.g. print 26 // 5
/ 'integer divide'
** 'high word of product' e.g. print 10000 ** 10000
* 'low word of product, or simply multiply' e.g. print 5 * 2
max 'signed max' returns the greater, e.g. print -10 max 10
min 'signed min' returns the lesser, e.g. print -10 min 10
> 'greater'returns true or false, e.g. print b0 > 0
= 'equal'e.g. print b0 = 0
< 'less than' returns true or false, e.g. print b0 < 0
^ 'bitwise exclusive or' e.g. print b0 ^ 1
| 'bitwise inclusive or' e.g. print b0 | 1
& 'bitwise and' e.g. print b0 & 15
- 'minus' e.g. print b0 - 2
+ 'plus'e.g. print b0 + 10
b9 e.g. print b9 ; let b9 = 5
b8 e.g. print b8 ; let b8 = 5
b7 e.g. print b7 ; let b7 = 5
b6 e.g. print b6 ; let b6 = 5
b5 e.g. print b5 ; let b5 = 5
b4 e.g. print b4 ; let b4 = 5
b3 e.g. print b3 ; let b3 = 5
b2 e.g. print b2 ; let b2 = 5
b1 e.g. print b1 ; let b1 = 5
b0 e.g. print b0 ; let b0 = 5

BASIC WORD VARIABLES
w4 e.g. print w4 ; let w4 = 500
w3 e.g. print w3 ; let w3 = 500
w2 e.g. print w2 ; let w2 = 500
w1 e.g. print w1 ; let w1 = 500
w0 e.g. print w0 ; let w0 = 500
BASIC I/O BITS
pins Pins is the BASIC I/O port. There are currently only 8 I/O bits available including the serial port Tx and Rx bits. They are encapsulated in the byte variable pins. e.g. print pins ; let pins = 1
dirs The 8 bit I/O port pins has a corresponding direction register called dirs. Zero bits are input ports and one bits are output ports.
pin7 e.g. print pin7 ; let pin7 = 0
pin6 e.g. print pin6 ; let pin6 = 1
pin5 e.g. print pin5 ; let pin5 = 0
pin4 e.g. print pin4 ; let pin4 = 1
pin3 e.g. print pin3 ; let pin3 = 0
pin2 e.g. print pin2 ; let pin2 = 1
pin1 e.g. print pin1 ; let pin1 = 0
pin0 e.g. print pin0 ; let pin0 = 1

Gadget Forth Mode
(Words that execute on the Host and Gadget when in Forth mode)


Host Words
(Words that execute on the host, when not in communication with the Gadget.)

jtag Change to the JTAG vocabulary, command line control of the JTAG interface.
host Change to the Host vocabulary, your starting point.
c2 Change to the C2 vocabulary, command line control of the C2 interface.
basic Change to the target BASIC vocabulary, for interactive testing.
words Show the words in the Forth vocabulary, both host and target.
t Turnkey compile job.fs in the current project directory, for turnkey installation.
d Download the object code from the file rom.bin to the target via RS232.
c Compile job.fs in the current project directory. For interactive testing.
bye Exit amrForth.
edit Start editing the file whose name follows on the command line.

Gadget Words
(Words that execute on the Gadget while in Forth Interpretative mode)
type (addr len - ) Send a string out the serial port.
.s ( - ) Show what's on the data stack, top of stack to the right.
dump ( addr len - ) Show a hexadecimal dump of target memory over the serial port.
. ( n - ) Display top of stack (TOS) via the serial port as a signed 16 bit number.
u. ( u - ) Display top of stack over the serial port as an unsigned 16 bit number.
dot ( u base - ) Display top of stack in radix specified by base.
hb. ( u - ) Display top of stack as two hex digits, 8 bits.
h. ( u - ) Display top of stack as four hex digits, 16 bits.
.hex ( digit - ) Display top of stack as a single hex digit, 4 bits.
cr ( - ) Send a carriage return, line feed pair out the serial port.
space ( - ) Send a space character out the serial port.
quit ( - ) Run the text target portion of the interactive text interpreter.
vectors ( - addr) The address of an array of used in quit, to implement the text interpreter.
perform ( - ) Receive a 16 bit address over the serial port and execute its code. Used in quit.
number ( - ) Receive a 16 bit number over the serial port. Used by quit.
emit ( c - ) Send a character over the serial port.
key ( - c) Receive a character over the serial port.
key? ( - flag) Flag is true if a character is waiting on the serial port.
abort ( - ) Reset the stacks and run the default startup word, 'quit' if debugging, 'go' if turnkeyed.
(s”) ( - ) Runtime behavior of s”. Don't run this from the command line. It is compiled inline by the word s”. It appears in the word list as an artifact of the compiler.
* ( n1 n2 – n2) Multiply n1 by n2 returning n3, a signed 16 bit number.
*/ ( u1 u2 u3 – u4) Multiply u1 by u2 then divide the 32 bit intermediate product by u3. All numbers are 16 bit unsigned, except the intermediate product.
/ ( u1 u2 – u3) Divide u1 by u2, returning the truncated quotient u3. All numbers are 16 bit unsigned.
mod( u1 u2 – u3) Divide u1 by u2, returning the remainder. All numbers are 16 bit unsigned.
/mod ( u1 u2 – u3 u4) Divide u1 by u2, returning the remainder u3 and the truncated quotient u4. All numbers are 16 bit unsigned.
max ( n1 n2 – n3) N3 is the greater of n1 and n2. All numbers are 16 bit signed.
min ( n1 n2 – n3) N3 is the lesser of n1 and n2. All numbers are 16 bit signed.
u> ( u1 u2 – flag) Flag is true, all bits set, if u1 greater than u2, all zero otherwise. Unsigned 16 bit numbers.
> ( n1 n2 – flag) Flag is true if n1 greater than n2, all zero otherwise. Signed 16 bit numbers.
= ( n1 n2 – flag) Flag is true is n1 equals n2. Signed 16 bit numbers.
< ( n1 n2 – flag) Flag is true if n1 less than n2. Signed 16 bit numbers.
negate ( n1 – n2) N2 is the two's complement negative of n1.
abs ( n1 – n2) N2 is the absolute value of n1, in other words it's positive.
2* ( n1 – n2) Multiply n1 by 2.    Actually shift the bits of n1 left one place. Much faster than an actual multiplication.
+! ( n addr - ) Add n to the value at address addr.
nip ( n1 n2 – n2) Drop the second number on the data stack.
clear ( ??? - ) Make the data stack empty.
count ( addr1 - addr2 c) Addr2 is addr1+1 and c is the byte value at address addr1. Called count because it takes advantage of the format of a counted string in forth.
um/mod ( ud u1 - u2 u3) The division primitive.    All numbers are unsigned. Divide the double precision (32 bit) number ud by 16 bit u1, returning 16 bit remainder u2 and 16 bit truncated quotient u3.
um* ( u1 u2 - ud) The multiplication primitive. All numbers are unsigned. Multiply 16 bit u1 by 16 bit u2 returning 32 bit ud.
u< ( u1 u2 -flag) Flag is true if u1 is less that u2. All numbers are 16 bit unsigned.
2/ ( n1 – n2) 2/ divides n1 by two, by shifting bits right one space. Much faster than actual division.
(next) ( - ) Runtime behavior of next, part of the for, next loop. Don't run this from the command line. It is compiled inline by the word next. It appears in the word list as an artifact of the compiler.
r@ ( - n) Copies the top of the return stack to the data stack. This word is compiled inline by for when using a for, next loop.
i ( - n) An alias for r@. Returns the index to a for, next loop.
invert ( n1 - n2) Invert all bits. Bitwise not.
not ( n1 - n2) Logical not. If n1 is zero is -1, true, otherwise n2 is zero.
0= ( n1 - n2) Logical not. An alias for not.    Returns true of top of stack is zero.
xor ( n1 n2 - n3) Exclusive or.
or ( n1 n2 - n3) Inclusive or.
c! ( c addr - ) Store the byte c at address addr. If the address is less than 256 it resides in internal RAM, otherwise it is in external data memory.
! ( n addr - ) Store the 16 bit word n at address addr. If address is less than 256 it resides in internal RAM, otherwise in external data memory.
!x ( n addr - ) Store the 16 bit word n at address addr. Address is always in external data memory.
!i ( n addr - ) Store the 16 bit word n at address addr. Address is always in internal RAM. The high byte of address is ignored.
c!i ( c addr - ) Store the byte c at address addr. Address is always in internal RAM. The high byte of address is ignored.
c@ ( addr - c) Fetch the byte c from address addr. If address is less than 256 it resides in internal RAM, otherwise in program memory.
@ ( addr - n) Fetch the 16 bit word n from address addr. If address is less than 256 it resides in internal RAM, otherwise in program memory.
@xd ( addr - n) Fetch the 16 bit word n from address addr in external data memory.
c@xd ( addr - c) Fetch the byte c from address addr in external data memory.
c@x ( addr - c) Fetch the byte c from address addr in program memory.
@i ( addr - n) Fetch the 16 bit word n from address addr in internal RAM.
c@i ( addr - c) Fetch the byte c from address addr in internal RAM.
r> ( - n) Pop the top of the return stack onto the data stack.
pop ( - n) An alias for r>.
push ( n - ) Push n onto the return stack.
>r ( n - ) An alias for push.
depth ( - n) Return the depth of the data stack, how many items are on the stack.
and ( n1 n2 - n3) Bitwise AND.
0< ( n - flag) Flag is true if n is negative.
- ( n1 n2 - n3) Subtract n2 from n1. Signed 16 bit numbers.
+ ( n1 n2 - n3) Add n2 to n1. Signed 16 bit numbers.
c!x ( c addr - ) Store the byte c at address addr in external data memory.
@x ( addr - n) Fetch the 16 bit word n from address addr in program memory.
flip ( n1 - n2) Flip or swap the bytes in 16 bit word n1.
over ( n1 n2 - n1 n2 n1) Copy the second number on the data stack onto the top of the data stack.
swap ( n1 n2 - n2 n1) Swap the order of the top two numbers on the data stack.
dup ( n1 - n1 n1) Make a copy of the top number on the data stack.
drop ( n1 - ) Drop the top number on the data stack.
2drop ( n1 n2 - ) Drop the top two numbers on the data stack.
branch The primitive for an unconditional branch. Compiled inline by again and repeat. Don't run this from the command line. It appears in words as an artifact of the compiler.
?branch The primitive for a conditional branch.    Compiled inline by if, until, and while. Don't run this from the command line. It appears in words as an artifact of the compiler.
noop ( - ) No operation, just delays a very short time and takes up a tiny bit of space.
execute ( addr - ) Jumps to and begins executing at the address left on the data stack.
lit ( - n) Runtime code for a word literal (a number to be placed on the data stack). Don't run this from the command line. It shows up in words as an artifact of the compiler.
clit ( - c) Pronounced 'see-lit'. Runtime code for a byte literal. Don't execute this from the command line.    It shows up in words as an artifact of the compiler.
Loops and For/Next

The do / loop construct is no longer supported. The pair occupied over 200 bytes and were just too complicated. Instead we now use for / next. Do/loop are still included in the library should you wish to add and use but the memory requirements were too great.

Use For / next when you need a counted loop. For / next counts down from the number on top of the stack to one, so 10 for next will execute 10 times. The word i still exists, and returns the index to the for / next loop. It is equivalent to R@. Unlike the version 5 for / next loop, this one uses a 16 bit index.





Goodbye to Old Friends

Several primitives have been eliminated, such as 1+, 1-, 2+, 2-, tuck, and rot. If you really need any of these they are easy to implement and still included in the libarary files.



Switching Between Forth and Assembler

It is possible now to switch back and forth between assembler and forth in a single definition, if it seems to help solve a problem. See the definition of C2reset in the file ~/amrforth/V6/300/jtag/main.fs in Linux or \amrforth\V6\300\jtag\main.fs in Windows for examples.



Target Heads

Another new feature is the ability to put heads on the target for a standalone interpreter. See the file headers.fs in the same jtag directory and main.fs for typical usage.



System Portability

Both Windows, Linux and BSD/Unix are now supported!

To achieve cross-platform portable TCL/TK are used for the GUI interface and serial port access. This results in a unique, portable system for Windows, Linux and BSD/Unix. Version 5 was limited to Linux only.

When installation is complete amrFORTH and amrBASIC work almost identically on all operating systems.



Comments and Suggestions

Comments and suggestions are very welcome. Please look at the HISTORY file in ~/amrForth/V6 or \amrForth\V6. We are keeping a TODO list at the top and documenting bug fixes and feature additions below. Once again comments and suggestions are welcome.

Good luck, have fun, and let us know your experiences!

email_support

History
Open Source is not just sharing source code but sharing knowledge.    We actively encourage users to modify and test their own variations and enhancements.    To enable this we share our development history here.
Terminology
Throughout this manual, the names of menu sequences, drives, directories, files and executable command line sequences are italicised. This convention avoids having to place quotation marks around items within a sentence.    This not only eliminates some visual clutter, but also avoids confusion where command sequences include quotation marks (e.g., Linux string specifications).

The following are various terms and abbeviations used througout this Development Manual.

  • JTAG Loader -- a f300 Target Board programmed with JTAG loader code
  • GUI -- amrForth Graphical User Interface window
  • Host -- Your workstation, the host for V6 which commuicates to the embedded system connected via a serial port
  • Linux/BSD -- So far we've tested V6 on Redhat, Debian, Suse, Yellow Dog linux and OpenBSD. Please share your experiences.
  • Mode -- The GUI command line interpreter has several modes. Each mode has its own set of commands which can be used by typing "words ". Interactive testing on the Gadget happens in either "forth" or "basic" mode only.
  • Target -- The embedded controller running V6 attached to the end of a serial .
  • Windows -- The worlds largest virus.
Application Notes
  • AN001   Driving a LCD while inputting pushbuttons
  • AN002   An Accurate timebase
  • AN003   Oversampling an A/D to increase resolution by 1 to 6 bits
  • AN004   Using amrFORTH/BASIC
  • AN005   Converting a serial bit stream to Morse Code
01NOV03
 AMR Home LinuxLogo
Valid HTML 4.01!