ドキュメント作成

[YACASL2.git] / doc / yacasl2.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename yacasl2.info
@settitle YACASL2 - Linux上のCASL2処理系
@c %**end of header

@exampleindent 2

@copying
Copyright @copyright{} 2010 j8takagi
@end copying

@titlepage
@title
@end titlepage
@node Top

@menu
* YACASL2の概要:about.
* YACASL2のインストール:install.
* YACASL2の使い方:tutorial.
@end menu


@c Output the table of contents at the beginning.
@contents

@insertcopying

@node about, install, Top, Top
@chapter YACASL2の概要

@cindex chapter, first

YACASL2は、Linux上で動作するオープンソースのCASL II処理系です。CASL IIは情報処理試験で用いられるアセンブラ言語で、次の資料により仕様が公開されています。

@quotation
@uref{http://www.jitec.ipa.go.jp/1_00topic/topic_20081027_hani_yougo.pdf, 試験で使用する情報処理用語・プログラム言語など（2008年10月版）}［PDFファイル］
別紙 1 アセンブラ言語の仕様
@end quotation

YACASL2は、CASL IIアセンブラ言語で記述されたファイルをアセンブルし、仮想マシンCOMET II上で実行します。アセンブルと実行は、連続で行うことも別々に行うことも可能です。
YACASL2の動作はCASL IIの仕様に準拠しているため、情報処理試験の問題をはじめ各種参考書やサイトに記載されたCASL IIのプログラムをそのままアセンブルして実行できます。また、本パッケージ中にCASL IIのサンプルプログラムが多数収録されています。

YACASL2は、「ふつうの処理系」として動作します。ほかの多くのCASL IIエミュレーターと違い、デバッガーとして動作したり、コンピューター内部の模式図を表示したりすることはありません。そのかわり、YACASL2は、次のような動作内容をすべてテキストで出力します。

@itemize @bullet

@item
ラベルとアドレスの対応

@item
アセンブル結果

@item
実行時のレジスタの内容

@item
実行時のメモリの内容
@end itemize

出力された動作内容は、GNU/Linuxのさまざまなツール、たとえば@command{cat}、@command{less}、@command{grep}、@command{wc}などを使って解析できます。

@unnumberedsec 要件
YACASL2は、Linux上で動作します。現在動作を確認しているのは、次のディストリビューションです。

@itemize @bullet

@item
Ubuntu Linux 9.04 / 8.04

@item
Vine Linux 4.2
@end itemize

インストール時に、@command{tar}、@command{gcc}、@command{make}が必要です。

@node install, tutorial, about, Top
@chapter YACASL2のインストール

YACASL2をインストールするには、Linux上で次の作業をします。

@enumerate

@item
@file{yacasl2.tar.gz}のダウンロード

@item
@file{yacasl2.tar.gz}の検証

@item
@file{yacasl2.tar.gz}の展開

@item
@command{casl2}、@command{comet2}、@command{dumpword}のビルド

@item
@command{casl2}の実行テスト

@item
詳細なテスト

@item
環境設定@var{PATH}の設定
@end enumerate

以下の操作は、端末を開きコマンドを実行します。

@section @file{yacasl2.tar.gz}のダウンロード
（詳細未定）

@cartouche
@example
$ @b{cd}
$ @b{wget somewhere/yacasl2.tar.gz}
$ @b{wget somewhere/yacasl2.tar.gz.md5sum}
@end example
@end cartouche

@section @file{yacasl2.tar.gz}の検証

（PGPを使った検証も導入予定）

ダウンロードが完了したら、@command{md5sum}と@command{diff}で正しくファイルがダウンロードができているかを検証します。

@cartouche
@example
$ @b{md5sum yacasl2.tar.gz | diff -s yacasl2.tar.gz.md5sum -}
Files yacasl2.tar.gz.md5sum and - are identical
@end example
@end cartouche

@section @file{yacasl2.tar.gz}の展開

@file{yacasl2.tar.gz}をダウンロードしたら、次のコマンドで展開します。

@cartouche
@example
$ @b{tar xvzf yacasl2.tar.gz}
@end example
@end cartouche

@section @command{casl2}、@command{comet2}、@command{dumpword}のビルド

展開したら、次のコマンドで@command{casl2}、@command{comet2}、@command{dumpword}をビルドします。

@cartouche
@example
$ @b{cd yacasl2}
$ @b{make}
make -C src
make[1]: Entering directory ‘/home/kazubito/yacasl2/src’
gcc -c -g -Wall -I ../include casl2.c
gcc -c -g -Wall -I ../include word.c
gcc -c -g -Wall -I ../include hash.c
gcc -c -g -Wall -I ../include cerr.c
gcc -c -g -Wall -I ../include struct.c
gcc -c -g -Wall -I ../include cmd.c
gcc -c -g -Wall -I ../include assemble.c
gcc -c -g -Wall -I ../include token.c
gcc -c -g -Wall -I ../include label.c
gcc -c -g -Wall -I ../include macro.c
gcc -c -g -Wall -I ../include exec.c
gcc -c -g -Wall -I ../include dump.c
gcc -g -Wall -I ../include -o ../casl2 casl2.o word.o hash.o cerr.o st
ruct.o cmd.o assemble.o token.o label.o macro.o exec.o dump.o
gcc -c -g -Wall -I ../include comet2.c
gcc -g -Wall -I ../include -o ../comet2 comet2.o word.o hash.o cerr.o
struct.o cmd.o exec.o dump.o
gcc -c -g -Wall -I ../include dumpword.c
gcc -g -Wall -I ../include -o ../dumpword dumpword.o word.o cerr.o
make[1]: Leaving directory ‘/home/kazubito/yacasl2/src’
@end example
@end cartouche

@section @command{casl2}の実行テスト

ビルドしたら、次のコマンドが正常に実行できるかを確認します。
正常に実行された場合は、「Hello, World!」と表示されます。

@cartouche
@example
$ @b{./casl2 as/hello.casl}
Hello, World!
@end example
@end cartouche

@section 詳細なテスト

次のコマンドを実行すると、正常にビルドできているかどうかを詳細にテストできます。

@cartouche
@example
$ @b{make check}
194 / 194 tests passed. Details in /home/kazubito/yacasl2/test/integra
tion/casl2/Test.log
All tests are succeded.
149 / 149 tests passed. Details in /home/kazubito/yacasl2/test/integra
tion/comet2/Test.log
All tests are succeded.
4 / 4 tests passed. Details in /home/kazubito/yacasl2/test/integration
/dumpword/Test.log
All tests are succeded.
@end example
@end cartouche

@section 環境設定@var{PATH}の設定

環境変数@var{PATH}にYACASL2のディレクトリーを追加すると、どのディレクトリーでも@command{casl2}、@command{comet2}、@command{dumpword}を実行できます。

環境変数の設定方法は使っているシェルによって異なります。シェルは、次のコマンドで確認できます。現在もっとも多く使われているのは、BASHでしょう。

@cartouche
@example
$ @b{echo $SHELL}
/bin/bash
@end example
@end cartouche

シェルがBASHの場合、次のコマンドを実行すると環境変数@var{PATH}にYACASL2のディレクトリーが追加されます。

@cartouche
@example
$ @b{PATH=$PATH:~/yacasl2 && export PATH}
@end example
@end cartouche

シェルの初期設定ファイルに上記のコマンドを追加すれば、今後ログインした後は自動的にどのディレクトリーでも @command{casl2}、@command{comet2}、@command{dumpword}を実行できるようになります。BASHの場合はホームディレクトリーにある@file{.bashrc}が初期設定ファイルのため、コマンドは次のようになります。

@cartouche
@example
$ @b{echo ’PATH=$PATH:~/yacasl2 && export PATH’ >>~/.bashrc}
@end example
@end cartouche

@node tutorial,, install, Top
@chapter YACASL2 の使い方

YACASL2 は、テキストファイルに記述されたCASLプログラムを処理します。以下の例で用いられるCASLプログラムのファイルは、テキストエディタなどで作成してください。また、インストールしたディレクトリーの中にある@file{as}ディレクトリーからコピーして作成することもできます。

@section 実行結果の出力だけを表示

インストール時にコマンド実行の確認に使った@file{hello.casl}は、次のような内容です。CASL IIのマクロ命令OUTは、文字列を出力します。

@cartouche
@example
$ @b{cat hello.casl}
MAIN     START
         OUT     OBUF,LEN
         RET
OBUF     DC      ’Hello, World!’
LEN      DC      13
         END
@end example
@end cartouche

次のコマンドを実行すると、CASL II のアセンブルと仮想マシン COMET II 上での実行が連続で行われ、文字列が出力されます。

@cartouche
@example
$ @b{casl2 hello.casl}
Hello, World!
@end example
@end cartouche

@file{addl.casl}は、3と1の和を求めます。

@cartouche
@example
$ @b{cat addl.casl}
;;; ADDL r,adr
MAIN     START
         LD      GR1,A
         ADDL    GR1,B
         RET
A        DC      3
B        DC      1
         END
@end example
@end cartouche

このプログラムには出力命令がないため、オプションなしで実行した場合には結果が出力されません。

@cartouche
@example
$ @b{casl2 addl.casl}
$
@end example
@end cartouche

実行内容を確認するには、後述のようにCPU 内にあるレジスターやメモリーの内容を表示するか、結果を出力するための処理を追加する必要があります。

@file{sum_10.casl}は、1から10までの整数の和を求めます。

@cartouche
@example
$ @b{cat sum_10.casl}
;;; sum_10.casl
;;; 出力 GR0: 1から10までの整数をすべて加算した値
MAIN    START
        PUSH    0,GR1
        LAD     GR0,0           ; GR0を初期化
        LD      GR1,FST         ; GR1に初項を転送
LOOP    ADDL    GR0,GR1         ; ループ先頭
        ADDL    GR1,STEP        ; GR1 <- GR1 + 公差
        CPL     GR1,LST         ; GR1が末項より大きい場合は終了
        JPL     FIN             ; ↓
        JUMP    LOOP            ; ループ終端
FIN     POP     GR1
        RET
FST     DC      1               ; 初項
LST     DC      10              ; 末項
STEP    DC      1               ; 公差
        END
@end example
@end cartouche

このプログラムも、オプションなしで実行した場合には結果が出力されません。
@cartouche
@example
$ @b{casl2 sum_10.casl}
$
@end example
@end cartouche

@section アセンブル結果の確認
casl2の処理途中で行われるアセンブルの結果を表示するには、オプション@option{-a}を指定します。また、ラベルとアドレスの対応表を表示するには、オプション@option{-l}を指定します。

次のコマンドでは@file{hello.casl}の、ラベルとアドレスの対応表と、アセンブル結果と、実行結果が表示されます。OUTはアセンブラ命令で複数の機械語命令で構成されているため、命令行1行に対して、複数行のコードが生成されます。

@cartouche
@example
$ @b{casl2 -a -l hello.casl}

Assemble hello.casl (0)

Label::::
MAIN.LEN ---> #0020
MAIN ---> #0000
MAIN.OBUF ---> #0013

Assemble hello.casl (1)
hello.casl:    1:MAIN    START
hello.casl:    2:        OUT     OBUF,LEN
    #0000   #7001
    #0001   #0000
    #0002   #7002
    #0003   #0000
    #0004   #1210
    #0005   #0013
    #0006   #1220
    #0007   #0020
    #0008   #F000
    #0009   #0002
    #000A   #1210
    #000B   #0021
    #0021   #000A
    #000C   #1220
    #000D   #0022
    #0022   #0001
    #000E   #F000
    #000F   #0002
    #0010   #7120
    #0011   #7110
hello.casl:    3:        RET
    #0012   #8100
hello.casl:    4:OBUF    DC      'Hello, World!'
    #0013   #0048
    #0014   #0065
    #0015   #006C
    #0016   #006C
    #0017   #006F
    #0018   #002C
    #0019   #0020
    #001A   #0057
    #001B   #006F
    #001C   #0072
    #001D   #006C
    #001E   #0064
    #001F   #0021
hello.casl:    5:LEN     DC      13
    #0020   #000D
hello.casl:    6:        END
Hello, World!
@end example
@end cartouche

@file{addl.casl}の、ラベルとアドレスの対応表と、アセンブル結果は、次のようになります。

@cartouche
@example
$ @b{casl2 -a -l addl.casl}

Assemble addl.casl (0)

Label::::
MAIN.A ---> #0005
MAIN.B ---> #0006
MAIN ---> #0000

Assemble addl.casl (1)
addl.casl:    1:;;; ADDL r,adr
addl.casl:    2:MAIN    START
addl.casl:    3:        LD      GR1,A
    #0000   #1010
    #0001   #0005
addl.casl:    4:        ADDL    GR1,B
    #0002   #2210
    #0003   #0006
addl.casl:    5:        RET
    #0004   #8100
addl.casl:    6:A       DC      3
    #0005   #0003
addl.casl:    7:B       DC      1
    #0006   #0001
addl.casl:    8:        END
@end example
@end cartouche

なお、オプション@option{-A}を指定すると、アセンブル結果が表示される時点で処理が終了します。仮想マシンCOMET II での実行は行われません。

@section 実行時のレジスターとメモリーを表示
YACASL2では実行中のCPUのレジスターとメモリーの内容をそれぞれ、@option{-t}と@option{-d}を指定することで表示できます。

また、@option{-M}で、仮想マシンCOMET II のメモリー容量を語(16 ビット)単位で指定できます。小さいプログラムを実行するときは、メモリー容量を小さくすれば結果が見やすくなります。

@file{addl.casl}に必要なメモリー容量は8語のため、次のようにCPUのレジスターとメモリーの内容を表示できます。

@cartouche
@example
$ @b{casl2 -t -d -M8 addl.casl | less}

Assemble addl.casl (0)

Assemble addl.casl (1)

Executing machine codes
#0000: Register::::
#0000: GR0:      0 = #0000 = 0000000000000000
#0000: GR1:      0 = #0000 = 0000000000000000
#0000: GR2:      0 = #0000 = 0000000000000000
#0000: GR3:      0 = #0000 = 0000000000000000
#0000: GR4:      0 = #0000 = 0000000000000000
#0000: GR5:      0 = #0000 = 0000000000000000
#0000: GR6:      0 = #0000 = 0000000000000000
#0000: GR7:      0 = #0000 = 0000000000000000
#0000: SP:       8 = #0008 = 0000000000001000
#0000: PR:       0 = #0000 = 0000000000000000
#0000: FR (OF SF ZF): 000
#0000: Memory::::
#0000: adr : 0000 0001 0002 0003 0004 0005 0006 0007
#0000: 0000: 1010 0005 2210 0006 8100 0003 0001 0000 
#0002: Register::::
#0002: GR0:      0 = #0000 = 0000000000000000
#0002: GR1:      3 = #0003 = 0000000000000011
#0002: GR2:      0 = #0000 = 0000000000000000
#0002: GR3:      0 = #0000 = 0000000000000000
#0002: GR4:      0 = #0000 = 0000000000000000
#0002: GR5:      0 = #0000 = 0000000000000000
#0002: GR6:      0 = #0000 = 0000000000000000
#0002: GR7:      0 = #0000 = 0000000000000000
#0002: SP:       8 = #0008 = 0000000000001000
#0002: PR:       2 = #0002 = 0000000000000010
#0002: FR (OF SF ZF): 000
#0002: Memory::::
#0002: adr : 0000 0001 0002 0003 0004 0005 0006 0007
#0002: 0000: 1010 0005 2210 0006 8100 0003 0001 0000 
#0004: Register::::
#0004: GR0:      0 = #0000 = 0000000000000000
#0004: GR1:      4 = #0004 = 0000000000000100
#0004: GR2:      0 = #0000 = 0000000000000000
#0004: GR3:      0 = #0000 = 0000000000000000
#0004: GR4:      0 = #0000 = 0000000000000000
#0004: GR5:      0 = #0000 = 0000000000000000
#0004: GR6:      0 = #0000 = 0000000000000000
#0004: GR7:      0 = #0000 = 0000000000000000
#0004: SP:       8 = #0008 = 0000000000001000
#0004: PR:       4 = #0004 = 0000000000000100
#0004: FR (OF SF ZF): 000
#0004: Memory::::
#0004: adr : 0000 0001 0002 0003 0004 0005 0006 0007
#0004: 0000: 1010 0005 2210 0006 8100 0003 0001 0000 
@end example
@end cartouche

@subsection 特定のレジスターを表示

@file{addl.casl}のレジスターやメモリーの中で、実行中に値が変化しているのはGR1だけです。こうした場合は、@command{grep}を使って表示される内容を絞り込むことで動作を検証しやすくなります。

@cartouche
@example
$ @b{casl2 -t addl.casl | grep 'GR1:'}
#0000: GR1:      0 = #0000 = 0000000000000000
#0002: GR1:      3 = #0003 = 0000000000000011
#0004: GR1:      4 = #0004 = 0000000000000100
@end example
@end cartouche

この内容を、先に出力したアセンブル結果と引き比べてください。
次の表のように、PRとGR1、命令行が対応していることがわかります。

@multitable @columnfractions .3 .3 .4
@item PR @tab GR1 @tab 命令行
@item #0000
@tab #0000
@item #0002
@tab #0003
@tab @code{LD GR1,A}
@item #0004
@tab #0004
@tab @code{ADDL GR1,B}
@end multitable

@subsection プログラム終了時の値を表示

@command{grep}と@command{tail}を組み合わせれば、プログラム終了時の値を表示できます。

@cartouche
@example
$ @b{casl2 -t addl.casl | grep 'GR1:' | tail -1}
#0004: GR1:      4 = #0004 = 0000000000000100
@end example
@end cartouche

@cartouche
@example
$ @b{casl2 -t sum_10.casl | grep 'GR0:' | tail -1}
#0010: GR0:     55 = #0037 = 0000000000110111 = '7'
@end example
@end cartouche

@subsection プログラムのステップ数を表示

@command{grep}と@command{wc}を組み合わせれば、プログラムのステップ数を表示できます。

@cartouche
@example
$ @b{casl2 -t hello.casl | grep 'GR1:' | wc -l}
11
@end example
@end cartouche

@cartouche
@example
$ @b{casl2 -t addl.casl | grep 'GR1:' | wc -l}
3
@end example
@end cartouche

@file{sum_10.casl}はプログラム内にループがあるため、ステップ数が大きくなります。

@cartouche
@example
$ @b{casl2 -t sum_10.casl | grep 'GR0:' | wc -l}
54
@end example
@end cartouche

@section アセンブルと実行を別に行う

@command{casl2}に@option{-O}<@file{ファイル名}>を指定すると、オブジェクトファイルを作成できます。

@cartouche
@example
$ @b{casl2 -Ohello.o hello.casl}
@end example
@end cartouche

作成されたオブジェクトファイルの内容は、@command{od}を使って確認できます。テキストファイルではないため、@command{cat}などでは確認できません。

@cartouche
@example
$ @b{od -t x2 hello.o}
0000000 7001 0000 7002 0000 1210 0013 1220 0020
0000020 f000 0002 1210 0021 1220 0022 f000 0002
0000040 7120 7110 8100 0048 0065 006c 006c 006f
0000060 002c 0020 0057 006f 0072 006c 0064 0021
0000100 000d 000a 0001
0000106
@end example
@end cartouche

オブジェクトファイルの実行には、@command{comet2}を使います。

@cartouche
@example
$ @b{comet2 hello.o}
Hello, World!
@end example
@end cartouche

@section 1語を解析する

CASL2では、1語（16ビット）を単位としてデータが処理されます。
@command{dumpword}は、指定した1語を10進数、16進数、2進数で表示します。

@cartouche
@example
$ @b{dumpword 72}
    72:     72 = #0048 = 0000000001001000 = 'H'
@end example
@end cartouche

マイナスの数は、次のように指定します。

@cartouche
@example
$ @b{dumpword -- -72}
   -72:    -72 = #FFB8 = 1111111110111000
@end example
@end cartouche

16進数で指定する場合は、次のように指定します。

@cartouche
@example
$ @b{dumpword '#0048'}
 #0048:     72 = #0048 = 0000000001001000 = 'H'
@end example
@end cartouche
@bye