This is an overview of the files comprising Riscy Pygness
(Pygmy Forth for the ARM).

riscypygness.txt
  Description and general information.

FILES
  This file, an overview of the files comprising Riscy Pygness.

COPYING
  Copyright information (basically an MIT/BSD-style license allowing
  anyone to use the code for any purpose).

LICENSE.txt
  Full text of the license.

makefile
  Edit this file to suit your environment (be sure the action lines
  begin with a literal tab rather than space(s)).  Note that the
  Gnu toolchain executables begin with arm-elf- (e.g. arm-elf-as)
  on my system.  You may need to adjust these names to match your
  system if they are named differently or if they are not on your
  PATH.

     make     (with no target)
        this will run the assembler and linker if riscy.asm has
        changed, going all the way to produce a combo.bin file
        that can be burned into the target's flash.

     make combo.dls
     make combo.dl
     make combo.jtag

        Use one of the above 3 lines to run one of the 3 flash utilities
        supported by the makefile to burn combo.bin into the target's flash.
        You might want to customize this to use your own downloader or
        to use a different baud rate, etc.

     make <anything>.hex
        e.g.  make combo.hex
        this will the objcopy program to produce an Intex Hex file
        from a binary file (some downloader may want an Intex Hex
        file rather than a binary file).

arm.lisp
  This is the main file.  It loads the other files.

mem.lisp
  Provides the memory image that represents the target processor's 
  memory plus utility functions to access and modify that memory
  image.

parse.lisp
  Provides the functions to parse Forth code in order to collect
  the Forth words to be interpreted.

prim.lisp 
  This makes the connection between the assembly language
  primitives assembled by the arm-elf-as GNU assembler and the rest of
  the Forth system.  The source code for the primitives is in the file
  riscy.asm.  prim.lisp reads a linker output file in order to build a
  table of Forth word names and their addresses, and imports the
  primitives into the target image.

riscy.asm This is the source code file for the Forth primitives.  This
  indicates that it is an assembly language file that will be
  preprocessed.  Note that any combinations of characters (usually
  omitting non-printing characters and the space) form a suitable
  Forth word name, but the benighted assemblers have more restrictions
  on their labels.  For example, the Forth word "DUP" is a valid
  assembler label but the Forth word "@" is not.  So, when defining
  "@" in riscy.asm we give it the label "fetch".  One of the purposes
  of prim.lisp to associate the real Forth word name with the altered
  assembler name.

riscy.lnkt riscy.bin riscy.lst
  These files are produced by the GNU ARM toolchain but they are not
  included in the distribution.

  The file prim.lisp will use those files to put the primitives into
  the target memory image and into the table of addresses.

  riscy.lst is the assembler output listing from assembling riscy.asm

forth.lisp This file defines the functions for compiling high-level
  Forth into the *target-memory* array on the host.  This image
  eventually must be downloaded into the target CPU for the Forth
  words to be executed.  The assembler generates the primitives.  Then
  the forth.lisp compiler, particularly the function
  FORTH-COMPILE-FILE, finishes the work of generating the full Forth,
  producing a binary image to be downloaded into the target's flash
  memory, typically named combo.bin.

term.lisp 

  This file provides the "smart terminal" interactive interface to the
  target computer.  The Forth should already have been downloaded into
  the target's flash.

  It is loaded automatically when you load arm.lisp and invoked by

      (interp)

  The to get out of it, enter a tilde ("~") by itself at the start of
  a line and press Enter.

  (You don't particularly need to know any of the following.)

  It uses mem.lisp and parse.lisp.  It also includes basic serial port
  functions (which perhaps should be broken out into a separate file).
  INTERPRET-WORD is the main work-horse function, although INTERP is
  the main function to use.  INTERP starts an interactive connection
  to the target and lets you type Forth words for the attached target
  CPU to execute.

  The normal operation when interpreting is to look up the string
  that represents a Forth word to get its address and send that to
  the target over the serial line so it will be executed.  Certain
  Forth words are "special" and cannot merely be executed on the
  target.  The *special-functions* assoc list associates the string 
  names of these (such as "RELOAD") with the Lisp function that should 
  be executed on their behalf.  This *special-functions* table 
  is analogous to the *macros* table used when compiling the 
  high-level Forth (see the file forth.lisp).

  interp-word FORTH-WORD   
     Given a FORTH-WORD string, handle it appropriately.  There are
     four possibilities.  They are checked in the following order.

       1. If it is a "special" word, execute the associated Lisp
          function.  As an example, the word .S, which prints the top
          3 items on the data stack could be done entirely by the
          target or mostly by the host.  If it were done on the host,
          it would be "special" because the interaction with the
          target is more complicated than merely asking the target to
          execute a word.  As part of the Lisp function .S, the target
          is asked to execute several Forth words and values are
          received by Lisp over the serial port and displayed.
          (Actually, at the moment (July, 2007), the target, not the
          host, executes .S.  But, to save space on the target, .S and
          other words such as DUMP, DU, and ? might be move to the
          host, at which time they too would be "special".
        
       2. Otherwise, if it is a target Forth word, look up its address
          in the target's memory and send a request over the serial
          port to ask the target to execute it.

       3. Otherwise, see if the word can be interpreted as a number
          (e.g. "123", "$FF32", "'A", but not "123B" or "'ABC" or
          "&PINSEL0" etc.).  If so, send the number to the target and
          ask it to push the number to its data stack.
 
       4. Otherwise, print a message indicating the word is unknown.

  interpret-string STRING
     Convert STRING to the *forth-input* stream then call 
     interp-word on each of the words in the stream.  Abandon
     the rest of the stream upon reaching an unknown word.

  interp
     Repeatedly collect a line of text from the user and pass the
     string to interpret-string.  To exit, enter a line with just
     a tilde on it (e.g. "~").

riscy.forth 
     This is the main file for high-level Forth.  This, loaded on top
     of the primitives, provides an image that is approximately
     equivalent to the "kernel" of the 16-bit DOS version of Pygmy.

mmc.forth
block.forth
fat16.forth
  Code for reading and writing to an MMC or SD flash disk.  Note, 
  mmc.forth is setup to use the SPI interface and to work with the
  specific pin connections shown at http://pygmy.utoh.org/riscy/mmc.

  For the lpc2378, which has a built-in MMC/SD interface, different
  code will be used.
         
.gdbinit
  This is a sample version of the GNU debugger init file for use
  with gdb.  It is setup to work with openOCD and a JTAG cable to
  let you single step, etc., through the primitives.  See the comments
  in the file for an example of the command line to use when starting
  gdb.

lpc2378_wig.cfg
  A configuration file for openOCD for use with a parallel port JTAG
  cable (a "wiggler"-style JTAG) to program the flash or to work with
  gdb for single stepping, etc.  This works with the lpc2378 but 
  probably works with other lpc2xxx family members with perhaps minor 
  changes.

burn.sh
  A Q&D script used by the makefile (or that can be run stand-alone)
  to burn combo.bin into the lpc2378's flash using the JTAG cable and
  openOCD.  This often fails and sometimes needs to be run several
  times to get a successful programming of the flash.  In spite of
  these problems, it is so convenient that I usually use it rather 
  than alternatives.

combo.bin
  Binary version of the combined assembly language 
  primitives plus the high-level Forth from riscy.forth and
  interp.forth.  It is created by loading arm.lisp, it is not included
  in the distribution.

  combo.bin, the base image burned into flash, contains at least the 
  primitives defined in riscy.asm and the high-level forth words 
  defined in forth.lisp.  These are "combined" into the file combo.bin
  by running (loading) arm.lisp.  combo.bin is then burned into the
  target ARM chip's flash.  Note that arm.lisp can load additional
  high-level forth code into combo.bin.  See arm.lisp and look at the
  lines such as  (forth-compile-file "riscy.forth").



  
