README

          GDB stub program for SH3(Version 1.0)

This program may be distributed under GNU Lesser GPL.

1. 初めに
このプログラムは SH3用 GDB stub です。ターゲットで実行することによりシ
リアル経由でホストで実行するgdbによるダウンロード、リモートデバッグが
可能です。このプログラムのオリジナルは Linux SH プロジェクト
(http://www.m17n.org/linux-sh/)で開発されたものであり、これを元に 
TOPPERS/JSP カーネル をサポートするための変更を行いました。なお、開発
環境のインストールに関しては TOPPERS のマニュアルを参照してください。
ライセンスはGNUGPL になっています。

サポートしているCPU は、SH7708,SH7709,SH7709Aで、サポートしているターゲット
は、以下の4種類です。

・EPSON製 CARD-E09A (SH7709A)
・三菱電機マイコン機器ソフトウエア製 MU200-RSH3 (SH7709)
・電産製 DVE7700 (SH7708)
・日立超LSIシステムズ製 MS7709ASE01 (SH7709A)



2. stubの概要
2.1 ワーク領域
stubはRAMの一部をワーク領域として使用します。この領域はプログラムで使
用ないでください。ターゲット毎の使用領域は、

・CARD-E09A     0x0C030000 ～ 0x0C033000
・MU200-RSH3    0x0C000000 ～ 0x0C001000
・DVE7700 	    0x0C000000 ～ 0x0C001000
・MS7709ASE01   0x0C000000 ～ 0x0C001000

です。なお、このワークエリアの設定はXXX.memファイルのRAMで始まる行で変
更可能です。


2.2 使用ポートと設定
ホストのgdbと通信を行うポートとボーレートは、次のようになります。全て
のターゲットにおいて データ:8bit, パリティ:無し ストップビット: 1bit 
です。

             使用ポート   ボーレート
・CARD-E09A     SCIF       115200bps
・MU200-RSH3    SCIF       115200bps
・DVE7700    	SCI         57600bps
・MS7709ASE01   SCIF       115200bps


2.3 trapaによる機能
trapa #0x3f を実行することによりstubの機能を呼び出します。

2.3.1 gdbのコンソールへの出力
r0 に0x00, r4 に出力したい文字を入れ trapa #0x3f を実行するとその文字
がホストの gdbのコンソールに出力されます。この出力はターゲットがブレー
クした時点でgdbのコンソールに出力されますが、リアルタイムに出力したい
場合は、gdbのソースを展開したインストールしたディレクトリ以下の
/gdb/remote.c にある関数remote_console_output()の

     else
        fputs_filtered (tb, gdb_stdout);

の箇所を

      else {
        fputs_filtered (tb, gdb_stdout);
        gdb_flush(gdb_stdout);
     }

と変更します．



2.3.2 例外/割り込みの登録
SH3 の例外機構はベクタ方式ではなく、例外/割り込みが発生すると VBR
+0x100,もしくは +0x600 番地から実行を開始します。そのため、stubは擬似
的なベクタテーブルを持ち例外/割り込みが発生するとその要因を判定してこ
のテーブルに登録された番地より実行を開始します。このベクタテーブルは 
RAM 上に置かれているため、ユーザープログラムで受け取りたい例外/割り込
みとそのハンドラを登録できます。登録は、r0 に 0x08, r4 に例外要因番号
(SH7709/A なら INTEVT2, SH7708 なら INTEV Tに設定される番号), r5 にハ
ンドラのアドレスを入れて trapa #0x3f を実行します。登録されたハンドラ
実行時の状態は VBR +0x400, +0x600 に配置したプログラムがCPU実行される
状態と同じです。なお、VBRを変更したり、stub が使用する例外/割り込み
(nmi,trapa,SCI等)を変更するとstubが正しく動作しなくなるので、注意して
ください。


2.4 gdbによるシリアル経由のブレーク
ターゲットでプログラムを実行中に gdb 上で ctrl-C を押すとブレークがか
かります。この機能は、gdb と通信を行うシリアルポートの受信割り込みによ
り実現しています。この割り込みの優先度は 0xf に設定します。この機能を
使用するためには、プログラム実行中の割り込みマスクの値を 0xe 以下に設
定してください。


2.5 レジスタの取り扱い
例外/割り込み発生に実行されるルーチンはentry.Sに記述していますが、r0 
～ r7 のバンクレジスタの使用方法が異なる entry_non_scrach.S も用意して
います。entry.S では、プログラムでは、常にバンク0を使用するものと想定
して gdb にバンク0のレジスタを送ります。entry_non_scrach.S はバンク1も
使用することを想定して、例外/割り込み発生時にアクティブなバンクのレジ
スタを gdb に送ります。レジスタはバンク0,1 共に破壊しません。その代り
例外/割り込み発生時のスタックをレジスタの退避のため、一時的に使用する
ため、スタックポインタの設定を誤るとリセットされます。entry.S ではスタッ
ク代りに バンク1の r0,r1 レジスタを使用するため、スタックポインタの設
定ミスが発生してもリセットされませんが、バンク1 のレジスタ r0,r1 が破
壊されるので、注意が必要です。


2.6 NMI
全てのターゲットにおいてNMI入力によるブレークをサポートしています。


2.7 他のターゲットへの移植
他のターゲットへの移植は、SH3が各種モジュールを内蔵していることもあり、
比較的容易に行えると思います。具体的には以下のファイルをターゲット用に
書きます。

init_XXX.S     : ハードウェア初期化ルーチン
XXX.mem        : メモリマップ
config.h_XXX   : コンフィグファイル
config.mk_XXX  : メイクファイル

後、sh-sci.c にボーレートを決定する SCBRR レジスタの設定値と sh-stub.ld.S
でXXX.memファイルをインクルードするように変更します。



3. インストール

s3.1 stubの作成
sh-stub.tar.gzを展開しターゲットに応じた config.h_XXX, config.mk_XXX 
ファイルをそれぞれ、config.h, config.mk とする。

   %cp config.h_XXX config.h
   %cp config.mk_XXX config.mk

sh-stub.tar.gzを展開したディレクトリで
   
   %make

とすると、ELF形式の sh-stub とバイナリのsh-stub.binが生成されます。他
の形式を作成するには，

make sh-stub.hex  : インテルHEXフォーマットを作成
make sh-stub.src  : モトローラSレコードフォーマットを作成

とします．これ以外のフォーマットで出力したい場合は，
sh-hitachi-elf-objdump で変換してください。このファイルをRSH3,DVE7700
はROMに焼いて実装します。MS7709ASE01は，ボードに付属しているROMモニタ
でフラッシュの先頭に書きます．ROMモニタでの書き込みに関しては，ボード
に付属のマニュアルを参照して下さい．CARD-E09Aは、sh-stub.bin をCFに書
き込み、startup.datを

   [DEBUGGER]
   "sh-stub.bin"

と変更して起動時に実行するようにしてください。


3.2 動作確認
ROMかフラッシュROMに書き込んだら、ホストマシンでターミナルソフトにより
接続します。適当に1文字入力してターゲットから $S05#b8 という文字列が返っ
てくるか確認してください。返ってこなければstubが正しく動作していないの
でROM、ジャンパの確認をしてください。


3.3 実行
まずプログラムを-gオプションを付けてコンパイルした後そのファイルをgdb
の引数に指定して実行します。

gdbが起動したら次のコマンドを実行します。
   (gdb) set remotebaud BPS
   (gdb) set endian ENDIAN
   (gdb) target remote /dev/TTY
   0xc031216 in ?? ()

BPS にはボーレート、ENDIAN にはエンディアン(bigなら指定しなくても良い)
TTYはターゲットに接続しているポートを指定します。
次にプログラムをダウンロードします。

   (gdb)load

ロードが終了したら実行します。

   (gdb)continue

実行中にctrl-Cを押すとプログラムの実行をブレークします。
後はホストで通常のgdbによるデバッグと等しい操作が行えます。
gdbの使い方は、各種マニュアルを参考にしてください。


-----------------------------------------------------------------------------
本田晋也(Shinya Honda),<honda@ertl.ics.tut.ac.jp> 9 Mar 2001