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 EPROM 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 ROMs 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 GET or 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 #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 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.
To develop an application using ROM PowerForth, your board requires an area which:
The area that is always EPROM 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 EPROM or Flash. Therefore, this area must have the ability to be alterable but also 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 EPROM as ROM PowerForth occupies less than 32k bytes of memory. Therefore, a header board can be made which converts one socket into two. For example, if the socket normally takes a 27512 EPROM, a board can be made which has a 32k EPROM with the ROM PowerForth development kernel and 32k bytes of RAM. To access the RAM, the write line is attached to a suitable point on the main board with a fly lead. After the application has been developed, the two images are combined back into a single EPROM.
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/EPROM area. Alternatively, it can be copied into an EPROM if the board allows.
The word SETUP takes the address of the word passed to it and marks this in the RAM/EPROM 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 EPROM 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.
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.
IODEF.FTH provides equates and protocol primitives for AIDE.
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 ROM/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 EPROM, which can then replace the RAM.
If the word RELINK is added to COLD, the application EPROM
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. The code has been updated for AIDE version 2.500 onwards.
: 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 INCLUDEd.
: $include \ $addr -- ; compile host file, counted string
Given a counted string representing a file name, compile
the file from AIDE.
: 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 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 or EPROM.
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\TEXTFILE.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.