bsps: Move documentation, etc. files to bsps

This patch is a part of the BSP source reorganization.

Update #3285.

5 files changed, 390 insertions, 0 deletions

diff --git a/bsps/sh/gensh1/README b/bsps/sh/gensh1/README
new file mode 100644
index 0000000000..6165403cb4
--- /dev/null
+++ b/bsps/sh/gensh1/README
@@ -0,0 +1,51 @@
+#  Author: Ralf Corsepius (corsepiu@faw.uni-ulm.de)
+#
+
+BSP NAME:           generic SH1 (gensh1)
+BOARD:              n/a
+BUS:                n/a
+CPU FAMILY:         Hitachi SH
+CPU:                SH 7032
+COPROCESSORS:	    none
+MODE:               n/a
+
+DEBUG MONITOR:      gdb
+
+PERIPHERALS
+===========
+TIMERS:             on-chip
+  RESOLUTION:         cf. Hitachi SH 703X Hardware Manual (Phi/4)
+SERIAL PORTS:       on-chip (with 2 ports)
+REAL-TIME CLOCK:    none
+DMA:                not used
+VIDEO:              none
+SCSI:               none
+NETWORKING:         none
+
+DRIVER INFORMATION
+==================
+CLOCK DRIVER:       on-chip timer
+IOSUPP DRIVER:      default
+SHMSUPP:            default
+TIMER DRIVER:       on-chip timer
+TTY DRIVER:         /dev/null (stub)
+
+STDIO
+=====
+PORT:               /dev/null (stub)
+ELECTRICAL:         n/a
+BAUD:               n/a
+BITS PER CHARACTER: n/a
+PARITY:             n/a
+STOP BITS:          n/a
+
+NOTES
+=====
+
+(1) The stub console driver (null) is enabled by default.
+
+(2) The driver for the on-chip serial devices (sci) is still in its infancy
+    and not fully tested. It may even be non-functional and therefore is
+    disabled by default. Please let us know any problems you encounter with
+    it.
+    To activate it edit libbsp/sh/gensh1/include/bsp.h
diff --git a/bsps/sh/gensh2/README b/bsps/sh/gensh2/README
new file mode 100644
index 0000000000..eceb272853
--- /dev/null
+++ b/bsps/sh/gensh2/README
@@ -0,0 +1,57 @@
+#  Author: Ralf Corsepius (corsepiu@faw.uni-ulm.de)
+#  Adapted by: John Mills (jmills@tga.com)
+#  Corrections: Radzislaw Galler (rgaller@et.put.poznan.pl)
+
+
+BSP NAME:           generic SH2 (gensh2)
+BOARD:              EVB7045F (note 2)
+BUS:                n/a
+CPU FAMILY:         Hitachi SH
+CPU:                SH 7045F
+COPROCESSORS:	    none
+MODE:               n/a
+
+DEBUG MONITOR:      gdb
+
+PERIPHERALS
+===========
+TIMERS:             on-chip
+  RESOLUTION:         cf. Hitachi SH 704X Hardware Manual (Phi/16)
+SERIAL PORTS:       on-chip (with 2 ports)
+REAL-TIME CLOCK:    none
+DMA:                not used
+VIDEO:              none
+SCSI:               none
+NETWORKING:         none
+
+DRIVER INFORMATION
+==================
+CLOCK DRIVER:       on-chip timer
+IOSUPP DRIVER:      default
+SHMSUPP:            default
+TIMER DRIVER:       on-chip timer
+TTY DRIVER:         /dev/console
+
+STDIO
+=====
+PORT:               /dev/sci0
+ELECTRICAL:         SCI0
+BAUD:               9600
+BITS PER CHARACTER: 8
+PARITY:             NONE
+STOP BITS:          1
+
+NOTES
+=====
+
+(1) The present 'hw_init.c' file provides 'early_hw_init'(void) which
+    is normally called from 'start.S' to provide such minimal HW setup
+    as is conveniently written in 'C' and can make use of global
+    symbols for 7045F processor elements. It also provides
+    'void bsp_hw_init (void)' normally called from 'bspstart.c', shortly
+    before RTEMS itself is started.
+
+    These are both minimal functions intended to support the RTEMS test
+    suites.
+
+(2) See README.EVB7045F
diff --git a/bsps/sh/gensh2/README.EVB7045F b/bsps/sh/gensh2/README.EVB7045F
new file mode 100644
index 0000000000..813cd6b816
--- /dev/null
+++ b/bsps/sh/gensh2/README.EVB7045F
@@ -0,0 +1,149 @@
+#  Author: Radzislaw Galler (rgaller@et.put.poznan.pl)
+#
+
+
+Getting started with EVB7045F and gensh2
+========================================
+This is a capture of success path to put a RTEMS sample
+'hello.exe' on the evaluation board EVB7045F.
+
+ What you need
+---------------
+   * Computer with two operating systems: Linux and Wndows 2000 (tm) -
+     that was in my case (see section 'Variations')
+
+   * Flash Development Toolkit (FDT) - available on HMSE homepage
+     (http://www.hmse.com/products/fdt/support.htm)
+
+   * 'gdbstubs' - available on SourceForge
+     (http://sourceforge.net/projects/gdbstubs/) 
+
+   * working GNU C compiler for Hitach SH processors; do-it-yourself
+     (on Linux) or download ready stuff for Windows'9x/NT/2k from
+     (http://www.hitachi-eu.com/hel/ecg/) or from Hitach Databook 2001
+     CD-ROM (if no luck try to search on the net for gnu99r1p1.zip)
+     
+   * GDB compiled for target sh-rtems  - do-it-yourself or download
+     from ftp://ftp.oarcorp.com:21/pub/rtems/snapshots/c_tools/
+
+   * RTEMS (ofcourse) you probably already have if you are reading this
+     document
+
+ Instalation of 'gdbstubs'
+--------------------------
+  Once you downladed and unzipped gdbstubs you have to compile
+  it. First modify the Makefile to use the compiler installed on your
+  machine.  Then issue the command:
+
+  $ make 
+
+  This should produce the default target sh2-7045edk.out. This is the
+  S-record file which should be added to FDT project (renaming it to
+  *.mot extension helps a bit). 
+  If you are lucky you will be able to put the file into the FLASH
+  following the instuctions in FDT and EVB manuals. 
+  
+  Well I wasn't lucky so I had to bypass the Universal Programming
+  Board (see EVB7045F User Manual) and manually put the processor into
+  BOOT mode. This can be done by shortening the capacitor C8 (or C108
+  on schematics) which puts the UPB into permanent reset state, and by
+  removing jumper JP4 (or JP104 on schematics) and connecting its
+  middle pin to the ground. After pressing CRES button the processor
+  is in BOOT mode. In FDT select "direct connection":
+
+  Menu Project->Properties->Device->Select Interface
+
+  After that there should be no problem in putting the program into the
+  FLASH. 
+
+ Loading 'hello.exe' on board
+------------------------------
+  I assume you are able to compile RTEMS with 'gensh2' BSP and
+  necessary tools. If not please refer to 'started.pdf' document which
+  describes the procedure (http://www.oarcorp.com/).
+
+  At the time of writing this document 'gdbstubs' default
+  communication port was SCI1. So it was the default port for
+  /dev/console in RTEMS. To avoid problems I had check these settings
+  both in 'gdbstubs' and $RTEMS_ROOT/c/src/lib/libbsp/sh/gensh2/include/bsp.h
+
+  After changing the line 
+
+  #define BSP_CONSOLE_DEVNAME "/dev/sci1"
+
+  to
+
+  #define BSP_CONSOLE_DEVNAME "/dev/sci0"
+
+  in 'bsp.h' and rebuilding RTEMS there should no problem in running
+  'hello.exe' and other samples. 
+
+  For downloading connect a serial cable to computer and EVB. You will
+  also need a second cable and second serial port to see the effects
+  of your work.
+
+  Assuming you are working in Linux and Xwindows fire up two terminal
+  windows. In the first one run sh-rtems-gdb, in the second run a
+  serial port terminal (for example 'minicom'). Set up the serial
+  terminal to a port connected to SCI0 and leave the window in a
+  visible place on the desktop. The debugger should be invoked best
+  from the directory where 'hello.exe' is placed. Assuming that here
+  is a GDB session:
+
+  --------start------
+  $ sh-rtems-gdb hello.exe 
+  GNU gdb 5.0
+  Copyright 2000 Free Software Foundation, Inc.
+  GDB is free software, covered by the GNU General Public License, and you are
+  welcome to change it and/or distribute copies of it under certain conditions.
+  Type "show copying" to see the conditions.
+  There is absolutely no warranty for GDB.  Type "show warranty" for details.
+  This GDB was configured as "--host=i686-pc-linux-gnu --target=sh-rtems"...
+  (gdb) set remotebaud 115200
+  (gdb) target remote /dev/ttyS0
+  Remote debugging using /dev/ttyS0
+  0x0 in ?? ()
+  (gdb) load 
+  Loading section .text, size 0x12d70 lma 0x444000
+  Loading section .data, size 0xb80 lma 0x456df0
+  Loading section .stack, size 0x10 lma 0xfffffec0
+  Start address 0x444000 , load size 80128
+  Transfer rate: 58274 bits/sec, 153 bytes/write.
+  (gdb) continue 
+  Continuing.
+
+  Program received signal 0, Signal 0.
+  0x44ec36 in exit (code=0) at exit.c:70
+  70	exit.c: No such file or directory.
+  (gdb) 
+  --------end-------
+  
+  And here is a capture from the serial terminal window:
+
+*** HELLO WORLD TEST ***
+Hello World
+*** END OF HELLO WORLD TEST ***
+
+  Beautiful, isn't it? That's all!
+  
+
+
+ Variations
+------------
+  I'm sure that not every one can afford having two operating systems
+  on one computer. I believe there will be a day that nobody will need
+  an MS stuff anymore... ;)
+
+  It is possible to repeat the success on MS Windows only. To do the
+  same on Linux only you need a tool to downlad 'gdbstubs' on the
+  board. This should be no problem to find it on the net but right now
+  I don't know about it.
+
+  For your convenience there are several graphical interfaces for GDB
+  available on the net. I just name two of them:
+
+  DDD - stands for Data Display Debugger
+        (http://www.gnu.org/software/ddd/)
+
+  Insight - a Tcl/Tk interface available both for MS Windows and
+            Xwindows (http://sources.redhat.com/insight/)
diff --git a/bsps/sh/gensh4/README b/bsps/sh/gensh4/README
new file mode 100644
index 0000000000..13e719d72f
--- /dev/null
+++ b/bsps/sh/gensh4/README
@@ -0,0 +1,91 @@
+#  Author: Alexandra Kossovsky <sasha@oktet.ru>
+#          Victor Vengerov     <vvv@oktet.ru>
+#   OKTET Ltd, http://www.oktet.ru
+#
+
+BSP NAME:           generic SH4 (gensh4)
+BOARD:              n/a
+BUS:                n/a
+CPU FAMILY:         Hitachi SH
+CPU:                SH 7750
+COPROCESSORS:	    none
+MODE:               n/a
+
+DEBUG MONITOR:      gdb (sh-ipl-g+ loader/stub)
+
+PERIPHERALS
+===========
+TIMERS:             on-chip
+SERIAL PORTS:       on-chip (with 2 ports)
+REAL-TIME CLOCK:    none
+DMA:                not used
+VIDEO:              none
+SCSI:               none
+NETWORKING:         none
+
+DRIVER INFORMATION
+==================
+CLOCK DRIVER:       on-chip timer
+IOSUPP DRIVER:      default
+SHMSUPP:            n/a
+TIMER DRIVER:       on-chip timer
+TTY DRIVER:         /dev/console
+
+STDIO
+=====
+PORT:               /dev/console
+ELECTRICAL:         n/a
+BAUD:               n/a
+BITS PER CHARACTER: n/a
+PARITY:             n/a
+STOP BITS:          n/a
+
+NOTES
+=====
+
+(1) Driver for the on-chip serial devices is tested only with 1st serial
+    port. We cannot test it on serial port with FIFO.
+
+    Console driver has 4 modes -- 2 with termios (interrupt-driven & 
+    poll-driven modes), one raw mode working with serial port directly,
+    without termios, and one mode working with gdb stub (using 'trapa'
+    handled by sh-ipl-g+).
+
+(2) The present 'hw_init.c' file provides 'early_hw_init'(void) which
+    is normally called from 'start.S' to provide such minimal HW setup.
+    It is written in C, but it should be noted that any accesses to memory
+    (except hardware registers) are prohibited until hardware not
+    initialized. To avoid access to stack, hw_init.c should be compiled with
+    -fomit-frame-pointer.
+
+    hw_init.c also provides 'bsp_cache_on'(void) normally called from
+    'start.S' after copying all data from rom to ram.
+
+(3) In 'configure.ac' you should properly set 'CPU_CLOCK_RATE_HZ'.
+    It is frequency fed to the CPU core (external clock frequency can be
+    multiplied by on-chip PLLs). Please note that it is not a frequency of
+    external oscillator! See Hardware Manual, section 10, for details.
+    Global variable 'SH4_CPU_HZ_Frequency' is declared in 'bsp.h' and 
+    initilized in 'bspstart.c' to ${HZ}. It is used by sci driver, 
+    which exists in 'libcpu/sh/sh7750'. 
+
+(4) There is SH4_WITH_IPL macro in console driver 'sh4_uart.h'. 
+    When it is defined, the application works under 
+    gdb-stub (it is able to turn cache on by 'trapa', use gdb mode in console
+    driver and get out from gdb to use other console modes).
+
+(5) There are 3 likcmds: 
+    - linkcmds: code and data loaded to RAM. No code/data moving required.
+    - linkcmds.rom: code executed from the ROM; .data section moved to the
+    RAM on initialization.
+    - linkcmds.rom2ram: execution started from the ROM (after reset); code
+    and data moved to the RAM and execution continued from RAM.
+
+    The same 'start.S' is used for all cases.
+
+(6) You can get gdb stub from http://www.oktet.ru/download/sh4/sh-ipl.tar.gz.
+    It is based on 'sh-ipl-g+' package used in sh-linux project.
+
+(7) This project was done in cooperation with Transas company
+    http://www.transas.com
+
diff --git a/bsps/sh/shsim/README b/bsps/sh/shsim/README
new file mode 100644
index 0000000000..866fedafa2
--- /dev/null
+++ b/bsps/sh/shsim/README
@@ -0,0 +1,42 @@
+Simple BSP for the SH simulator built into gdb.
+
+Simulator Invocation
+====================
+sh-rtems[elf|]-gdb <executable>
+(gdb) target sim
+(gdb) set archi [sh|sh2]
+(gdb) load <executable>
+(gdb) run
+
+Status
+======
+
+* The simulator invocation procedure outlined above produces error messages
+with gdb-5.0, nevertheless seems to work. With gdb versions > 5.0 these
+error messages are gone. I.e. if you plan to seriously work with the gdb
+simulator better use gdb versions > 5.0.
+
+* gdb's simulator is not able to correctly emulate memory areas esp. shadowing
+and non-consecutive memory. I.e. access to memory areas besides area 0 will 
+(bogusly) generate SIGBUS exceptions.  This includes access to area 5 
+(On-chip peripherials) and prevents simulation of configuration and access
+to on-chip peripherials.
+
+* Due to limitations of the simulator you will only be able to run
+applications which do not try to access any SH control registers.
+
+Currently, this excludes all applications, which apply timers and serial 
+devices, i.e. almost any real world application.
+
+* This BSP supports 3 different console devices (cf. configure --help):
+- trap34, an interface base on gdb's trap34 emulation. Known to work with
+  gdb-5.0.
+- gdbsci1, a stripped down sci device driver adapted to apply gdb's sci1
+emulation. This is known to fail with gdb-5.0, because of a bug in gdb-5.0's 
+sh-sim, a patch is submitted, but .. ~==
+- devnull, redirection of console io to /dev/null. Try to single step this,
+if you want to understand the details on how SH-RTEMS console redirection
+works.
+
+NOTE: the trap34 interface is incomplete and is temporarily disabled
+inside of configure.in.