0. About fpga-shell
-------------------
The fpga-shell is part of the Suska-Project. 
For the Suska-III-BF and Suska-III-B board it is 
mandatory Software that provides the following services:
- powerup the board 
- initialize the FPGA 
- fill the OS-Flash 
- fill the Config-Flash
- handle PS2 Keyboard/Mouse
- debug and test functions
For the Suska-III-C board the software is optional
powerup and FPGA init is done by the System-Controller
and the OS-Flash can be configuered by a PC-Tool on this
Board too.

1. Install
----------
on Suska-III-C it needs to be flashed to the SDC-Controller 
(ATMEGA644) on the board.
on Suska-III-B(F) probably it is already installed on the ATMEGA649/644
on the board. 

2. Requirements
---------------
- Suska Board :-)
- PC with UART-Usb-Adapter 
- (mirco)SD-Card formated with FAT16/32
- Any terminal application 
  (Setting: 38400 Bd, 8 Bit, 1 Stopbit, no partity, Local Echo) 

3. fpga-shell Commands
----------------------
3.1 help
--------
Just lists all available commands with short usage

3.2 Commands for Handling of the FPGA-Config-Flash
--------------------------------------------------
- as-getid
  Displays Information of the Config-Flash-Chip
- as-write config.rbf
  Writes configuration file to the config flash
- as-read save.rbf
  copies the content of the config flash to a file on the SD-Card

3.3 Commands for Handling of the TOS-Flash
------------------------------------------
- f-dump flashoffset number-of-16bit-words
  Creates a hexdump of the flash area on the screen
- f-erase
  Erases the complete flash memory
- f-read flashoffset number-of-16bit-words outfile
  Creates a binary dump of the flash area on the SD-Card
- f-write flashoffset number-of-16bit-words infile
  fills the flasharea with the content of the file on the SD-Card

A typical workflow to fill the TOS-Flash (on Suska-III-B/BF):
- create a Raw-TOS-file containing a concatination of up to 16 512k TOS files
- copy this File to the SD-Card and insert this Card in the (lower) SD-slot
- erase flash:       f-erase
- write to flash:    f-write 0 tosfile.img

A typical workflow to fill the TOS-Flash (on Suska-III-C):
- copy all required TOS images to the SD-Card and insert this Card in the SD-slot
- 1. erase flash:       f-erase
- 2. select TOS-Slot with Switch SW1(2-4)
- 3. write to flash:    f-write 0 tosfile.img
- 4. repeat from 2. until all Tos images are flashed

3.4 Common Commands
-------------------
- info
Displays some information about the FPGA and Firmware
- ls
shows directory of the SD-Card
- cat file.txt
shows content of the file as ASCII-text
- hex file.bin
shows content of the file as Hexdump
- do file.bat
executes the commands in the file
Remark: A file named "init.txt" placed on the SD-Card will be executed in the same
        way automatically at powerup.
- reset
Suska-III-B(F): Powerdown of the system. 
Suska-III-C:  Reboot AVR (remount of SD-Card) 
Remark: On Suska-III-B(F) the "#"-key will power up the System (again).
- res level
  sets the reset pin of the fpga to "level"
  level == 1 means reset active
  level == 0 means reset inactive
  level == 2 generates a 0.5 sec reset pulse
- cres level
  sets the corereset pin of the fpga to "level"
  level == 1 means corereset active
  level == 0 means corereset inactive
  level == 2 generates a 0.5 sec corereset pulse

3.5 Other Commands
------------------
There may be some other commands available in the fpga-shell.
The help command will give a complete list. The commands not
mentionened above are for debuging and testing only and may
disturb the normal functions of the board.
Example: 
- puzzle iterations
 Will execute a puzzle benchmark. While it is running (several minutes)
 the normal function of the BF-Board (PS2-Interface) will be frozzen.
- sd cpm-image
 This programm will start a fileserver that presents the File "cpm-image"
 to the fpga. A special Core (Multicomp) is needed to create a Z80 Computer
 being able to boot cp/m. This is a endless loop - a power cycle is needed
 to return to normal operation. While the fileserver is running there is no
 ps2 functionality available.
- r-write offset binfile
 currently writes the content of "binfile" to the internal RAM of a AVR-Core
 This is only implemented in a special AVR-Core. In future it may be used to
 load the TOS image into the RAM as an ROM-replacement.