ROM PowerForth utilities

Introduction

Supplied as source in the ROMFORTH directory are utilities to:

  • compile source code on your target board from the cross-compiler IDE
  • upload a binary image from your target to your PC
  • download a binary image to your target from your PC.
  • 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.

    Compiling text files

    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.

    The required files

    To compile text files from your target board, cross-compile the files IODEF.FTH and TEXTFILE.FTH.

    Compiling a specified text file

    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.

    Downloading a binary image

    A binary image can be downloaded from the target to your host PC. Two utilities are provided:

  • Intel hex download
  • XMODEM download
  • For both utilities the cross-compiler IDE or a suitable communications package will be required.

    XMODEM binary image download

    Binary images can be downloaded to your PC using the XMODEM protocol.

    Required files

    To use this utility you must cross-compile the file COMMON\XMODEMTXRX.FTH.

    Using the XMODEM binary download utility

    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.

    Intel hex download

    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.

    Required files

    To use this utility you must cross-compile the file INTELHEX.FTH.

    Using the Hex download utility

    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

    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.

    Hardware requirements

    To develop an application using ROM PowerForth, your board requires an area which:

  • is always Flash
  • is always RAM
  • is RAM for development and Flash for application
  • Flash area

    The area that is always Flash contains the development kernel.

    RAM area

    The area that is always RAM is used for variables and all changeable data.

    RAM/Flash area

    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.

    Types of board

    The type of board that can be used to develop using ROM PowerForth is restricted to:

  • three site boards
  • two site boards with battery backed RAM
  • two site boards with socket converter.
  • Three site boards

    The three areas are provided by three memory sockets:

  • Flash holding development kernel
  • RAM which holds the variables and changeable data
  • Flash or RAM which is selectable by a link on the board
  • Two site boards with battery backed RAM

    The three areas are provided by two sockets:

  • Flash holding the development kernel
  • battery-backed RAM which is split into two areas.
  • Two site boards with socket converter

    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.

    Making your application turnkey

    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.

    Configuring a turnkey application

    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

    Discarding the application RAM area

    The application can be discarded by typing:

      0 ROM !

    Changing the application RAM start address

    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 file server protocols

    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.

    IODEF.FTH

    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.

    AIDE support

    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.

    Miscellaneous

    : cls           \ --
    Clear PowerTerm screen

    Application Extensions

    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.

    INCLUDE source code from AIDE

    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.

    INCLUDE and friends

    : 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 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.

    Making life easier

    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.

    Simple source file loader

    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.

    Intel Hex transfers

    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.

    Block support

    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.

    Primitives

    : BLK-READ      \ addr blk# --
    Reads one block from host to addr.

    : BLK-WRITE     \ addr blk# --
    Sends given block number to host.

    Application words

    $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.

    Block file management

    : -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.

    Target BUFFER: and VARIABLE

    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>

    Some simple tools

    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.