-*- mode: Text; mode: auto-fill; -*-

P/EMU/SDL
=========

これは，Naoyuki Sawa さんによる P/ECE エミュレータ P/EMU を改造した版で
す．

・原作は Win32 に依存していたものを，SDL に移植しました．このため，SDL
が動作するプラットフォームであれば少ない工数で移植できるはずです．とり
あえず Windows, Linux と PSP 版の makefile を用意してあります（各種ツー
ルは未移植）．CPU コアのエミュレーションにエンディアンネス依存部分が多々
ありますので，MacOS X 等への移植は当分簡単にはいかないでしょう．

・メモリイメージ方式を採用し，エミュレータの実行に実機は必要なくなりま
した．システムアップデート用のイメージファイルが公式サイトで公開されて
いますので，このイメージファイルを使えば実機不要ブートができます．現状
イメージの生成や編集の手順が面倒です．

・このプログラムはまだ開発途上です．エミュレータとして当然要求されるは
ずの多くの機能が未実装です．

このドキュメントは長いですが，読まないときっとハマります．

Windows 版
----------

800MHz ～ 1GHz 程度のクロックで動く CPU が必要ですが，とりあえず動きま
す．Windows XP SP2 でしか検証していません．相変わらず遅いですが，原作
のように CPU 利用率 100% にはならないはずです．

SDL.dll は別途用意してください．

Linux 版
--------

気が向いたときに VMware でコンパイルして検証している程度ですが，とりあ
えず動きます．ツール類はまだ移植していません．リビジョンによってはこけ
るかもしれませんが適当にほげってくださいということで（ぉ

Vine Linux 3.2 でコンパイルと動作検証をしています．Turbolinux だと SDL
も自力ビルドする必要があるかもしれません．

添付の makefile.linux で作られる実行ファイルは piemu.linux です．


PSP 版
------

なんというかネタビルドです（ぉ　現状まともな速度では動作しません．
とりあえず HOME キーでエレガントに終了することはできますが，その程度で
す（ぉ

添付の makefile.psp を使ってコンパイルすると，Firmware 1.5 用の実行ファ
イルは piemu と piemu% ディレクトリにできます．Firmware 1.0 用の実行ファ
イルは EBOOT.PBP です．


実機を持っているとき
--------------------

実機をお持ちであれば，フラッシュメモリイメージを実機から吸い出して作成
することができます．P/ECE 実機を USB に接続して，コマンドラインから
tools/ ディレクトリにある FlashRipper.exe を実行すると，カレントディレ
クトリに piece.pfi というファイルができます．これがフラッシュメモリイメー
ジですから，piemu.exe と同じディレクトリに置いてください．置かないとエ
ラーすら出さずにクラッシュします．一度 piece.pfi を生成したら後は実機は
不要です．

SDL のランタイムを入手し，piemu.exe と同じディレクトリか PATH の通って
いるところにおいてください．そして piemu.exe を実行すると，通常なら
startup.pex が起動するはずです．


実機を持っていないとき
----------------------

P/ECE 公式サイトではシステムアップデートのためにカーネルのイメージファ
イルを配布しています．このイメージファイルに細工することで，P/EMU/SDL
の実行に必要な piece.pfi 形式イメージファイルを実機から吸い出すことなく
生成することができます．

まずは公式サイトから最新のシステムアップデートを入手し，中の
update/all.bin を用意します．all.img では *ありません*．フラッシュ 2MB
対応版や MMC/SD 対応版でもかまいません（が，MMC/SD のエミュレーションは
実装していません）．これをどっかのディレクトリに放り込んでおいて，
P/EMU/SDL のアーカイブの tools/ ディレクトリにある mkpfi.exe を以下のコ
マンドラインで実行します．

mkpfi.exe [-512kb|-2mb] all.bin [piece.pfi]

用意した all.bin が対応するフラッシュ容量に応じて -512kb か -2mb のどち
らかのオプションをつけてください．デフォルトは -512kb です．piece.pfi
へのパスは任意です．省略すると all.bin と同じディレクトリに生成されます．

こうしてできあがった piece.pfi ファイルがフラッシュメモリイメージですか
ら，piemu.exe と同じディレクトリに置いてください．置かないとエラーすら
出さずにクラッシュします．一度 piece.pfi を生成したら後は all.bin 等は
不要です．

SDL のランタイムを入手し，piemu.exe と同じディレクトリか PATH の通って
いるところにおいてください．そして piemu.exe を実行すると，通常なら
startup.pex が起動するはずです．


ファイルシステムイメージの編集
------------------------------

P/EMU/SDL のフラッシュイメージファイルには，P/ECE カーネルと P/ECE フラッ
シュファイルシステム（PFFS）が保存されています．PFFS にファイルを追加し
たり削除したりするには，（いまのところ）tools/ ディレクトリの pffs.exe
を使います．このツールの使い方は次の通りです．

pffs.exe piece.pfi -{adelv} [file [...]]

-a	   file を追加 or 上書きする。
-d	   file を削除する
-e	   file を取り出す
-l	   ファイル一覧と空き容量をみる
-v	   イメージのシステム情報をみる


……これらのツールの GUI 版も必要でしょう．


操作
----

原作にあったジョイスティック対応は今のところ削除されています（ぉ

Windows/Linux 版

Z	      A
X	      B
A	      START
S	      SELECT
カーソルキー  方向キー

PSP 版

○            A
×	      B
START	      START
SELECT	      SELECT
HOME	      終了
方向キー      方向キー


TODO
----

- エミュレータ実行中にフラッシュメモリをイメージファイルに書き戻す
手段が必要．今のままでは動作中に書き換えられたフラッシュメモリの内容が
残らない．
- 各種ツールの GUI 化．
- もっと高速化．
- USB エミュレーション．Windows サイドには偽 pieceif.dll を用意するこ
とで対処する．
- MMC/SD エミュレーション．もともとはシリアル拡張端子だけど．
- CPU エミュレーション部分のクリーンアップ．
- フラッシュメモリイメージ形式をさっさと確定させる．
- きっとまだたくさんある．


ハックするには
--------------

あらかじめ SDL-devel を入手し、VC++ ならそのパスを環境変数 LIB や
INCLUDE に書いておきます。Linux 版や PSP 版なら SDL のパスは（ちゃんと
インストールされていれば）自動検出されます。

GNU make が必要です。オプションで bash や rm があれば makefile の各コマ
ンドを直接使えます。


VC++ 版
-------

VC++.NET 2003 でコンパイルしています。そのまま make でコンパイルできま
す。


Linux 版
--------

Vine Linux 3.2 でコンパイルと動作確認しています。make -f
  makefile.linux でコンパイルします。piemu.linux が実行ファイルです。


PSP 版
------
  /bin/mkdir "piemu"; /bin/mkdir "piemu%"
  make -f makefile.psp all

プロジェクトディレクトリにできる EBOOT.PBP が Firmware 1.0 用の実行ファ
イルです。1.5 用のファイルは make -f makefile.psp kxploit とすれば
piemu と piemu% というディレクトリにそれぞれ入ります。


開発
----

開発は ヅラChu さんの Subversion リポジトリにて行われています．

最新バージョンのソースコードは，svn://tamaki.zurachu.net/piemu/trunk か
ら匿名でもチェックアウトできます．ビルドには Visual C++.NET 2003 か
Cygwin gcc が必要です．基本的に開発は内輪で行われています．


-----
Yui N. (aka Autch)
http://www.autch.net/

---------------------------------------------------------------------
以下は実装途中のメモです．


つかいかた

実機から吸い出して使う：

実機を USB につないで tools/FlashRipper.exe を実行
できた piece.pfi を piemu.exe と同じ dir において実行

all.bin を使う：

all.bin を tools/mkpfi.exe と同じ dir に置く

tools/mkpfi.exe all.bin として実行、or mkpfi.exe に all.bin を DnD

できた piece.pfi を piemu.exe と同じ dir において実行

一度 piece.pfi を作ったら実機は不要。all.bin も不要。piemu.exe と
piece.pfi （と SDL）だけ持ち歩けばよい。

ファイルエリアの編集：

吸い出した or ねつ造したイメージのファイルエリアを編集するには、
	pffs.exe piece.pfi -adelv [file [...]]
	-a	   file を追加 or 上書きする。
	-d	   file を削除する
	-e	   file を取り出す
	-l	   ファイル一覧と空き容量をみる
	-v	   イメージのシステム情報をみる
これから -i（初期化）も必要になると思う。

ほかに要りそうなツール

dlpfi	pfi を実機へ書き込む(!)
editpfi pfi の SYSTEMINFO を書き換える

大事

現在の PFFS では FAT エントリが全部で 496 個までしか使えないので、最大
サイズは 4,096 * 496 = 2,031,616 bytes まで。同様にファイルの個数は全部
で 96 個まで。


なぜ使い分ける

p/ece（というか S1C33000）はブート時にフラッシュメモリ先頭に書かれてい
るアドレス（リセットベクタ）へジャンプするようになっている。フラッシュ
メモリの先頭（アドレス $c00000, s1c33 のアドレス空間は 28bit）から 2 セ
クタ、8192 バイト分は緊急用カーネルが入っている。p/ece はブート時にアド
レス $c00000 の内容を読む。ここには $c00004 と書かれているので、（すぐ
隣の）そこへジャンプする。

$c00004 にはさらに緊急カーネルへのエントリポイントへの相対ジャンプ命令
が書かれているので、（カーネルシグナチャや GUID 領域を飛び越えた）そこ
へジャンプする。そこで割り込みの禁止、SP や PSR の初期化をしてから、
$c02000 から $1000 単位で通常カーネルのシグナチャを探す。

シグナチャは +8 のオフセットのところにあるので、$c02008, $c03008,
$c04008, ... とメモリを見ていき、そこにカーネルシグナチャがあればオフセッ
ト +0, つまり $c02000, $c03000, $c04000, ... の内容を読み出し、そこが示
す先（普通オフセット +4）へジャンプする。

$c02004 にはさらに通常カーネルエントリポイントへの相対ジャンプ命令が書
かれているので、通常カーネルをブートすることができる。

p/ece カーネルアップデートに使う all.bin 形式のイメージファイルは、先頭
2 セクタ分の緊急カーネルが省かれており、USB 経由で ku.srf を使って
$c02000 以降のセクタを書き込むようになっている。カーネルアップデート時
に緊急カーネルまで上書きしてしまっては、書き込みが失敗したときに緊急カー
ネルの意味を成さなくなるためである。

FlashRipper で実機から吸い出すイメージファイルには、緊急カーネルの先頭
2 セクタ分が含まれているので、これをエミュレータのアドレス $c00000 へ読
み込んでやれば問題なくブートすることができる。

all.bin のイメージには先頭 2 セクタ分のイメージが欠けているので、このま
ま $c00000 へロードしてもブートすることはできない。そこで、all.bin から
ブートイメージを作るときに、先頭 2 セクタ分を捏造することで対応すること
にした。ブート時に最初にアクセスされる $c00000 に$c02004 を書き込んでし
まうのだ。こうすれば s1c33 はいきなり通常カーネルがあるはずのエントリポ
イントを見に行くことになる。SP や PSR の初期化等は通常カーネルでも行わ
れるので問題ない。

PFI ファイルフォーマット（P/EMU Flash Image file format）

p/emu/sdl が利用している pfi 形式イメージファイルには、p/ece のシステム
情報（piece.h の SYSTEMINFO 構造体）も保存されている。この情報はハード
ウェアのエミュレーションに必須のため、フラッシュメモリイメージと一緒に
含めてしまうことにした。この情報は本来カーネルメモリイメージから取って
こられるのだが、非実機環境で簡単に取得する方法がないので、FlashRipper
で実機から吸い出す際に一緒に取得することにし、all.bin で実機不要ブート
するときには標準的なパラメータを mkpfi が生成するようにした。

pfi ファイル形式の簡単な説明を示す。すべてリトルエンディアンである。

DWORD dwSignature

ファイル識別子 'PFI1'. リトルエンディアンなのでバイトの並びは "1IFP" と
なる。

DWORD dwOffsetToFlash

フラッシュメモリイメージの開始オフセット。

SYSTEMINFO siSysInfo

P/ECE システム情報構造体。内容は「p/ece API リファレンス」を参照。

（そしてフラッシュメモリイメージが続く）

PFI フォーマットの将来のバージョンで siSysInfo 以降からフラッシュメモリ
イメージまでの間にデータが増えるかもしれない。その増えたデータがエミュ
レータの実行に必須のときは、ファイル識別子の末尾の数字を PFI2, PFI3,
PFI4, ... のように増やす。
	

TODO
	32bit color 化 for PSP
	SYSTEMINFO のねつ造（overclocking, etc.）
	virtual USB
	virtual MMC -- ディスクイメージ方式？
	PFFS editor
	how to save the modification to PFFS
	// SDLize  // done
	making it more faster
	endianness problem
	porting for PSP

TBD
	PFFS と kernel 分離する？
		system.pfi	PFI0	SYSTEMINFO とカーネル
		piece.pfi	PFI1	↑と↓両方
		pffs.pfi	PFI2	PFFS 部分だけ


ライセンス
	nsawa さんが何と言うか……。