Supplied as source in the ROMFORTH directory are utilities to:
Note that the target source code supplied with cross compiler versions 6.02 onwards is incompatible with code supplied for previous versions of the cross compiler.
These utilities can be used to generate an image that has all the tools required to develop an application, or can be used during development to transfer modules to and from your PC. All the code is designed to be used with the MPE development environment, AIDE. The code will also work with other compatible terminal emulators.
Users who wish to distribute images containing the ROM PowerForth utilities should contact MPE for details of the OEM licence, which includes documentation on disc of the Forth kernel and the ROM PowerForth utilities.
Source text files can be compiled from the host PC onto the target system. This saves time in not having to cross-compile the entire source if a small modification is made. The utilities permit text file to be split into pages for better layout when printed. An ASCII Form Feed character (decimal 12) separates one page from another.
To compile text files from your target board, cross-compile the files IODEF.FTH and TEXTFILE.FTH.
To compile all or part of a specified text file onto your target,
use INCLUDE
in the form:
INCLUDE <filename>
This compiles the file <filename> into the target's dictionary. AIDE's internal file server must be enabled (in the console window configuration), and will be triggered automatically.
A binary image can be downloaded from the target to your host PC. Two utilities are provided:
For both utilities the cross-compiler IDE or a suitable communications package will be required.
Binary images can be downloaded to your PC using the XMODEM protocol.
To use this utility you must cross-compile the file COMMON\XMODEMTXRX.FTH.
To download a binary image from the target system to your PC,
use BIN-DOWN
in the form:
addr #bytes BIN-DOWN
where addr] is the start address and *\i{#bytes is the number of bytes to down-load starting from addr. For example,
1200 400 BIN-DOWN
sends the area of memory from 1200 to 1599 to your host PC. AIDE's internal file server must be enabled (in the console window configuration), and will be triggered.
Binary images can be downloaded to your PC using the Intel hex format. Because this format only uses the standard printable character and CR/LF, the data can be captured by very simple tools.
To use this utility you must cross-compile the file INTELHEX.FTH.
To download a binary image from the target system to your PC,
use HEX-DOWN
in the form:
addr #bytes HEX-DOWN
where addr is the start address and #bytes is the number of bytes to down-load starting from addr. For example,
1200 400 HEX-DOWN
sends the area of memory from 1200 to 1599 to your host PC. In AIDE, turn on console logging to receive the file. In other packages this may be referred to as file capture.
ROM PowerForth can be used to generate a stand-alone Forth system. With these utilities, you can generate an image that contains an interactive Forth with the ability to develop an application. Note: A licence is required to distribute open Forth systems. Contact MPE for more details.
To develop an application using ROM PowerForth, your board requires an area which:
The area that is always Flash contains the development kernel.
The area that is always RAM is used for variables and all changeable data.
This area is used to develop your application. Therefore, it must be RAM while developing. Once your application is developed, the application's image must be saved into battery-backed RAM or Flash. Therefore, this area must have the ability to be alterable but also be non-volatile.
The type of board that can be used to develop using ROM PowerForth is restricted to:
The three areas are provided by three memory sockets:
The three areas are provided by two sockets:
On many boards, there is unused space in the Flash as ROM PowerForth occupies less than 32k bytes of memory. A RAM image can be saved to Flash or external serial EEPROM and then restored at power up. Such code is device-specific and is not part of the generic ROM PowerForth.
Once your application has been developed, it needs to be made turnkey so that it is always available. The application can be made semi-permanent by compiling into battery-backed RAM in the RAM/Flash area. Alternatively, it can be copied into Flash if the board allows.
The word SETUP
takes the address of the word passed to it
and marks this in the RAM/Flash header as the address of
the word to be run at power-up. If a value of zero is passed
to SETUP, the interactive Forth kernel will be run at power up.
For example, the word JOB
is to be run at power-up. Therefore
you type,
' JOB SETUP
The application can be discarded by typing:
0 ROM !
The constant ROM returns the start address of the application RAM area. If the address of this area is to be changed, the Flash must be modified. To do this, the cell value in ROM must be changed.
AIDE's file server must be enabled for automatic file handling. Details of the protocols used should be obtained from this manual and the source code in the COMMON\ROMFORTH directory.
The file Common/ROMFORTH/IODEF.FTH provides equates and protocol primitives for AIDE.
Before compiling this file, synonyms may need to be defined
for SER-EMIT
, SER-KEY?
and SER-KEY
. Add
these in the control file before compiling IODEF.FTH.
variable disk-error \ -- addr ; set non-zero on error
This variable is set true when a transfer error occurs.
: wait-ack \ -- ; wait for ACK character
This word waits for the host to send an ACK at the end of
part of a transfer.
INTERNAL.
: wait-ack/nack \ -- t/f ; true for NACK
This waits for either a NACK or an ACK from the host
and leaves true or false on stack.
INTERNAL.
: send-block# \ n -- ; send block number to server
Sends a single length number as two bytes 00-FF,
low byte first.
INTERNAL.
: synch-to-host \ -- ; sync host to us
Waits for a START (0x01) character, flushes the input,
and sends an ACK.
INTERNAL.
INTERNAL.
: cls \ --
Clear PowerTerm screen
ROM PowerForth can be used to generate a stand-alone Forth system. With these utilities, you can generate an EPROM that contains an interactive Forth with the ability to develop an application. Note: A licence is required to distribute open Forth systems. Contact MPE for more details.
The code in COMMON\ROMFORTH\LINK.FTH provides the facilities to link the extension area into the ROM PowerForth kernel.
appl-rom equ ROM \ start of ROM/RAM area
Define the address of a Flash/RAM area in which applications
are to be developed. This area is RAM during development.
When development is complete, the word SETUP
is executed
to initialise the memory area.
The compiled image is then downloaded to the PC using the
tools in the ROMFORTH directory. The image is then programmed
into Flash, which can then replace the RAM.
If the word RELINK
is added to COLD
, the application Flash
will be automatically linked in when the target powers up.
variable rp EM rp ! \ top of RAM area
If your processor has separate CODE and DATA address spaces,
it has a HARVARD architecture. This word is only
compiled for Harvard targets such as 8051s.
The working RAM area has the interactive RAM dictionary at
the bottom and the application buffer space at the top.
Define the initial value of RP to be the highest available
free location in the RAM area. Application variable and
buffer space will then be allocated downwards from this
address. When creating an application to be ROMmed,
download the code for BUFFER
and the redefined VARIABLE
first of all.
: setup \ xt|0 -- ; sets up for ROM generation
Use XT as the xt of the word to be run when the extension
is found.
: use-setup-data \ --
Apply the data in the setup area.
: link-rom \ --
Link in the application ROM area.
: link-ram \ -- ; link in application RAM area
Link in the application RAM area.
: link-nv-ram \ -- ; link in for NV-RAMs
Link in the application NV-RAM area.
: relink \ -- ; re-link application if there
Link in the application ROM/RAM/NV-RAM area.
The file COMMON\ROMFORTH\TEXTFILE.FTH provides support for compiling a source file from the AIDE server. It also provides some additional words to enhance compatibility between cross-compiled and directly compiled code.
: end-load \ -- ; switch back to keyboard input
This word is automatically performed at the end of a download
to tidy up the comms.
: file-error \ n --
Handle an error when a file is being INCLUDE
d.
: $include \ $addr -- ; compile host file, counted string
Given a counted string for a file name, compile a file across
the serial line from the AIDE file server. Use in the form:
c" <filename>" $include
The filename extension must be supplied. The file name may include spaces.
: include \ "<filename>" -- ; load file from host
Compile a file across the serial line from the AIDE file server.
Use in the form:
include <filename>
The filename extension must be supplied. The file name must not include spaces.
This section provides words that make your life easier when including files during development that will be cross compiled for production. You can always ask us to add some more if you really need them; otherwise you can add them yourself.
: (( \ -- ; (( ... ))
Block comment operator. Any source following this is ignored
upto and including the terminator, '))', which must be white
space separated.
: const \ x -- ; -- x
A synonym for CONSTANT
.
: equ \ x -- ; -- x
A synonym for CONSTANT
.
: buffer: \ len "name" -- ; -- addr
Reserve len bytes of space to form a named buffer.
Only for targets compiling to RAM.
len buffer: name
: wvariable \ -- ; -- addr
A variable holding two bytes. Only in 32 bit targets.
Only for targets compiling to RAM.
: cvariable \ -- ; -- addr
A variable holding one byte.
Only for targets compiling to RAM.
: compiler ; immediate
A cross-compiler directive treated as a NOOP
. It may
lead to redefinitions.
: interpreter ; immediate
A cross-compiler directive treated as a NOOP
. It may
lead to redefinitions.
: target ; immediate
A cross-compiler directive treated as a NOOP
.
The code in COMMON\ROMFORTH\FILETRAN.FTH provides a simple
source file loader which can be used with most terminal
emulators. The download is controlled by XON/XOFF flow
control. When using the PowerTerm terminal emulator in AIDE,
use the INCLUDE <filename>
system which supports nested
files and needs no special termination.
Each file compiled must include a single line
END-UP-LOAD
at the end to reset the interpreter.
For slow 8 bit CPUs without queued serial input, the terminal server may need to include pacing delays after each character and an additional after CR/LF pairs.
: Up-Load \ -- ; Load ASCII text
Compile a file delivered by the terminal emulator.
This word is intolerant of compilation errors.
: End-Up-Load \ -- ; Finish Up-Loading
Used on the target to restore the Forth interpreter after a
file has been compiled.
The code in COMMON\ROMFORTH\INTELHEX.FTH provides a simple way to transfer binary images from ROM PowerForth to a host. The Intel Hex format is printable and can be captured (logged) by most terminal emulators including AIDE.
: HEX-DOWN \ addr #bytes --
Send #bytes at addr from ROM PowerForth to the host
in Intel Hex format.
BLOCKS.FTH provides support for the transfer of 1k blocks between a host PC and the embedded target. Although the use of blocks as source screens is now obsolete, blocks are still useful for the transfer of binary data, especially for data loggers which use paged RAM or Flash for data storage. AIDE version 3 or above is required.
Despite the comment about the obsolescence of screens, the code in BLOCKS.FTH provides screen file support for legacy systems.
: BLK-READ \ addr blk# --
Reads one block from host to addr.
: BLK-WRITE \ addr blk# --
Sends given block number to host.
$400 equ /block \ -- size ; size of a block
The size of a block.
/first buffer: FIRST \ -- addr ; first element is block no.
The data buffer. The first cell contains the block number and is
followed by /BLOCK
data bytes.
: SAVE-BUFFERS \ --
Save the data buffer if it has been modified.
: EMPTY-BUFFERS \ --
Mark the data buffer as empty.
: UPDATE \ --
Mark the data buffer as modified.
: FLUSH \ --
Force a changed buffer to be uploaded to the host.
: BLOCK \ u -- addr
Addr is the address of the first character of the block buffer
assigned to mass-storage block u. An ambiguous condition exists
if u is not an available block number. If block u is already in
a block buffer, a-addr is the address of that block buffer. If
block u is not already in memory and there is an unassigned
block buffer, transfer block u from mass storage to an unassigned
block buffer. Addr is the address of that block buffer. If
block u is not already in memory and there are no unassigned
block buffers, unassign a block buffer. If the block in that
buffer has been UPDATEd, transfer the block to mass storage
and transfer block u from mass storage into that buffer. Addr
is the address of that block buffer. At the conclusion of the
operation, the block buffer pointed to by addr is the current
block buffer and is assigned to u.
: -trailing \ addr len -- addr len' ; strip trailing spaces
This word strips the trailing spaces from a string. It is most useful when
displaying lines from a screen to strip the trailing spaces from the
64 byte fixed length lines.
: .LINE \ line# blk# --
Display line# from blk#.
: ?LOADING \ --
THROW #-501 if input from console.
: LIST \ blk# -- ; display screen given
Display screen blk# as 16 lines of 64 characters.
: L \ --
LIST the current screen in SCR.
: N \ --
LIST the Next screen.
: P \ --
LIST the Previous screen.
: Index \ n1 n2 --
Display the top lines in the (inclusive) range of screens.
: Qx \ --
INDEX all available screens.
: LOAD \ blk# -- ; compile given screen
Save the current input-source specification. Store u in BLK
(thus making block u the input source and setting the input
buffer to encompass its contents), set >IN to zero, and interpret.
When the parse area is exhausted, restore the prior input
source specification. Other stack effects are due to the words LOADed.
: THRU \ first last --
LOAD screens from first to last in that order.
: --> \ --
LOAD the next screen.
: $using \ $addr --
Select the file specified by the counted string at $addr as
the current block/screen file.
: using \ "<file>" --
Use in the form "USING <filename>" to select the current
block/screen file. The AIDE file server is required.
AIDE takes care of creating non-existent files.
The definitions below reorganise the use of RAM for ROM PowerForth applications which are themselves to be put in Flash.
The variable RP points to the top of available RAM, and is
decremented by the amount of RAM required. The word
BUFFER:
allocates memory from this space, returning its
base (low) address. Words such as VARIABLE
can then be
defined in terms of BUFFER:
.
: Buffer: \ n -- ; -- addr
Return the address of an n byte buffer. Use in the form:
<size> BUFFER: <name>
: variable \ -- ; -- addr ; replacement
Create a new variable. Use in the form:
VARIABLE <name>
The file COMMON\ROMFORTH\TOOLS.FTH provides some simple application tools.
The words (#IN)
and #IN
are provided to collect
numbers from the keyboard in decimal. (#IN)
is useful
because it returns the number of digits converted so that 0
digits indicates that the user just pressed <Enter>, rather
than entering a valid number of value 0.
: (#in) \ -- n #chars
Read a decimal number from the keyboard returning the number
and the number of digits converted.
: #in \ -- n
Collect a decimal number from the keyboard.