<texit info>
author=Bernd Paysan
title=Gforth EC R8C
</texit>

====== R8C-Forth ======

In der Dezember-Ausgabe der [[http://www.elektor.de|Elektor]] wurde ein [[http://eu.renesas.com/|Renesas]]-[[http://eu.renesas.com/fmwk.jsp?cnt=r8ctiny_series_landing.jsp&fp=/products/mpumcu/m16c_family/r8c_tiny_series/|R8C]]-[[http://www.elektor.de/Default.aspx?tabid=109|Board]] von [[http://www.glyn.de|Glyn]] verteilt. Die Software von Glyn beinhaltet einen C-Compiler, aber interessanter ist es natürlich, ein Forth auf der CPU laufen zu lassen.

Hier auf der Seite wird kurz beschrieben, wie das Gforth-ec in den R8C kommt und benutzt werden kann. 

Wer sich mit Unix etwas auskennt, wird sich leicht zurecht finden. Wer so rein gar nichts mit Unix zu tun hatte in seinem Leben, wird aber auch nicht im Stich gelassen. Denn es gibt auch noch die Schritt für Schritt bebilderten Anleitungen um mit Gforth erste Versuche auf dem R8C machen zu können - [[projects:r8c:r8c_forth_manual_de|für Windows XP]] - [[projects:r8c:fuer_linux|für Linux]] - (und leider bisher nur ein [[für Apple Mac OSX]]). 

===== Aufgabenverteilung =====

  * Heinz Schnitter schreibt den Assembler <latex>\checkmark</latex>
  * [[http://bernd-paysan.de|Bernd Paysan]] passt Gforth-EC an den R8C an <latex>\checkmark</latex>

===== Status 09jul2006 =====

Das System ist fertig.

{{  projects:r8c:r8c.jpg}}

  * Das Forth sagt OK über die UART, kann LEDs und LCD ansteuern, legt selbstdefinierte Programme per Default im (sehr knappen) RAM ab. Umschalten zwischen RAM und ROM mit den Wörtern ''ram'' und ''rom'' ;-).
  * Das Daten-Flash kann mit ''flashc!'' und ''flash!'' programmiert werden.
  * Gforth ist so anpasst, dass Code Flash-gerecht abgelegt wird (also jedes Bit genau einmal gelöscht wird). Immediate- und Compile-only-Bit sind also zunächst gesetzt (bedeutet natürlich "nicht immediate" und "nicht compile-only"), und werden bei Bedarf gelöscht. Ebenso ist '':dovar'' an einer Adresse, die das Ändern auf andere Doer (mit ''DOES>'') ermöglicht (''$C0FE'').
  * Gforth EC R8C erlaubt das Anlegen von bis zu 4k Forth-Programmen im Datenflash. Ein ''savesystem'' speichert eine Kopie des RAMs in dieses Flash; damit sind auch Turnkey-Applikationen möglich. Das Datenflash kann öfter neu programmiert werden als das Programmflash, damit ist auch mehr Platz für Experimente. Ein ''empty'' löscht das gespeicherte System wieder.
  * Der Assembler ist jetzt wirklich komplett.
  * Der Rest des im ROM zur Verfügung stehenden Platzes ist mit benutzerfreundlichen Fehlermeldungen gefüllt
  * Es gibt ein Terminal-Programm, das auch das Nachladen von Dateien über ein einfaches Handshake erlaubt (Xon/Xoff scheitert am Polling-Intervall des USB-Controllers, krude Abhilfe: 250ms Newline-Delay)
  * Eine Adaption von ''tt.fs'' passt in die 4K ROM.
  * Millisekunden werden über Timer C realisiert.
  * Nested ''include'' ist möglich (neu).
  * Alle bisher bekannten Bugs sind behoben.

===== Download von gforth =====

Die **aktuelle** Entwicklerversion von [[http://bernd-paysan.de/gforth.html|Gforth]] kann über [[http://www.complang.tuwien.ac.at/forth/gforth/cvs-public/|pserver-CVS geladen]] werden. Mit älteren Versionen des Gforth kann manches der weiter unten aufgeführten Beispiele nicht ausgeführt werden, so war früher z.B. noch kein Gforth--Terminal für den r8c dabei. Wer die [[http://www.complang.tuwien.ac.at/forth/gforth/Docs-html|Doku von Gforth]] nicht auf der [[http://bernd-paysan.de/gforth.html|Gforth-Seite]] suchen will, findet sie [[http://www.complang.tuwien.ac.at/forth/gforth/Docs-html|hier]]. Da Gforth--EC nur ein Subset der Wörter im normalen Gforth hat, hilft ein ''WORDS'', um alle im R8C verfügbaren Wörter aufzulisten.

Für Windows-Nutzer, die keine Lust haben, Cygwin zu installieren, gibt's einen [[http://bernd-paysan.de/gforth-0.6.2-20060709.exe|Snapshot]] in Form einer ''setup.exe'' der aktuellen Entwicklerversion. 

===== Download von gforth-ec =====

Das [[http://bernd-paysan.de/gforth-r8c.mot|Gforth-R8C]] selbst ist als S-Record-Datei abgelegt und wird in dieser Form in das Flash-Memory des R8C geladen.  Im Prinzip geht das mit dem FDT, wir verwenden aber Thomas Fischls [[http://www.fischl.de/thomas/elektronik/r8c/r8c_flasher.html|m16c-flash]] unter Linux.
===== Installation und Handhabung des gforth =====

Installiert man zunächst [[http://www.cygwin.com|Cygwin]] und dann Gforth aus den Sourcen, sollte man vor dem ''./configure && make'' noch die [[http://loreley.ath.cx/cygwin/cygwin-1.5/libffi-cygwin-standalone/libffi-2.00-beta-1.tar.bz2|libffi]] installieren.

Installiert man obige ''setup.exe'', werden alle benötigten Libraries mitinstalliert. 

**Hinweis:** ''setup.exe'' installiert in Windows-XP eine Gruppe von Programmen. Dies sind: Bash, Gforth, Gforth Manual, Gforth Manual (PDF) und noch einige. Gehe zu dieser Programmgruppe und starte die ''Bash'' (Start --> Alle Programme --> Gforth --> Bash) ''Bash'' ist eine Shell (die "Bourne Again SHell"). Diese meldet sich im Bash-Fenster nun als ''sh:-3.00$'' oder ähnlich. Auf dieser Komandozeile werden alle Anweisungen, die nun folgen, eingegeben.

Alle folgenden Anweisungen gehen also von einer frisch geöffneten Shell aus (für Cygwin-Nutzer: Im Gforth-Verzeichnis). Innerhalb der ''shell'' muss tatsächlich ''/'' benutzt werden (der //slash// und nicht wie in Windows sonst üblich ''\'' der //backslash//) -- also zeichengenau so abtippen wie es hier im Folgenden nun geschrieben steht. ;-)


==== ROM-Image für den R8C erzeugen ====

Mit
<code>
sh ./build-ec r8c
</code>
erzeugt man eine Datei ''rom-r8c.mot'' (sie sollte der ''[[http://bernd-paysan.de/gforth-r8c.mot|gforth-r8c.mot]]'' von oben entsprechen). Es wird auch noch ein ''data-r8c.mot'' erzeugt, mit dem man ein zerschossenes Daten-Flash wieder in Ordnung bringen kann. Das ''rom-r8c.mot'' lädt man in's Flash. Danach kann man ein Terminal mit 38400 Baud 8N1 anschließen (etwa das Hyperterm, das in Windows eingebaut ist --- Verbindung auf "COMx" setzen), und interaktiv mit dem Forth im R8C arbeiten. Die Kommunikation findet über dieselbe serielle Schnittstelle statt, mit der man das Flash programmiert --- kein Umstöpseln nötig. Das Nachladen von Dateien geht mit einem normalen Terminalprogramm nur, wenn man ca. 250ms als Newline-Verzögerung einstellt, da Xon/Xoff zu langsam reagieren.

Spielen Sie ein wenig mit dem Forth das nun im R8C ist, etwa

<code forth>
1 2 + .
lcdpage
s" Hello World" lcdtype
adc@ .
</code>

Alle erlaubten Wörter werden mit

<code forth>
words
</code>

gelistet (zuletzt definierte zuerst).

==== Forth-Terminal von gforth aus ====

Mit
<code>
./gforth arch/r8c/terminal.fs
</code>
startet man das in Gforth eingebaute Terminal. Das Terminal hat kein eigenes Fenster, sondern läuft nun //innerhalb der shell//. Wenn die Verbindung zum r8c steht, gibt es ein ''ok'' sobald man //<return>// gedrückt hat. 

Mit diesem Terminal kann man nun auch
<code forth>
include arch/r8c/tt.fs
</code>
eingeben, und das adaptierte Tetris-for-Terminals von Dirk Zoller laden (dauert etwas --- der R8C compiliert den Code schließlich selbst). Starten mit
<code forth>
tt</code>

Es folgen einige Hinweise für die verschiedenen Betriebssysteme.


=== Windows XP ===
Das Terminal nimmt per Default die Verbindung über COM2 auf --- wenn nötig, die Datei ''terminal.fs'' editieren: Ganz gegen Ende der Datei wird das grad angelegte Terminal aufgerufen, die Schnittstelle ausgewählt und das Skript verlassen ''terminal COM2 bye''. Hier kann man statt dessen ''COM1'' eintragen; stimmt der Port nicht, reagiert das Terminal nicht! 

Weiterer Hinweis: Auf dem [[http://www.elektor.de/Default.aspx?tabid=27&year=2006&month=1&art=5550655&PN=On|Application-Board für den R8C/13]] von Elektor ist der USB-serial-Wandler PL2303X von Prolific schon mit drauf. Der braucht einen  [[http://www.prolific.com.tw/eng/downloads.asp?ID=31|passenden Treiber]]. Dieser trägt sich im System als COMx ein, wobei x für den nächsten freien COM-Port steht -- bei mir war es COM5. Diesen Portnamen in der Datei terminal.fs wie beschrieben eintragen und das Gforth-Terminal arbeitet über USB mit dem Gforth im r8c.

Oder --- bei Verwendung eines USB-Adapters --- die Schnittstelle über den Gerätemanager auf COM2 festlegen. 

=== Linux ===
Hier wird ''/dev/ttyUSB0'' verwendet und auch hier kann man entsprechend durch Editieren eine andere Schnittstelle festlegen.


==== Lauflicht im R8C ====

Ein einfaches Lauflicht, das nach dem Reset gleich losläuft, bis man über's Terminal eine Taste drückt:

<code forth>
rom
: licht!  led!  &100 ms ;
: lauf  1 licht! 2 licht! 4 licht! 8 licht!
  4 licht! 2 licht! ;
: dauerlauf  BEGIN  lauf  key?  UNTIL ;
' dauerlauf is bootmessage
ram
savesystem
</code>

==== ADC Wandler im R8C ====

Eine Schleife, die vom ADC liest und auf dem LCD ausgibt:

<code forth>
: adcmeter
  BEGIN  6 adc@ 0 <# #s #> lcdpage lcdtype &200 ms
         key? UNTIL ;
</code>

==== Multitasker ====

Und hier gibt's einen ganz einfachen Multitasker, der genau **einen** Hintergrundtask erlaubt:

<code forth>
rom

Variable bgtask ram $20 cells allot rom
:noname  bgtask @ 0= ?EXIT
    rp@ bgtask @ sp@ cell+ bgtask ! sp! rp! ;
IS pause
: task r> bgtask $20 cells + !
  bgtask $20 cells + bgtask $10 cells + !
  bgtask $10 cells + bgtask ! ;
:noname echo @ IF
     BEGIN pause key? UNTIL THEN (key) ;
is key

ram
</code>

Als Beispiel eine adaptierte Version des Lauflichts von oben:

<code forth>
rom
: licht!  led!  &100 ms ;
: lauf  1 licht! 2 licht! 4 licht! 8 licht!
  4 licht! 2 licht! ;
: dauerlauf
  task  BEGIN  lauf  AGAIN ;
ram
</code>

==== Lauftext ====

Analog zum Lauflicht kann man auch einen Lauftext erzeugen --- und über das Poti die Textgeschwindigkeit einstellen:

<code forth>
rom

Create text
," GNU Forth EC R8C -- Mikroprozessor -- "
Create ledtable 1 c, 2 c, 4 c, 8 c, 4 c, 2 c,
Variable /text

: lauftext  task
  BEGIN  text count /text @ over mod /string
         16 min dup >r lcdpage lcdtype
         r@ 16 < IF  text 1+ 16 r@ - lcdtype  THEN
         rdrop 1 /text +!
         /text @ 6 mod ledtable + c@ led!
         6 adc@ 2/ ms
  AGAIN ;

ram
</code>

===== Tipps und Tricks =====

Wenn man sich [[ausgesperrt]] hat, hilft dieser Trick von Erich Wälde.

===== Links =====

  * Peter Ouwehand beschreibt das [[http://home.iae.nl/users/pouweha/lcd/lcd0.shtml#hd44780|HD44780 LCD]]. Und hier kann man das [[http://www.ak-modul-bus.de/stat/lcd_modul_162b.html|LCD-Modul 162b]] kaufen (hat auch ein Link auf das [[http://www.ak-modul-bus.de/cat/documentation/162b series-v12.pdf|Datenblatt]] drin)
  * [[http://www.elektor.de/default.aspx?tabid=29&view=topic&forumid=23&postid=3645|Thread zum Programmieren des Daten-Flashs]]
  * Thomas Fischl hat einen [[http://www.fischl.de/thomas/elektronik/r8c/r8c_flasher.html|Flasher für Linux und Mac OS X]] an den R8C angepasst.

~~DISCUSSION~~