If anything here doesn't make sense or if you have additional questions, please email about it: frank@pygmy.utoh.org
Here are questions that have been asked or might be asked.
The Riscy Pygness system involves software on the host and on the target:
The image can be thought of as having 3 pieces
The assembler and compiler let you generate new Forth images for the target's flash and the compiler lets you extend the target's Forth dictionary by defining new words interactively into RAM.
The smart terminal provides the communication link over a serial port through which you interact with the target, exercising words in the target's dictionary and/or defining new words.
No, but you must install at least binutils for the assembler and related utility programs.
You do not need to install GCC. Earlier versions (generations 1 and 2) of Riscy Pygness did need GCC for the assembler preprocessor. That is no longer the case with generation 3.
Yes. The smart terminal that runs on the host is written in Common Lisp and you need a Common Lisp to run it. This same program also does the high-level compiling of the Forth image and also the interactive (incremental) compiling of additions to the Forth dictionary. So, to do anything at all, you need to have a Common Lisp installed, preferably CLISP. It is very easy to install. It is available (typically as a binary package) for every Linux distribution, the xBSD versions of Unix, and probably all other versions of Unix, Microsoft Windows and the Mac.
As you work interactively, new words that you define are stored in
RAM. If you reset your target board or power it off, the
definitions vanish from the target's RAM but are still in the
smart terminal's image of the target's RAM, where typing RELOAD
will restore them to the target's RAM.
As you finish testing parts of your application, from time to time you will want to generate a new Forth image for the flash memory that will contain your new/tested words.
Yes! When you are in the interpreter and type a colon at the beginning of a line, the interpreter knows to compile that line (thus updating the target image on the host) and then to send that target image extension to the target for it to program into its RAM. Also, you can compile a region (some text that you have highlighted) in your editor on the host (if you are running Emacs) and have that region compiled and sent to the target with an Emacs keystroke.
I have hopes of updating this sample session to illustrate this at Sample Session 1, but at the moment, it applies to an earlier version.
No, for now the code runs strictly out of Flash and RAM. There are alternatives to consider, but that is the way it is at the moment. Keep in mind that subwords take only 2 bytes each within a high-level definition and that tail calls are optimized by eliminating the 'exit' and changing the previous subword from a call to a jump (when it is possible to do so), resulting in a further saving of space. Since the onboard flash on an lpc2106 allows over 100 KBytes of code, you can fit a lot of Forth into that flash.
The original plan for Riscy Pygness is to have several threading models to take advantage of various speed/space tradeoffs, and we certainly could make a version that would allow loading of code on the fly into RAM. However, I am so happy with the current threading system that I think we will stick with it.
Feel free to edit riscy.asm and set up interrupt handlers, etc. I don't expect any problems at all. I, myself, expect to set up an interrupt handler for serial input. Note the caution about programming flash regarding interrupts. I do not plan to write any of the interrupt handlers as high-level words. Write them in assembler in riscy.asm — quick in and out to fetch a byte and stuff it into a queue, or whatever — then let the normal high-level application deal with the data at its leisure.
First, study the manual for the LPC2124 to see how closely the configuration addresses (for timers, I/O ports, interrupts, etc.) match those of the LPC210x chips, etc. As long as the symbols do not conflict, just extend equates-lpc2xxx.asm to include any new symbols needed. Then create a new files named something like custom-lpc2124.asm and olimex-lpc2124-equates.asm for the CPU or board-specific information such as what pin is connected to the LED. Start by copying one of the other custom-*.asm files. The idea is to localize chip-specific items in these files that riscy.asm includes.
The main source code files would by riscy.asm (for primitives) and riscy.forth (for the basic high-level Forth code). CPU-specific items go in a CPU-specific assembly file (see custom-lpc2106.asm, custom-lpc23xx.asm, etc.). Here are the items that come to mind (but let's extend them as we run across others):
*equate-files* then comment out
"olimex-lpc2106-equates.asm" and uncomment
"olimex-lpc2378-equates.asm"..equ lpc2106, 1" line and uncomment the
".equ lpc23xx, 1" line. (Then, take a quick look at the .ifdef
statements just before the label COLD: to see how this will
affect things.)Look for the section "Use this section for lpc2378" and uncomment its variables (i.e. CPU and CCLK).
*.cfg file.Probably any Common Lisp will work, with perhaps minor adjustments.
CLISP is perfect. It is what I am using on Linux.
First, the primitives must be produced (you might be able to use the pre-compiled files in the tgz download file if your hardware is sufficiently similar to mine) by running 'make' to assemble and link riscy.asm into riscy.bin (the binary image of the primitives) and riscy.lnkt (the symbol table output from linker that Lisp will parse to find out the addresses of the primitives).
Then, load the file arm.lisp. The command to do this is in a comment near the top of the file arm.lisp. This loads the other Lisp files that are needed and loads the primitives into the target image and then compiles the Forth high-level source code (files such as lpc.forth, riscy.forth, mmc.forth), and finally writes the target image to the file combo.bin. The file arm.lisp is short, so don't hesitate to look at it and change it. You will see where it loads the Forth files, so you can add other Forth files, etc.
Finally, from a shell prompt, download combo.bin to the target using whatever bootloader facility you have available.
Then, to talk to the target, start up the interpreter by executing (INTERP) in Lisp. (Again, this command is shown in comments near the top of the file arm.lisp.)
These steps are illustrated in Sample Session 1 (but they are not fully applicable, yet, to the current version). Also, see Generating a Target Image.
Usually I use the burn.sh script but it does not always work. Another option is to do it "manually" by starting openOCD at a shell prompt with something like
openocd -f lpc2378_wig.cfg
then at another shell prompt, set up a telnet connection to openOCD and type the commands to halt the target, erase the flash, program the flash, and resume execution, e.g.
telnet localhost 4444
> halt
> flash erase 0 0 2
> flash write 0 combo.bin 0
> resume 0
I am happy to receive bug reports and comments and suggestions. I would like to retain artistic control, so the system stays beautiful (to my eyes). If you contribute, please license it BSD/MIT-style, or better yet, assign the copyright to me. I want the core to be free and useable by everyone for any purpose, but without any restrictions on how applications built on top of it must be licensed. That is, you are not required to publish etc. your extensions or applications just because you use Riscy Pygness
Generally, I will be happy to link to related work or extensions even if I don't incorporate them directly into Riscy Pygness.
Additional documentation, experience, recommendations are always welcome.
Specifically, what needs to be done? See the To Do List.
Type "~" (i.e. a tilde) at the beginning of a line and press return.
Type Ctrl-C (perhaps several times).
I type
:Q
followed by
(interp)
to get back in.