1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claudeが清書したaxx general assemblerテクニカルマニュアル

1
Last updated at Posted at 2026-10-06

axx — 汎用アセンブラ

axx (Arbitrary eXtended X assembler) は汎用アセンブラです。アセンブラ自体は
いかなる命令セットの知識も持ちません。プロセッサ固有の知識はすべて、外部の宣言的な
パターンファイルに置かれます。あるプロセッサ用のパターンファイルを書けば、そのプロセッサ
用のアセンブラが手に入ります。

クイックスタート

git clone https://github.com/fygar256/axx.git
cd axx
make                            # caxx, paxx, axx をこのディレクトリにビルド
make faxx                       # 任意: faxx をビルド(ccforth が要る。下を参照)
sudo make install               # 任意: caxx・paxx・faxx を /usr/local/bin に、man ページを
                                # /usr/share/man/man1 に入れる

make all は caxx・paxx・axx・faxx をまとめて作ります。make install は faxx も
入れるので、先に make faxx を済ませるか、その行を外してください。C 実装だけを
ビルドする場合:

gcc caxx.c -o caxx -lm -lquadmath -O2   # -lm は式評価器が、-lquadmath は
                                        # 128 ビット浮動小数点の変換
                                        # (strtoflt128) が使う

Forth 実装は、ビルドせずにリポジトリの最上位から gforth で動かすか、
build_ccforth.sh(make faxx が呼ぶもの)で実行ファイル faxx にします:

gforth faxx.fs patfile/z80.axx asmsrc/z80.s -b out.bin
./build_ccforth.sh              # ./faxx を作る。ccforth と C コンパイラが要る

build_ccforth.sh は引数に出力ファイル名(既定 faxx)を取り、環境変数 CCFORTH
(使う ccforth)・CC・CFLAGS・MEMSIZE(Forth のメモリのバイト数、既定 64MB)・
KEEPC(生成した C をその名前で残す)を読みます。ccforth は
https://github.com/ncw/ccforth にあります。

アセンブル:

./axx patfile/z80.axx asmsrc/z80.s -v            # リスティングを標準出力へ
./axx patfile/z80.axx asmsrc/z80.s -b out.bin    # 生バイナリ
./axx patfile/x86_64.axx asmsrc/hello.s -o out.o # ELF 再配置可能オブジェクト
./axx patfile/8080toz80.axx asmsrc/hello8080.s -V > out.s  # 翻訳したテキストを標準出力へ

axx は axx.py の写し(Python 版)で、make がこのディレクトリに作ります。
make install は axx を入れないので、インストールしたものを使うときは paxx
(Python 版)・caxx(C 版)・faxx(Forth 版)のどれかを打ちます。以降の例の axx は、これらのどれと
読み替えても同じです。

リポジトリではパターンファイルが patfile/、アセンブリソースが asmsrc/ に入って
います。以降の例では読みやすさのためファイル名だけを書きますが、クローンしたままの
配置で動かすときは上のようにディレクトリを付けてください。

3 つの実装

言語 ファイル 愛称 役割
Python axx.py Paxx リファレンス実装。新機能はまずここに入る
C caxx.c Caxx はるかに高速(x86_64 の hello world が約 0.1 秒。Paxx は数秒)
Forth faxx.fs, faxxsrc/ Faxx axx.py をもとに書いた実装。gforth で動き、ccforth で実行ファイルにもなる(同じ hello world が約 0.2 秒)

3 つは同じ入力に対してバイト単位で同一の出力を生成することを意図しています。
同梱のパターンファイル、テストソース、test1 スクリプトは、Paxx と Caxx について
まさにそれを検証するために存在します。test1 は同梱の 114 組のパターン/ソースの対を
両方でアセンブルし(片側 220 回の実行)、結果を cmp します。-b のイメージのほか、
-V の翻訳テキスト(.textmode の組、exprmiss.axx、regress.axx)、標準エラーへ
出た .echo の行(echo.axx、ministr.axx)、_err.s と回帰テストの診断、
リロケーションのテストの ELF オブジェクト、--elfdesc の出力も比べます。中核の 16 組は
-o・-m 3 -f 32 -o・-g -o・-v・-V でも走らせるので、ELF32/ELF64 の
オブジェクト、DWARF、リスティング、テキスト出力の経路も比較されます(全 256 組)。
一覧は付録 B にあります。

Faxx は test1 では走りません。この文書で「両方の実装」と書くときは、test1 が
確かめる Paxx と Caxx のことです。Faxx は axx.py をもとに書かれているので同じ規則に
従い、違う点は 2.4 節にまとめてあります。

目次

  1. 適用範囲: axx にできること・できないこと
  2. コマンドライン
  3. パターンファイルリファレンス
  4. VLIW と EPIC プロセッサ
  5. アセンブリソースリファレンス
  6. 式と演算子
  7. マクロ層
  8. オブジェクト出力、エクスポートとインポート
  9. エラー
  10. 設計ノートと背景

付録: A. 例 ·
B. 同梱パターンファイル ·
C. 関連資料 ·
D. ロードマップ ·
E. プロジェクトノート


1. 適用範囲: axx にできること・できないこと

この節を最初に読んでください。以降の文書は、境界がどこにあるかを知っていることを前提と
しています。

1.1 モデル

パターンファイル内のすべてのパターンは、次の形をしています:

instruction :: error_patterns :: binary_list
  • instruction — アセンブリ行と照合する構文。必須。
  • error_patterns — その行をエラーとする条件。省略可。
  • binary_list — 出力するバイト列。必須。

例 (x86_64):

RET :: 0xc3

これがモデルのすべてです。axx の主張は 2 本の独立した脚に支えられており、それぞれ
射程が異なります。

1.2 第 1 の脚: 命令構文 — 非常に広い

instruction は次の任意の組み合わせです:

  • 文字列リテラル(大文字、数字、記号)、
  • 整数値で置換可能なシンボル、
  • 整数式、
  • 整数因子、
  • 浮動小数点式。

これは実質的にあらゆる手続き型アセンブリ言語の表層構文を表現するのに十分であり、
従来のニーモニック+オペランド形式に限定されません。r1 = r2 + r3 は正当な命令
パターンであり、これにより axx はアセンブラとしてだけでなく汎用バイナリジェネレータ
としても使えます。

1.3 第 2 の脚: バイナリ生成 — 意図的に狭い

binary_list が持つ制御構造は 5 つだけです。代入、三項演算子、; 修飾子、
アラインメント、@@[] です。これは万能エンコーダではありません。実用上の条件は
次のとおりです:

axx は、命令が機械語に一対一で対応するプロセッサをアセンブルできる。

ここから 2 つの帰結が導かれますが、どちらも見落としではなく設計上の決定です:

パターン記法自体がチューリング不完全です。 これによりパターンマッチングの停止性
が保証されます。無制限の計算を必要とするエンコーディングは binary_list 単独では
書けません。

無制限の計算は利用可能ですが、明示的に要求した場合に限られます。 binary_list の
要素は .call name(...) にでき、これは 3.15 節の
ミニ言語で書かれた関数を実行します。ループ、再帰、条件分岐、配列を備えており、
したがってチューリング完全です。マッチングは依然として停止し、エンコーディング段階
だけが固定上限なしに計算できますが、それも 3.15 節のステップ数・深さ・出力の上限に
よって実用上は制限されます。(7 節のマクロ層はこれとは別の、より早い段階であり、
同様に制限されていません。)

現実のアーキテクチャの中にはモデルの外にあるものもあります。 構文が書き下せない
からではなく、そのエンコーディングを binary_list で生成できないからです:

プロセッサ 適用範囲外である理由
Mill CPU ベルトアーキテクチャ: オペランド参照が実行履歴に依存する
ZISC そもそも命令が存在しない
Thinking Machines 超並列。命令ごとのエンコーディングという対象がない

量子コンピュータと LISP マシンも適用範囲外です。それらが実行するのは手続き型
アセンブリ言語ではありません。

EPIC および VLIW マシンは機械語にメタレベルの構造を持ち、基本モデルではカバーできま
せんが、後の拡張で扱われます — 4 節を参照。

ここでいう「一対一の対応」を、ISA の性質として一般的に言い直したものが
1.7 節の
「有限静的変換」です。

1.4 他のツールとの位置関係

axx は LLVM、CGen、customasm よりも低い抽象度で動作します。すぐに広く使えると
いう意味での「汎用アセンブラ (general-purpose assembler)」ではなく、すべてのター
ゲットの下に 1 つの共通機構を持つという意味での「汎用アセンブラ (general assembler)」
です。

特定チップ向けの手書きアセンブラが行う最適化は行いませんし、構造化アセンブリや関数型
アセンブリの構成要素を手続き型に落とすこともしません。ただし完全なマクロ層は備えて
います(7 節)。

パターンファイルとソースファイルが分離しているため、パターンファイルを差し替えるだけ
で同じソースを別のプロセッサ向けにアセンブルでき、共通のソース言語で複数のプロセッサ
をターゲットにできます。それが有用かどうかは、パターンファイルにどれだけ労力を
かけるかに完全に依存します。

1.5 パターンファイル記述に関する実践的な注意

大きな ISA 用のパターンファイルを書くのは長い作業ですが、完成すれば恒久的に使え、
再利用できます。フォーマットは宣言的かつ機械的なので、AI による生成の対象として
妥当です。小さな ISA であれば、モデルにパターンファイルを生成させて短時間で動作
するアセンブラを得られます。

あるパターンの表現が難しいと分かった場合、次の回避策が常に使えます: 本当に評価が
必要なオペランドだけを渡し、残りは文字列リテラルとして書くことです。構造化に馴染ま
ない ISA の一部は、単に列挙してしまえばよいのです。

実行プラットフォームは重要ではありません。DOS 行末の chr(13) は無視されますし、
Paxx は Python 3 が、Faxx は gforth が動く場所ならどこでも動きます。

1.6 実装上の制約

1.3 節はモデルとしての適用範囲を述べました。この節は、実装(axx.py と caxx.c。
faxxsrc/ も、2.4 節に書いた式の入れ子の深さを除いて同じ)のコードが課している
具体的な上限をまとめます。通常のノイマン型プロセッサであれば、
これらに触れることはほとんどありません。

アセンブルできないもの

対象 理由(実装上の根拠)
最小アドレス単位が 64 ビットを超えるマシン .bits のワード幅は 1〜64 に制限されています(Paxx の bits()、Caxx の .bits 処理とも 1..64)。命令は複数ワードにまたがれるので命令長の制約ではなく、メモリの最小アドレス単位の制約です
2 進以外のマシン(3 進の Setun など) 出力は各ワードを (1 << bts) - 1 でマスクした 2 進整数として書き出されます(_store() / flush())。トリットなど 2 進以外の値を表す仕組みはありません。BCD のように 2 進でコード化された 10 進マシンは問題なく扱えます
実行履歴によってエンコーディングが変わるマシン(Mill CPU など) パターン照合は 1 行ごとに静的にバイナリを決めます。実行時の状態に依存するオペランド参照は原理的に表せません

細かな制約

  • 1 つのパターンの省略可能部分 [[ ]] は 20 個まで、試す組み合わせは 1 行につき
    65,536 通りまでです(Paxx の _MAX_OPT_GROUPS と _MAX_COMBINATIONS、Caxx の
    MAX_OPT_GROUPS と MAX_COMBINATIONS)。超えたときの振る舞いは 3.8 節にあります。
  • .vliw の NOP 値は 64 ビットに切り詰められます(Paxx は & 0xFFFFFFFFFFFFFFFF、
    Caxx は uint64_t で受け取ります)。命令スロットが 64 ビットより広い場合、上位は 0 で
    埋まるので、64 ビットを超える非ゼロの NOP エンコーディングは .vliw の指定だけでは
    表せません。
  • 式評価とミニ言語の整数は 256 ビットで回り込みます(_MINI_BITS = 256、Caxx は
    uint256_t)。出力は複数ワードに分けられるので、実用上の支障はほとんどありません。
  • 式の入れ子(括弧・単項 - ~ @・三項演算子 ?:)は 500 段までです(Paxx の
    _EXPR_MAX_DEPTH、Caxx の EXPR_MAX_DEPTH)。超えると
    expression nesting too deep. を報告し、その部分を 0 として読みます。
  • 浮動小数点の変換(enfloat())は IEEE 754 形式(半精度〜4 倍精度)のみです。IBM の
    16 進浮動小数点や VAX 形式のデータは組み込みでは出力できません。これは命令ではなく
    データ定義の制約です。

1.7 一般性の命題: 有限静的変換で書ける ISA ならどのプロセッサでも

1.3 節の「命令が機械語に一対一で対応する」という条件は、次のように一般的な形で
言い表せます。

命題. 命令型アセンブリ言語を持ち、そのアセンブリから機械語への写像が
有限静的変換である ISA — これを generic processor ISA(汎用プロセッサ
ISA)と呼びます — であれば、axx はそれがどのプロセッサのアセンブリであっても
処理できます。その ISA を記述したパターンファイルを書けば、そのプロセッサの
アセンブラが得られます。

1.7.1 定義

命令型アセンブリ言語とは、ソースが行(命令・ディレクティブ・ラベル)の列であり、
各命令行がそれぞれ機械語の断片を表す言語です。ニーモニック+オペランドの形である
必要はなく、r1 = r2 + r3 のような代入形式でも構いません(1.2 節)。

アセンブリから機械語への写像が有限静的変換であるとは、次の 2 つを満たすことです。

静的 — 各命令行の符号化が、アセンブル時に分かる情報だけで決まること:

  • その行の文字列(と、そこから捕捉した値・綴り)、
  • パターンファイルの宣言(シンボル、集合、.check、.map、.sub など)、
  • ラベル・.equ の値と位置カウンタ $ / $$。

プログラムを実行したときの状態(レジスタの中身、実行履歴、それまでに実行した命令の
並び)には依存しません。

有限 — 次の 3 つがどれも有限であること:

  1. 命令形式の数。 命令の書き方の種類が有限個の形式で書き尽くせること。オペランドの
    値が無限に多くても、形式が有限であればよい(値は捕捉子 !・!!・!F などが受け
    持ちます)。形式の数が多いときは、マクロ層(7 節)や集合・サブテーブルで生成できます。
  2. 出力の長さ。 1 つの命令行が出すワード列が有限であること。各ワードは 2 進の
    1〜64 ビット幅です(.bits、1.6 節)。命令は複数ワードにまたがれるので、命令長
    そのものに上限はありません。
  3. 符号化の計算。 捕捉した値・ラベル値・位置カウンタからワード列を求める計算が、
    有限の手順で終わること(つまり計算可能な関数であること)。

VLIW・EPIC のように複数の命令を束ねるものも、束(バンドル)を単位として同じ条件を
満たせば generic processor ISA に入ります(4 節)。

1.7.2 なぜ処理できるのか — 実装との対応

この定義の各項目は、axx の仕組みにそのまま対応しています。

有限静的変換の条件 それを受け持つ axx の仕組み
命令形式が有限個 1 形式を 1 パターン行 instruction :: error_patterns :: binary_list で書く。文字単位の照合なので、構文の切り方はパターン側が決める(3.3 節)
同じ行に複数の形式が当たりうる 当たったパターンすべてに特異度スコア (n_expr, -n_lit, n_sym) を付け、最小のものを選ぶ。書く順序に依存しない(3.2 節)
オペランドの値の範囲・制約 error_patterns の条件式、.check・.map・集合によるレジスタクラスの制約(3.4 節、3.7 節)
式で書ける符号化 binary_list の式(ビット演算、@、'、*(x,y) など。6 節)
式では書きにくい符号化 .call で呼ぶミニ言語。ループ・再帰・配列を備えたチューリング完全な言語なので、計算可能な符号化はここで書ける(3.15 節)
ラベルの値に依存する符号化 Pass 1 の relaxation が、全ラベルの番地が前回と一致するまで反復して決める(可変長命令の前方参照を含む)
出力がワード列 .bits で 1〜64 ビットのワード幅を指定。-b で生バイナリ、-o で ELF(3.7.7 節)

実装では、Paxx の Assembler.lineassemble2()(Caxx は lineassemble2_impl())が 1 行に
対して候補のパターンをすべて照合し、最良のパターンの error_patterns を評価してから
binary_list をワード列にします。これは、1 行を「その行の文字列と宣言とラベル環境」
から「有限のワード列」へ写す関数そのものであり、有限静的変換の定義と同じ形をしています。
ラベルへの依存は Assembler.run() の relaxation ループが反復して解き、配置が前回と
一致した時点で収束とします。

したがって、generic processor ISA であれば、

  1. 命令形式を 1 つずつパターン行に書き写し、
  2. 範囲や制約を error_patterns と .check などで書き、
  3. 符号化を式で、必要ならミニ言語の関数で書く

ことで、そのプロセッサのアセンブラが得られます。この手順は ISA の種類に依存しません。
4004 のような 4 ビット機から x86_64(AVX-512 まで)、AArch64(SVE/SME2 まで)、
Power ISA v3.1、RISC-V RV64 全体、MIPS、SPARC、そして Itanium 型 EPIC までが同梱の
パターンファイル(付録 B)で実際に動いていることは、この命題の具体例です。

同じことは、出力をテキストにした場合にも成り立ちます。あるアセンブリ言語から別の
アセンブリ言語への書き換えが有限静的変換であれば、binary_list に文字列テンプレートを
書き .textmode を宣言することで、その翻訳器が得られます(3.18 節)。

この命題を意味関数の言葉で書き、パターンファイルの構成手順を示したものが
axxsemantics.md の 14.1 節にあります。

1.7.3 適用の目安

定義に当てはまるかどうかは、次の問いで確かめられます。

  • 命令の書き方を、有限個の形式の表として書き出せるか。
  • 各命令の機械語を、その命令の文字列とラベルの値だけから決められるか。
  • 符号化の手順を、有限で終わるアルゴリズムとして書けるか。
  • 出力を 64 ビット以下の 2 進ワードの列として表せるか。

すべてに「はい」と答えられれば、その ISA は generic processor ISA であり、axx で扱えます。
1.3 節と 1.6 節の表に挙げたマシン(Mill CPU、ZISC、Thinking Machines、3 進の Setun
など)は、この問いのいずれかが当てはまらないものとして整理できます。たとえば Mill CPU
はオペランドの参照が実行履歴で決まるので「静的」に当たらず、Setun は出力が 2 進ワード
ではありません。量子コンピュータと LISP マシンは、命令型アセンブリ言語という前提の外に
あります。

実用上の上限としては、ミニ言語の 1 回の .call あたり実行文 4,000,000、呼び出しの
入れ子 128 段、出力 1,048,576 ワード、配列長 1,048,576 があります(3.15 節)。通常の
命令の符号化はこれよりはるかに小さな計算で済みます。


2. コマンドライン

2.1 書式

axx [-h] [--osabi ELF_OSABI] [-b OUTFILE] [-e EXPORT_TSV]
    [-E EXPORT_ELF_TSV] [-i IMPORT_TSV] [-o OBJ_FILE] [-f {32,64}]
    [-m MACHINE] [-v] [-V] [-d] [-g] [--no-macro] [-P [FILE]] [-p [FILE]]
    [--elfdesc] patternfile [sourcefile]
引数 意味
patternfile パターン定義ファイル (.axx)。必須。
sourcefile アセンブリソース (.s)。省略すると標準入力から読む(プロンプトモード)。名前を stdin と書くと、標準入力をソースファイルとして全部読んでから組む(改行・UTF-8 でないバイトの扱いと .include の基準のディレクトリはファイルと同じで、基準は作業ディレクトリ)。
オプション 意味
-b OUTFILE 生バイナリを書き出す
-o OBJ_FILE ELF 再配置可能オブジェクトを書き出す。クラスは -f で選択
-f {32,64} -o の ELF クラス。既定はパターンの .elfclass、無ければそのマシンの慣習クラス(3.7.7 節)
-m MACHINE ELF の e_machine 値。既定はパターンの .elfmachine、無ければ 62 (EM_X86_64)。組み込みの表に無い番号も書けます(3.7.7 節)
--osabi ELF_OSABI ELF OSABI。既定値 Linux。FreeBSD/Linux、大文字小文字を区別しない
-e EXPORT_TSV ラベルを TSV にエクスポート(プレーン形式)
-E EXPORT_ELF_TSV ラベルを TSV にエクスポート(ELF セクションフラグ付き)
-i IMPORT_TSV TSV からラベルをインポート
-v, --verbose アセンブルリスティングを標準出力へ出力(既定: 無出力)
-V, --text-output テキストテンプレート(3.5.2 節)で組み立てたテキストを素のまま標準出力へ出力(既定: 無出力)。.textmode(3.18 節)でソースを翻訳するときに使う。.textmode のときは -b と同じバイト列(.emit の分も含む)を書く
-d, --debug デバッグ出力: 前方参照フォールバック、リラクゼーションログ
-g, --gen-debug DWARF (.debug_info/.debug_abbrev/.debug_line) を出力。-o が必要(ELF32・ELF64 のどちらでも書ける)
--no-macro ソース側・パターン側の両方でマクロ層を無効にする
-P [FILE] ソースをマクロ展開し、アセンブルせずに書き出す
-p [FILE] パターンファイルをマクロ展開し、アセンブルせずに書き出す
--elfdesc いま有効な ELF マシン記述(組み込みの表+パターンファイルの宣言)を、パターンファイルの宣言の形で標準出力へ書き出し、アセンブルせずに終わる(3.7.9 節)
-h, --help 使い方

出力オプションを何も指定しない場合、何も書き出されません。実行結果を目に見えるよう
にするのが -v です。テキストテンプレートの翻訳結果だけを素のまま受け取りたいときは
-V を使います。

2.2 ELF 出力

-o は再配置可能オブジェクトを生成し、FreeBSD と Linux で動作します。x86_64 に
限定されません。-m は、axx が再配置番号を組み込みで持つ次のアーキテクチャを
受け付けます:

値 マシン 値 マシン
3 i386 43 SPARCV9
4 M68K 62 x86-64(既定)
20 PowerPC 183 AArch64
21 PowerPC64 243 RISC-V
22 s390x
40 ARM
42 SuperH

この表に無い e_machine の番号も -m に書けます。そのときリロケーション型・
ELF クラス・RELA/REL・ヘッダの欄は、パターンファイルの ELF 記述(3.7.7 節)から
来ます。宣言が無ければ、型の決まらない参照はリロケーションを出しません
(当てずっぽうの型番号を書かないためです)。-m を書かなければ、パターンの
.elfmachine が、それも無ければ 62(x86-64)が対象になります。

セクションの数に上限はありません。節番号が SHN_LORESERVE(0xff00)以上の
セクションがあるときは、ELF の決まりどおり e_shnum / e_shstrndx を 0 番目の
セクションヘッダに置き、シンボルの節番号を .symtab_shndx(SHT_SYMTAB_SHNDX)に
書きます。

上の表の中身も、パターンファイルの宣言で書けるものだけでできています。
ELF を書くコードには機種番号で分かれる処理がありません。表を使わずに記述を
すべてパターンファイルに書くこともできます(.elfbuiltin::0、3.7.9 節)。

-f は -m とは独立に ELF32 か ELF64 を選びます。書かなければパターンの
.elfclass、それも無ければそのマシンの慣習クラス(32 ビット機は ELF32、64 ビット
機は ELF64、表に無いマシンは ELF64)になります。選んだマシンにとって慣例的でない
組み合わせ(たとえば実際の x32 ABI レイアウトである -m 62 -f 32)も、警告付きで
受け入れられます。

2.3 C 版との差異

caxx は axx.py と同じオプション名を取りますが、次の点が異なります:

  • -d / --debug の出力のうち、照合や前方参照のフォールバックの途中で捕まえた Python の
    例外の中身とトレースバックは axx.py だけが出します(caxx には例外がありません)。
    リラクゼーションの収束、省いたリロケーションの知らせなど、ほかの行は両方が同じに出します。
  • -P の後のファイル名は省略可能なため、caxx はパターンファイルとソースファイルの
    両方が既に与えられている場合にのみ、次の引数を出力ファイルとして扱います:
    caxx pat.axx src.s -P out.s。-p も同じ規則に従います。
  • コマンドラインの誤り(未知のオプション、値の欠けや不正な値、余分な引数)は、
    どちらも終了コード 2 で止まりますが、文面と使い方の表示は違います。axx.py は
    Python の argparse の書式で、caxx は独自の書式です。-h のヘルプの文面も
    違います。
  • 診断の中に UTF-8 の非 ASCII 文字を書き出すとき、axx.py は Python の
    repr() と同じく印字できない文字(U+00A0 などの空白類)を \xa0 のように
    逃がし、caxx はバイトをそのまま書きます。診断が出る場所と数は同じです。
  • 内部で VLIW の区切りに使う文字が違います。caxx は 0xFE / 0xFF の 1 バイトを、
    axx.py は U+0092 / U+0093 を使うので、ソースにその文字(Latin-1 の þ ÿ、
    または C1 制御文字)を書くと、それぞれ別の所で区切りと取り違えます。UTF-8 の
    ソースに 0xFE / 0xFF のバイトは現れません。

2.4 Forth 版との差異

faxx(と gforth faxx.fs)は axx.py と同じ引数を取ります。2.3 節で C 版が
axx.py と違う点について、Faxx は次のとおりです:

  • -d / --debug: caxx と同じく、Python の例外やトレースバックは出ません。
    ほかの行は同じです。
  • コマンドラインの誤り: axx.py と同じく Python の argparse の書式で、終了コードは
    2 です。-h は axx.py のヘルプの文面を出します(いくつかの行の字下げが違います)。
  • 診断の中の UTF-8 の非 ASCII 文字: caxx と同じく、バイトをそのまま書きます。
  • VLIW の区切り: caxx と同じく 0xFE / 0xFF の 1 バイトです。
  • 1.6 節の式の入れ子の上限は、Faxx では 1,000 段です(faxxsrc/expr.fs の
    EXPR-MAX-DEPTH)。ほかの 2 つが expression nesting too deep. で断る 501〜1,000 段の
    単項 - の連なりも、Faxx は受け付けます。
  • ファイル名つきの -P / -p など、2.3 節のほかの規則で上に書いていないものは
    3 つとも同じです。

faxx.fs は部品を作業ディレクトリからの相対パス(faxxsrc/load.fs)で読むので、
gforth ではリポジトリの最上位から動かしてください。build_ccforth.sh で作った
実行ファイルにはこの制約はありません。gforth では x86_64 の hello world に数秒
(Paxx と同じくらい)、ccforth で作ったものは約 0.2 秒で、Caxx に近い速さです。

2.5 プロンプトモード

ソースファイルを指定しない場合、axx は >> プロンプトで端末からアセンブリ行を読み
ます。? はラベルテーブルを表示します。このモードではマクロ層はバイパスされます。


3. パターンファイルリファレンス

3.1 構造

パターンファイルはプロセッサ記述ファイルです。小さな ISA 記述言語 (ISADL) — アセンブリ
テキストと機械語の対応関係を記述するメタ言語です。

instruction :: error_patterns :: binary_list
instruction :: error_patterns :: binary_list
:

3 つのフィールドは :: で区切られます。error_patterns は空でも構いませんが、完全に
省略すると行には :: が 1 つだけになり、それが 2 フィールド形式です。

コメント。 /* がコメントを開始します。同じ行の後方に */ が現れた場合、
/* と */ の間のテキストだけが除去され、行の残りは通常どおり読まれます —
/* note */ MORE は MORE を残します。そうでなければコメントは本物のブロックコメント
のように振る舞い、*/ を含む行が見つかるまで後続の行へ続きます。終了行の */ より
後のテキストは再び通常どおり読まれます。

1 つの本物のブロックを開く代わりに、コメント行すべての先頭に /* を書く古いパターン
ファイルとの後方互換性のため、次のいずれかが成り立つときコメントは自分の行を超えて
延長しません:

  • すぐ次の行自体が /* で始まる、または
  • ファイル内のそれ以降どこにも */ が現れない。

どちらの場合も行は自分の /* の位置で切り詰められ、何も持ち越されません。これは元々の
単一行の振る舞いと一致します。そしてそのような行の連なり全体が同じように扱われます。
連なりの最終行の直後が通常の(コメントでない)内容であっても同様です。

要するに、すべてのブロックコメントを自分の */ で閉じることも、すべてのコメント行を
自分の /* で開くことも、どちらも完全にサポートされた記法であり、1 つのファイル内で
自由に混在させられます。

文字列の中。 "..." の中の /* はコメントを開かず、:: は欄を区切りません。
.setsym::msg::"a::b"、.error::3::"x /* y"、.call f("p::q")、ミニ言語の
u = "/* r */" などは、書いたとおりの文字列になります。" が文字列を開くのは、同じ行に
閉じる " があるときだけです。閉じない "、\"、文字定数 '"' はただの文字として
読むので、instruction 欄に書いた " で行の残りが文字列になってしまうことはありません。

行の継続。 改行の直前が \ の行は、その \ を除いて次の行とつながります(ソースと
同じ規則、5 章)。長い binary_list は途中で \ を置いて折り返せます。次の行の先頭の
空白もそのまま中身に入るので、式の途中で折るなら次の行は字下げせずに書きます。\ を
置かずに折った行は :: の無い行として警告されます。

3.2 パターンの順序は問わない

ディレクティブの定義は順序に依存します — 後の .setsym は前のものを上書きし、
.check は現れた位置から適用されます。パターンは順序に依存しません。
ディレクティブも順序に依存させたくないときは、パターンファイルに .unordered を
書きます(3.19 節)。

axx は最初にマッチしたパターンで止まりません。すべてのパターンを試し、マッチに成功した
ものそれぞれにスコアを付け、最良のものを出力します。スコアは次のタプルです:

(n_expr, -n_lit, n_sym)

ここで n_expr は ! 前置の式キャプチャの数、n_lit はマッチしたリテラル文字の数、
n_sym はシンボルキャプチャの数です。最小のタプルが勝ち、これは次のように読めます:

  1. 式キャプチャが最も少ないもの。
  2. 同点なら、リテラル文字のマッチが最も多いもの。
  3. 同点なら、シンボルキャプチャが最も少ないもの。

言い換えれば、どの順序に置かれていようと最も具体的なパターンが勝ちます。次が与えられ
たとき

MOV A,!d :: 0xAA,d
MOV A,B  :: 0xBB

mov a,b は 0xBB を、mov a,5 は 0xAA 0x05 を出力し、2 行を入れ替えても何も
変わりません。

これにより、テーブル駆動のアセンブラが通常要求する管理作業がなくなります — 特殊形が
一般形より前に来るように命令テーブルを手で並べ替える必要はありません。これが最も
効いてくるのは大きなパターンファイルで、特殊ケースがそれを上書きする一般規則から
遠く離れている場合です。

3.3 大文字小文字と変数

instruction フィールドでは:

書き方 意味
大文字、数字、記号、エスケープされた文字 文字定数。大文字はソース中の大文字・小文字両方にマッチする。
小文字の名前 その位置のシンボルの値
!x その位置の整数式の値
!!x その位置の整数因子の値
!Fx 32 ビット浮動小数点式の IEEE-754 ビットパターン
!Dx 64 ビット浮動小数点式の IEEE-754 ビットパターン
!Qx 128 ビット浮動小数点式の IEEE-754 ビットパターン
!Lx !x と同じく整数式の値。違うのは、テキスト置換モードでソースのどこにも定義のないラベルをエラーにしないことだけ(3.18 節)
!Ex .enum で宣言された列挙オペランドリストの値(3.7.1 節)
!Yx[z] 集合 x(3.6.2 節)の項目名を 1 つ読み、その番号を変数 z に束縛(3.6.3 節)
!S{{name}}x .sub で宣言されたサブテーブル name のマッチしたエントリの値(3.7.2 節)

!L に限らず、どの書き方で拾った変数も、値と一緒にソースに書かれていたままの綴りを
覚えます。その綴りは、テキストテンプレートの {{.exp(x)}}(3.18 節)と、ミニ言語の
.call の引数の .exp(x)(3.15 節)で、文字列として取り出せます。小文字変数なら当たった
シンボルの名前(b、cx)、!x なら読んだ式(1+2*3)、!E ならリスト全体
(a0-a2)が取り出せます。書き方ごとの綴りは 3.18 節「どの捕捉子でも綴りを覚える」の表に
あります。

キャプチャされた値は error_patterns と binary_list から名前そのもので参照します —
そこで ! 前置を繰り返すことはありません。すべての変数はパターン行ごとに 0 にリセット
されるので、マッチしなかった省略可能オペランドは 0 として読まれます。

式・因子が無ければ当たらない。 式を拾う !x・!Lx・!Fx・!Dx・!Qx と、因子を
拾う !!x は、その位置に式・因子が無ければマッチしません。空のとき(LD A,!n に対する
ld a,)だけでなく、式の中で因子が欠けているとき — 1+、-、~、()、( ) — も
同じです。値を 0 として読んで当ててしまうことはありません。当たらなかった行は、ほかの
パターンが当たればそちらになり、どれにも当たらなければ Syntax error(.passthru が
有効なら素通し、3.16 節)になります。オペランドを省けるようにしたいときは [[ ]]
(3.8 節)で囲みます。

LD A,!n :: 0x3e,n
ソース 結果
ld a,5 0x3e 0x05
ld a,(2) 0x3e 0x02
ld a, 当たらない
ld a,1+ 当たらない
ld a,() 当たらない

変数名。 上では変数を x と書いていますが、名前はより長くできます。小文字で始まり、
小文字・数字・_ が続くので、abcdef、var1、var_2 はすべて変数名です。同じ名前が
.check、.enum、.clrcheck、.clrenum、.map、.reloc、.clrreloc、
.free でも使われます。

.check::reg::BC,DE,HL,SP
INC reg,!imm_1 :: :: 0x03|reg,imm_1

長さは関係ありません。a も var_2 も同じ規則で読まれます。error_patterns と
binary_list では、小文字で始まる連続したテキストは変数です。その行がキャプチャした
かどうかは問いません — キャプチャされていない名前は 0 として読まれ、マッチしなかった
省略可能オペランドと同じです。事前に何も宣言する必要はありません。

したがって、そこに現れる小文字だけの単語は決してラベルではありません。連なりは小文字・
数字・_ でない最初の文字で終わり、続く文字がラベルに含まれうるもの(大文字または .)
であれば、その単語全体はやはりラベルになります — よって aB と a.b はラベルとして
読まれ、a1 と var_2 は変数です。パターン行が名指しする必要のあるラベルは、どこかに
大文字か . を含んでいなければなりません。

キャプチャの前後のアンダースコア。 _ は変数名を続ける文字なので、instruction の
中でキャプチャの直後に書いた _ は、文字として照合されずにその名前に飲み込まれます。
!a_X は変数 a_ と読まれ、5_X に当たりません。キャプチャの前でも、小文字の変数名の
直後なら同じで、r_!c は r_ という名前になります。区切りたいところに空白を入れて
!a _X、r _!c と書けば、名前はそこで終わり、_ は文字として照合されます。パターンの
空白はソースの 0 個以上の空白に当たるので、!a _X は 5_X にも 5 _X にも当たります。

LD !a _X :: :: 0x10,a          /* ld 5_X -> 0x10 0x05 */
DP r _!c :: :: 0x50,r,c        /* dp A_3 -> 0x50 0x01 0x03(r は .check の候補) */

\_ と書いて _ をエスケープしても同じく名前が終わります(3.12 節)。

MRS xt,S!S{{tbl}}a\_Z          /* mrs x0,s3_z に当たる */

2 つの式のキャプチャを _ で区切るときも同じです。!v_!w では _ が変数名 v_ に飲まれて
文字として照合されないので、3_5 に対して v_ が 3 を、!w が _5 というラベル(_ は
ラベルの先頭に書けます)を読んでしまいます。!v _!w または !v\_!w なら _ が文字として
照合され、3 と 5 に分かれます。なお、本体の式の数値リテラルは _ を桁の区切りとして受け付け
ません(3_5 は 1 つの数にはなりません。_ が使えるのは flt{} などの中身(5.4 節)、
ミニ言語の .int()、マクロ層の整数リテラルです)。どの種類のキャプチャ(記号のプレースホルダ、!x、!!x、
!S{{name}}x)でも同じです。キャプチャにも変数名にも続かない _ は区切らなくて構いません
(_!b、X_!c はそのまま当たります)。_ を含む .setsym の名前 — TPIDR_EL0 — も、_
が既定のシンボル文字集合に入っていて全体で 1 つのシンボルになるので、影響を受けません。

アセンブリ行は、ラベルとセクション名を除いて大文字小文字を区別しません。

エスケープ文字 \ は instruction の内部で使えます(3.12 節)。

3.4 error_patterns

エラーを発生させる条件をカンマ区切りで並べ、それぞれ ; の後にエラーコードを付けます:

a>3;4,b>7;5

ここで a>3 はコード 4 を、b>7 はコード 5 を発生させます。!= を含む比較演算子が
使えるので、a!=3;2 も (s&0xf!=0)||(s>>4)>3;9 もどちらも有効です。

条件の後ろは ;、コードの後ろは , か欄の終わりでなければなりません。a>3 x;4 や
a>3;4 5 のように式の後ろに文字が残るとき、a>;4 や a>3; のように因子が欠けている
ときはエラーです(3.5 節の要素と同じ規則)。

コード 1、2、3、5、6 にはメッセージ本文があります。9 節を参照。それ以外の
コード — 4 や 7 以上を含む — もエラーを発生させアセンブルを中断しますが、空のメッセージ
を表示します。本文のある 5 つのどれかを選ぶか、axx.py と caxx.c の ERRORS テーブル
に自分のものを追加してください。

error_patterns の 条件;コード の組は、まず整数モードで評価されます。整数は正確に
比べられるので、e>18446744073709551615;3 のような 64 ビットの範囲検査も書いたとおりに
働きます。次のどれかに当たる組だけは浮動小数点モードで評価され、値は IEEE-754 倍精度
ビットパターンとして運ばれます(2**53 を超える整数は丸められます)。

  • !F などで取った、浮動小数点モードで書かれた変数を読む組
  • 1.5 のような浮動小数点の定数を含む組
  • / か ** を含む組(整数と浮動小数点で結果が違うため。7/2>3 は 3.5>3 として真)

浮動小数点モードでも、ビット演算子とシフト演算子は内部で補正するので、(8>>2)>0;2 は
書いたとおりに評価されます。

-o でリンカが値を決めるラベル。 -o では、外部のラベル(.extern・.weak・
-i)と、いまアセンブルしているセクションとは別のセクションのラベルの値はリンカが
決めます。今の値(外部は 0、別セクションはそのセクションの中の位置)から求めた変位や
大きさには意味がないので、そうしたラベルを綴りに含む変数に触れる条件は判定しません。
範囲はリンカが確かめます(GNU as もリロケーションを出すだけです)。同じセクションの
ラベルと数への条件はふだんどおり判定します。ラベルを含むかは .islabel(3.15 節)と
同じく綴りで見ます。同じ理由で、.reloc が命令フィールド型(.elffield を持つ型)を
付けた変数への条件も、-o では判定しません。その欄はまだ 0 で、値はリンカが入れます。

.extern ext
.org 0x20000
bra.w ext            ; 68000.axx。-o ではエラーにせず R_68K_PC16 を出す

3.5 binary_list

カンマ区切りの出力値です。0x03,d は 0x03 に続けて d を出力します。

各要素は 1 つの式(か下の文字列・.call)で、要素の後ろには , か欄の終わりしか
書けません。0x3e,n m や n|0x68) のように式の後ろに文字が残るとき、1+ や n| の
ように因子が欠けているときはエラーです(以前は残りを黙って捨て、欠けた因子を 0 と読んで
いました)。

ADD A,R!n :: n>7;5 :: n|0x68

add a,r1 は 0x69 を出力します。n>7 はコード 5(レジスタが範囲外)を発生させます。

  • 空要素はアラインメントを行います。先頭のカンマ、あるいは 0x12,,0x13 は、
    正確なアドレスまでパディングします。
  • ; で始まる要素は、その値が 0 のとき抑制されます。
  • ;; で始まる要素は、評価されますが決して出力されません。0x11,;;n,0x22 は
    2 ワードを出力し、;;n だけの binary_list は何も出力しません。

3.5.1 @@[] — 繰り返し

@@[n,<str>] は <str> を n 回繰り返します。%% は繰り返しインデックスで、%0 は
それを 0 にリセットします。

3.5.2 テキストテンプレート — 文字列の出力

binary_list の要素は、式の代わりにダブルクォートで囲んだ文字列にできます。これは
テキストを構築します。そのソース行のアセンブル結果を、別のニーモニック構文で書いた
ものです。これによりパターンファイルはソース間トランスレータになります。同じテキストは
バイナリとしても、1 バイトにつき 1 ワードで出力されるので、文字列自体がその行の
出力になります。

MOV R!r,!e:: "LD R{{r}},0x{{.hex(e)}}"

MOV R1,0x10 が与えられると、このパターンは LD R1,0x10 をテキストとして、また
10 バイト 4c 44 20 52 31 2c 30 78 31 30 として出力します。

文字列は他の要素と同じくリストの 1 要素なので、式と自由に混在させたり、@@[...] で
繰り返したり、複数回書いたりできます。文字列の内側のカンマは要素を区切りません。

MOV A,!e::"load a,{{e}}\n",0x12,0x13
MOV A,3   ->  6c 6f 61 64 20 61 2c 33 0a 12 13   ("load a,3\n" の後に 0x12 0x13)

置換されるのは {{ }} だけです。 文字列内のそれ以外はすべて書いたとおりのテキスト
です — 大文字、小文字、波括弧の外の .hex(e)、そのすべてがそのまま出てきます。他に
読まれるのはバックスラッシュエスケープだけです。{{ }} の中は下の表の形の 1 つで、
式の後ろに文字が残るとき({{e 1}}、{{.hex(e)z}})と因子が欠けているとき({{e+}})は
エラーです。

形式 意味
{{<expr>}} 式を評価して 10 進で挿入
{{.hex(<expr>)}} 値の 16 進数字
{{.dec(<expr>)}} 値の 10 進数字
{{.bin(<expr>)}} 値の 2 進数字
{{.float(<expr>)}} 値を 10 進 128 ビット浮動小数点数、有効数字 34 桁として(16 は 16.0 になる)
{{<name>}} {{<name>[<expr>]}} 文字列シンボルまたは配列シンボル、さもなければパターン変数 — 下記参照
{{.index <name>[<expr>]}} {{<name>[<expr>]}} が使う添字そのものを 10 進で(3.6.1 節)
{{.exp(<変数>)}} 変数が拾った式・ラベル・シンボルなどを、ソースに書かれていたままの文字で(3.18 節)
\n \t \r \\ \" 改行、タブ、復帰、バックスラッシュ、ダブルクォート
\<char> その他の <char> をそのまま

4 つの変換は数字だけを出力し、基数プレフィックスは付かないので、プレフィックスは自分で
書きます — 0x{{.hex(e)}}、0b{{.bin(e)}}。

.float は値を 10 進 128 ビット浮動小数点数として描画します。有効数字 34 桁、偶数丸め
です。小数部のない値にも小数部が付くので、16 は 16.0 と書かれます。34 桁を超える
場合、あるいは非常に小さな値では指数形式に切り替わります
(1.234567890123456789012345678901235e+36)。両実装はバイト単位で同一のテキストを
生成します。

{{ }} 内の名前。 波括弧の中に単独で書かれた名前は、次の順序で解決されます:

  1. 文字列シンボル — .setsym::<name>::"<text>" — そのテキストを挿入する;
  2. 配列シンボル — [<expr>] 付きで、そのインデックスの項目;
  3. それ以外 — 式。したがってパターン変数はその値を 10 進で与える。

R{{r}} が R1 になるのはこのためです。R は波括弧の外なのでリテラルであり、r は
!r で束縛されています。

数値の .setsym シンボルは意図的に規則 1 では参照されません。そのため、ただの単語が
黙って数値に置き換えられることはありません。数値シンボルの値が欲しいときは {{#NAME}}
と書きます。

文字列シンボル。 .setsym は値フィールドがダブルクォートで始まるとき、数値ではなく
テキストを格納します:

.setsym::x::"LD"
MOV R!r,!e::"{{x}} R{{r}},{{.dec(e)}}"        ->  LD R0,12
.setsym::x::"LO"
.setsym::y::"AD"
MOV R!r,!e::"{{x}}{{y}} R{{r}},{{.dec(e)}}"   ->  LOAD R0,12

mov r0,12 が与えられると、これらは LD R0,12 と LOAD R0,12 を生成します。文字列
シンボルは数値を持たないので式の中には現れられません。テキストテンプレートのために存在
します。.clearsym は数値シンボルと同じように文字列シンボルを削除します。

MOV R1,0x10 が与えられたとき:

MOV R!r,!e:: "LD R{{r}},0x{{.hex(e)}}"    ->  LD R1,0x10
MOV R!r,!e:: "LD R{{r}},{{.dec(e)}}"      ->  LD R1,16
MOV R!r,!e:: "LD R{{r}},0b{{.bin(e)}}"    ->  LD R1,0b10000
MOV R!r,!e:: "LD R{{r}},0f{{.float(e)}}"  ->  LD R1,0f16.0

テキストの行き先:

  • 行末の改行は書いたぶんだけ入ります。1 行が 1 行になるようにしたいときは、テンプレート
    ごとに \n を書く代わりに .eol(3.17 節)を使えます。

  • .ascii(4.4 節)とまったく同じようにバイトとして出力されます。描画されたテキストは
    UTF-8 でエンコードされ、各バイトが 1 出力ワードになるので、その行はロケーションカウンタ
    を進め、バイナリと ELF 出力に入ります。出力ワード幅 (.bits) より広いバイトは警告付き
    で切り詰められます。\0 や \xHH のエスケープはありません — テキストでないバイトは、
    文字列の隣にリスト内の数値として書きます。

  • -V を付けたとき、描画された行だけが標準出力にも書かれるので、翻訳されたプログラムを
    単にファイルへリダイレクトできます。標準出力にはソース 1 行ごとに改行を 1 つ付けて
    書くので、テンプレートの末尾に \n を書くと標準出力では空行が入ります(出力ワードの
    側には書いたぶんだけ入ります。両方を 1 行 1 行にしたいときは \n の代わりに .eol、
    3.17 節)。-V を付けなければ標準出力には何も出ません(既定は無出力)。

  • -v ありのとき、その行の診断出力の末尾、// の後にダブルクォートで囲まれて現れます:
    ... MOV R1,0x10 // "LD R1,0x10"。そこではエスケープされて表示されます — 改行は
    改行そのものではなく \n と読めます — ので診断出力は 1 行に収まり、複数の文字列を
    持つ行はフィールドに書かれたとおりに分けて表示されます: ... // "A","B"。

    ;; 要素は評価されますがテキストを含めどこにも出力されません。; 付きの文字列は、
    描画結果が空のときスキップされます。

このように 1 つのパターンファイルが 2 つの用途を同時に果たします。翻訳のための標準出力
へのテキスト(-V)と、アセンブルのためのバイナリ内の同じ文字列(-b/-o)です。

NOP  :: "ABC"
DW !e:: e,e>>8
NOP        ->  0x41 0x42 0x43
NOP        ->  0x41 0x42 0x43
L1:
DW L1      ->  0x06 0x00        ; L1 は 6。各 NOP の 3 バイトが数えられている

3.6 シンボル

.setsym :: name :: value

1 つのディレクティブがあらゆる種類のシンボルを定義します。どの種類になるかは値フィールド
の見た目で決まります:

値フィールド 定義されるもの
0x20, #OTHER+1 数値シンボル — 任意のパターン式
"LD" 文字列シンボル — テンプレート用のテキスト (3.5.2)
[1,"A",#B] 配列シンボル — 数値とテキストのリスト (3.6.1)
other その文字列シンボルまたは配列シンボルのコピー、どちらでもなければその名前を保持する文字列シンボル (3.6.1)
r0,r1,r2 集合 — 名前のリスト (3.6.2)
a&b, a|b, a^b, a+b, a-b 他の集合から計算された集合 (3.6.2)

特殊形 — クォート、ブラケット、裸の名前、名前のリスト、集合式 — は当てはまる場所では
そのように認識されます。どれにも当てはまらないフィールドは数値式として読まれます。
各形式は隣に記した節で説明されています。

シンボル名には文字、数字、記号文字を含められます。シンボルは大文字小文字を区別しません。
同じ名前の後の定義は前のものを上書きするので、同じ識別子がファイルの異なる領域で異なる
意味を持てます:

.setsym::B::0
.setsym::C::1
ADD A,s              /* ここでの C は 1

.setsym::NZ::0
.setsym::Z::1
.setsym::NC::2
.setsym::C ::3
RET s                /* ここでの C は 3

.unordered のファイル(3.19 節)では再定義はできません。代わりに .map で変数ごとに
値を持たせます。

別のシンボルからシンボルを定義するには # を使います:

.setsym ::symbol1 ::1
.setsym ::symbol2 ::#symbol1

ダブルクォートで始まる値フィールドは文字列シンボルになります:

.setsym::x::"LD"

文字列シンボルは数値ではなくテキストを保持するので、式の中には現れられません。テキスト
テンプレート(3.5.2 節)で使われ、そこで {{x}} は LD を挿入します。.clearsym は
他のシンボルと同様にこれらを削除します。

3.6.1 配列シンボル

[ で始まる値フィールドは配列シンボルになります。その項目は数値式、素の名前、
文字列リテラル、またはその混在にできます:

.setsym::x::[1,2,3,4,5]
.setsym::y::["A","B","C","D","E"]
.setsym::regs::[R0,R1,R2]          /* ["R0","R1","R2"] と同じ */

項目はトップレベルのカンマで区切られます。"..." の内側や、入れ子のブラケット・括弧の
内側のカンマは分割しません。素の名前(R0、_tmp など)の項目は、書かれたままの
綴りのテキストとして保持されます。したがって [r0,r1] は小文字のままです。それ以外の
項目は通常のパターン式なので、先に定義したシンボルが使えます
(.setsym::m::[1,#BASE,#BASE+1])。名前そのものではなく、その名前に .setsym や .map
で与えた数値が欲しいときは #R0 と書きます。

項目は [<index>] で選択し、0 から数えます。インデックス自体が式なので、パターン変数で
駆動できます:

場所 書き方 例
テキストテンプレート (3.5.2) {{x[3]}} {{y[3]}} → D
式 #x[3] MOV !e :: #x[3],e は 4 を出力

テンプレートでは、数値項目は 10 進で書かれ、文字列項目はテキストとして挿入されます。
式の中の #x[3] は数値項目を必要とします — 文字列項目は数値を持たないので、そこでは
エラーです。テンプレート中でインデックスのない配列名は、全項目を , で連結したものに
展開されます。

添字の解決順。 テンプレートの {{<name>[<expr>]}} と {{.index <name>[<expr>]}}
では、文字列リテラルで書かれた添字がまずその中身に開かれます。したがって
arrb["CX"] は arrb[CX] と同じに読まれます。テンプレートの中ではパターン自身の文字列の
閉じ " が先に来るので、リテラルは {{.index arrb[\"CX\"]}} と逃がして書きます。開かれた
テキストは次の順で解決されます:

  1. 文字列シンボルの名前 — その中身を添字として読み直す;
  2. パターン変数の名前 — 4 へ(変数の値を使う);
  3. その配列の項目の名前 — その項目の位置。
    それが無ければ、同じ名前の .setsym / .map の数値シンボル — その値;
  4. どれでもない — ふつうの式。

名前を添字として使えるのは規則 3 のおかげです。

.map::r::AX,BX,CX                  /* AX=0, BX=1, CX=2 と .check::r */
.setsym::arrb::[R0,R1,R2]
.setsym::arra::[AX,BX,CX]
.setsym::var1::BX                  /* var1 は BX という名前(3.6 節) */

このとき {{arrb[var1]}} は R1 です。var1 は BX という名前(規則 1)、BX は
arrb の項目ではないが .map が定義した数値シンボル 1(規則 3)なので、添字は 1 に
なります。{{arra[var1]}} は規則 3 の前半で BX(arra の位置 1 の項目)です。
{{arrb[r]}} は規則 2 なので、
MOV r,!e::"LD {{arrb[r]}},0x{{.hex(e)}}" は mov bx,5 を LD R1,0x5 にします。

.index — 添字そのもの。 {{.index <name>[<expr>]}} は、まったく同じ規則で添字を
解決し、項目の代わりにその添字を 10 進で書きます。引き当ての「名前から番号へ」の向きです:

.setsym::var1::BX
TEST v::"LD A,{{.index arra[v]}}"     /* TEST CX  ->  LD A,2 */
                                      /* {{.index arrb[var1]}}    ->  1 */
                                      /* {{.index arrb[\"CX\"]}}   ->  2 */
                                      /* {{.index arra[\"CX\"]}}   ->  2 */

最後の 2 つは規則 3 の両半分が同じ答えに着くところです。CX は arrb の項目ではないので
その数値シンボル 2 が添字になり、arra では位置 2 の項目そのものです。

.index(<name>[<expr>]) と括弧で括って書いてもよく、2 つの形は同じです。他の参照と
同じように、配列が存在し、添字が範囲内でなければなりません。

範囲外のインデックスや、配列でない名前への name[...] はエラーとして報告されます。
.clearsym は他のシンボルと同様に配列シンボルを削除します。

コピー。 配列シンボルまたは文字列シンボルの名前だけを書いた値フィールドは、それを
コピーします:

.setsym::x::["R1","R2","R3"]
.setsym::y::x                  /* y は x のコピーになった */

コピーは独立しているので、後で x を再定義しても y は元のままです。配列でも文字列
シンボルでもない素の名前は、その名前を保持する文字列シンボルになります:

.setsym::var1::BX              /* var1 は BX という名前。{{var1}} は BX と出る */

これによって名前を持ち回り、添字として使えます(上の「添字の解決順」を参照)。その名前に
.setsym や .map で与えた数値が欲しいときは #BX、BX というラベルの値が欲しい
ときは BX+0 のように(名前ひとつではなく)式にして書きます。

配列は要素リストの代わりになれます。 ディレクティブが列挙された名前のリストを取る
ところ — .check、.enum、.map — では、配列シンボルの名前を書くとその場でその内容に
展開されます:

.setsym::regs::["R0","R1","R2","R3","R4"]
.check::x::regs           /* .check::x::R0,R1,R2,R3,R4 と同じ */
.map::x::regs::1<<x       /* .map::x::R0,R1,R2,R3,R4::1<<x と同じ */
.enum::f::regs::…

配列とただの名前は 1 つのリスト内で混在できます (.check::x::regs,SP)。数値項目はその
10 進表記を寄与します。したがってレジスタ名のリストを一度だけ書いて、それを必要とする
すべてのディレクティブで使えます。

Z80 レジスタの例:

.setsym ::B ::0
.setsym ::C ::1
.setsym ::D ::2
.setsym ::E ::3
.setsym ::H ::4
.setsym ::L ::5
.setsym ::A ::7
.setsym ::BC ::0x00
.setsym ::DE ::0x10
.setsym ::HL ::0x20
.setsym ::SP ::0x30

シンボルには句読点や数字を含められます: .setsym ::$s5:: 21。

クリア。 .clearsym::ax は ax を未定義にします。引数なしの .clearsym はすべてを
クリアします(.clrcheck・.clrreloc・.clrenum の引数なしの形と同じく、:: の無い行
でも警告は出ません)。

文字集合。 .symbolc::<characters> はシンボルに使える文字集合を拡張します。既定は
文字、数字、および _%$-~&| です。.symbolc は英数字に加える文字を書き直すもので、
既定の _%$-~&| は置き換わります。残したい文字は一緒に書いてください
(.symbolc::_%$-~&|{})。

- が既定の集合に入っていることに注意してください。これがシンボルの直後に負の変位を
続けられる理由です — マッチャは最長のシンボル接頭辞を先に試し、失敗すればフォールバック
します:

MOV EAX,[RBX-8]      ; x86_64.axx -> 8b 83 f8 ff ff ff
LD A,(IX-5)          ; z80.axx

同じ規則により、パターンがシンボルを期待する位置に負の値を書くと — 命令に即値形式が
ないときの ASR #-1 など — 範囲エラーではなく undefined symbol: '#-1' として報告
されます。

3.6.2 集合

カンマで区切られた名前だけのリストである値フィールドは、集合になります:

.setsym::a::a1,a2,a3
.setsym::b::b1,b2,b3,a2

集合はそれらの名前を項目とする配列シンボルなので、3.6.1 節のすべてが当てはまります —
.check::x::a、.map::x::a::…、.enum::f::a::…、テンプレート中の {{a}} や
{{a[0]}} がすべて動きます。項目は数値ではなく名前なので、式の中の #a[0] は他の
テキスト配列と同様に文字列項目として報告されます。名前は他のシンボル名と同様に大文字化
され、リスト中で繰り返された名前は 1 つだけ保持されます。リスト中の名前がそれ自体集合
である場合はその場で展開されるので、.setsym::c::a,b は 2 つの和集合になります。

集合代数。 集合は 5 つの演算子で結合できます:

書き方 結果
a&b 積集合 — 両方に含まれる名前
a|b 和集合 — どちらかに含まれる名前
a+b 和集合、a|b と同じ
a^b 対称差 — 一方にだけ含まれる名前
a-b 差集合 — a にあって b にない名前
.setsym::x::a&b        /* A2                      */
.setsym::y::a|b        /* A1,A2,A3,B1,B2,B3       */
.setsym::z::a^b        /* A1,A3,B1,B2,B3          */
.setsym::t::a+b        /* A1,A2,A3,B1,B2,B3       */
.setsym::q::a-b        /* A1,A3                   */

各結果は独立したコピーなので、後で a を再定義しても x … q は元のままであり、
.setsym::a::a|b は安全です。

順序は各名前が最初に現れた順に従います。左オペランドの名前が先で、次に右オペランドの
名前です。演算子は固有の優先順位を持たず左から右へ適用されるので、a&b|c は
(a&b)|c を意味します。

フィールドが集合でない場合。 集合としての解釈は通常の数値解釈より先に試され、
フィールドが集合になりえない場合は必ず数値解釈に譲るので、以前アセンブルできていた
ものの意味が変わることはありません:

  • カンマリストの各項目は名前でなければなりません — .setsym::X::1,2 のように数字で
    始まる項目を含むリストは式評価器に委ねられます;
  • 各演算子のオペランドは既存の集合を指す裸の識別子でなければなりません —
    .setsym::X::#N1+#N2 は従来どおり 2 つの数値シンボルを加算します;
  • 単一の名前を保持するフィールドはコピー (3.6.1 節) であり、1 要素の集合ではありません。
    それが欲しいときは .setsym::a::["A1"] と書きます。

-、&、| はシンボル名の中に現れうるので、オペランドが集合と認識されるのは文字・
数字・_ だけで綴られている場合に限られます。

3.6.3 シンボル捕捉子 (!Y)

!Y<集合>[<変数>]

instruction フィールドのその位置で、集合(3.6.2 節)の項目名を 1 つ読み、その
番号(0 から数えた項目の位置)を <変数> に束縛します。番号は他のキャプチャと
まったく同様に、error_patterns、binary_list、テキストテンプレートから裸の名前で
参照できます。

.setsym::y::R0,R1,R2
.setsym::x::AX,BX,CX
MOV !Yx[z],!e::"mov {{y[z]}},0x{{.hex(e)}}"
mov ax,0x12      ->  mov R0,0x12
mov bx,0x34      ->  mov R1,0x34
mov cx,0x56      ->  mov R2,0x56

ax は集合 x の 0 番なので z は 0 になり、{{y[z]}} が集合 y の 0 番 R0 を
出します。名前から番号へ、番号から名前へという引き当てなので、同じ並びを持つ 2 つの
集合があれば、一方の綴りを他方の綴りへ置き換えられます。

.check がその位置を集合の中の 1 つに制限するだけなのに対し、!Y は制限したうえで
何番目だったかを渡します。番号はただの整数なので、テンプレートの添字だけでなく式にも
書けます:

.setsym::x::AX,BX,CX
ENC !Yx[z] :: 0x40|z          /* enc ax -> 0x40, enc bx -> 0x41, enc cx -> 0x42 */

注意点。

  • 集合の名前は小文字で始まり、小文字・数字・_ が続く綴りで書きます(変数名と同じ
    規則)。照合の時点でその名前の集合または配列シンボルが無ければ、その行はマッチしません。
  • 変数名は [ ] で括ります。集合の名前とは別なので、!Yx[x] のように同じ綴りに
    する必要はありません。
  • 最長一致です。.setsym::over::A,AX,AL に対して al は A ではなく AL に
    当たります。項目名の直後がソースで英数字・下線なら語の途中なので一致とみなしません。
  • 項目名の大文字小文字は区別しません。配列シンボルの素の名前は書かれたままの綴りで
    保持されますが(3.6.1 節)、照合は両側を大文字にして行います。
  • 数値の項目(.setsym::m::[1,2,3] の各項目)は名前を持たないので、照合の相手に
    なりません。名前の項目だけが候補です。
  • 具体度は式ではなくシンボルとして数えます。取れる綴りが集合の項目に限られるので、
    同じ位置に !a と書いたパターンより !Yx[z] のほうが先に選ばれます。

3.7 シンボルチェック (.check)

.check::x::r1,r2,r3

x がキャプチャする位置に現れてよいものを制限します。それ以外はエラーです。
.clrcheck::x は制限を解除します。リストは配列シンボル(3.6.1 節)や集合(3.6.2 節)、
またはそれらとただの名前の混在にできます。

小文字の変数が 2 つ以上のオペランドクラスで再利用されるときは、必ず .check を
設定する価値があります。
これがないと変数はパターンファイルのどこかで定義された
任意のシンボルを受け付けてしまい、意味をなさないオペランドの組み合わせが拒否される
代わりに黙って誤ったバイト列にアセンブルされます。.check は位置依存で、変更される
まで有効であり続けるので、変数の意味が変わる各地点で新しい .check(または
.clrcheck)を置いてください。

同じニーモニックを共有する異なる幅のレジスタ:

.setsym::AL::0x00
.setsym::BL::0x01
.setsym::AX::0x00
.setsym::BX::0x01
.check::s::AL,BL
.check::t::AX,BX
MOV s,!a :: 0xb0|s,a
MOV t,!a :: 0xb8|t,a,a>>8

これにより mov al,0x12 と mov ax,0x1234 が区別されます。

3.7.1 列挙オペランドリスト (.enum)

.check が位置を集合の中の1 つのシンボルに制限するのに対し、.enum はそれらの
リストを取る位置を宣言します — 68000 の MOVEM のようなレジスタリストです。

.enum::<変数>::<要素,要素,...>::<式>

要素リストは、名前を書き並べる代わりに配列シンボル(3.6.1 節)でも構いません。

要素の順序が列挙順序であり、それがソース中の - 範囲の意味になります。<式> の中で
各要素名は次のように評価されます

  • その要素がソースのリストに現れていれば、その .setsym 値、
  • 現れていなければ 0。

リストは !E<変数> でキャプチャされます。<式> の値が変数に束縛され、その後は他の
すべてのキャプチャとまったく同様に、error_patterns と binary_list から裸の文字で
参照されます。

.setsym::A0::0x01
.setsym::A1::0x02
.setsym::A2::0x04
.setsym::B0::0x08
.setsym::B1::0x10
.setsym::B2::0x20
.enum::x::A0,A1,A2,B0,B1,B2::A0|A1|A2|B0|B1|B2
MOVEM !Ex :: :: @@[8,*(x,%%)]
movem a0-a2,b2       -> 27 00 00 00 00 00 00 00   (0x01|0x02|0x04|0x20)
movem a0-a2/b2       -> 同じ。`,` と `/` はどちらも区切り文字
movem a0/a2          -> 05 00 00 00 00 00 00 00
movem a1             -> 02 00 00 00 00 00 00 00

式は通常の axx 式なので、要素はビットマスクとして組み合わさる必要はありません。手で
重み付けすれば、代わりに位置表現のエンコーディングになります:

.enum::y::A0,A1,A2,B0,B1,B2::A0*100000+A1*10000+A2*1000+B0*100+B1*10+B2

注意点。

  • 区切り文字。 , と / はどちらも要素を区切り、first-last は列挙順序上の範囲
    です。区切り文字は別の要素が後続する場合にのみ消費されるので、パターンはリストの後で
    , を使い続けられます: PUSH !Ex,-(SP) は push a0-a2,-(sp) にマッチします。
    要素が後続しない - も同様にパターンの残りに委ねられるので、SUBT !Ev-!d は
    subt a0-9 にマッチします。
  • 逆順の範囲 (a2-a0) は範囲として読まれません。- はパターンに委ねられます。
  • ソースに現れるが .setsym 定義を持たない要素は、黙って 0 を寄与するのではなく、
    パターンをマッチさせなくします。
  • <式> の中の #name は素の .setsym 値であり、その要素が現れたかどうかに影響され
    ません。
  • .enum は .check と同じく位置依存です。同じ変数に対する後の .enum は前のものを
    置き換え、.clrenum::x(または引数なしの .clrenum)はそれを削除します。

3.7.2 サブテーブル (.sub / .return / .endsub)

サブテーブルは、instruction フィールドの一位置に差し込める、名前の付いた選択肢の
集合です。.check が位置を 1 つのシンボルに制限するのに対し、サブテーブルはその位置を
まるごと 1 つのパターンにでき、各選択肢が自分の値を持ちます。

.sub::<name>
<pattern>::<value list>
...
.return

ブロックの終わりは .return でも .endsub でも書けます。綴りが違うだけで意味は同じで、
1 つのパターンファイルの中で混ぜて構いません。.func … .endfunc(3.15 節)と
綴りをそろえたいときに .endsub を使ってください。

.sub::<name>
<pattern>::<value list>
...
.endsub

テーブルは !S{{<name>}}<変数> で参照されます。すべてのエントリが書かれた順に試され、
エントリの <pattern> が参照の位置でマッチされ、その <value list> の値が変数に束縛
されます。その後は他のすべてのキャプチャとまったく同様に、error_patterns と
binary_list から裸の文字で参照されます。

MOV!S{{sub1}}x A,!e :: 0x01,x<<8,x,e<<8,e
.sub::sub1
R1::0x01,0x01
R2::0x02,0x02
R3::0x03,0x03
.return
movr1 a,0x22         -> 01 00 01 00 22
movr2 a,0x33         -> 01 00 02 00 33

2 要素以上の値リストは 1 つの値にパックされます。最初の要素が最上位で、それぞれ
.bits ビットです — したがって 0x01,0x02 は既定幅では 0x0102 です。単一要素は
その値そのものです。

注意点。

  • エントリパターンは通常のパターンなので、それ自身がキャプチャできます: NZ::0 /
    Z::0x08 を保持する .sub::cc があれば、JMP!S{{cc}}c !e は jmpz 0x1234 に
    マッチします。
  • 値リストはマッチの後に評価されるので、エントリパターンがキャプチャした変数を
    使えます: R!n::n はキャプチャした数字を束縛します。
  • エントリはサブテーブルの中にのみ存在します。通常のパターン行としてマッチされること
    は決してありません。
  • 参照が解決される前にパターンファイル全体が読まれるので、テーブルはその使用箇所より
    後に定義できます。未知のテーブル名と循環参照は、パターンファイルを読むときに一度
    報告されます。

入れ子。 .sub ブロックを別の .sub ブロックの中に書くことはできません。
それはエラーです。入れ子は代わりに、エントリパターンが 2 つ目のテーブルを参照すること
で表現します。それは通常のパターン中の参照とまったく同じように展開されます:

LD!S{{outer}}a :: 0x10,a
.sub::outer
A!S{{inner}}b::b
B!S{{inner}}b::b+0x40
.return
.sub::inner
1::0x01
2::0x02
.return
lda1                 -> 10 01
ldb2                 -> 10 42

内側の変数が外側より先に束縛されるので、外側の値リストはそれを使えます — 上の例では
b が内側の値で、外側のエントリがそれに 0x40 を加えています。

参照の連鎖は最大 8 段まで展開されます。それより長い連鎖は展開されず、その行は単に
マッチしません。

3.7.3 .map — シンボルテーブルとそのチェックを 1 行で

.map::<変数>::<名前,名前,...>::<変数を使った式>
.map::<変数>::<名前,名前,...>::<値,値,...>

リスト中の各名前に値を与え、変数をそのリストに制限します。値フィールドはどちらの形でも
読まれます。すべての値を計算する 1 つの式か、名前と 1 対 1 で対応する値のリストです。

式の中で変数は、リスト中のその名前の位置を表し、0 から数えます。

.map::x::R0,R1,R2,R3,R4::1<<x

は次と完全に等価です:

.setsym::R0::1<<(0)
.setsym::R1::1<<(1)
.setsym::R2::1<<(2)
.setsym::R3::1<<(3)
.setsym::R4::1<<(4)
.check::x::R0,R1,R2,R3,R4

式は省略でき、その場合は変数自身になるので、名前には順に 0, 1, 2, … が与えられます:

書き方 R0…R4 に与えられる値
.map::x::R0,R1,R2,R3,R4 0, 1, 2, 3, 4
.map::x::R0,R1,R2,R3,R4::x 0, 1, 2, 3, 4
.map::x::R0,R1,R2,R3,R4::1<<x 1, 2, 4, 8, 16
.map::x::R0,R1,R2,R3,R4::10**x 1, 10, 100, 1000, 10000

値のリスト。 値フィールドがカンマで区切られた複数の項目を保持する場合、項目は名前と
順に対応します:

.map::x::R0,R1,R2,R3::9,7,14,41

は次と完全に等価です:

.setsym::R0::9
.setsym::R1::7
.setsym::R2::14
.setsym::R3::41
.check::x::R0,R1,R2,R3

これは値に規則性のないテーブル向けの形式です。2 つのリストは同じ長さでなければならず、
そうでなければディレクティブはエラーを報告し何も定義しません。各項目は他と同じく式なので、
.map::x::R0,R1,R2::x*10,100+x,7 は 0、101、7 を与えます — 変数は依然として位置を
表します。

ブラケットの外のカンマだけが項目を区切るので、自分のカンマを含む式は単一項目のままです:
.map::x::R0,R1,R2::*(#W,x) は 1 つの式のままで、名前には W の連続するバイトが与え
られます。

レジスタファイル、ビットマスク、その他名前そのものが番号付けになっているテーブルが
よくあるケースで、.setsym 行を手で書き並べるとリストと値がずれやすくなります。.map
はパターンファイルを読むときに上記のディレクティブへ展開されるので、下流では特別扱い
されません。

位置は括弧に包んで式に代入されるので演算子の優先順位は影響を受けず、置換されるのは変数の
単語全体としての出現だけです — 0xff の x はそのままです。

空要素 ("") はシンボルを定義せずに位置を消費するので、番号付けを揃えたまま、その
オペランドを .check リスト中で省略可能と印付けられます。値のリストと併用する場合は
その値も消費するので、2 つのリストは揃ったままです。

リストは配列シンボル(3.6.1 節)でもよいので、レジスタ名を一度書いて .check や
.enum と共有できます:

.setsym::regs::["R0","R1","R2","R3","R4"]
.map::x::regs::1<<x

省略可能な位置。 .check リスト中の "" はその位置が欠けていることを許します:

.setsym::a1::1
.setsym::a2::2
.setsym::a3::3
.setsym::b1::1
.setsym::b2::2
.setsym::b3::3
.setsym::c1::1
.setsym::c2::2
.setsym::c3::3
.check::a::a1,a2,a3,""
.check::b::b1,b2,b3,""
.check::c::c1,c2,c3,""
MOV a b c :: ::a*100+b*10+c
mov                  0
mova1              100
mova1c3            103
movb2               20
movb2c1             21

変数と変数のあいだは空白で区切って書きます。変数名は小文字・数字・_ が続くかぎり
1 つの名前なので、MOVabc と続けて書くと abc という 1 つの変数になってしまいます。
パターンの空白はソース側に空白があってもなくても当たるので、mova1c3 のように続けて
書いたソースにも当たります。続けて書かれた綴りの切れ目は、マッチャが決めます。その位置
で取れる最長の語から、定義済みのシンボルになるところまで削って戻るので、a1c3 は
a1 と c3 に分かれます。

AVX-512 のマスク記法も同じ仕組みを使います:

.symbolc::{}
.setsym::EAX::0
.setsym::EBX::1
.setsym::{K1}::1
.setsym::{K2}::2
.check::x::EAX,EBX
.check::k::{K1},{K2},""
FOO x k,y :: :: 0x90,k,x,y
FOO EAX,EBX          -> 0x90 0x00 0x00 0x01   (k 省略)
FOO EAX{K1},EBX      -> 0x90 0x01 0x00 0x01
FOO EAX{K2},EBX      -> 0x90 0x02 0x00 0x01
FOO EAX {K1},EBX     -> 0x90 0x01 0x00 0x01   (空白を入れてもよい)

.symbolc::{} で { } がシンボルの文字になるので、x の位置ではまず EAX{K1}
全体が取られ、EAX まで削って戻ってから、残りの {K1} を k が読みます。

3.7.4 .free — すべてのテーブルから名前を解放する

.free::x1,y1,z1

パターン層が保持するすべてのテーブルから各名前を削除するので、どのディレクティブが
定義したかを覚えていなくてもその名前を再利用できます。次のものをクリアします:

  • その名前の .setsym 数値・文字列・配列・集合シンボル;
  • その名前の .sub テーブル;
  • .check リスト中の候補として現れるその名前;
  • そして、その名前が変数名として読める場合、その変数の .check リスト全体、その
    .enum、およびその .reloc 宣言。

.clearsym や .clrcheck と同様に、.free は位置依存です。その上に書かれたパターン
はまだ名前を見ることができ、下のパターンは見られません。

.setsym::N1::7
.sub::T1
X::0x99
.return
BEFORE     :: :: #N1        /* 0x07 */
.free::N1,T1
AFTER      :: :: #N1        /* エラー - undefined symbol: '#N1' */

3.7.5 .reloc — リロケーション型の宣言

.reloc::<変数>::<型名>[::<マスク>[::<型>@<オフセット>[,<型>@<オフセット>...]]]

その変数が捕らえたラベル参照を、指定の ELF リロケーション型で -o の出力に書き
出します。.check と同じく位置依存で、後の .reloc が前のものを置き換え、
.clrreloc::x(引数なしなら全部)で解除します。.free も解除します。

型名は -m で選んだマシンの名前表 — ソース側で ::pc32 と書くときと同じもの
(8.3 節)— から引きます。.elftype(3.7.6 節)で決めた名前も書けます。そちらが
先に引かれるので、同じ綴りの組み込みの名前を自分の宣言で上書きできます。

宣言が効くのは -o を指定したときだけです。指定がなければ以下の行は宣言が無い
のと全く同じに振る舞うので、1 組の行で両方の出力を兼ねられます。-o ならリンカ
に渡すリロケーション、-b なら axx が自分で出した答えです。

なぜ必要か。 通常、リロケーションの型と加数は出力バイト列から推定されます。
値が素の整数として連続バイトに並んでいるので、「出力された値 − ラベル値」が加数に
なるからです。ところが AArch64 の分岐やアドレス生成では、値は 32bit 命令語の中の
飛び飛びのビット欄に、しかも語単位・ページ単位に縮めて詰められます。この形からは
加数を逆算できず、幅だけを見た推定では bl に PREL32 が当たってしまい、リンクは
通るのに 4 倍ずれた先へ分岐する、という壊れ方をします。

.reloc はその型を命令ごとに宣言します。加数はパターンが捕らえたオペランド値と
ラベル値の差になるので、bl func なら 0、bl func+8 なら 8 です。命令語側の
ビット欄は 0 にして出力されます(RELA なのでリンカが埋めます。GNU as と同じ形)。

.reloc::t::call26
BL !t :: :: @@[4,(0x94000000|(((t-$$)>>2)&0x3ffffff))>>(%%*8)]
.clrreloc::t
bl func      ->  R_AARCH64_CALL26  func + 0
bl func+8    ->  R_AARCH64_CALL26  func + 8

シンボル側では指定できない理由。 型はシンボルではなくオペランドの位置で決まり
ます。AArch64 で 1 つのアドレスを作る adrp / add の対は、同じシンボルを
ADR_PREL_PG_HI21 と ADD_ABS_LO12_NC という別々の型で参照します。.extern 名前::型 のようなシンボル単位の指定では、原理的にこれを表せません。

.reloc::p::adrp
ADRP X!d,!p :: :: …
.clrreloc::p
.reloc::o::add_abs_lo12_nc
ADD X!d,X!n,#!o :: :: …
.clrreloc::o
adrp x0,msg      ->  R_AARCH64_ADR_PREL_PG_HI21  msg + 0
add  x0,x0,#msg  ->  R_AARCH64_ADD_ABS_LO12_NC   msg + 0

しかも、ソースにシンボル単位で書いた型はパターンファイルの .reloc より
強い(3.7.8 節)ので、こういう参照をされるシンボルには書かないでください。
.extern msg::abs64 と書けば、上の 2 命令ともその型になります。

大きなパターンファイルではほぼ全行の被演算子変数が t なので、.clrreloc は
.reloc と同じだけ重要です。これが無いと、以降パターン走査が通り過ぎる全ての行に
宣言が効いたままになります。実例は aarch64.axx の Relocation modifiers 節で、
:lo12: :pg_hi21: :abs_g*: :prel_g*: :got: :got_lo12: のそれぞれに型を
宣言し、その行群の直後で解除しています。

1 回の実行で両方の出力を求めたときは注意が必要です。0 にした欄は生バイナリでも 0
のままなので、-o と並べて書いた -b の像は、そのオブジェクトをリンクした後で
ないと正しくありません。RELA ではデータの欄(.quad sym+8)も同じで、加数は項目が
持ち、欄は 0 です(GNU as と llvm-mc の書き方)。黙って通さず、axx が知らせます:

 warning - 16 field(s) were left 0 for the linker (.text+0x0, ...);
 this raw binary is only correct after linking a.o. Drop -o to have axx fill
 them in.

AArch64 で使える命令フィールド型は次のとおりです。データ型(abs64 abs32
abs16 pc64 pc32 pc16)は従来どおり .reloc なしでも推定されます。

型名 ELF 欄
call26 / jump26 283 / 282 bl / b の imm26
condbr19 280 b.cond、cbz の imm19
tstbr14 279 tbz / tbnz の imm14
ld_prel_lo19 273 リテラル ldr / ldrsw / prfm の imm19
adr_prel_lo21 274 adr の immlo/immhi
adr_prel_pg_hi21 (adrp) 275 adrp の immlo/immhi
adr_prel_pg_hi21_nc 276 同上、オーバーフロー検査なし
add_abs_lo12_nc 277 add の imm12
ldst8_abs_lo12_nc 278 ロード/ストアの imm12
ldst16 / ldst32 / ldst64 / ldst128_abs_lo12_nc 284 / 285 / 286 / 299 同上、幅ごとの縮尺
movw_uabs_g0 … g3(_nc 付きも) 263–269 movz / movk の imm16
movw_prel_g0 … g3(_nc 付きも) 287–293 同上、PC 相対
got_page (adr_got_page) 311 adrp の immlo/immhi — GOT ページ
got_lo12 (ld64_got_lo12_nc) 312 64bit ldr の imm12 — GOT 内オフセット
got_ld_prel19 309 リテラル ldr の imm19
ld64_gotpage_lo15 313 imm12

GOT の 2 つは他と性質が違います。値はリンカが作る GOT エントリのアドレスなので、
アセンブル時には決まりません。欄は 0 のまま出て、意味はすべてリロケーションが
担います。

マスクの欄 — 1 つの型で形の違う 2 つの欄。 省略できる第 4 欄は、その下の行に
ついて、型の .elffield(3.7.7 節)のマスク — RELA なら 0 にし、REL なら加数を
詰めるビット — を置き換えます。オフセット・シフト・補正は .elffield のまま、
型番号も変わりません。1 つのリロケーション型を幅の違う欄に使い、どちらかを命令で
見分ける ABI のためのものです。PowerPC64 の R_PPC64_ADDR16_DS / _LO_DS は、
DS 形式(ld・std。ビット 2〜15 の 14 ビットの欄で、ビット 0〜1 は命令のビット)
と DQ 形式(lq・lxv。ビット 4〜15 の 12 ビットの欄で、ビット 0〜3 は命令の
ビットと TX)の両方に使われ、リンカは命令を見て下位のビットを残します。
.elffield 1 つでは両方を言えません。DQ のマスクでは DS 形式の行でアドレスの
ビット 2〜3 がオブジェクトに漏れ、DS のマスクでは DQ 形式の行が TX を失います。
そこで型には DS のマスクを付け、DQ 形式の行が自分のマスクを書きます。

.elffield::addr16_ds::0xfffc::2           /* DS: 下位ハーフワードのビット 2-15 */
.reloc::d::addr16_ds::0xfff0              /* DQ: ビット 4-15                   */
LXV xt,!d(ra) :: ...
.clrreloc::d
ld  3,ext+12(1)   ->  e8 61 00 00   R_PPC64_ADDR16_DS  ext + 12
lxv 35,ext+48(1)  ->  f4 61 00 09   R_PPC64_ADDR16_DS  ext + 48   (TX と XO は残る)

マスクは定数式(1〜0xFFFFFFFFFFFFFFFF)で、.elffield を持つ型にだけ書けます。
それ以外の型に書くとエラーです。型と同じく -o のときだけ読まれ、.clrreloc /
.free で型といっしょに外れます。型のマスクのまま次の欄を書くときは、この欄を
空にします(.reloc::v::型::::lo16@4)。

追加の再配置 — 1 行で複数の欄。 第 5 欄には、各行に足すリロケーションを
<型>@<オフセット> の形でカンマで区切って 8 つまで並べます。参照の先頭から
<オフセット> バイト(.elffield のオフセットと同じ数え方)の位置に <型> を、
同じシンボルを指し、同じ加数(オペランドの値 − ラベルの値)に型の補正を足して
書きます。RELA なら、その位置の型の .elffield のマスクを 0 にし、REL なら
ほかの命令欄の型と同じく加数を欄へ書き戻します(.elfencode も効きます)。
いくつもの命令に展開する疑似命令に要るものです。MIPS の la は 1 つのシンボルの
%hi と %lo を持つ lui + addiu で、n64 の dla は 6 語に 4 つのリロケーション
が付きます。

.reloc::v::hi16::::lo16@4
LA t,!v :: .call la32(t,v)
.reloc::v::highest::::higher@4,hi16@12,lo16@20
DLA t,!v :: .call la64(t,v)
.clrreloc::v
la  $t1,ext+0x12348   ->  3c09 0001  R_MIPS_HI16  ext   (o32、REL: 丸めた上位)
                          2529 2348  R_MIPS_LO16  ext
dla $t0,ext           ->  R_MIPS_HIGHEST / HIGHER / HI16 / LO16  ext + 0   (n64、語 0 4 12 20)

.elfanchor::<型> — 命令そのものを指すリロケーション。 .elfanchor で宣言した
型の追加の再配置は、シンボルではなく、その行の最初のリロケーションの位置に axx が
置く局所シンボルを指し、加数は型の補正だけです。RISC-V の auipc の対がこれです。
2 つ目の命令の %pcrel_lo は、%pcrel_hi を持つ auipc を指します。そのため、
両方に展開する疑似命令には、自分の auipc に置くラベルが要ります。

.elfanchor::pcrel_lo12_i
.reloc::v::pcrel_hi20::::pcrel_lo12_i@4
LA d,!v :: .call pair_i(v-$$,d,0x13|(d<<15)|(d<<7))
.clrreloc::v
la a0,ext   ->  auipc a0,0    R_RISCV_PCREL_HI20    ext + 0
                addi  a0,a0,0 R_RISCV_PCREL_LO12_I  .Lanchor0 + 0

局所シンボルの名前は .Lanchor<n> です(.Lcfi<n> と同じく、ラベルと重なる間は
_ を足します)。1 つの位置には、いくつのリロケーションが指しても 1 つのシンボル
を置きます。.elfanchor が効くのは追加の再配置だけで、.reloc が直接
pcrel_lo12_i を付けた行(%pcrel_lo(label))は今までどおりそのラベルを指します。
並べる型は .elffield を持つこと、オフセットは 0〜255 です。-b では、行が自分で
すべてを計算するのは今までどおりです。

3.7.6 .elftype — リロケーション型名を自分で決める

.elftype::<名前>::<値>[::<幅>[::<PC相対>]]

ELF のリロケーション型番号に名前を付けます。付けた名前は、型名を書けるところ
すべてで使えます。

書くところ 例
パターンファイルの .reloc(3.7.5 節) .reloc::t::gotpcrelx
ソースの .extern(5.6 節) .extern ext1::gotpcrelx
ソースの .global(5.6 節) .global here::tpoff32
ソースの .EQU / .reloctype(5.5.1 節) .reloctype ,,gotpcrelx,
取り込み TSV(8.3 節) otherlabel::gotpcrelx 401020
  • 値は型番号(ELF の r_info の型欄に入る数)で、1 以上の整数の定数式です。
    10 進でも 0x 付きの 16 進でも、20+3 のような式でも書けます。0 は「型を
    指定しない」の意味で内部的に使っているので取りません。
  • 名前の大小は区別せず、名前欄の空白は落とします(.reloc の型名と同じ読み方
    です)。同じ名前を 2 度書けば後の宣言が勝ちます。
  • 引かれる順は「.elftype の名前 → -m で選んだマシンの名前表」です。同じ綴り
    の組み込みの名前があっても、自分の宣言のほうが先に引かれます。
  • 宣言はパターンファイルを読み終えた時点でそろえられます。だから .reloc より
    後ろに書いた宣言も引けますし、パターン表をたどる前に読まれるソースの
    .extern / .global からも引けます。
  • -E の書き出しでは、マシンの名前表に名前が無い型番号にこの名前が使われます。
    取り込み側も同じ名前で引くので、書き出し → 取り込みがそのまま往復します。

何のためにあるか。 axx が持っている名前表は各マシンでよく使う型だけを載せて
います。そこに無い型(x86-64 の R_X86_64_GOTPCRELX や TLS 系、あるいは axx が
名前を知らないマシンの型)を使いたいときに、パターンファイル側で名前を決めて
しまえます。

.elftype::gotpcrelx::41            /* R_X86_64_GOTPCRELX */
.elftype::rexgotpcrelx::0x2a       /* R_X86_64_REX_GOTPCRELX */
.elftype::tpoff32::23              /* R_X86_64_TPOFF32 */

.reloc::t::gotpcrelx
CALLX !t :: 0xe8,t,t>>8,t>>16,t>>24
.clrreloc::t
        .extern ext1::gotpcrelx
        callx   ext1        ->  R_X86_64_GOTPCRELX  ext1 + 0

幅と PC 相対(省略可)。 4 番目の欄はその型が書き換える欄のバイト幅
(1・2・4・8 のいずれか、それ以外も 1〜8 なら書けます)、5 番目の欄は 0 以外
なら「PC 相対の型」という印です。

.elftype::abs16::2::2          /* 2 バイトの絶対参照        */
.elftype::pcrel16::4::2::1     /* 2 バイトの PC 相対参照    */

どちらも省いたときは、番号が名前表に載っている型と同じなら幅も PC 相対性も
そこから分かり、載っていない番号なら「幅は問わない」扱いになります
(.reloctype の幅検査も通ります)。組み込みの名前表を持たないマシンで
.elfwidth や .elfextern(3.7.7 節)から引かせる型には、幅を書いてください。
加数の計算に欄の幅が要るためです。命令語のビット欄に値を詰める型は .reloc と
組み合わせて使ってください(3.7.5 節)。

実例は同梱の elftype.axx / elftype.s です。

3.7.7 ELF の記述 — 組み込みの表に無いマシンで -o を出す

axx は 11 機種 — i386(3) m68k(4) PowerPC(20) PowerPC64(21) s390x(22) ARM(40)
SuperH(42) SPARCV9(43) x86-64(62) AArch64(183) RISC-V(243) — のリロケーション
番号を組み込みで持っています。それ以外の e_machine でも、ELF オブジェクトを
どう書くかをパターンファイルに宣言すれば -o で出せます。

宣言 決めるもの
.elfmachine::<番号>[::<名前>] e_machine の番号(と診断に出す名前)
.elfclass::<32> / <64> ELF クラス(ELF32 / ELF64)
.elfrela::<1> / <0> RELA(1、rela とも書けます)か REL(0、rel)か
.elftype::<名前>::<番号>[::<幅>[::<PC相対>]] リロケーション型(3.7.6 節)
.elfwidth::<バイト幅>::<型> その幅の参照に使う既定の型
.elfextern::<型> .extern が型名を書かなかったときの既定の型
.elfdwarf::<型> -g の DWARF が書く絶対アドレス参照の型
.elfheader::<欄名>::<値> ELF ヘッダの欄
.elfsection::<名前>::<sh_flags>[::<sh_type>[::<整列>[::<要素長>]]] セクションヘッダの属性
.elffield::<型>::<マスク>[::<オフセット>[::<シフト>[::<補正>]]] 命令フィールド型のリロケーション(下の「命令フィールド型」)
.elfpcguess::<0> / <1> 幅から推定した絶対型を PC 相対型に取り替えるか(3.7.9 節)
.elfrelax::<0> / <1> リンカがコードを縮めうるか。セクションの中のラベル差をリロケーションで残すかが決まる(3.7.10 節)
.elfanchor::<型> .reloc の追加の再配置のうちこの型のものは、行の最初のリロケーションに置く局所シンボルを指す(3.7.5 節)
.elfresolve::<型> この PC 相対の型の欄が同じセクションの局所ラベルを指すなら、axx が解決してリロケーションを出さない(下記)
.elfunaligned::<型>::<代わりの型> データの欄のセクションの中の位置が欄の幅の倍数でなければ、この型の代わりに使う型(3.7.9 節)
.elfbuiltin::<0> / <1> 組み込みの表を土台にするか(3.7.9 節)
.elfextra::<型>::<添える型>[::<シンボル>] 同じ位置に添えるリロケーション(3.7.10 節)
.elfdiff::<幅または型>::<足す型>::<引く型> ラベルの和と差を足す型と引く型の組で出す(3.7.10 節)
.elfcfi::<戻り番地の列>::<コード整列>::<データ整列>[::<詰め>] CFI(.eh_frame)の CIE の欄(3.7.11 節)
.elfcfiinit::<命令> CIE の初期命令(3.7.11 節)
.elfcfireg::<名前>::<DWARF 番号> CFI の指令に書くレジスタ名(3.7.11 節)
.elfencode::<型>::<関数> REL で加数を欄へ書き戻す関数(3.7.10 節)
.elfrinfo::<関数> r_info を組む関数(3.7.10 節)
.elfunit::<byte> / <word> 加数とシンボル値の単位(3.7.10 節)
.elfgroup::<名前>::<署名>::<フラグ>::<メンバー>[,...] セクショングループ(3.7.10 節)
.elflink::<セクション>::<sh_link>[::<sh_info>] セクションの sh_link / sh_info(3.7.10 節)
  • どの宣言も、-m で選んだ組み込みの表に重ねる差分です。組み込みの表に
    ある機種なら、書いた分だけが差し替わります(例えば x86-64 に .elftype で
    型名を足すだけ、.elfheader::flags を足すだけ、といった使い方ができます)。
  • <型> と書いたところには、.elftype で決めた名前・組み込みの名前・型番号
    (10 進、0x 付き 16 進)のどれでも書けます。名前の大小は区別しません。
  • .elfwidth のバイト幅は 1 〜 8 のどれでも書けます。ソースが ::型名 を
    書かなかった参照は、欄のバイト幅からこの表を引きます。2 の冪でない幅も
    書けるのは、1 ワードが 8 ビットでない機種(.bits、3.10 節)では参照の幅が
    1 ワードのバイト数の倍数になるからです。12 ビット機の 3 ワード参照は 6 バイト
    ですし、8 ビット機でも 3 バイトの欄を持つ ISA はあります(R_MN10300_24 など)。
  • 宣言はどこに書いても構いません。.elftype と同じくパターンファイルを読み
    終えた時点でそろえられるので、使う側より後ろに書いても引けます。

-m / -f との関係。 -m を書かなければ .elfmachine の番号が対象に
なり、-m を書けばそちらが勝ちます(同じパターンファイルを別の番号で使い
回せます)。-f も同じで、書かなければ .elfclass、それも無ければそのマシン
の慣習クラス(組み込みの表に無いマシンなら ELF64)になります。

宣言が足りないとき。 型の決まらない参照は、当てずっぽうの型番号を書く
代わりにリロケーションを出しません(どこを飛ばしたかは -d を付けると出ます)。
-m に組み込みの表に無い番号を書いて -o を出すときは、そのことを知らせる
警告が出ます。-g の DWARF も、.elfdwarf(または組み込みの表)で絶対参照の
型が分かるときだけ出ます。

.elfheader で書ける欄。

欄名 ELF ヘッダの欄 既定値 範囲
type e_type 1(ET_REL) 0〜0xFFFF
flags e_flags 0 0〜0xFFFFFFFF
version e_version 1(EV_CURRENT) 0〜0xFFFFFFFF
entry e_entry 0 0〜0x7FFFFFFFFFFFFFFF
osabi e_ident[EI_OSABI] --osabi の値(既定 0) 0〜0xFF
abiversion e_ident[EI_ABIVERSION] 0 0〜0xFF

機種固有の e_flags(ARM EABI の版数、RISC-V の ABI 印など)を出すための欄
です。書かなかった欄は既定値のまま出ます。値は定数式で書けます。

.elfsection で決めるセクションの属性。 書かなかったセクションは、いままで
どおり名前から決まります。

名前(前方一致) sh_flags sh_type
.text SHF_ALLOC+SHF_EXECINSTR(6) SHT_PROGBITS(1)
.data SHF_ALLOC+SHF_WRITE(3) SHT_PROGBITS(1)
.bss SHF_ALLOC+SHF_WRITE(3) SHT_NOBITS(8)
.rodata・その他 SHF_ALLOC(2) SHT_PROGBITS(1)
.elfsection::.vectors::0x6           /* ALLOC+EXECINSTR、型は既定のまま */
.elfsection::.noinit::0x3::8         /* ALLOC+WRITE、SHT_NOBITS         */
.elfsection::.note.axx::0::7         /* 欄なし、SHT_NOTE、整列は 4      */
.elfsection::.vectors2::0x6::1::2    /* 整列を明示して 2                */
.elfsection::.rodata.str1.1::0x32::1::1::1
                                     /* ALLOC+MERGE+STRINGS、要素長 1   */

名前で決まる規則を持たないセクション — その機種のベクタ表、.bss という名前で
はない未初期化領域、ノートセクション、リンカが要素単位で扱う文字列表 — を出す
ための宣言です。

  • セクション名は大小を区別せず、書いた名前と丸ごと一致したときだけ当たります
    (名前から決まる規則が前方一致であるのとは違います)。
  • sh_flags と sh_type はどちらも 0〜0xFFFFFFFF の定数式です。sh_type を
    書かなければ、型は名前の規則のまま残ります。
  • SHT_NOBITS(8)にしたセクションは、sh_size だけを持ち中身をファイルに
    書きません(.bss と同じ扱いになります)。
  • 第 4 欄は sh_addralign です。0 か 2 の冪でなければならず(ELF の要求)、
    そうでなければ診断して読み飛ばします。
  • 第 5 欄は sh_entsize です。そのセクションが固定長の要素を並べたもので
    あるときの 1 要素のバイト数で、0〜0xFFFFFFFF の定数式です。書かなければ 0
    (=固定長の要素を持たないセクション)になります。SHF_MERGE(0x10)を
    立てたセクションは、リンカが要素の幅を知らないと重複を畳めないので、この欄が
    0 でないことを要求します。文字列表(SHF_MERGE|SHF_STRINGS、0x30)なら 1 です。

sh_link と sh_info を書く欄はありません。再配置可能オブジェクトでこの 2 つに
意味があるのは、.rela.* と .symtab — どちらも axx が自分で組み立てるセクション
— だけで、そこには正しい節番号が自動で入ります。

整列の既定値。 整列を書かなかったセクションは 16 になります。ただし
SHT_NOTE(7)だけは 4 です。note は sh_addralign が 4 か 8 でなければ
ならず、16 だと binutils が Corrupt note: alignment 16, expecting 4 or 8
と言って中身を読めません。ELF64 でも 8 ではなく 4 なのは、note の
n_namesz / n_descsz の詰め物が整列値に従うからで、.note.gnu.build-id
のような実在の note が ELF64 でも 4 で書かれているのに合わせています。8 が
要る note(.note.gnu.property)は、この欄に 8 と書いてください。

実例は同梱の elfsec.axx / elfsec.s です。elfsec.s は整列が正しいこと
を確かめられるよう、readelf -n が読める形の note を書いています。

その場で解決する(.elfresolve)。

.elfresolve::<型>

<型>(.elffield を持つ PC 相対の命令欄の型)の欄が、いまアセンブルしている
セクションの局所ラベルを指すなら、リロケーションは出しません。リンカが書くのと同じ
値 (ラベル + 加数 + 補正 − 位置) >> シフト を、マスクのビットへ下から詰めて書きます。
GNU as と llvm-mc がセクション内の分岐を自分で解決するのと同じです。.elfencode の
関数(3.7.10 節)を持つ型は、代わりにその関数が (欄の値, ラベル + 加数 + 補正 − 位置) から書きます。欄の中でビットが並び替わる型 — AArch64 の adr、RISC-V の
B・J・CB・CJ 形式、auipc + jalr に分かれる RISC-V の call — はこれで書きます。ラベルはこの
セクションで定義され、.global でも .weak でもないこと。それ以外の参照は
リロケーションのままです。欄に収まらない値(.elffield のマスクのビット数をシフトの
後で超えるもの)や 1 << シフト の倍数でない値はエラーです。-o ではパターンの範囲
検査をリンカに任せているためです。型ごとに 1 行ずつ書き、値が範囲検査のある変位で
ある型にだけ使います。SPARC の %pc10 のような
切り詰める型に書くと範囲外と報告されます。緩和する機種(.elfrelax::1、
3.7.10 節)では何も解決しません。

.elffield::wdisp22::0x3fffff::0::2
.elfresolve::wdisp22
start: nop
       nop
       ba start      ->  10bf fffe   リロケーションなし(2 語前)
       nop
       ba ext        ->  1080 0000   R_SPARC_WDISP22 ext

sparc.axx は WDISP30・WDISP22・WDISP19・WDISP16 を解決します(セクション内で
分岐するオブジェクトも、後ろの 3 つを扱えない ld.lld でリンクできるようになります)。
ppc64.axx / ppc64le.axx は REL24・REL14、mips_isa.axx は PC16・PC21_S2・
PC26_S2・PC19_S2、riscv64.axx / riscv64full.axx は BRANCH・JAL・CALL_PLT(と
RVC_BRANCH・RVC_JUMP)、aarch64.axx は JUMP26・CALL26・CONDBR19・TSTBR14・
LD_PREL_LO19・ADR_PREL_LO21 を解決します。どれも llvm-mc 19 が解決するものと同じ
で、ページ相対や %pcrel_hi / %pcrel_lo の対、MIPS の ldpc は、そこと同じく
リロケーションのままです。

例。 EM_MSP430(105)— axx が組み込みの表を持たないマシン — の記述です。

.bits::8

.elfmachine::105::MSP430
.elfclass::32
.elfrela::1

.elftype::abs32::1::4
.elftype::abs16::2::2
.elftype::pcrel16::4::2::1
.elftype::abs8::3::1

.elfwidth::4::abs32
.elfwidth::2::abs16
.elfwidth::1::abs8
.elfextern::abs16
.elfdwarf::abs32

.elfheader::flags::0x2a
.elfheader::abiversion::1

CALL !t :: 0xb0,0x12,t,t>>8
.reloc::t::pcrel16
JMP !t :: 0x00,0x3c,t,t>>8
.clrreloc::t
        .extern ext1            ->  R_MSP430_ABS16   ext1 + 0
        call    ext1
        jmp     start           ->  R_MSP430_PCR16   start + 6

実例は同梱の elfgen.axx / elfgen.s です。

命令フィールド型(.elffield)。

.elffield::<型>::<マスク>[::<オフセット>[::<シフト>[::<補正>]]]

<型> が、値を素の連続バイトではなく命令語のビット欄に詰める型であることを
宣言します。組み込みの表が AArch64 に与えているものを、どの機種にも与える宣言です。
.reloc::t::<型>(3.7.5 節)で型を付けた行は、加数が「オペランドの値 − ラベルの値
+ <補正>」になり、そのオペランドの範囲・整列の検査はリンカに任されます。
欄の中身は RELA と REL で違います。

  • RELA(.elfrela::1)では欄は 0 で出力され、加数はリロケーションの項目に
    入ります(GNU as と同じ形)。

  • REL(.elfrela::0)では加数を <シフト> ビット右へずらし、<マスク> の
    立っているビットへ下から順に詰めて欄に書き戻します。マスクの外のビット
    (命令の残り)はそのまま残ります。

  • <マスク> はリンカが書き込むビットです。型の幅(.elftype の幅欄かマシンの
    名前表)ぶんのバイト列を、対象のバイト順で読んだ整数の中のビットで書きます。
    2つの命令語にまたがる 34 ビット欄は、64 ビットのマスク1つになります。
    64 ビットのどのビットも使えます(1〜0xFFFFFFFFFFFFFFFF)。8 バイトの欄では
    最上位ビットまで届くことがあります — RISC-V の R_RISCV_CALL_PLT は
    auipc+jalr の対に当たり、リトルエンディアンで読むと jalr の imm12 が
    ビット 52〜63 に来るので、マスクは 0xfff00000fffff000 です。

  • <オフセット>(省略時 0)は、その欄が、その行がオペランドのために出す最初の
    ワードから何バイト目に始まるかです。r_offset もそこを指します。32 ビット語の
    下位半分にある 16 ビット欄は、ビッグエンディアンで 2、リトルエンディアンで 0 です。

  • <シフト>(省略時 0、0〜63)は、REL のとき加数を欄へ書き戻す前に右へずらす
    ビット数です。ARM の bl のように欄が語単位(4 バイト単位)なら 2 です。RELA
    では使いません。

  • <補正>(省略時 0、−2147483647〜2147483647)は加数に足す定数です。PC が命令の
    先頭より先を指す機種で、そのずれをリンカに伝えます。ARM の分岐は命令番地+8 から
    数えるので −8 です(GNU as も bl ext の加数を −8 にします)。

  • 型は .elftype の名前、組み込みの名前、番号のどれでも書けます。同じ型を
    もう一度書くと、後の宣言が前の宣言を置き換えます。

  • 同じ型番号で欄の形が違う行は、.reloc の第 4 欄でマスクを置き換えられます
    (3.7.5 節)。

  • マスクのビットへ下から順に詰めるので、欄の中でビットの並びが入れ替わる型
    (RISC-V の B 形式など)を REL で書き戻すことはできません。そういう型を持つ
    機種は RELA で書いてください(実在の ABI もそうなっています)。

.elftype::rel24::10::4::1
.elftype::addr16_ha::6::2
.elffield::rel24::0x03fffffc            /* PowerPC64 bl の LI 欄        */
.elffield::addr16_ha::0xffff::2         /* 下位半語(ビッグエンディアン) */

.reloc::t::rel24
BL !t :: .call w4(0x48000001|((t-$$)&0x3fffffc))
.clrreloc::t
bl ext+8        ->  R_PPC64_REL24  ext + 8

REL の例です(ARM、同梱の elfrel.axx)。

.elfrela::0
.elftype::call::28::4::1
.elftype::movw_abs_nc::43::4
.elffield::call::0x00ffffff::0::2::-8   /* imm24、語単位、PC+8 */
.elffield::movw_abs_nc::0x000f0fff      /* imm4:imm12          */
bl   ext                  ->  eb fffffe   R_ARM_CALL         ((0 − 8) >> 2)
bl   ext+16               ->  eb 000002   R_ARM_CALL         ((16 − 8) >> 2)
movw r1,%lo16(dat+0x12345) -> e302 1345   R_ARM_MOVW_ABS_NC  (imm12 ← 下位 12 ビット、imm4 ← 次の 4 ビット)

型名を書かない .extern は、.reloc が命令フィールドに与えた型を上書きしません。
3.7.8 節の優先順位で「ソースファイル」に当たるのは、ソースが型を書いたとき
(.extern ext::abs64)だけです。

3.7.8 リロケーション型の優先順位

1 つの参照の型は 3 か所で決められます。強い順に並べると

順位 決めるところ 書き方
強 ソースファイル .extern/.global/.EQU/取り込み TSV の ::<型名>、.reloctype(5.5.1 節)
中 パターンファイル .reloc::<変数>::<型名>(3.7.5 節)
弱 既定 欄のバイト幅からの推定(.elfwidth、マシンの表)

です。つまり 既定 < パターンファイル < ソースファイル で、ソースが最後に
決めます。

  • パターンファイルは、その命令の欄が普通どちらの型を運ぶかを .reloc で
    書きます。幅からの推定では足りない命令(AArch64 の分岐や adrp など)に
    型を与えるのがこれです。
  • ソースが ::<型名> を書いたシンボルは、その型で出ます。同じ命令行でも、
    シンボルごとに型を取り替えられます。.reloc が「値は命令語のビット欄に
    入っている」と教えている場合、その知識と加数の求め方はそのまま使われ、
    型番号だけが差し替わります。
  • どちらも書かれていない参照は、欄の幅から引いた既定の型になります
    (.elfwidth、3.7.7 節)。
.reloc::t::pcrel16              /* パターン: この欄は PC 相対      */
JMP !t :: 0x00,0x3c,t,t>>8
.clrreloc::t
        .extern ext::abs16      ; ソースが型を書いたシンボル
        .global start
start:
        jmp     start           ->  R_MSP430_PCR16   start + 2
        jmp     ext             ->  R_MSP430_ABS16   ext + 0
        dw      start           ->  R_MSP430_ABS16   start + 0

注意。 AArch64 の adrp / add の対のように、同じシンボルを 2 つの型で
参照する命令に .reloc で型を与えているパターンファイルでは、そのシンボルに
ソース側で ::<型名> を書かないでください。書くとどちらの命令もその型に
なります(3.7.5 節の「シンボルに書けない理由」)。型が命令の位置で決まる
ものは、パターンファイル側だけで書くのが正しい形です。

実例は同梱の elfprio.axx / elfprio.s です。

3.7.9 組み込みの表も宣言で書ける — .elfbuiltin / .elfpcguess / --elfdesc

axx が 11 機種ぶん持っている組み込みの表(2.2 節)は、パターンファイルの宣言を
あらかじめ書いておいたものにすぎません。表の項目はどれも 3.7.6〜3.7.7 節の宣言で
同じものが書け、ELF を書くコードには機種番号で分かれる処理がありません。

表の項目 同じことを書く宣言
機種の名前 .elfmachine::<番号>::<名前>
慣習の ELF クラス .elfclass
RELA か REL か .elfrela
型の名前・番号・幅・PC 相対 .elftype
幅ごとの既定の型 .elfwidth
.extern の既定の型 .elfextern
DWARF の絶対参照の型 .elfdwarf
命令フィールド型(AArch64) .elffield
絶対型→PC 相対型の推定(m68k) .elfpcguess

.elfbuiltin::<0|1>。 0 と書くと、-m の番号に組み込みの表があっても
使わず、パターンファイルの宣言だけで記述を組みます。既定の 1 では、表に宣言を
重ねます(3.7.7 節)。表の型がまぎれ込まない、閉じた記述を書くときに使います。

.elfpcguess::<0|1>。 1 なら、.reloc が型を付けていない欄の参照を、次の
2 つの方法で PC 相対と見分けます。

  • 綴りで。 オペランドが「ラベル − $$ + 定数」と書かれていれば(.long ext-$$、
    .quad ext+8-$$、.short ext-$$-2)PC 相対です。欄の幅の PC 相対型になり、
    加数は定数部、RELA なら欄は 0 です(GNU as が .long ext-. に付けるのと同じ
    リロケーション)。いまアセンブルしているセクションのラベルなら距離は決まって
    いるので、リロケーションは出さず、欄にその値を残します。綴りは 3.7.10 節の
    ラベル差と同じ読み方(ラベル、数、+、-、括弧)で読みます。ソースがその
    ラベルに型(::<型>)を書いていれば、幅が合うときはそれを使います。
    「ラベル − いまアセンブルしているセクションのラベル」も同じように読みます
    (.long ext-dat は ext-$$ に「dat から欄までの距離」を足したもので、それは
    加数に入ります)。GNU as と llvm-mc の読み方です。
    その幅の対を .elfdiff(3.7.10 節)が宣言していれば、代わりにその対で書きます。
    足す型はラベルを指して定数部を加数に持ち、引く型は axx が欄に置く局所シンボル
    (.Lanchor<n>、.elfanchor と同じ)を指します。llvm-mc が RISC-V の
    .quad ext-. に付ける形です。RISC-V には 64 ビットの PC 相対型がありません。
  • 値で。 それ以外で、型が欄の幅からの推定(ソースが型を書いていない)で、
    欄がオペランドの値(ラベルと、いっしょに書かれた定数)を持っていなければ、
    パターンがそこから変位を計算したもの — m68k の bra.w label の欄、
    binary_list の中の t-$$-2 — として、幅から推定した絶対型を同じ幅の
    PC 相対型に取り替えます。.long ext+4 の欄は ext+4 を持つので絶対型のままです。
    比べるのは欄の幅のビットだけです。加数は「綴りの定数 +(欄 − ラベル + 位置 − 定数を
    欄の幅で符号付きに折り返したもの)」です。欄は幅で切られているので、位置が欄の幅を
    超えるところ(68000 の .org 0x10000 の後の bra.w ext など)でも加数がずれません。

どちらの場合も PC 相対型はデータの型です。.elffield を持つ型(命令の欄。RISC-V の
R_RISCV_BRANCH も PC 相対で幅 4 です)は選びません。

.elfunaligned::<型>::<代わりの型>。 .reloc が型を付けていない欄(データ)で、
決まった型がこの型で、欄のセクションの中の位置が欄の幅の倍数でなければ、代わりの型に
します。境界に合わない位置用の型を持つ機種のためのもので、sparc.axx は r64 / r32 /
r16 に R_SPARC_UA64 / UA32 / UA16 を当てています(llvm-mc と同じ)。型を欄の幅から
推測したあと、.elfpcguess の取り替えのあとに見ます。--elfdesc は型番号の小さい順に
書きます。

.elfunaligned::r64::ua64
        .section .data
        WORD    ext             ; .data+0  -> R_SPARC_32
        XWORD   ext+8           ; .data+4  -> R_SPARC_UA64(4 は 8 の倍数でない)

値ではなく綴りを読むのは、値だけでは ext-$$ と ext+<定数> を見分けられない
からです。-o では $$ はセクションの先頭からの相対位置なので(3.7.10 節)、
ext-$$ の値は ext に負の定数を足したものと同じ形になり、セクションのオフセット 0
ではなおさらです。

組み込みの表では m68k だけがこれを 1 にしています。どの機種でも書けます。
ppc64.axx と ppc64le.axx は R_PPC64_REL64 / REL32 / REL16 のために、
riscv64.axx と riscv64full.axx は ADD / SUB の対のために、mips_isa.axx は
R_MIPS_PC32(と n64 の組み合わせ型 R_MIPS_PC32 / R_MIPS_64)のために 1 にしています。

--elfdesc。 いま有効な記述 — -m の機種の組み込みの表に、パターンファイルの
宣言を重ねたもの — を、先頭に .elfbuiltin::0 を置いた宣言の並びとして標準出力へ
書き出し、アセンブルせずに終わります。ソースファイルは要りません。

$ axx aarch64.axx -m 183 --elfdesc
.elfbuiltin::0
.elfmachine::183::AArch64
.elfclass::64
.elfrela::1
.elftype::abs64::257::8
.elftype::abs32::258::4
...
.elfwidth::8::abs64
.elfextern::pc32
.elfdwarf::abs64
.elfpcguess::0
.elffield::movw_uabs_g0::0x1fffe0::0::0::0
...

この出力をパターンファイルに貼れば(あるいは include すれば)、組み込みの表なしで
同じ ELF が出ます。組み込みの 11 機種すべてと同梱の ELF 系パターンファイルで、
出力がバイト単位で一致することを確かめています。組み込みの表に近い機種を新しく
書くときは、近い機種の --elfdesc を写して書き換えるのが早道です。

型は名前で書き、名前の無い型は番号で書きます。.elfheader・.elfsection・
.elflink・.elfgroup はパターンファイルに書いたものだけが出ます(組み込みの表は
これらを持ちません)。3.7.10 節の .elfunit・.elfdiff・.elfextra・.elfencode・
.elfrinfo と、3.7.11 節の .elfcfi・.elfcfiinit・.elfcfireg も書き出します。.elfencode と .elfrinfo が名前を挙げる関数そのものは
書き出さないので、関数を定義したパターンファイルと一緒に使ってください。

実例は同梱の elfrel.axx / elfrel.s です。ARM(EM_ARM、40)を .elfbuiltin::0
で組み込みの表なしに記述し、REL の命令フィールド型(R_ARM_CALL・R_ARM_JUMP24・
R_ARM_MOVW_ABS_NC・R_ARM_MOVT_ABS)を出します。命令語とリロケーションは llvm-mc
の出力と一致し、ld.lld -m armelf でリンクした結果も一致します。

3.7.10 対になるリロケーション、書き戻し関数、r_info、単位、グループ

3.7.6〜3.7.9 節の宣言で書けるのは「1 つの参照に 1 つのリロケーション、欄は
ビットの並び、r_info は ELF の決まりの形」という機種です。この節の宣言は、
その外にある機種 — リンカがコードを縮める機種、REL で欄の書き方が込み入った
機種、r_info の並びが違う機種、アドレスをワードで数える機種 — を書くための
ものです。

宣言 決めるもの
.elfextra::<型>::<添える型>[::<シンボル>] その型のリロケーションに、同じ位置へもう 1 つ添える
.elfdiff::<幅>::<足す型>::<引く型> ラベルの和と差(a-b、a-b+c-d+4、-(a-b))を、足す型と引く型の組で出す
.elfdiff::<型>::<足す型>::<引く型> 同じことを .reloc でその型を付けた欄(ULEB128、6 ビットの欄など)に
.elfrelax::<0> / <1> リンカがコードを縮めうるか。0 ならセクションの中の差は定数
.elfencode::<型>::<関数> REL のとき、加数を欄へ書き戻す関数
.elfrinfo::<関数> リロケーション項目の r_info を組む関数
.elfunit::<byte> / <word> 加数とシンボル値(st_value / st_size)の単位
.elfgroup::<名前>::<署名>::<フラグ>::<メンバー>[,<メンバー>...] セクショングループ(SHT_GROUP)
.elflink::<セクション>::<sh_link>[::<sh_info>] セクションヘッダの sh_link と sh_info

.elfextra — 添えるリロケーション。 <型> のリロケーションを出すたびに、
同じ r_offset へ <添える型> を加数 0 で続けて出します。<シンボル> が 0
(既定)なら添えるほうのシンボル番号は 0、1 なら元と同じシンボルです。RISC-V の
call に付く R_RISCV_RELAX がこれで、リンカはこの印を見て auipc+jalr を
jal に縮めます。同じ型に何度でも書けます。

.elftype::relax::51
.elfextra::call::relax          /* call ext -> R_RISCV_CALL_PLT ext, R_RISCV_RELAX */

.elfdiff — ラベルの和と差。 dword a-b のように、欄の値がラベルの
足し引きでできている参照には、.elfdiff がその幅の欄に

  • 足されるラベルそれぞれへの <足す型>
  • 引かれるラベルそれぞれへの <引く型>

を同じ位置に出します。定数部(a-b+4 なら 4)は最初の足す型の加数に置き、足す
ラベルが無い式(-a+5)では最初の引く型の加数に符号を反転して置きます。項目は
足す型を先に、引く型を後に並べます(欄を上書きする SET 型が先に効くように)。
リンカが命令を縮める機種では、同じセクションの中の差でもリンク後に値が変わるので、
この組が要ります(RISC-V の R_RISCV_ADD32 / R_RISCV_SUB32 など)。

  • 取り込む式は、ラベル・数・+・-・括弧だけでできたものです。各ラベルの符号は
    取り込んだ式の綴りから決め、括弧の前の - は中の符号を反転します。
    a-b+c-d+4、-(a-b)、a-(b-c) が書けます。掛け算などを含む式、同じラベルが
    2 回現れる式は曖昧としてリロケーションを出しません。
  • ラベルが 1 つでも符号が負(-a+5)なら、.elfdiff があれば引く型だけで出し、
    無ければ出しません(足す型の加数では表せないため)。
  • RELA では欄そのものは 0 で出します。この種の型は欄の中身に足し引きするので、
    定数は加数の側に置きます(GNU as・llvm-mc と同じ形)。REL では定数が欄に入ります。
  • その幅に .elfdiff が無ければ、リロケーションを出しません(-d で
    報告されます)。

型付きの差。 .elfdiff の第 1 欄に幅ではなく型名を書くと、.reloc で
その型を付けた欄に同じ組を出します。

.elftype::set6::53::1
.elftype::sub6::52::1
.elffield::set6::0x3f                  /* バイトの下位 6 ビット */
.elfdiff::set6::set6::sub6
.reloc::v::set6
ADV6 !v :: 0x40|(v&0x3f)               /* DW_CFA_advance_loc の形 */
.clrreloc::v

.elftype::set_uleb128::60
.elftype::sub_uleb128::61
.elfdiff::set_uleb128::set_uleb128::sub_uleb128
.reloc::v::set_uleb128
ULEB !v :: .call uleb(v)               /* 長さの変わる欄 */
.clrreloc::v
  • 欄の位置と幅は、その型に .elffield があればそれに従い、RELA ではマスクの
    ビットを 0 にします。.elffield が無ければ、この参照が出したワード列そのもの
    が欄で、中身は組み立てた値のまま残します(ULEB128 は、リンカが既存の長さを保って
    書き直すため)。
  • 定数部は .reloc の欄と同じく「オペランドの値 − ラベルの和と差」です。

同じ位置に複数の項目があるとき(REL)。 .elfdiff の対や .elfextra の
添え物は、同じ r_offset に 2 つ以上の項目を作ります。REL では、加数を欄へ書き
戻すのはその位置の最初の項目だけです(後の項目の加数 0 で消さないため)。

.elfencode — 書き戻し関数。 REL では加数を欄に書き戻します。欄が
ビットの並びなら .elffield のマスク・シフト・補正で足りますが、そうでない
欄もあります。

  • MIPS の R_MIPS_HI16 は、続く LO16 の符号付きの下位半分をリンカが足し戻す
    ので、欄には (加数 + 0x8000) >> 16 を入れます(丸め)。
  • Thumb の BL は、ビットの一部が別のビットとの排他的論理和です(J1 / J2)。

.elfencode::<型>::<関数> は、その型の書き戻しをミニ言語(3.15 節)の関数に任せ
ます。関数は (欄の値, 加数) を受け取り、新しい欄の値を返します。欄の値は、
型の幅ぶんのワードを対象のバイト順で読んだ整数です(.elffield のマスクと同じ
読み方)。加数は負になりえます。.elffield と両方あれば .elfencode が書き戻しを
受け持ちます(.elffield はリロケーションの位置と、RELA で欄を 0 にするのに使わ
れます)。RELA では、.elfresolve の型の欄をその場で解決するとき(3.7.7 節)にだけ、
(欄の値, 値) で呼ばれます。

.elftype::hi16::5::4
.elffield::hi16::0xffff
.elfencode::hi16::hi16enc

.func hi16enc(f, a)
.return (f & 0xffff0000) | (((a + 0x8000) >> 16) & 0xffff)
.endfunc
lui 3,%hi(ext+0x18000)    ->  3c03 0002   R_MIPS_HI16 ext      ((0x18000 + 0x8000) >> 16)

.elfrinfo — r_info の形。 ELF64 の r_info は既定で
(シンボル番号 << 32) | 型、ELF32 は (シンボル番号 << 8) | 型 です。MIPS64 は
シンボル番号の後ろに 1 バイトの型を 3 つ(type3 / type2 / type)並べ、
リトルエンディアンで読むと型が最上位バイトに来ます。.elfrinfo::<関数> の関数は
(シンボル番号, 型番号) を受け取り、r_info の値を返します。3 つの型を 1 項目で
持つ複合型は、3 バイトを詰めた型番号を .elftype で宣言すれば書けます。-g の
DWARF のリロケーションにも同じ関数が使われます。ELF32 で 255 を超える型番号の
警告(3.7.7 節)は、r_info の形を関数が決めているときは出しません。

.elfrinfo::rinfo64
.func rinfo64(sym, t)
.return sym | (((t >> 16) & 0xff) << 40) | (((t >> 8) & 0xff) << 48) | ((t & 0xff) << 56)
.endfunc

関数は 2 つの引数を取らなければならず、数を返さなければなりません。名前の無い
関数、引数の数の違う関数は、パターンファイルを読み終えた時点でエラーにします。

.elfunit — 加数とシンボル値の単位。 1 ワードが 8 ビットでない機種
(.bits、3.10 節)では、axx はアドレスをワードで数えます。ELF の r_offset と
sh_size は常にバイトですが、加数とシンボル値をどちらで数えるかは機種の ABI が
決めます。

値 加数 st_value / st_size
byte(既定) バイト(ワードの差 × 1 ワードのバイト数) バイト
word ワード(axx が数えたまま) ワード

1 ワードが 8 ビットの機種では、どちらでも同じ値になります。

.elfrelax — リンカがコードを縮めるか。 1(.elfdiff を宣言したときの既定)
なら、リンカがコードを緩和しうるので、ラベル差はセクションの中のものも足す型・
引く型のリロケーションで書き、3.7.11 節の CFI も位置の進みをリロケーションで
書きます。0(それ以外の既定)なら、リンク時に何も動きません。どのラベルも 1 つの
セクションで定義され、足す項と引く項の数が同じ差は定数で、リロケーションを出さず
欄に書きます。CFI も普通の形です。GNU as の -mno-relax や、緩和なしの llvm-mc が
書くのと同じです。セクションをまたぐ差や外部シンボルとの差は、それでも対になります。

.elfdiff::4::add32::sub32
.elfrelax::0
dword dat2-dat     ->  距離そのもの、リロケーションなし
dword ext-dat      ->  R_RISCV_ADD32 ext   R_RISCV_SUB32 dat

riscv64.axx と riscv64full.axx は 0 です(そこでは R_RISCV_RELAX を出しません)。
それを出す elfpair.axx は 1 を宣言しています。--elfdesc は宣言されたときだけ
これを出します。

.elfgroup — セクショングループ。 SHT_GROUP のセクションを出します。
COMDAT(フラグ 1、GRP_COMDAT)のように、リンカが同じ署名のグループを 1 つに
まとめるためのものです。

  • <名前> はグループのセクション名(普通は .group)、<署名> は署名の
    シンボル名です。署名がシンボル表に無く、セクション名と一致すればそのセクション
    シンボルを使います。どちらでもなければ警告して 0 にします。
  • メンバーのセクションには SHF_GROUP(0x200)が立ち、そのリロケーション
    セクションも同じグループに入ります。
  • グループのセクションはセクションヘッダ表の先頭(メンバーより前、gABI の
    要求)に置かれます。
  • 出力に無いメンバーは警告して読み飛ばします。メンバーが 1 つも無いグループは
    出しません。

.elflink — sh_link と sh_info。 .elfsection(3.7.7 節)が書かない
2 つの欄です。SHF_LINK_ORDER(0x80)のセクションが関連するセクションを指す
ときなどに使います。値はセクション名(出力するセクション、.rela.* / .rel.*、
.symtab、.strtab、.shstrtab、-g の DWARF セクション、大小を区別しません)
か数(10 進か 0x 付き 16 進)です。名前が見つからなければ警告して 0 にします。

.elfsection::.meta::0x82               /* ALLOC+LINK_ORDER  */
.elflink::.meta::.text                 /* sh_link -> .text  */
.elfsection::.text.foo::0x6
.elfgroup::.group::foo::1::.text.foo   /* COMDAT [foo]      */

例。 同梱の 4 組です。どれも同じコードを llvm-mc でアセンブルしたものと
照合しています。

パターン / ソース 機種 見るもの
elfpair.axx / elfpair.s RISC-V(riscv64.axx を include) .elfextra(R_RISCV_RELAX)、.elfdiff(ADD32/SUB32、ADD64/SUB64、多項の式、-(a-b)、型付きの SET_ULEB128/SUB_ULEB128 と SET6/SUB6)、.elfgroup(COMDAT)、.elflink(SHF_LINK_ORDER)、リンカ緩和の機種の CFI。リロケーション・グループ・セクションヘッダが llvm-mc と一致し、ld.lld のリンカ緩和の後も差の値と CFI の表が正しく縮みます
elfmips.axx / elfmips.s MIPS32(REL、ビッグエンディアン) .elfencode(R_MIPS_HI16)と .elffield(R_MIPS_26、R_MIPS_LO16)。命令語・リロケーションが llvm-mc と一致し、ld.lld でリンクした .text もバイト単位で一致します
elfmips64.axx / elfmips64.s MIPS64(n64、リトルエンディアン) .elfrinfo。readelf -r が各項目の 3 つの型を llvm-mc の出力と同じに読みます
elfword.axx / elfword.s 1 ワード 16 ビットの架空の機種 .elfunit::word。加数とシンボル値がワードで書かれます

範囲の外 — 実行ファイルと共有ライブラリ。 axx が出すのは再配置可能
オブジェクト(ET_REL)です。-o(と -E)では、binary_list の中、パターンの
照合(オペランドの取り込みと error_patterns)、.db などの値(5.3 節)で、同じ
セクションのラベルと $$ / $. はセクション先頭からの相対値で埋まります(リンカが
場所を決めるため。-b だけのときは、セクションが順に並んだ平らなイメージの中の番地
です)。.org などの組み込みディレクティブの引数は、どちらでも平らなイメージの中の
番地で読みます。
そのため
実行ファイル(ET_EXEC、プログラムヘッダ付き)を出すには、axx が自分で型ごとの
計算式でリロケーションを解決しなければなりません。それはリンカの仕事そのもので、
共有ライブラリ(ET_DYN、.dynamic / .dynsym / ハッシュ表)も同じです。
番地の決まった生のイメージが要るときは -b を、実行ファイルが要るときは -o の
出力をリンカに渡してください。

3.7.11 CFI — .cfi_* から .eh_frame を組む

ソースに GNU as と同じ .cfi_* 指令を書くと、-o の ELF に .eh_frame
(CIE と FDE)とそのリロケーションセクションが加わります。例外の巻き戻しや
デバッガが、各命令の位置で「呼び出し元のフレームがどこにあるか」を知るための表です。
機種に依存する部分は、パターンファイルで宣言します。

宣言(パターンファイル) 決めるもの
.elfcfi::<戻り番地の列>::<コード整列>::<データ整列>[::<詰め>] CIE の戻り番地のレジスタ番号、コード整列係数、データ整列係数、CIE と FDE を詰める単位(省略時はポインタの大きさ)
.elfcfiinit::<命令> CIE の初期命令。.cfi_ を除いた指令の形で書き、書いた順に並ぶ(def_cfa rsp, 8)
.elfcfireg::<名前>::<DWARF 番号> .cfi_* に書くレジスタ名と、DWARF のレジスタ番号
.elfcfi::16::1::-8                     /* x86-64: RA = rip(16)、code 1、data -8 */
.elfcfiinit::def_cfa rsp, 8
.elfcfiinit::offset rip, -8
.elfcfireg::rbp::6
.elfcfireg::rsp::7
.elfcfireg::rip::16
.elfsection::.eh_frame::0x2::0x70000001   /* SHT_X86_64_UNWIND */

ソースの指令。 書ける指令は次のとおりです。レジスタは .elfcfireg の名前か
数、オフセットは定数式です。

指令 意味
.cfi_startproc [simple] / .cfi_endproc 関数(FDE)の始まりと終わり。simple は CIE の初期命令を使わない
.cfi_def_cfa r, off / .cfi_def_cfa_offset off / .cfi_def_cfa_register r / .cfi_adjust_cfa_offset n CFA(呼び出し元のフレーム)の規則
.cfi_offset r, off / .cfi_rel_offset r, off / .cfi_val_offset r, off レジスタの保存場所
.cfi_restore r / .cfi_undefined r / .cfi_same_value r / .cfi_register r1, r2 レジスタの規則
.cfi_remember_state / .cfi_restore_state 規則の退避と復元
.cfi_return_column r / .cfi_signal_frame CIE の戻り番地の列、シグナルフレーム(拡張文字 S)
.cfi_window_save / .cfi_negate_ra_state DW_CFA_GNU_window_save(0x2d)
.cfi_escape b, ... 命令のバイトをそのまま書く
.cfi_personality enc, sym / .cfi_lsda enc, sym パーソナリティ関数と LSDA(拡張文字 P / L)。符号化は絶対(0x00)か PC 相対(0x10)の 2・4・8 バイトとポインタの大きさ、間接(0x80)の印も書ける。0xff は「無し」
.cfi_sections ... 読み飛ばす(.eh_frame だけを出す)

組み立て。 CIE は拡張文字列 zR(必要なら P・L・S)、FDE の番地の
符号化は DW_EH_PE_pcrel|sdata4(0x1b)です。同じ設定の関数は 1 つの CIE を
共有します。命令の位置の進みは 6 ビット・1・2・4 バイトのうち収まる最小の形で
書き、各命令は GNU as・llvm-mc と同じ形を選びます(オフセットが負なら _sf 形)。
FDE の番地には、実効表の型を宣言順に見て最初の「4 バイトの PC 相対のデータ型
(命令欄の型を除く)」を使います(x86-64 は R_X86_64_PC32、AArch64 は
R_AARCH64_PREL32。RISC-V は R_RISCV_32_PCREL を .elftype で宣言します)。

リンカ緩和の機種。 .elfdiff::4 が宣言されていれば、関数の長さと命令の
位置の進みを、その足す型・引く型の組で書きます(進みは DW_CFA_advance_loc4)。
そのための局所シンボル .Lcfi<n> を、関数の始まり・進む位置・終わりに置きます。
FDE の番地もその局所シンボルに対して書きます。こうすると、リンカがコードを縮めても
表が正しく縮みます。このときコード整列係数は 1 でなければなりません。

誤り。 .cfi_startproc の外の指令、閉じていない関数、データ整列係数で
割り切れないオフセット、remember_state の無い restore_state、知らない
シンボルや符号化、.elfcfi の無いパターンファイルは、エラーにします。

実例は同梱の elfcfi.axx / elfcfi.s(x86-64)と、elfpair.axx / elfpair.s
(RISC-V、リンカ緩和)です。x86-64 では llvm-dwarfdump --eh-frame が読む表が
llvm-mc の出力と一致し、詰めを 4(.elfcfi の第 4 欄)にすると .eh_frame は
バイト単位で一致します。AArch64 でも一致を確かめています。RISC-V では、ld.lld の
リンカ緩和で call が jal に縮んだ後の表が、llvm-mc の出力をリンクしたものと
同じ位置になります。

3.8 省略可能部分 ([[ ]])

二重ブラケットは命令の省略可能な部分を示します:

INC (IX[[+!d]]) :: 0xdd,0x34,d

inc (ix+0x12) は 0xdd,0x34,0x12 を出力します。inc (ix) は 0xdd,0x34,0x00 を
出力します。小文字の変数は既定で 0 だからです。

省略可能部分を書いたときは、閉じの ]] を空白として読みます。[[xxx]]yyy は
xxx yyy です。こうしないと、変数どうしが 1 つの名前につながってしまいます
([[rep]]p は repp ではなく rep p)。省略可能な接頭辞はこの形で書けます:

.setsym::REP::0xf3
.check::rep::REP
[[rep]]MOVSB :: :: ;rep,0xa4
[[rep]]p MOVSB :: :: ;rep,0x60|(p&7),0xa4

movsb は 0xa4、rep movsb は 0xf3 0xa4 です。rep を書かなければ変数は 0 なので、
;rep は何も出しません。

上限。 省略可能部分は、取り除く群の数を 0 個から増やしながら組み合わせを試すので、
できるだけ残す形から当たります。1 つのパターンで省略可能として扱う群は 20 個までで、
それを超えた分は常に含めます。試す組み合わせは 1 つの行につき 65,536 通りまでで、
超えると、当たるはずの行でもそのパターンは不一致として扱います。たとえば 17 個の群の
うち 9 個以上を省く行がこれに当たります。どちらも、そのパターンについて一度だけ、
最初に起きた行の場所を付けて警告します。同梱のパターンファイルの 1 行の群は 7 個までで、
上限には触れません。群が多くなるときは、パターンを複数の行に分けてください。

3.9 パディング

.padding::0x12

アラインメントで使われるパディングバイトを設定します。既定は 0x00。

3.10 8 ビット以外のワード幅 (.bits)

.bits::12
.bits::big::12

ビットスライスプロセッサや、ワードがバイトでないマシン向けです。既定は 8 ビットと
little です。

出力は常に 8 ビット単位なので、4 ビットマシンは 1 バイトあたり下位 4 ビットを出力し、
11 ビットマシンはエンディアンに応じて(下位 8、上位 3)または(上位 3、下位 8)を出力
します。バイト内の未使用ビットは 0 にマスクされます。

.bits が有効なとき、ロケーションカウンタはバイトではなくワードを数えます。
x86_64 のようなバイトアドレスのマシンでは .bits は不要です。

3.11 インクルード

.include "file.axx"

パターン側では、これはマクロ展開の後に処理されるので、マクロが .include 行自体を
生成できます。インクルードされた各ファイルは順にマクロ展開され、トップレベルのパターン
ファイルで定義されたマクロを継承します。

3.12 式中のエスケープ

式の評価はエスケープ文字 \ で停止します。エスケープされた部分は先送りされ、パターン
ファイル内で再度処理されます。

LEAQ r, [ s + t * !h \+ !i ] :: 0x48,0x8d,0x04,((@h)-1)<<6|t<<3|s,i

は leaq rax,[rax+rbx*(2+2)+0x40] にマッチし、

LEAQ r,(s+t*!!h+!!i) :: 0x48,0x8d,0x04,((@h)-1)<<6|t<<3|s,i

は括弧形式 leaq rax,(rax+rbx*(2+2)+0x40) にマッチします。

エスケープは、そのままだと続いてしまう名前を終わらせる役目も持ちます。変数名は小文字・
数字・_ の上を続くので、区切りのつもりの _ は、前にキャプチャがある所ではエスケープ
しなければなりません:

MRS xt,S!S{{p0}}a\_!S{{d8}}b\_C!S{{d16}}c\_C!S{{d16}}e\_!S{{d8}}f
T   xt,!v\_!w

1 行目は mrs x0,s3_3_c4_c2_0 に当たり、5 つの欄を別々に束縛します。2 行目は
t x0,3_5 を 3 と 5 として読みます。エスケープを書かなければ、どちらも _ が変数名に
飲まれて区切りを失います。aarch64.axx は汎用のシステムレジスタの綴りに 1 行目の形を使って
います。この振る舞いのもとになる規則は 3.3 節にあります。

3.13 負のインデックス変位

mov rax,[rbp-8]

は次にマッチします

MOV RAX,[RBP+!e]

パターンが + を持つ位置でソースに - が現れたとき、マッチャは両者を対応させ、
パターンの + をスキップし、- から始まる式を式評価器に渡します。パターンファイルに
特別な記法は必要ありません。

3.14 カスタムエラーメッセージ (.error)

.error::n::"メッセージ本文"

エラーコード n に対して表示される本文を登録します — error_patterns の条件が ;n
で発生させるのと同じ n です(3.4 節)。6 つの組み込みコードのうち 2 つ(4、および
7 以上)はメッセージなしで出荷されます(9 節)。.error はそれらに本文を与え、既存の
コード(1、2、3、5、6)の本文を上書きすることもできます。n は非負の整数式でなければ
ならず、メッセージはダブルクォートで囲んだ文字列リテラルで、.INCLUDE のファイル名
(3.11 節)と同じ \n \t \r \" \\ \xHH \uHHHH \UHHHHHHHH エスケープが
使えます。

.error::4::"このアドレッシングモードでは即値を表現できません。"
.error::9::"シフト量が範囲外です。"
ADD A,!v :: v<0||v>0xff;4 :: 0xc6,v
SHL A,!v :: v>7;9 :: 0xd0,v

add a,300 は既定の空テキストではなく上記のメッセージでコード 4 を報告するように
なり、shl a,9 は新しく定義されたコード 9 を報告します。.setsym と同様、同じ n に
対する後の .error は前のものを上書きしますが、.setsym と違ってこのテーブルには
領域依存の再定義という意味のある概念がないので、実際にはファイル先頭付近にコードごとに
1 つの .error を置くのが自然なスタイルです。メッセージが一度も与えられないコードも
依然としてエラーを発生させ、出力ファイルの書き出しをブロックします。今日の未宣言コード
とまったく同様に、印字されるテキストが空白のままになるだけです。

3.14.1 .echo — 本文行からのデバッグ出力

.echo(<項目>, <項目>, ...)

パターンファイルの本文行に書けるデバッグ出力です。標準エラーへ 1 行出すだけで
ワードは出さないので、足しても消しても生成されるバイト列は変わりません。

項目は "..." の文字列リテラルかパターン層の式で、混ぜて書けます。文字列はそのまま、
式は 256bit 符号つき 10 進で出て、1 回の .echo の項目は空白区切りで 1 行にまとまり
ます。.echo() は空行を出します。体裁はミニ言語の .echo(3.15 節)とマクロ層の
!echo(7 節)と共通の出力ルーチンで決めているので、3 者で揃います。

.setsym::N::7
.echo("head", 1+2, "#N=", #N)      /* -> head 3 #N= 7 */
.echo("tab:\there", "colon::ok")   /* -> tab:<TAB>here colon::ok */
.echo()                            /* -> 空行 */

文字列の逃げ記号はミニ言語の .echo と同じ \\ \" \n \t の 4 つで、それ以外の
\ はエラーです。文字列の中に /* は書けません(パターンファイルのコメント記号として、
.echo が読むより前に落とされるためです)。この行は :: で欄に分解しないので、文字列の
中の :: はそのまま出ます。

いつ出るか。 照合はソース 1 行ごとにパターン表をたどり直すので、.echo の行もソース
1 行につき 1 回実行されます。書いた位置で回数は変わりません(照合は一番具体的な
パターンを選ぶためにパターン表を走査しきります)。命令長を測るだけの試し打ちと収束途中の
パス 1 では黙るので、組み立てた 1 行につき 1 行だけ出ます。ソース 1 行ごとに実行される
ぶん照合は遅くなるので、デバッグが済んだら消してください。

式はパターン層の式なので、#名前(.setsym の数値シンボル)やラベル、$$ が書けます
(6.3 節)。パターン変数 a〜z はディレクティブ行の評価の前に空にされるので、値は
入っていません。

.echo は .sub(3.7.2 節)の中には書けません。.func の本体に書いた .echo は
ミニ言語の文です(3.15 節)。

3.15 ミニ言語 (.func / .call)

binary_list の要素は .call name(引数, ...) にできます。これは小さな手続き型言語で
書かれた関数を実行し、その関数が生成するワードを出力します — .emit に渡した値と、
戻り値があればそれが続きます。この言語には代入、.if/.elif、.while、.for、再帰、
配列、文字列があるので、固定式として書けないエンコーディングを計算で求められます。.echo は
何も出力せずに標準エラー出力へ印字し、関数がなぜその結果を生んだかを調べるのに使えます
(同じ .echo はパターンファイルの本文行にも書けます。3.14.1 節)。

関数はパターンファイルのトップレベルで定義します:

.func <name>(<引数, 引数, ...>)
<文>
.endfunc

ヘッダと対応する .endfunc の間のすべてが本体です。それらの行が通常のパターン行として
マッチされることはありません。引数は空でも構いません (.func name()、あるいは単に
.func name) — それを呼び出す .call name(...) と同じ形です。古い
.func::name::params ヘッダも依然として読まれます。.func の直後の :: がそれを選ぶ
ので、既存のパターンファイルは動き続けます。

MOV a,!b,!c :: .call name(a,b,c)

呼び出し側の引数は通常の axx パターン式なので、そこでの a、b、c はキャプチャされた
パターン変数を意味します。関数の内側ではそれらが引数になり、その呼び出しに対してローカル
です。.call は他と同じくカンマ区切りの 1 要素なので、素の値と混在できます:

MIX !e :: 0x90,.call rep(e),0xff

[e1, e2, ...] と書かれた引数は配列です。その要素もパターン式で、"..."・.exp(変数)・
文字列シンボルの名前を書けば文字列の要素になります。[] は空配列です。

LOG !v :: .call table([0x11,0x22,v],3)

"..." と書かれた引数は文字列です(下記「文字列」)。文字列の中のカンマや括弧で
引数が割れることはありません。

MSG !n :: .call func1(n,"text")

.exp(変数) と書かれた引数は、そのパターン変数がソースから拾った綴りの文字列です。
テキストテンプレートの {{.exp(変数)}}(3.18 節)が出すものと同じで、どの捕捉子で
拾った変数でも使えます。

SPELL !x,r :: .call func1(x,.exp(x),.exp(r))     /* spell 1+2*3,rb → func1(7, "1+2*3", "rb") */

.islabel(変数) と書いた引数は、そのパターン変数が拾った綴りがラベルを含めば
数 1、含まなければ 0 です。ここでのラベルは、name: で定義したもの、外部のもの、
リロケーション型を持つ .equ、まだ定義されていない名前(前方参照)です。数・文字定数・
文字列・$$・#記号・パターンの記号・定数の .equ は数えません。綴りを走査する
だけで評価はしないので、どのパスでも同じ答えになります。既知の値なら短くし、
リンカが埋めるシンボルなら決まった形を保たなければならない疑似命令のためのもので、
GNU as は SPARC の set と setx をそうしています。

.reloc::v::hi22::::lo10@4
SET !v,rd :: .call setuw(rd,v,.islabel(v))   /* set ext,%o0 -> sethi %hi + or %lo */
.clrreloc::v

引数が文字列シンボル(3.6 節、.setsym::名前::"...")の名前 1 つだけなら、その
文字列が渡ります。.call func1(10,"...") と直接書いたのと同じに読むので、逃げ記号も
同じものが開きます。名前の大文字・小文字は区別しません。msg+1 のように式の一部に
なっているときは今までどおり式として読み、同じ名前のパターン変数があっても {{名前}} と
同じく文字列シンボルが先に当たります。

.setsym::msg::"text"
MSG :: .call func1(10,msg)          /* func1(10, "text") */

引数が配列シンボル(3.6.1 節、.setsym::名前::[...])の名前 1 つだけなら、その配列が
渡ります。数の項目は整数、"..." の項目と裸の名前(AX など)の項目は文字列
({{名前[i]}} が出すものと同じ)です。同じ名前の文字列シンボルがあればそちらが先に
当たり、配列の中([regs])には書けません。

.setsym::regs::[AX,BX,0x10]
REGS :: .call func1(regs)           /* func1(["AX", "BX", 16]) */

3.5 節の ; 修飾子は .call にも適用されます。;.call f(a) は、
その呼び出しの出力全体が 0 に等しい単一ワードのとき何も出力しません。これは時々存在
しないプレフィックスバイトの書き方です。;;.call f(a) は呼び出しを実行してその出力を
捨てます。

文

文 意味
name = expression ローカル変数への代入
name[index] = expression 配列要素への代入
name[lo:hi] = expression 範囲の置き換え。lo から hi の手前までを右辺(文字列には文字列、配列には配列)で置き換える。長さは変わりうる
.emit(e1, e2, ...) 整数 1 つにつき 1 ワードを出力に追加。文字列は 1 バイト 1 ワード、配列は要素ごと(文字列の要素は 1 バイト 1 ワード)
.echo(item, item, ...) 文字列と値を標準エラー出力へ印字 — デバッグ専用、何も出力しない
.raise <expr> エラーコードが <expr> の値であるエラーを報告
.call name(args) 別の関数を呼ぶ
name = .call name(args) 別の関数を呼び、その戻り値を代入
... .call name(args) ... 式の中の項としての呼び出し — その値は戻り値
.if <expr> .then / .elif <expr> .then / .else / .endif 条件分岐。.elif は繰り返せ、.else は省略可
.while(<expr>) / .endwhile 条件が非零の間ループ
.for <name> in range(...) / .next range(stop)、range(start, stop)、range(start, stop, step) 上のループ
.for <name> in <配列> / .next 配列の要素(整数か文字列)を添字 0 から順に回すループ。回り始める前に写しを取るので、本体で配列を書き換えても回る要素は変わらない
.nonlocal a, b これらの名前をローカルではなく外側の呼び出しに束縛する
.return 関数から戻る。本体のどこにでも(トップレベルでも .if/.while/.for の中でも)、何度でも書ける
.return <expr> 関数から値を返す
.endfunc 関数本体を閉じる(上記参照)

.emit は値 1 つにつき .bits 幅のワードを 1 つ追加します — 既定幅なら 1 バイトです。
呼び出しが出力するワード数が命令の長さになるので、アドレスが収束するためには関数が
両方のパスで同じ個数を出力しなければなりません。

.if と .elif の行は .then で終わらなければなりません。.if の後に任意個の
.elif 分岐が続けられ、.else が連鎖を閉じ、1 つの .endif が連鎖全体を終えます:

.if n > 100 .then
.emit(0xff, n & 0xff)
.elif n > 10 .then
.emit(0xfe, n & 0xff)
.else
.emit(n & 0xff)
.endif

.echo は .emit のデバッグ版です。標準エラー出力へ書き、出力には何も追加しないので、
これを足したり消したりしても生成バイトが変わることはありません。各項目は "..." 文字列
リテラルか式で、両者を混在できます:

.echo("Example", n, 1)          /* -> Example 7 1 */
.echo("n=", n, "arr=", a)       /* -> n= 7 arr= [7, 14] */

文字列は書いたとおりに、整数は符号付き 10 進で、配列は [1, 2, 3](文字列の要素は
["ab", 1] のように " で囲む)として印字され、
1 回の呼び出しの項目はスペース区切りで 1 行を共有します — マクロ層の !echo が使うのと
同じ出力ルーチンなので、両者は一致します。項目なしの .echo() は空行を印字します。
アセンブラが命令長を測定している間やパス 1 で収束している間は何も印字されないので、
各行はリラクゼーションの反復ごとではなく、アセンブルされた命令ごとに一度現れます。

項目には式で作った文字列も書けます(.echo("n=" + n))。文字列は書かれたバイトのまま
出し、NUL(.chr(0))だけは \0 と書いて出します。

.raise <expr> は、エラーコードが <expr> の値であるエラーを報告します。error_patterns
フィールドが condition;code に対して生成するのとまったく同じ形式です
(3.4 節)。.error::code::"text" で登録されたメッセージも同じ
ように使われ、未登録のコードは番号だけを印字します。報告は関数を止めません — 実行は次の
文へ続くので、そこで止めたければ後に .return を置いてください — そして .echo と同様、
命令長を測定しているだけの間とパス 1 のリラクゼーション中は静かにしているので、アセンブル
された各命令は多くとも一度だけ報告します。発火した error_patterns と同様に、アセンブルは
失敗し出力ファイルは書かれません。

.error::3::"immediate out of range"

MOV !n :: .call mov(n)

.func mov(n)
.if n > 255 .then
.raise 3
.return
.endif
.emit(0xb0, n)
.return
.endfunc

値は 256 ビット 2 の補数整数で、axx の他のあらゆる場所と同じです。演算子は、緩いものから
きついものへ: ||、&&、!、比較 (== != < <= > >=)、|、^、&、<< >>、
+ -、* / %、単項 - + ~、**、添字。/ はゼロ方向へ切り捨て、% は被除数の符号を
取ります。>> は算術シフトです。

4 つの項は代わりにアセンブラ自身の式評価器に渡されます: $$、$.、#name、および
どのローカル変数も主張しない裸の名前(ラベルまたは .equ として読まれます)。双方とも
256 ビットなので、値はそのまま使える形で返ってきます。

BR !t :: .call rel8(t)

.func rel8(target)
d = target - $.
.if d < -128 || d > 127 .then
.echo("branch out of range:", d)
.endif
.emit(d & 0xff)
.return
.endfunc

パターン変数と !!! はそこでは利用できません。.func 本体の実行中はそれらを束縛
しているものが何もないからです。代わりに呼び出し側で .call f(a,b) として渡してください。
6.3 節に完全な表があります。未定義ラベルから導かれた値は 0
として渡され、.call の引数と同じ扱いなので、巨大なセンチネル値がループ回数を吹き飛ばす
ことはありません。

戻り値

.return <expr> は値を返し、呼び出し側は var = .call name(args) でそれを受け取ります:

.func hypot2(a,b)
.return a*a+b*b
.endfunc

.func emit_h(a,b)
v = .call hypot2(a,b)
.emit(v)
.return
.endfunc

値は数値でも配列でもよく、配列はコピーとして渡されます。代入先は配列要素でもよく
(a[i] = .call f(x))、その場合返される値は数値か文字列でなければなりません。何も返さない関数を
この形で呼ぶのはエラーです。

.call name(args) はより大きな式の中の項としても現れられ、そこでは関数が返す値を
表します:

d = .call hypot2(a,b) + .call hypot2(c,e)
.if(.call firstdiv(n) == n)
m = t[.call idx(k)]

呼び出しは別の呼び出しの引数の中に入れ子にでき、その引数は通常の式です。何も返さない
関数はこの形では使えません — 代入形式と同様にエラーです。.return は本体を閉じません —
それをするのは .endfunc だけです — ので、.return <expr> はブロックの内側からの
早期リターンとしても、何度でも使えます:

.func firstdiv(n)
i=2
.while(i<n)
.if n%i==0 .then
.return i
.endif
i=i+1
.endwhile
.return 0
.endfunc

関数が binary_list から直接呼ばれたとき、その戻り値は出力になります。数値は 1 ワード、
配列はインデックス 0 から要素 1 つにつき 1 ワード(文字列の要素は 1 バイトにつき 1 ワード)、
文字列は 1 バイトにつき 1 ワードです(テキスト置換モードでは文字列はテキストとしても
出ます。3.18 節)。これは .emit に渡したものに
加えてなので、.emit するだけで何も返さない関数は従来とまったく同じ振る舞いをします。

SEQ !n :: 0xaa,.call seq(n),0xbb

.func seq(n)
a=[]
.for i in range(n)
a[i]=0xc0+i
.next
.return a
.endfunc
seq 4                -> aa c0 c1 c2 c3 bb

配列

配列は []、[e1, e2, ...] と書くか、スライスで生成します。配列は関数の引数としても
渡せます。関数間でも、binary_list の呼び出し側からでも可能です。

a = []
a[3] = 5          /* a は [0,0,0,5] になる — 隙間は 0 で埋められる */
.emit(a[0])       /* 0 */
.emit(a[99])      /* 0 — 末尾を超えた読み出しは 0 を返し、拡張しない */
.emit(.len(a))    /* 4 */
b = a[1:3]        /* [0,0] — 終端インデックスは含まれない */

末尾を超えた代入は配列をゼロで拡張します。末尾を超えた読み出しや負のインデックスでの
読み出しは 0 を返し、配列はそのままです。スライスの境界は配列にクランプされます。
.len(x) は長さです。配列要素は数値か文字列で、配列にはなりません(a = ["ab", 1]、
a[i] = "x")。

配列の範囲の置き換え a[lo:hi] = 右辺 の右辺は配列でなければなりません。文字列を書くと、
要素に分解されることはなく、エラーになります。文字列 1 つを要素として入れたいときは、
[...] で包んで要素 1 つの配列にします。

a = [1, 2, 3]
a[1:2] = "qwert"       /* エラー: an array slice can only be given an array */
a[1:2] = ["qwert"]     /* [1, "qwert", 3] — 要素 1 つを文字列 1 つで置き換える */
a[1:2] = [7, 8, 9]     /* [1, 7, 8, 9, 3] — 要素 1 つを 3 つで置き換え、長さが変わる */
a[1:2] = []            /* [1, 3] — 要素を取り除く */

(どの行も a = [1, 2, 3] に対して書いたときの結果です。)

文字列

値は整数・配列のほかに文字列も取れます。"..." と書き、式の中、変数への代入、
関数の引数と返り値のどこにでも使えます。binary_list からは .call func1(10,"text")
のように渡します。

文字列はバイトの並びです。ソースに書いた文字は UTF-8 のバイトとして入るので、
"あ" の長さは 3 です。長さも添字もバイト単位で、両実装で同じ値になります。

書き方 結果
"ab" + "cd" "abcd"(連結)
"n=" + 7、7 + "!" "n=7"、"7!"(整数は符号付き 10 進にしてつなぐ)
"ab" * 3、3 * "ab" "ababab"(繰り返し。0 以下なら "")
s == t、s != t 中身が同じかどうか。文字列と整数は常に等しくない
s < t など バイト順の辞書式比較。文字列と整数は比べられない(エラー)
s[i] i バイト目の値(0〜255)。範囲外・負は 0
s[lo:hi] 部分文字列。配列と同じく範囲に切り詰め、hi は含まない
s[i] = v i バイト目を書き換える。v は 0〜255 の整数か 1 バイトの文字列。末尾より先なら NUL(0)で埋めて伸ばす
s[lo:hi] = t 範囲を文字列 t で置き換える。長さは変わりうる("abc" に s[1:2] = "10000" で "a10000c")。境界は s[lo:hi] と同じく切り詰め、lo == hi なら挿入
.len(s) バイト数
.str(v) 整数を符号付き 10 進の文字列にする。文字列はそのまま
.chr(n) 値 n(0〜255)の 1 バイトの文字列
.int(s) 文字列を整数として読む。前後の空白、+ -、0x 0b、_ を受け付ける。読めなければエラー
.func label(n, s)
t = s + ":" + n           /* "loop:3" */
.emit(.len(t))
.emit(t)                  /* 1 バイトを 1 ワードとして出す */
.return t[0:1] * 2        /* "ll" */
.endfunc

.emit(s) も、binary_list から呼んだ関数が返した文字列も、各バイトを 1 ワードとして
順に出します。文字列は 1 バイトずつ書き換えられ(s[i] = 65 と s[i] = "A" は同じ意味。
写しで渡るので他の変数には影響しない)、配列の要素にもなりますが、
条件や算術(.if s .then、s - 1)にも使えません。エスケープは \\、\"、\n、
\t の 4 つで、それ以外の \ はエラーです。NUL は .chr(0) で作ります。文字列の中には
/* も :: も書けます(3.1 節「文字列の中」)。長さの上限は配列と同じです。

スコープと入れ子

各呼び出しは自分の変数を持ちます。設定される前に読まれた名前はエラーなので、タイプミスが
黙ってゼロを読むことはありません。

関数は他の関数の中で定義できます。内側の関数は外側の関数から見え、名前を外向きに解決
します。.nonlocal を使うと、自分のものを作る代わりに外側の呼び出しの変数へ代入でき
ます:

.func outer()
n=7
.func inner()
.nonlocal n
n=n+1
.emit(n)
.return
.endfunc
.call inner()
.call inner()
.emit(n)
.return
.endfunc
-> 08 09 09

.nonlocal は、その関数内でその名前が他の用途で使われる前に現れなければなりません。

例

篩(ふるい)と、エンコーディングが Collatz のステップ数である命令:

PRIMES !n  :: .call sieve(n)
COLLATZ !n :: .call collatz(n)

.func sieve(n)
mark=[]
mark[n]=0
i=2
.while(i*i<n)
.if mark[i]==0 .then
j=i*i
.while(j<n)
mark[j]=1
j=j+i
.endwhile
.endif
i=i+1
.endwhile
.for k in range(2,n)
.if mark[k]==0 .then
.emit(k)
.endif
.next
.return
.endfunc

.func collatz(n)
c=0
.while(n!=1)
.if n%2==0 .then
n=n/2
.else
n=3*n+1
.endif
c=c+1
.endwhile
.emit(c)
.return
.endfunc
primes 50            -> 02 03 05 07 0b 0d 11 13 17 1d 1f 25 29 2b 2f
collatz 27           -> 6f

同じ内容は MINI.md(日本語)と mini_en.md(英語)に独立した文書として保管されて
います。

実在 ISA での実践例

aarch64_logical_mini.axx は AArch64 の論理即値グループ(AND / ORR / EOR / ANDS / TST、
32 ビットと 64 ビット)をこの方法でエンコードします。ARM の DecodeBitMasks を逆向きに
実行するものが 4 つの関数 — highbit、find_e、pack_rs、emit_logical — に分割
されており、おかげで各命令行は短く済んでいます:

AND  d,n,#!v ::v==0;3,v==0xFFFFFFFFFFFFFFFF;3 :: .call emit_logical(v,1,0,n,d,64)

付録 A.3は同じエンコーディングを、単一の連鎖三項演算子による
binary_list として書いたものを示します。ミニ言語はまさにそれを置き換えるために
あります。どちらも同じ 256 ビット演算で計算します。関数形式が得るのは、各呼び出しが
自分のローカルスコープを持つのでその作業変数がパターン層のキャプチャ変数と衝突しない
こと、そして 1 つの本体が両方の幅に対応できることです — 32 ビット形式は要素サイズの
探索を 64 ではなく 32 に制限するだけですが、binary_list 版では幅を式の中に折り込む
必要があります。

ELF の書き出しから呼ばれる関数

binary_list の .call のほかに、-o の ELF を書くときに axx が関数を呼ぶ宣言が
2 つあります(3.7.10 節)。

宣言 引数 返り値
.elfencode::<型>::<関数> (欄の値, 加数) REL で書き戻す新しい欄の値
.elfrinfo::<関数> (シンボル番号, 型番号) リロケーション項目の r_info

引数は 2 つ、返り値は数(配列と文字列は不可)で、違えばエラーです。加数は負になりえます
(256 ビットの 2 の補数で渡るので、>> と & で必要なビットを取り出します)。
ここで .emit した値は出力ワードになりません。

制限

この言語はチューリング完全なので、バグのあるパターンファイルがそのままではアセンブラを
ハングさせかねません。次の上限がそれを防ぎ、代わりに問題の行を報告します:

上限 値
.call ごとに実行される文の数 4,000,000
呼び出しの入れ子 128
.call ごとに出力されるワード数 1,048,576
配列長・文字列のバイト数 1,048,576
式の入れ子(括弧・[ ]・単項 - + ~ !) 1,000
文の入れ子(.if .elif .while .for) 1,000

最後の 2 つは構文の上限で、パターンファイルを読んだ時点で報告されます。

未定義ラベルから来た引数は 0 として渡されるので、前方参照が最初のパスでループ回数を
吹き飛ばすことはありません。

3.16 .passthru — マッチしない行の素通し

既定では、どのパターンにもマッチしないソース行は Syntax error(コード1)になり、
出力は破棄されます。.passthru はその行をエラーにせずそのままテキストとして出す
ように切り替えます。トランスレータとして使うとき(3.5.2 節のテキストテンプレート)、
書き換えたい行だけをパターンに書き、残りを通したい場合のためのものです。

.passthru          /* on と同じ */
.passthru::on      /* 素通しする */
.passthru::off     /* 素通しをやめる(既定) */

行末の改行はこのディレクティブの仕事ではありません。1行が1行になるようにしたいときは
.eol(3.17 節)を併せて書きます。

素通しされた行は、エンコーディング欄が "<その行>" というテキストテンプレートだった
パターンにマッチしたのと同じ扱いになります。つまり UTF-8 の 1 バイトが 1 ワードとして
出力され、ロケーションカウンタもその分進み、-V を付ければ標準出力にもテキストとして
出ます。両方のパスで同じテキストを出すので、素通しした行のあとのラベルも正しい
アドレスになります。

.bits::8
.passthru
.eol
.map::r::AX,BX,CX
.setsym::rn::[AX,BX,CX]
MOV r,!e::"LD {{rn[r]}},0x{{.hex(e)}}"
	mov	bx,5        ->  LD BX,0x5
	xyzzy	foo, bar    ->  xyzzy foo, bar     /* 素通し */
	r1 = r2 + r3        ->  r1 = r2 + r3       /* 素通し */

出るのは照合にかけた形の行です。タブや連続した空白は 1 つの空白に詰められ、; から
始まるコメントと行頭のラベル定義は落ちています(ラベルはラベルとして登録されます)。
テキスト置換モード(3.18 節)では、そのコメントとラベル定義が書かれていたとおりの綴りで
出力に戻り、行頭の字下げ(空白・タブ)も書かれていたとおりに戻ります。

パターンファイルは 1 行ごとに全部走査されるので、.passthru はファイル全体にかかる設定
として働きます(同じファイルに複数書いた場合は最後のものが効きます)。

.ascii や .resb のような組み込みのアセンブリディレクティブ(5.3 節)は素通しより先に
処理されるので、そのままの意味で働きます。一方、.aling のような綴り違いは素通しされ
ます
— 素通しを有効にすると、書き損じがエラーにならずそのまま出力に流れることに
注意してください。

3.17 .eol — 行ごとに改行を入れる

テキスト変換のための設定です。出力を出した行ごとに改行(\n)を 1 ワード足します。
テキストテンプレートの一つ一つに \n を書いて回らなくても、ソースの 1 行が出力の 1 行に
なります。

.eol          /* on と同じ */
.eol::on      /* 行ごとに改行を足す */
.eol::off     /* 足さない(既定) */
.bits::8
.eol
.map::r::AX,BX,CX
.setsym::rn::[AX,BX,CX]
MOV r,!e::"LD {{rn[r]}},0x{{.hex(e)}}"
NOP::"NOP"
	mov	ax,0x10     ->  LD AX,0x10\n
	nop                 ->  NOP\n
  • 足すのは出力ワード列の側だけです。標準出力へ流すテキスト(-V のトランスレータ
    としての出力)には足しません — そちらは行ごとに改行して出しているので、二重に改行
    しないようにしてあります。つまり -b/-o のファイルには改行が入り、標準出力の
    見た目は変わりません。
  • 出力ワードを 1 つも出さなかった行には足しません(コメントだけの行、何も出さない
    パターン、.section のようなディレクティブ行)。.ascii などが直接書き出すバイトと、
    .db / .dw / .dd / .dq / .do / .dy / .dz の行(5.3 節)にも足しません。テキスト置換モード(3.18 節)ではコメントだけの行も
    ディレクティブの行もテキストを出すので、そちらには改行が入ります。
  • .vliw が有効なときは、パケットを壊さないよう何もしません。
  • .passthru(3.16 節)で素通しした行にも、同じように改行が入ります。

パターンファイルは 1 行ごとに全部走査されるので、これはファイル全体にかかる設定として
働きます(同じファイルに複数書いた場合は最後のものが効きます)。

3.18 .textmode — テキスト置換モード

ソースを別の書式のテキストへ書き換える(トランスレータとして使う)ための設定です。
次の 5 つをまとめて行います。

.textmode          /* on と同じ */
.textmode::on      /* テキスト置換モードにする */
.textmode::off     /* やめる(既定) */
  1. .passthru(3.16 節)を立てる — マッチしない行はそのまま出ます。
  2. .eol(3.17 節)を立てる — ソースの 1 行が出力の 1 行になります。
  3. !L(下記)が拾った式の中の未定義ラベルをエラーにしません。値は 0 になり、
    {{.exp()}} は書かれたとおりの文字を出します。
  4. ソースの ; コメントを落とさず、書き換えたテキストの後ろに付けて出します
    (下記)。
  5. ソースの行頭の字下げ(空白・タブ)を落とさず、書き換えたテキストの前に付けて
    出します
    (下記)。

.passthru と .eol はまとめて動くので、どれかだけを別にしたいときはこの行の
後ろでそちらを書きます(ディレクティブは書いた順に効きます)。

テキスト置換モードでは、-V は -b が書くのとまったく同じバイト列を、ファイルの
代わりに標準出力へ書きます。書き換えたテキストと .eol が足す改行のほか、テキストで
ない出力、たとえばミニ言語の関数が .emit に渡したワードや返した数(3.15 節)も出ます。
各ワードのバイトは -b のファイルと同じく .bits の幅とバイト順に従います。.eol を
切ったときは、標準出力でも改行は足されません。テキスト置換モードでないときの -V は、
今までどおり文字列テンプレートで組み立てたテキストをソースの 1 行につき 1 行で出します。

!L<変数> — 式・ラベル捕捉子

!<変数>(3.3 節)とまったく同じように式を 1 つ読んで値を束縛し、そのうえで
「ソースに書かれていたままの文字」も覚えます
。テキストテンプレートの
{{.exp(<変数>)}} がその文字をそのまま出します。文字を覚えるのは !L だけでなく、
どの捕捉子も同じです(下記「どの捕捉子でも綴りを覚える」)。!L が違うのは、テキスト
置換モードで、ソースのどこにも定義のないラベルを拾ってもエラーにしないことです。

.textmode
LXI H,!La :: "LD HL,{{.exp(a)}}"
JMP  !La  :: "JP {{.exp(a)}}"
	lxi	h,msg       ->  LD HL,msg
	lxi	h,0x1234+2  ->  LD HL,0x1234+2
	jmp	loop        ->  JP loop

(矢印の右は行頭の字下げを省いて示しています。実際の出力には左と同じ字下げが付きます
— 下記「行頭の字下げ」を参照してください。)

値ではなく綴りが要るのはこの場合です。{{.hex(a)}} で書けばラベルは 0x122 のような
数値に潰れてしまい、書き換えた結果からラベルが消えます。{{.exp(a)}} なら msg は
msg のまま、0x1234+2 は 0x1234+2 のまま出ます。ここで !a ではなく !La で
拾うのは、翻訳するソースには、そのファイルのどこにも定義のないラベル(別のファイルで
定義されるものなど)がよく出てくるからです。!a で拾うとそれがエラーになりますが、
!La なら値を 0 として続けます。同じファイルの後ろで定義する前方参照は、どちらでも
エラーになりません。

  • 値の側は今までどおり使えます。同じ行で {{.exp(a)}} と {{.hex(a)}} の両方を
    書けますし、error_patterns で a>0xffff;2 と検査もできます。
  • 拾う範囲は !<変数> と同じで、!La\, のように \ で停止文字も指定できます。
    前後の空白は落として覚えます。
  • [[ ]](3.8 節)の中に入っていてその回は拾わなかったときは、{{.exp()}} は
    空文字になります。変数として使われていない名前を {{.exp()}} に書いたときは
    書き損じなのでエラーになります。
  • テキスト置換モードでないときの !L は ! とまったく同じに振る舞います
    (未定義ラベルはエラーです)。文字を覚えるのはどちらでも同じです。

どの捕捉子でも綴りを覚える

綴りを覚えるのは !L だけではありません。instruction フィールドのどの書き方で
拾った変数も、!L と同じように値と綴りの両方を覚え、{{.exp(<変数>)}} がその綴りを
出します。ミニ言語の .call の引数に .exp(<変数>) と書けば、同じ綴りを文字列として
関数へ渡せます(3.15 節)。!L との違いは、テキスト置換モードで未定義ラベルを許すかどうかだけです。

書き方 {{.exp()}} が出す綴り
小文字変数 当たったシンボルの名前(b、cx など)
!x 読んだ整数式
!!x 読んだ整数因子
!Fx !Dx !Qx 読んだ浮動小数点式
!Ex 列挙リスト全体(a0-a2 など)
!S{{name}}x 当たったエントリのパターンが拾った範囲全体
!Lx 読んだ式・ラベル
!Yx[z] 読んだ項目名(綴りは z が覚える)
.textmode
.check::r::B,C,D
MOV r,r2       :: "mov {{.exp(r)}}<-{{.exp(r2)}} ; {{.hex(r)}},{{.hex(r2)}}"
EXPR !a        :: "expr [{{.exp(a)}}] = {{.hex(a)}}"
LD!S{{sz}}s !a :: "ld [{{.exp(s)}}] = {{.hex(s)}} [{{.exp(a)}}]"
.sub::sz
.B::1
.W::2
.endsub
	mov	c , b      ->  mov c<-b ; 1,0
	expr	1+2*3      ->  expr [1+2*3] = 7
	ld.b	0x10+1     ->  ld [.b] = 1 [0x10+1]
  • 前後の空白と、\, のような停止文字は綴りに入りません。
  • !S{{name}} は入れ子にできますが、外側の変数の綴りは内側の範囲を含みます
    (X!S{{inner}}i のエントリに x2 が当たれば、外側は x2、内側は 2)。
  • [[ ]] の中に入っていてその回は拾わなかった変数や、.check で省略を許した
    小文字変数が省かれた回は、空文字になります。
  • 同梱の expcap.axx / expcap.s がすべての書き方を確かめるテストです。

行頭の字下げ

テキスト置換モードでは、ソースの行頭にあった字下げ(空白・タブ)が書かれていた
とおりに出力の先頭に付きます
。ソースの見た目がそのまま翻訳結果に残るので、訳した
結果をそのまま人が読めますし、アセンブラにも通せます。

	lxi	h,msg
here:	nop
	nop
	; 字下げしたコメントだけの行
	LD HL,msg
here: NOP
	NOP
	; 字下げしたコメントだけの行
  • 出るのはタブと空白で、書かれていたとおりの綴りです(タブはタブのまま出ます)。
    照合のために空白は 1 つに詰めていますが(3.16 節)、字下げはここで元に戻します。
  • 付けるのは label: と ; コメントを付け直した後の行全体の先頭です。字下げと
    その後ろの間に余分な空白は入りません。行頭にラベルのある行は字下げが無いので、
    今までどおり行の先頭から出ます。
  • 空行と空白だけの行は今までどおり何も出しません(字下げだけを出す行は作りません)。
  • 字下げを付けるのはテキストを出した行です。テキストではなく数値を出した行
    (.ascii など 5.3 節の組み込みディレクティブ)はデータを壊さないようそのままに
    します。.vliw が有効なときは、.eol と同じくパケットを壊さないよう何もしません。
  • テキスト置換モードでないときの .passthru(3.16 節)は今までどおりで、字下げは
    残りません。
  • ラベルの値は、その行が出す字下げを含めた先頭を指します。両方のパスで同じ
    テキストを出すので、行の大きさもラベルの値も 2 つのパスで一致します。

この節で矢印(->)を使って示している例は、行頭の字下げを省いて書き換えたところだけを
並べたものです。実際の出力には、矢印の左と同じ字下げが付きます。

行頭の label:

テキスト置換モードでは、行頭のラベル定義がそのまま出力の先頭に付きます。
ラベルはラベルとして登録されたうえで、書かれていたとおりの綴りで出力にも残るので、
書き換えた結果をそのままアセンブルできます。

	lxi	h,msg
here:	nop
msg:
	LD HL,msg
here: NOP
msg:

ラベルだけの行も 1 行として出ます。テキストではなく数値を出した行
(.ascii など 5.3 節の組み込みディレクティブ)はデータを壊さないよう、
ラベルを付けずそのままにします。.vliw が有効なときは、.eol と同じく
パケットを壊さないよう何もしません。

ラベルの値は、その行が出す字下げとラベルの綴りを含めた先頭を指します。両方の
パスで同じテキストを出すので、行の大きさもラベルの値も 2 つのパスで一致します。

; コメント

テキスト置換モードでは、ソースの ; コメントが書かれていたまま出力に残ります。
書き換えたテキストの後ろに、間に空白 1 つを置いて付きます。

	mvi	c,9		; BDOS function 9    ->  LD C,9 ; BDOS function 9
	.org	0x100		; 0x100 にロード     ->  .org 0x100 ; 0x100 にロード
here:	; ラベルの後ろだけコメント           ->  here: ; ラベルの後ろだけコメント
; 行全体がコメントの行               ->  ; 行全体がコメントの行
  • 行全体がコメントの行も1 行として出ます。テキスト置換モードでないときは
    今までどおり、何も出しません。
  • 文字列 "..." や文字リテラル 'x' の中の ; は本物のデータなので、コメントの
    始まりとは見ません。\; と書いた ; も、バックスラッシュを外したただの ; に
    なるだけでコメントは始めません(3.2 節)。
  • コメントを付けるのは、テキストを出した行と、コメントだけ・ラベルだけの行です。
    テキストではなく数値を出した行はデータを壊さないようそのままにします。
    .vliw が有効なときは、.eol と同じくパケットを壊さないよう何もしません。
  • .include の行のコメントは出しません。取り込んだ先の行が訳されて出た後に
    その行のコメントだけが出てくると、順序が入れ替わって読めなくなるからです。
  • ラベルの値は、コメントを含めたその行の先頭を指します。両方のパスで同じテキストを
    出すので、行の大きさもラベルの値も 2 つのパスで一致します。

組み込みディレクティブの行

テキスト置換モードでは、axx 自身の組み込みアセンブリディレクティブ(5 節)の行も
テキストとしてそのまま出ます。翻訳結果から .org や .section の行が消えて
しまわないようにするためです。

	.org	0x100        ->  .org 0x100
	.section .text       ->  .section .text
	.global	start        ->  .global start
buf:	.resb	16           ->  buf: .resb 16
msg:	.ascii	"Hello"      ->  msg: .ascii "Hello"
val:	.equ	0x1234       ->  val: .equ 0x1234
  • .org .align .zero .ascii .asciz .resb .resw .resd .resq、
    .db .dw .dd .dq .do .dy .dz は、テキストとして出すだけで自分では何も出しません。詰め物や生のデータを
    出しながらその行のテキストも出すと中身が二重になり、書き換えたテキストに
    混ざってしまうからです。テキスト置換モードでの出力は「書き換えたテキスト
    そのもの」なので、-b に書いたファイルは翻訳結果のテキストそのままになります。
  • .section .endsection .labelc .extern .reloctype .export .global、
    そして label: .equ 式 は、今までどおり効いたうえでテキストとしても出ます。
  • .include だけは出しません。取り込んだ先の行がその場で訳されて出るので、
    二重になるのを避けるためです。

パターンファイルは 1 行ごとに全部走査されるので、これはファイル全体にかかる設定として
働きます(同じファイルに複数書いた場合は最後のものが効きます)。

.call が返す文字列

テキスト置換モードでは、binary_list に書いた .call(3.15 節)が文字列を返すと、
その文字列はテキストとしても出ます。バイト列は -b のファイルに入り、同じ文字列が
-V にも出ます。"..." のテキストテンプレートと同じ扱いです。行頭の label:・;
コメント・字下げも同じように前後に付き、同じ行の "..." テンプレートとつながります。

.textmode
.func ld(d,s)
.return "LD " + d + "," + s
.endfunc
.func id(x)
.return x
.endfunc
MOV r,r2  :: .call ld(.exp(r),.exp(r2))
MVI r,!La :: "LD ",.call id(.exp(r)),",",.call id(.exp(a))
start:	mov	a,b	; copy   ->  start: LD a,b ; copy
	mvi	c,msg+1      ->  	LD c,msg+1
  • テキストになるのは戻り値の文字列だけです(-v の一覧にテキストとして出る部分で、
    ラベルとコメントはその前後に付きます)。.emit に渡したワードや、数・配列の戻り値は
    テキストではありませんが、-V には出ます。テキスト置換モードの -V は -b と
    同じバイト列を書くからです(上記)。
  • ;.call は文字列が空なら何も出さず、;;.call は捨てます("..." と同じ)。
    ; 無しで空文字列を返したときはテキストとして扱うので、その行のラベルとコメントは出ます。
  • NUL(.chr(0))を含む文字列は、-b には全部入り、テキストは最初の NUL の手前までです。
  • テキスト置換モードでないときは、文字列の戻り値は今までどおり -b にだけ出ます。
  • 同梱の callstr.axx / callstr.s の対がこのテストです。

例: 8080 から Z80 へ

同梱の 8080toz80.axx がこのモードの実例です。Intel 8080 のソースを読み、
同じ動作の Zilog Z80 のソーステキストを出します。

axx 8080toz80.axx hello8080.s -V > helloz80.s

同梱の hello8080.s が入力で、

        .org 0x100        ; .COM は 0x100 にロードされる
start:
        mvi c,9          ; BDOS function 9 = print $-terminated string
        lxi d,msg        ; DE = アドレス of msg
        call 0x0005      ; BDOS entry at 0005h
        ret              ; CP/M に戻る

msg:    db 'Hello, world$'

出てくる helloz80.s がこれです。

        .org 0x100 ; .COM は 0x100 にロードされる
start:
        LD C,9 ; BDOS function 9 = print $-terminated string
        LD DE,msg ; DE = アドレス of msg
        CALL 0x0005 ; BDOS entry at 0005h
        RET ; CP/M に戻る
msg: db 'Hello, world$'

オペランドは !L で拾って {{.exp()}} で出しているので、msg はラベルのまま、
0x0005 は書かれたままの綴りで出ます。コメントも書かれていた場所に残り、行頭の
字下げもソースのままです。テキストを標準出力へ流すのは -V の仕事なので、
これを付けないと翻訳結果は画面に出ません(-b へ書けばファイルには同じテキストが
入ります)。

最後の msg: db 'Hello, world$' の行だけは訳されません。8080toz80.axx に DB の
パターンが無いので素通しで db のまま出ますが、z80.axx も DB を定義していない
ので、出てきた helloz80.s をそのまま z80.axx に渡すとこの行が Syntax error に
なります。訳した結果をそのままアセンブルしたいときは、入力側のデータ行を組み込み
ディレクティブで書いてください(msg: .db "Hello, world$" や
msg: .ascii "Hello, world$"、5.3 節)。組み込み
ディレクティブの行はテキストとしてそのまま出るので(下記「組み込みディレクティブの
行」)、z80.axx がそのまま受け取れます。素通しそのものは .textmode の設計どおりの
振る舞いで、訳せた行と訳せなかった行が出力を見れば分かるようになっています。

例: Intel 記法から AT&T 記法へ

同梱の intel2att.axx は同じモードのもっと大きな実例で、x86-64 の Intel 記法の
ソースを GNU as がそのまま受け取る AT&T 記法へ書き換えます。

caxx intel2att.axx intel2att.s -V > att.s
caxx intel2att.axx intel2att.s -V | as --64 -o att.o -

やっていることは 5 つです。

  • オペランドの順序を入れ替える(dst,src → src,dst);
  • レジスタに %、即値に $ を付ける;
  • [base+index*scale+disp] を disp(%base,%index,scale) にする;
  • サイズ指定(QWORD PTR など)かレジスタ幅から接尾辞 b/w/l/q を決める;
  • 綴りが変わる命令(cqo→cqto、cdq→cltd、stosd→stosl など)を差し替える。

即値とメモリの区別は NASM と axx の流儀に従います。mov rdi, msg のようにラベルを裸で
書いたオペランドは、番地そのものの即値(movq $msg, %rdi)になります。GNU as の Intel
記法(.intel_syntax)では、同じ書き方が msg の番地にあるメモリを指すので意味が逆に
なります。GNU as 向けに書いたソースを訳すときは、メモリは [msg]、番地は offset msg
と書いてください。どちらの流儀でも同じ意味になり、意図どおりに訳されます。

        mov     rsi, offset msg          ->  movq $msg, %rsi
        mov     eax, 4                   ->  movl $4, %eax
        add     rsp, 8*4                 ->  addq $8*4, %rsp
        mov     rax, [rbx+rcx*8+32]      ->  movq 32(%rbx,%rcx,8), %rax
        mov     byte ptr [rdi+rcx], 0x41 ->  movb $0x41, (%rdi,%rcx)
        lea     rsi, [rip+msg]           ->  leaq msg(%rip), %rsi
        movzx   eax, byte ptr [rsi]      ->  movzbl (%rsi), %eax
        push    qword ptr [rbx+8]        ->  pushq 8(%rbx)
        jne     start                    ->  jne start
        cqo                              ->  cqto

書き方の要点は 3 つです。レジスタ名とニーモニックは配列シンボルの集合として
.setsym で宣言し、!Y集合[変数](3.6.3 節)でどれに
当たったかの番号を捕らえます。番号なので、同じ番号で別の集合を引けば AT&T 側の
綴りがそのまま出ます。ラベルと式は !L で拾って {{.exp(…)}} で出すので、
8*4 も msg も書かれたままの綴りで残ります。そしてメモリオペランドの 28 通りの
形([B]・[B+D]・[B+I*S+D]・[RIP+D] …)を 4 つのオペランドサイズと 3 通りの
サイズ指定の書き方に対して書き下すのは手作業では無理なので、マクロ層の
!def / !while(7 節)で生成しています。展開後のパターン表は
caxx intel2att.axx -p out.axx で読めます。

対応していない書き方(lock 付きの 2 オペランド命令、push word ptr など)は
.textmode の素通しでそのまま出るので、翻訳できたところとできなかったところが
出力を見れば分かります。

例: AArch64 から x86_64 へ — bf インタプリタの移植

同梱の a64tox64_axx.axx は、AArch64 のアセンブリを x86_64 のアセンブリへ翻訳します。
出力は axx の x86_64.axx でそのままアセンブルできる記法なので、翻訳からリンクまで
axx だけで閉じます。実例として、AArch64 で書いた Brainfuck インタプリタ
bf_aarch64.s を x86_64 の実行ファイルにできます。

caxx a64tox64_axx.axx bf_aarch64.s -V | cat a64ext.s - > bf_x64.s
caxx x86_64.axx bf_x64.s --osabi FreeBSD -o bf.o
caxx x86_64.axx a64rt_axx_freebsd.s --osabi FreeBSD -o a64rt.o
ld -static -e __a64_start bf.o a64rt.o -o bf
./bf mandelbrot.bf

Linux では a64rt_axx.s を --osabi Linux で組み、-e _start でリンクします。
a64ext.s はランタイムの名前を .extern で宣言する 1 行で、翻訳結果の先頭に付けます。

この手順は同梱のスクリプト bfsh/bf_x64_freebsd.sh と bfsh/bf_x64_linux.sh にまとめてあり、
build_bf_freebsd/bf または build_bf_linux/bf を作ります。引数に .bf ファイルを
渡すと、作ったあとでそれを走らせます。引数に run だけを渡すと、同梱の
mandelbrot.bf を走らせます。AXX=paxx で Python 版を使えます。
Linux 版は FreeBSD の Linuxulator(linux64.ko)でも動きます。FreeBSD の ld は
出力に FreeBSD のブランドを付けるので、FreeBSD 上で実行した bf_x64_linux.sh は
リンクの後で brandelf -t Linux を付け直します。ほかの CPU の bf インタプリタを
動かすスクリプトとあわせて、付録 A.4 に
まとめてあります。

        ldr x19, [sp]               ->  mov rbx, [rsp]
        cmp x19, #2                 ->  cmp rbx, 2
        b.ge open                   ->  jge open
        adrp x1, usage              ->  lea rsi, [RIP+usage]
        add  x1, x1, :lo12:usage    ->  ; :lo12:usage (adrp で計算済み)
        ldrb w9, [x20, x21]         ->  movzx r10, [r12+r13*1]
                                        mov [RIP+__a64_x9], r10
        cbz  w9, done               ->  mov r11, [RIP+__a64_x9]
                                        test r11d, r11d
                                        jz done
        svc  #0                     ->  call __a64_svc
        bl   putc                   ->  call putc
                                        mov rdi, rax
        ret                         ->  mov rax, rdi
                                        ret

やっていることは 4 つです。

  • レジスタの対応。 引数の x0〜x5 を SysV と同じ順の rdi rsi rdx rcx
    r8 r9 に、x8 を rax に、callee-saved の x19〜x23 を rbx r12〜r15
    に置きます。x86 に入りきらない x6 x7 x9〜x18 x24〜x28 はランタイムの
    8 バイトの置き場所(__a64_x9 など)に置き、r10 r11 を作業用に使います。
  • 呼び出し規約のつなぎ。 ret は戻り値を rdi(x0)から rax へ、bl は
    rax から rdi へ移します。stp x29, x30, [sp, #-N]! のようなフレームの
    出入りも対応づけます。
  • システムコール。 svc #0 はランタイムの __a64_svc を呼びます。AArch64 Linux
    の番号を表で引き直して syscall し、FreeBSD 版はキャリーフラグ方式のエラーを
    Linux の負の戻り値に直します。
  • プロセスの入口。 翻訳元は入口で [sp] を argc として読みます。FreeBSD/amd64
    のカーネルは argc の場所を rdi で渡し、rsp を 16 バイト境界合わせのために
    8 バイトずらすので、FreeBSD 版ランタイムの __a64_start が rsp を rdi に
    合わせてから _start へ飛びます。

152 行の記述が、マクロ層(7 節)で展開後 1,903 行のパターンになります。
レジスタ名の集合と !Y(3.6.3 節)でどのレジスタかの番号を
捕らえ、同じ番号で x86 側の綴りを引く書き方は intel2att.axx と同じです。
翻訳した bf は mandelbrot.bf を走らせ、C で書いた参照用インタプリタと同じ出力
(48 行、6,240 バイト)を出すことを FreeBSD/amd64 で確かめてあります。

3.19 .unordered — ディレクティブも順序に依存させない

.unordered

パターンは書く順序に依存しません(3.2 節)。ふつうのパターンファイルでは、
ディレクティブのほうは順序に依存します — 後の .setsym が前のものを上書きし、
.check は現れた位置から効きます。.unordered を 1 行書いたパターンファイルでは、
ディレクティブも順序に依存しなくなります。すべてのディレクティブがファイル全体に
効くので、パターンより後に書いても、ディレクティブ同士をどう並べても意味は同じです。
宣言自体もどこに書いても構いません(インクルードしたファイルの中でも)。

規則。

  • ディレクティブは、ソース 1 行ごとにパターンを試す前にすべて処理されます。順序は
    (1) 設定もの(.symbolc、.bits、.padding、.vliw、EPIC、.passthru、
    .eol、.textmode)、(2) .setsym、(3) その他(.check、.map、.enum、
    .reloc、.error、.echo、ELF の記述など)です。
  • .setsym の値が別の .setsym の名前を読むときは、読まれる側を先に処理します。
    .setsym::HI::#BASE+1 を .setsym::BASE::0x40 より前に書いても動きます。名前は
    文字・数字・_ の連なりとして拾います。互いに読み合う定義は循環としてエラーです。
  • 同じものへの定義は 1 つだけです。同じ名前の .setsym、同じ変数の .check / .map、
    同じ変数の .enum、同じ変数の .reloc、同じ番号の .error、そして同じ設定もの
    を、中身を変えて 2 度書くとエラーです。一字一句同じ繰り返しは構いません。
  • 「ここから先は」という位置の意味しか持たない .clearsym、.clrcheck、.clrenum、
    .clrreloc、.free は使えません(エラー)。
  • ELF の記述(.elf*)は従来どおり何度でも書けます。

.map は変数ごとの表を作ります。 ふつうのパターンファイルの .map は名前を
シンボルとして定義します(3.7.3 節)。.unordered のファイルでは、名前と値は
その変数だけの表に入り、その変数が捕らえたときだけその値になります。同じ名前を
別の変数が別の値で持てるので、同じ名前を .setsym で書き直す必要がありません。
Z80 の C はレジスタとしては 1、条件(キャリー)としては 3 です:

.unordered
LD r,r2 :: 0x40|r<<3|r2
JP cc,!nn :: 0xc2|cc<<3,nn&0xff,nn>>8
RET cc :: 0xc0|cc<<3
.map::r::B,C,D,E,H,L,A::0,1,2,3,4,5,7
.map::r2::B,C,D,E,H,L,A::0,1,2,3,4,5,7
.map::cc::NZ,Z,NC,C,PO,PE,P,M
ld a,c          -> 79
jp c,0x1234     -> da 34 12
ret c           -> d8

この表の名前は式の中の #C からは見えません。式で値を使いたい名前は .setsym で
定義してください。.check は従来どおり .setsym のシンボルを候補にします。

既存のパターンファイル。 .unordered を書かないファイルは従来どおり上から順に
読まれ、出力は変わりません。

同梱の unordered.axx / unordered.s がこの節のテストです。パターンを先に、
ディレクティブを後に、ディレクティブ同士もばらばらの順に書いてあります。


4. VLIW と EPIC プロセッサ

4.1 .vliw

.vliw::<バンドルビット数>::<命令ビット数>::<テンプレートビット数>::<NOP コード>
.vliw::128::41::5::00

この例は Itanium を記述しています。128 ビットのバンドルが 41 ビットの命令 3 つ
(123 ビット)と 5 ビットのテンプレートを保持し、NOP は 0x00 です。

  • 非 EPIC マシンでは、テンプレートビット数に 0 を与えます。
  • テンプレートビット数が正ならテンプレートを右端に、負なら絶対値を幅として左端に
    配置します。
  • .bits::big は既定の little に対して出力のバイト順を逆にします。

パターンが出力するバイト数は (バンドルビット数 − テンプレートビット数) ÷ 8 を
切り上げた値と一致しなければなりません。

4.2 EPIC

EPIC パターンは第 4 のフィールド、インデックスコードを取ります。

/* VLIW
.setsym::R1::1
.setsym::R2::2
.setsym::R3::3
.setsym::R4::4
.vliw::128::41::5::00
EPIC::1,2::0x8|!!!!
EPIC::1::0x01
AD a,b,c:: ::0x01,0,0,a,b,c::1
LOD d,[!e]:: :: 0x00,0x01,0,d,e,e>>8::2
  • EPIC::1,2::0x8|!!!! は、インデックスコード 1 と 2 の命令からなるバンドルを、
    テンプレート 0x8 とストップビットの OR で記述します。
  • !!!! はストップビットを表します。
  • AD a,b,c のインデックスコードは 1、LOD d,[!e] は 2 です。

EPIC パターンではエラーフィールドを明示的に書かなければなりません。 空のときも
同様です — だから :: :: となっています。

(上記の値はテストフィクスチャであり、実際の Itanium エンコーディングとは対応して
いません。)

4.3 非 EPIC VLIW

/* VLIW
.setsym::R1::1
.setsym::R2::2
.setsym::R3::3
.setsym::R4::4
.vliw::128::32::0::0x00
AD a,b,c::0x01,a,b,c
LOD d,[!e]::0x02,d,e,e>>8
JMP !a ::0x03,a,a>>8,0

4.4 ソース中でのバンドル化

命令は !! でバンドル化します:

ad r1,r2,r3 !! lod r4,[0x1234]

binary_list では !!! が !! で結合された命令の数であり、バンドル末尾の !!!! が
ストップビットを設定します。

バンドルは 1 行です。次のものはエラーです(以前は命令を黙って落としていました): !! の
前か後ろが空のスロット(ad r1,r2,r3!!、!!ad r1,r2,r3、!!!! だけの行)、パケットの
スロットに入りきらないバイト数の命令、.vliw の無いパターンファイルで命令の後ろに続く
!!。文字列の中の !! はただの文字です。

4.5 エンディアン

binary_list に値を書く順序で決まります。


5. アセンブリソースリファレンス

ソースファイルまたは標準入力から読まれる行をアセンブリ行と呼びます。コメントは
; で始まります。コメントは落とされますが、テキスト置換モード(3.18 節)では
書かれていたとおりの綴りで出力に残ります。

  • 行の終わり。 LF・CR LF・CR のどれでも 1 行が終わります(CR だけで改行した
    ファイルも行に分かれます)。パターンファイルも同じです。
  • 指令の引数の後ろ。 .org .align .zero .resb / .resw / .resd / .resq
    .ascii / .asciz .db / .dw / .dd / .dq / .do / .dy / .dz
    .equ .section は、引数の後ろに空白とコメント以外の文字が残ると
    エラーです(.ascii "a","b" や .section .data,"aw" の後ろを黙って捨てません)。
  • 行の継続。 改行の直前が \ の行は、その \ を除いて次の行とつながります。
    つないだ行は塊の最後の物理行の番号で数え、前の物理行は空行として残るので、診断と
    -v の一覧の行番号はファイルの見た目のままです。\ の後ろに空白やコメントが
    あれば継続になりません。逆に、; のコメントが \ で終わると次の行もコメントに
    入ります(; C:\ など)。パターンファイル(3.1 節)と !include で取り込む
    ファイルも同じです。
  • 空白。 語を区切る空白はスペースとタブだけです。\f(改ページ)や \v、
    ノーブレークスペース(U+00A0)、全角空白(U+3000)などは空白ではなくふつうの
    文字として読むので、命令の綴りの中や行頭・行末にあれば照合に失敗します。
  • 文字コード。 ソースは UTF-8 として読みます。UTF-8 として読めないバイトも
    そのまま運ばれ、.ascii などではそのバイトが出力に入り、-v の一覧にも
    そのまま書かれます。

5.1 ラベル

label1:
label2: .equ 0x10
label3: nop
label4: .equ label1

ラベルは文字・数字・一部の記号の並びで、数字以外で始まります。.equ で定義された
ラベルは再配置情報を失い、定数として扱われます。

.equ は後ろで定義するラベルも参照できます。前方参照は pass 1 の反復(リラクゼーション)
ごとに決まるので、a: .equ b+1 / b: .equ c+1 / … のような連鎖は 1 回に 1 段ずつ決まります。
反復の上限は 16 回ですが、前の反復から値の変わったラベルの数が最小を更新した反復は数えない
ので、16 段を超える連鎖でも組めます(そうでない反復が合わせて 16 回になれば打ち切り、
配置が振動していればそう報告します)。

.labelc <characters>(ソースの指令なので :: は付けません)はラベルの文字集合を拡張
します。既定は文字、数字、_、. です。英数字に加える文字を書き直すもので、既定の _
と . も残したいときは一緒に書きます(.labelc _.@)。書いた行から後ろに効き、パスごと
に既定から数え直すので、前に書いたラベルには効きません。

5.2 ロケーションカウンタ

.org 0x800
.org 0x800,p

.org はロケーションカウンタを設定します。,p を付けると、カウンタが目標値より下に
ある場合、その隙間がパディングされます。

生バイナリ(-b)では、.org でカウンタを後ろへ戻して前に書いた所を上書きできます。
ELF オブジェクト(-o)とセクション付きのエクスポート(-E)では、後ろへ戻す
.org はエラーです(GNU as と同じ)。各セクションの中身は「入ったところから出た
ところまで」の範囲で持つので、後ろへ戻すと範囲が負になったり、書いたものが範囲の
外へこぼれたりするためです。
範囲は出たときの位置カウンタまでなので、セクションの終わりの .org で進めた分も
セクションに入り、その後ろのラベルはセクションの終わりちょうどを指します。.section
を一度も書かないソース(暗黙の .text)も同じで、.text は 0 番地から最後の位置
カウンタまでです。

.org・.align・.zero・.resb などの引数が未定義のラベルを含む(未定義を含む
.equ の値を使った場合も含む)と、「argument contains undefined label」と報告し、
その行は何もしません。

.align 16

16 の倍数に整列し、.padding バイトでパディングします。引数なしの場合、前回の(または
既定の)アラインメントが使われます。-o と -E ではセクションの先頭から数えた倍数
(リンカがセクションを揃った番地に置くため)、-b だけのときは平らなイメージの中の
番地の倍数です。

5.3 データ

.ascii "sample1"        ; 文字列バイト
.asciz "sample2"        ; 文字列バイトと末尾の 0x00
.zero 65536             ; 65536 個のゼロバイト

バイトを出力せずに記憶領域を予約する — ロケーションカウンタが進むだけです:

.resb n     ; n バイト
.resw n     ; n ワード       (n*2 バイト)
.resd n     ; n ダブルワード (n*4 バイト)
.resq n     ; n クワッドワード (n*8 バイト)

式の値をワード列にして出すデータディレクティブです:

.db   1, 2, 'A', "Hi\n", 0      ; 1 ワードずつ。.db だけ文字列も書ける
.dw   0x1234, -2, label         ; 2 ワードずつ
.dd   0x12345678, end-start     ; 4 ワードずつ
.dq   0x1122334455667788        ; 8 ワードずつ
.do   0x112233445566778899aabbccddeeff00   ; 16 ワードずつ
.dy   1                         ; 32 ワードずつ
.dz   -2                        ; 64 ワードずつ
  • 大きさ。 1 つの値は .db が 1 ワード、.dw が 2、.dd が 4、.dq が 8、
    .do が 16、.dy が 32、.dz が 64 ワードです(名前は NASM の DO / DY / DZ
    と同じで、o はオクタワード、y と z は YMM / ZMM レジスタの幅に由来します)。.resb などと同じく
    ワード数で数えるので、.bits::8 なら 8 / 16 / 32 / 64 / 128 / 256 / 512 ビット、
    .bits::16 なら .db は 16 ビット、.dw は 32 ビットになります。名前は大文字でも
    小文字でも構いません。
  • 並び順。 .bits のバイト順(3.10 節)に従います。little(既定)なら下位の
    ワードから、big なら上位のワードから並べます。68000.axx・mips.axx・ppc64.axx・
    sparc.axx のように .bits::big::8 と書いたパターンファイルでは、パターンファイルに
    何も足さずに上位のバイトから並びます。
  • 値。 カンマで区切った式です。式の値は 256 ビットの符号付きとして読み(6.4 節)、
    欄に符号付きか符号なしのどちらかで収まらない値はエラーです(.db 256、.db -129)。
    .dy と .dz の欄にはどの値も収まり、.dz では 256 ビットより上を符号拡張で
    埋めます。前方参照のラベルも書けます。
  • 文字列。 .db だけは "..." を値として書け、.ascii と同じ規則(エスケープと
    UTF-8 のバイト)でワードになります。文字定数 'A' は式なので、どれにも書けます。
  • 誤り。 範囲外の値、未定義のラベル、値の無い ,、.db 以外の文字列、値の後ろに
    残った文字はエラーです。誤った値の分も 0 のワードを出すので、後ろの行の番地はずれません。
  • -o。 値はパターンの出力と同じ仕組みで書き出すので、ラベルを含む値には
    リロケーションが付きます。値が「ラベル+定数」の欄は、同じ幅の絶対型になります
    (x86-64 なら .dq が R_X86_64_64、.dd が R_X86_64_32。型を書かない .extern
    のシンボルも同じ)。.reloctype で選んだ型と、型を書いたラベルの型はそのまま使います。
    $$ を含む値(.dd ext-$$)は、パターンと同じく PC 相対の推測にかけます。同じ行に
    同じラベルを指す値が並んでも(.dq L1, L1)、値ごとに別のリロケーションになります。
    その幅のリロケーション型が無い欄(x86-64 の .do など)では、リロケーションを
    省いて警告を出します。
  • テキスト置換モード(3.18 節)では、他の組み込みディレクティブと同じくテキストと
    してそのまま出し、自分では何も出しません。.eol(3.17 節)の改行は足しません。
    .vliw の中では、.ascii と同じくパケットに入れずに直接書き出します。

同梱のパターンファイルの DB !v :: v のようなパターン(8048.axx・4004.axx など)は
ドットの付かない別の名前なので、組み込みの .db とは重なりません。パターンファイルに
関係なく常に使えるデータディレクティブは、.ascii、.asciz、.zero、
.resb/.resw/.resd/.resq、そして .db/.dw/.dd/.dq/.do/.dy/.dz
です。

5.4 浮動小数点

!F / !D / !Q は命令中のある位置で浮動小数点オペランドをキャプチャします:

VMOV.F32 S!n,#!Fd :: 0x80|n,d>>24,d>>16,d>>8,d

vmov.f32 s0,#3.14 は 0x80,0xc3,0xf5,0x48,0x40 を出力します。

通常の整数式の中に浮動小数点値を書くには — たとえば .equ で名前を与えるには — 波括弧
形式を使います。それぞれ本体を浮動小数点として評価し、IEEE-754 ビットパターンを整数と
して返します:

flt{expr}     ; 32 ビット  (binary32) ビットパターン
dbl{expr}     ; 64 ビット  (binary64) ビットパターン
qad{expr}     ; 128 ビット (binary128) ビットパターン

逆関数はそれらの本体の内側で使えます:

enfloat(v)  / enflt(v)     ; v の下位 32 ビットを float として読み戻す
endouble(v) / endbl(v)     ; v の下位 64 ビットを double として読み戻す

これにより名前付きの浮動小数点定数が機能します。格納されたラベルがデコードして再計算
できるビットパターンを保持しているからです:

c1: .equ flt{3.14}
    LDF A,flt{enfloat(:c1)*2}

そのような式の中の :label は、ラベルの値を 256 ビットの符号付き整数として直接読み
ます(-o ではセクション内の相対値で、再配置は作りません)。inf、-inf、nan が
受け付けられます。

波括弧の中身は Python の数の規則に従います(両実装が同じ小さな構文解析器を持ちます。
Python の eval ではありません):

  • 数は Python のリテラルの綴りです。10 進・0x・0o・0b、桁の間の _、小数点や
    指数のある浮動小数点(.5、5.、1e-3)。10 進の整数は 0 で始められないので
    (0 そのものと 00 は可)、01 はエラーです。
  • 演算子は優先順位の低い順に |、^、&、<< >>、+ -、* / // %、単項の
    + - ~、** です(** は右結合で、左の単項より強いので -2**2 は -4)。比較・
    論理演算・条件式はありません。
  • 整数は正確なまま計算します。整数どうしの + - * // % ** << >> & | ^ ~ は整数に
    なるので、dbl{2**70+1-2**70} は 1.0 です。整数の結果が 256 ビットの符号付きに
    収まらないときは、その演算だけを倍精度でやり直します(dbl{2**300})。<< だけは
    そのときエラーです。収まらない整数のリテラルは倍精度として読みます。
  • / と、倍精度のオペランドを含む演算は倍精度で計算します。整数は正しく丸めて倍精度に
    し、整数どうしの / は真の商を正しく丸めます(Python と同じ)。// と % は負の
    無限大の方向へ丸め、% の符号は割る数に従います(倍精度でも同じ)。
  • << >> & | ^ ~ は整数だけを取ります。0 で割る、負のシフト量、0 の負の数乗、負の数の
    非整数乗、途中で有限でない値が出る、はどれもエラーです。
  • enfloat / enflt / endouble / endbl の引数は 1 個です。倍精度の引数は 0 の方向へ
    切り捨てた整数にしてから、下位 32 / 64 ビットを読み直します。

波括弧の外の enflt{v} / endbl{v} は、v(整数の式として評価)を float / double
として読み直します。浮動小数点の文脈ではその値に、整数の文脈では 0 の方向へ切り捨てた
整数になります(c が flt{-2.5} のとき enflt{c}*2 は -4)。有限でない値と、絶対値が
2**255 以上の値はエラーです。

幅を越えた値はエラーです。 !F / !D / !Q と flt{} / dbl{} / qad{} の
どれでも、有限の計算の結果がその幅の範囲を越えたら「変換できない」と報告して中断します
(無限大を黙って出しません)。flt{1e39}、dbl{1e309}、qad{1e4933} はどれも
エラーです。一方、明示して書いた inf / -inf / nan はそのまま通ります —
波括弧の中身がちょうどその綴りのときは値として扱うので、qad{inf} は無限大の
ビットパターンになります。演算に混ぜた qad{inf+2} は式なのでエラーです。

!Q と qad{} の算術は binary128 で演算ごとに丸めます。 数は binary128 へ正しく
丸めて読み、+ - * / のたびに binary128 へ偶数丸めします(Caxx の __float128 の演算と
同じで、Paxx も同じ丸めを有理数で再現しています)。読める文法は数・括弧・単項の
+ - と + - * / だけで、0 で割る・結果が有限でない・読めない文字が残る場合は、
倍精度で計算した値を %.17g で十進に書いてから binary128 に変換します。どちらの経路
でも両実装は同じビットを出します。!Q では倍精度の計算で 0 になる数で割っても、binary128 の
値が出ればエラーにしません(1/1e-4000 は 1e4000 の近く)。0 に丸まる積や商も符号を
保ちます(qad{1e-4960*-1e-10} は -0)。

整数は 256 ビットの符号付きとして読みます。 !F / !D / !Q の式が整数になった
とき、その値は 256 ビットの 2 の補数として浮動小数点に変換します。たとえば 64 桁の
0xfff…f は -1 で、-1.0 になります。浮動小数点の文脈の比較は 1.0 / 0.0 を
返し、-0.0 は偽です。

5.5 セクション

.section .text
.segment .text          ; 現在は意味が同一
.endsection
.endsegment

セクション名は、-o と -E 出力用の ELF セクションフラグを導く際に .text、.data、
.rodata、.bss と照合されます。

注意。 .section(または .segment)がセクションを切り替える唯一の方法です。
素の .text / .data / .rodata / .bss という短縮形はありません。それらを単独の
行に書くと、Paxx でも Caxx でも構文エラーです。

5.5.1 .reloctype

現在のソースファイルにおける、自動検出されたラベル参照に対するマシン既定の幅推測
再配置タイプを上書きします:

.reloctype name8,name16,name32,name64

書いた行から(パスごとに先頭から数えて)後ろに効き、空けた位置の幅は推測のままです。
上書きするのは幅からの推測と、型を書かない .extern の既定の型で、パターンの .reloc
が決める型は変えません。上書きした型は、欄の値を見て絶対と PC 相対を選び直す推測に
かけません。

5.5.2 セクションの順序

セクションは書かれた順序どおりに配置されるので、次のコードは:

.section .text
ld a,9
.section .data
.asciz "test1"
.section .text
ld b,9
.section .data
.ascii "test2"

セクションごとにまとまりません。secsort.py を実行すると次が得られます:

.section .text
ld a,9
ld b,9
.section .data
.asciz "test1"
.ascii "test2"

5.6 リンケージ

.export label
.export label1,label2,label3
.global label1,label2
.global label1::pc32             ; label1 への参照は再配置タイプ pc32 を使う
.extern label1,label2
.extern label1:2,label2          ; label1 は再配置タイプ 2 を使う
.extern label2::gotpcrel         ; 型名でも書ける
  • .export はラベルを -e / -E 出力の対象として、そのセクション/セグメントとともに
    マークします。ここで名指しされたラベルだけがエクスポートされます。
  • .global はラベルを外部へ渡します。-e / -E でも書き出されます。
  • .global と .extern は、名前の後ろに ::型名 を付けてその名前への参照に使う
    再配置タイプを指定できます。型名は -m で選んだマシンの名前表(8.3 節)の名前か、
    パターンファイルの .elftype(3.7.6 節)で決めた名前です。認識されない名前は
    警告を出して無視されます。宣言は参照より前に書いてください。
  • .extern はその名前が他所で解決されることを宣言します。再配置タイプは : で個々の
    名前に付けられます。型名を書かなかったときの既定の型はマシンごとに決まっていて、
    パターンファイルの .elfextern(3.7.7 節)で変えられます。

.extern と -i は一緒に使うよう設計されています。-i が外部ラベルの実アドレスを
供給し、.extern がその名前が他所で解決されることを宣言します。両方が同じラベルを
名指しした場合、-i が持ち込んだ値が優先されます。

.global と .extern は ELF オブジェクトライタが消費します。

5.6.1 ELF シンボルの属性

-o が出すシンボル表は、名前とアドレスのほかに型・大きさ・束縛・可視性を
持ちます。リンカはこれを見て仕事を変えます — STT_FUNC でないシンボルには
ARM / AArch64 の中継命令(veneer)が作られず、大きさの無いシンボルは
--gc-sections で残せず、弱いシンボルは他の定義に負けます。機種の記述
(3.7.7 節)がそろっても、この欄が既定のままではリンクできる .o にならない
ので、ソース側の宣言でここを埋めます。

宣言 決めるもの
.type <名前>::<種別> st_info の型欄(STT_*)
.size <名前>::<式> st_size
.weak <名前> 束縛を STB_WEAK にする
.hidden <名前> / .protected <名前> / .internal <名前> st_other の可視性(STV_*)
.other <名前>::<値> st_other のバイトそのもの
.comm <名前>::<大きさ>[::<整列>] SHN_COMMON のシンボル
  • どれも 名前1::…, 名前2::… とカンマで並べられます。名前の後ろの :: は
    .extern 名前::型名(5.6 節)と同じ区切りです。
  • 宣言はどこに書いても構いませんが、.extern と同じく参照より前に書くのが
    安全です。属性は出力にしか効かないので、アドレスは動きません。
  • 宣言していないシンボルは今までどおり STT_NOTYPE、大きさ 0、可視性
    STV_DEFAULT で出ます。

.type の種別。 名前でも番号(0〜15)でも書けます。名前の大小は区別しません。

種別 STT_* 使うところ
notype 0 型を言わない(既定)
object 1 データ
func(function) 2 関数の入口
section 3 セクションシンボル
file 4 ファイル名シンボル
common 5 共通シンボル
tls(tls_object) 6 スレッド局所データ
gnu_ifunc(ifunc) 10 GNU の間接関数

.size の値はワード数です。 ラベルの値と同じく 1 ワードのバイト数を掛けて
st_size に入ります。8 ビット機(.bits の既定)では掛ける数が 1 なので、
書いたままの数が入ります。.size func::func_end-func のように、関数の終わりに
置いたラベルとの差で書くのが普通です。

.weak は名前を外へ出します。 その名前がこのファイルで定義されていれば
.global と同じく外部公開し、束縛だけを弱くします。まだ知らない名前は型名なしの
.extern と同じに登録するので、.weak maybe と書くだけで「解決できなければ 0
になる参照」(弱い参照)が書けます。.weak を書いたシンボルは必ずシンボル表の
大域側に来るので、局所シンボルを弱くすることはできません(ELF がそれを許さない
ためです)。

.other はバイトを丸ごと置き換えます。 下位 2 ビットが可視性(STV_*)で、
上位 6 ビットは機種ごとの意味を持ちます(PowerPC64 ELFv2 の局所入口のずれは
ビット 5〜7 にあります)。.hidden などの可視性の宣言は下位 2 ビットだけを
書き換えるので、.other で上位を書いたあとに可視性を書いても上位は残ります。
逆の順に書くと .other が可視性を上書きします。

.comm は SHN_COMMON のシンボルを出します。 実体はリンカが作るので、この
オブジェクト自身は領域を持ちません。st_value が整列(バイト、書かなければ 1、
0 か 2 の冪)、st_size が大きさ(ワード数 × 1 ワードのバイト数)になります。
型は .type を書かなければ STT_OBJECT にします(GNU as と同じ)。名前は
.extern と同じく外部シンボルとして登録されるので、そのまま参照でき、
リロケーションもその名前に対して出ます。

        .extern printf                  ; 普通の外部参照
        .weak   maybe                   ; 弱い参照(未定義のままでもよい)
        .comm   sharedbuf::64::8        ; 64 ワード、8 バイト整列

        .global func
        .type   func::func
        .other  func::0x60              ; st_other をバイトごと書く

        .global datum
        .type   datum::object
        .size   datum::4
        .protected datum

        .section .text
func:
        nop
        dd      printf
        ret
func_end:
        .size   func::func_end-func
   Num:    Value  Size Type    Bind   Vis        Ndx Name
     6: 00000000     0 NOTYPE  WEAK   DEFAULT    UND maybe
     7: 00000000     0 NOTYPE  GLOBAL DEFAULT    UND printf
     8: 00000008    64 OBJECT  GLOBAL DEFAULT    COM sharedbuf
    10: 00000000     4 OBJECT  GLOBAL PROTECTED    2 datum
    11: 00000000    12 FUNC    GLOBAL [<other>: 60]  1 func

実例は同梱の elfsym.axx / elfsym.s です。

5.7 インクルード

.include "file.s"

ソース側ではこれはマクロ層をバイパスします。マクロ定義を取り込むには !include
(7 節)を使ってください。


6. 式と演算子

アセンブリ行とパターンデータは同じ式評価器を呼ぶので、両者はほぼ同一に振る舞います。
唯一の制限は、小文字のパターン変数をアセンブリ行から参照できないことです。

6.1 特殊な項

項 意味
!!! !! で結合された命令の数
%% %% がこれまでに現れた回数(0 起点のインデックス)
$$ 現在のロケーションカウンタ
$. 次の命令の開始アドレス
'c' 文字定数。c は 1 バイトの文字(ASCII か、UTF-8 として読めない 1 バイト)で、値はそのバイト。'\n' '\t' '\xHH' などの逃がしも書ける。'é' のような UTF-8 の多バイト文字は文字定数にならない

6.2 演算子

優先順位はおおむね Python に従い、緩いものが後です。Python と違うのは、| が ^ より
きつく結合すること(Python は逆)、** が左結合であること(2**3**2 は 512 ではなく 64)、
単項の - が ** よりきつく結合すること(-2**2 は 4)、比較が連鎖しないこと
(5>3>1 は (5>3)>1 で 0)です。両実装とも下の表どおりに読みます。

(expr)          括弧で囲んだ式
#               後続シンボルの値
*(x,y)          x を y バイト右へずらした値 (y>=0)。下位 8 ビットが y 番目のバイト
-, ~            符号反転、ビット NOT
@               最上位の立っているビットの位置。右から数える
'c'             文字コード
:=              代入
**              べき乗
*, /, //, %     乗算、除算、整数除算、剰余
+, -            加算、減算
<<, >>          シフト
&               ビット AND
|               ビット OR
^               ビット XOR
'               符号拡張
<=, <, >, >=, !=, ==     比較
not(x)          論理 NOT
&&              論理 AND
||              論理 OR
x?a:b           三項演算子
  • d:=24 は d に 24 を代入し、24 に評価されます。
  • #name はシンボル name の値を返します。
  • @v は v の最上位の立っているビットの位置を右から数えて返します。
    (ヘビマルマッタ演算子。)
  • a'24 は a の下位 24 ビットを取り、ビット 23(幅 − 1)を符号ビットとして符号拡張
    します(0xff'8 == -1、0x80'7 == 0)。(SEX 演算子。)
  • *(x,y) は x >> (8*y) で、上位のビットは落としません(*(0x123456,1) == 0x1234)。
    1 バイトの欄に出せば、その下位 8 ビット — x の下から y 番目のバイト — が残ります。
    @@[2,*(v,%%)] のように繰り返しと組み合わせて、多バイトの値を下位から並べるのに使います。
  • / はゼロ方向へ切り捨てます(-7/3 == -2)。% は Python と同じで、結果は
    除数の符号に従います(-7%3 == 2、7%-3 == -2)。/ と % のあいだに
    a == (a/b)*b + a%b は成り立ちません。
  • ここでの % の符号はミニ言語(3.15 節)とマクロ層(7.3 節)の % とは
    違います。あちらは C と同じで被除数の符号に従うので、同じ -7%3 が
    ミニ言語とマクロ層では -1 になります。層をまたいで式を写すときは
    負の値に注意してください。
  • binary_list の中では %0 は剰余ではなく、@@[] の繰り返しインデックスを
    0 に戻す項です(3.5.1 節)。x%0 と書いても剰余のゼロ除算は報告されません。
    剰余を書くつもりなら x % 0 のように空白を置くか括弧で囲んでください。
  • && と || は短絡します。左で結果が決まれば(&& なら偽、|| なら真)右は評価せず、
    三項演算子 ?: の選ばれなかった側と同じく読み飛ばします。右だけで起きる 0 除算などの
    エラーは出ず、右の := の代入も走りません。x!=0 && 100/x>3;3 のような見張りは
    x が 0 でも働きます。左が未定義のラベルを含むときは決められないので、右も評価します。
  • ** の指数は 0〜1024 で、結果の絶対値が 2**256 以上になるとエラーで、値は 0 に
    なります(2**255 や (-2)**129 は計算できます。2**192 以上の値の扱いは 6.4 節)。

6.3 どこで何が使えるか

同じ評価器が 3 か所から呼ばれます — アセンブリ行、パターンファイルのフィールド、そして
(委譲によって)マクロ層とミニ言語です — が、すべての項がすべての場所で意味を持つわけ
ではありません。ケイパビリティ記述子が決定するので、機能セットは呼び出しの時点によって
変わります:

項 パターン行 アセンブリ行 ミニ言語 マクロ層
ラベル / .equ 可 可 可 前回の反復の値
$$ / $. 可 可 可 $ / $$、前回の反復
#symbol 可 可 可 —
パターン変数 可 大文字のみ 不可 不可
!!! / !!!! 可 不可 不可 不可
@, ', *(x,y) 可 可 不可 可

ミニ言語でパターン変数が外されているのは、.func 本体の実行中にそれらを束縛している
ものが何もないからです — 代わりに呼び出し側で渡してください。!!! は VLIW パターン行
でしか意味を持ちません。パターンファイルではマクロ層がソースのアセンブル前に走るので、
読むべきラベルもロケーションカウンタもまったく存在しません。

@、'、*(x,y) は一度だけ実装され、アセンブラの評価器とマクロ層の両方から呼ばれる
ので、どちらでも同じ意味です。マクロ層では ' はビット演算子より緩く、&& よりきつく
結合します。この位置はアセンブラでの位置(^ と比較の間)とは異なります。マクロ層の
優先順位は C に従い、そこでは比較がビット演算子よりきつく結合するからです。

ミニ言語はこの 3 つを持ちません。3.15 節が挙げる演算子が
すべてで、@ と ' は構文エラー、*( は乗算として読まれます。同じ働きは
.call の呼び出し側(パターン行)で書いて、結果を引数として渡してください。

6.4 非常に大きな値と UNDEF センチネル

未定義ラベルは通常の算術を通してセンチネル値を運ぶので、label+4 は例外を発生させる
代わりに未定義と認識できる形を保ちます。Paxx はそのセンチネルを帯域外に置けます —
その整数は任意精度なので、センチネルは実際の値が到達しない 2**768 より上に存在します。
Caxx には 256 ビットより上の余裕がないので、2**192 以上の任意の大きさをセンチネル由来
として扱い、警告で一度そう述べます。

計算値を 2**192 より下に保てば、2 つの実装は完全に一致します。それを超えると、
それぞれ独自の道を行きます:

値 Paxx Caxx
絶対値 ≥ 2**192 通常の値 未定義ラベル参照として報告
ビット 255 が立つ 正なので >> はゼロを詰める 負なので >> は 1 を詰める
≥ 2**256 そのまま保持 256 ビットに巻き戻す

両実装とも、値が判断できない帯域に入ったとき警告します(Caxx は 2**192 以上の値に
ついて一度、2**256 を超えて巻き戻したときにも一度)。これはセンチネル設計の性質で
あって、特定の演算子の性質ではありません。Caxx に帯域外センチネルを持たせるには、値型
を 256 ビットより広げる必要があります。

センチネルの大きさは実装ごとに違いますが、未定義ラベルを踏んだあとの振る舞いは
両実装で同じ
になるよう、次の規則で扱います:

  • 演算の毒。 演算子(+ - * / // % ** << >> & | ^ '、比較、&& ||、単項の
    - ~ @、*(x,y))のオペランドのどちらかが未定義なら、結果も未定義そのものに
    なります。未定義の値どうしの算術が、センチネルの大きさの違いで別の値になることは
    ありません。0 で割る・シフト量が大きすぎるといった、未定義の値から生じるはずの
    診断も出ません。
  • error_patterns。 条件の評価中に未定義のラベルや変数に触れた条件は、判定
    しません(エラーコードを出しません)。未定義はすでに報告されているからです。
  • テキストに出すとき。 テンプレートの {{ }}(.hex などを含む)と本文行の
    .echo は、未定義の値を数字ではなく UNDEF と書きます。配列シンボルの添字が
    未定義なら、範囲外とは報告せずに引けなかったことにします。
  • 浮動小数点の捕捉。 !F / !D / !Q で捕捉した値が未定義なら、変換エラーに
    せず 0 にします。
  • ミニ言語の .call の引数に未定義の値を渡すと、従来どおり 0 として渡ります。

どの場合も、アセンブルは「未定義ラベル」のエラーで終わり、出力は書かれません。上の
規則は、そこに至るまでに出る診断と -V のテキストを両実装でそろえるためのものです。


7. マクロ層

同じ内容は MACRO.md(日本語)と macro_en.md(英語)に独立した文書として保管されて
います。

これはアセンブラ本体の前に走るソース間変換です。それでもソースファイル中のマクロは
ラベル値、.equ 定義、$ / $$ ロケーションカウンタを読めます。見えるのは前回の
リラクゼーション反復の値です(最初の反復では 0 / 未定義)。展開が反復ごとに変わりうる
ため、収束はリラクゼーションループ自体によって強制されます — 反復回数に上限を設け、
振動を検出し、誤ったバイナリを出力する代わりに出力ファイルを書かずに中断します。
パターンファイルのマクロはソースのアセンブル前に走るので、どちらにもアクセスできません。
詳細は MACRO.md / macro_en.md を参照してください。

axx.py と caxx.c は同じ仕様を実装しています。唯一の違いは数値表現です。Paxx は任意
精度整数を、Caxx は int64 を使います。結果が食い違うのはマクロ時の計算が 64 ビットを
超える場合だけで、マクロ層はソーステキストを出力するので、アセンブラ自身の 256 ビット
式評価には影響しません。

7.1 文

すべての文は行頭の ! で始まります(先頭の空白は無視されます)。

構文 意味
!def name(p1, p2, p3 = default) { ... } マクロ / コンパイル時関数
!return expr 値を返す。早期脱出も兼ねる
!if expr !then { ... } !elif expr !then { ... } !else { ... } 条件分岐
!while expr { ... } ループ
!break / !continue ループ制御
!set name = expr 代入。内側から外側へスコープを探索し、見つからなければ現在のスコープに作成
!local name [= expr] 現在のスコープで宣言
!undef name 変数またはマクロを削除
!name(a, b) マクロを文として展開
!include "file" 展開時にテキストをインクルード
!error expr エラーで展開を中断
!warning expr / !echo expr 標準エラー出力へ書く(!echo はミニ言語の .echo とレイアウトを共有。3.15 節)

開き { はヘッダ行の最後になければならず、閉じ } は行頭になければなりません。
; コメント は文の後に続けられます。

7.2 補間

記法 意味
!{expr} 値をテキストとして展開
!{expr:04x} Python 形式のフォーマット指定を適用
\!{ リテラルな !{

フォーマット指定は Python のフォーマットミニ言語です。両実装は同じ指定を受け入れ、
同じ指定を拒否し、エラーの文面も一致します。

[[fill]align][sign][z][#][0][width][grouping][.precision][type]
  align     ::= "<" | ">" | "=" | "^"
  sign      ::= "+" | "-" | " "
  grouping  ::= "," | "_"
  type      ::= b c d e E f F g G n o s x X %

!{255:#06x} は 0x00ff、!{1234567:,d} は 1,234,567、!{255:*^10b} は
*11111111*、!{255:.2f} は 255.00 を与えます。Python の制約も適用されます。整数型
に精度は指定できず、x/X/o/b/c/n に , は使えず、文字列に符号や # は
付けられません。

Python との既知の相違が 2 つあります:

  • 両実装とも解釈前に指定の前後の空白を除去するので、空白を符号とする形式(!{5: d}、
    Python では ' 5' になる)は表現できません。!{5:d} と同じに振る舞います。
  • !{0:c} は Paxx では NUL 文字を返しますが、Caxx では空文字列になります。C 文字列は
    内部に NUL を持てないためです。

7.3 値、演算子、組み込み関数

値は整数と文字列です。演算子は C 準拠です:

?:  ||  &&  |  ^  &  ==  !=  <  <=  >  >=  <<  >>  +  -  *  /  %
単項:  -  +  ~  !

/ と % は C と同様にゼロ方向へ切り捨てます (-7/2 == -3)。どちらかのオペランドが
文字列なら + は連結し、"ab" * 3 は繰り返します。整数リテラル: 10、0x1f、
0b1010、0o17。アンダースコアが使えます。'A' は 1 バイトなら文字コード、それ以上なら
文字列です。

文字列はミニ言語(3.15 節)と同じく UTF-8 のバイトの並びです。len("あ") は 3、
substr() の位置と長さもバイトで数え、upper() / lower() は ASCII の英字だけを
変え、< などの比較もバイトの並びで決まります。'é' は 2 バイトなので文字コード
ではなく文字列です。名前と数字に使える文字も ASCII だけです。書式指定(7.2 節)の
幅と精度だけは、Python と同じく文字の数で数えます。

さらに 3 つがアセンブラ自身の評価器から持ち込まれ、実装を共有しているのでどちらの場所
でも同じ意味を持ちます: @v(最上位の立っているビットの位置)、v'bits(符号拡張)、
*(v, n)(バイト抽出)です — !{@255} は 8、!{0xff'8} は -1、!{*(0xabcd,1)} は
171 です。' はビット演算子より緩く、&& よりきつく結合します。位置がアセンブラと
異なる理由は 6.3 節を参照してください。値が期待される位置の
*( だけがバイト抽出です。中置の * は依然として乗算です。

組み込み関数:

len(s)  hex(v[,digits])  str(v)  int(s[,base])  upper(s)  lower(s)
substr(s,start[,length])  abs(v)  min(...)  max(...)  uid()  label(name)
defined(name)

substr() は開始位置と長さを文字列にクランプします。負の開始位置は先頭 (0) を意味し、
Python 風の末尾からのインデックスではありません。負の長さは 0 として扱われます。

label(name) は、label(".L1") のようにマクロ識別子として書けない名前について、
アセンブラ側のラベルまたは .equ の値を読みます。有効な識別子である名前は裸で書いて
読みます — 裸の識別子はまずマクロ変数として解決され、変数が見つからない場合にのみラベル
として解決されます。どちらの形式もソースファイルでのみ機能します。パターンファイルでは
まだラベルが存在しないので、裸の識別子はマクロ変数としてのみ解決されます。どちらの形式
が読むのも、この節の冒頭で述べたとおり前回のリラクゼーション反復の値です。

マクロ内の暗黙変数:

名前 内容
__id__ 呼び出しごとに一意な整数 — ローカルラベル生成用
__name__ マクロ名

7.4 パターンファイル中のマクロ

パターンファイルも同じマクロ層を通ります。命令テーブルはレジスタ番号やオペコードだけが
異なる同形の行の並びになりがちなので、その行を生成できます:

!def alu(name, base) {          /* 文の行では、パターンファイルのコメント構文
!local r = 0
!while r < 8 {
!{name} A,R!{r} :: 0x!{base + r:02x}
!set r = r + 1
}
}
!alu("ADD", 0x80)
!alu("SUB", 0x90)

エラーフィールドも生成できるので、一度書いた範囲チェックが生成されたすべての行に適用
されます:

!def imm(name, op) {
!{name} A,!v :: v>0xff;2,v<0;2 :: 0x!{op:02x},v
}
!imm("ADDI", 0xc6)
!imm("SUBI", 0xd6)

ソース側と異なる点が 3 つあります。構文、組み込み関数、暴走防止は同一です。

  1. 独立した名前空間。 パターン側とソース側は独立したマクロ環境を持ち、互いのマクロ
    や変数を見ることはできません。したがってパターンファイルのマクロがソースファイルの
    展開のされ方を変えることは決してなく、リラクゼーション中にソース側が行うパスごとの
    リセットが、パターンファイルの読み込み中に定義されたマクロを消し去ることも決して
    ありません。
  2. 文の行のコメントは /* を使い、 パターンファイルの慣習に合わせます。そこでは
    ; はコメントマーカーではありません。エラーフィールドでエラーコード接尾辞を導入する
    からです (v>0xff;2)。
  3. より厳しい起動条件。 パターンファイルでは ! はパターン変数のシジル (ADD A,!d)
    であり、ほぼすべての行に現れるので、その行が本当にマクロ文として取られる場合、
    エスケープされていない !{...} を含む場合、または } で始まる場合にのみ層が起動
    します。マクロを使わないパターンファイルは層を完全にスキップします。同梱のすべての
    パターンファイルはバイト単位で自分自身に展開され、従来と同じ時間でアセンブルされます。

生成されたパターンテキストをアセンブルせずに確認するには -p を使います。

7.5 互換性と制限

後方互換性:

  • ! で始まる行が横取りされるのは、キーワードを含む場合、定義済みマクロを名指しする
    場合、または直後に ( が続く場合だけです。VLIW の !! と !F / !D / !Q 形式は
    そのままです。
  • 行頭の } がブロックを閉じるのは、ブロックが開いているときだけです。
  • マクロを含まないソースは、マクロ層が存在する前と同一の出力を生成します。

制限:

  • ソース側の .include はマクロ層をバイパスします。マクロ定義ファイルには !include
    を使ってください。(パターン側の .include は層を通ります。)
  • !{a ? b : c:04x} — 三項演算子とフォーマット指定の組み合わせ — は現在パースできません。
  • プロンプトモードはマクロ層をバイパスします。

暴走防止: 再帰 200 段、!while 反復 1,000,000 回、生成行 2,000,000 行、!include の
入れ子深さ 64。いずれかの上限を超えるとエラーを発生させ、そのパスの残りの展開を中断
します。

7.6 例

!include "lib.inc"

!def table(name, from, to) {
!{name}:
!set v = from
!while v <= to {
DB !{v}
!set v = v + 1
}
}

!def loopblk(n) {
!if n == 0 !then {
!return
}
L!{__id__}_top:
LD A,!{n}
LD HL,L!{__id__}_top
}

!def sq(x) {
!return x * x
}

start:
LD HL,end
!table("mytab", 1, 5)
!loopblk(2)
LD HL,!{sq(16)}
end:
NOP

8. オブジェクト出力、エクスポートとインポート

8.1 ファイル形式

-e、-E、-i が扱うファイルはタブ区切りです。フィールドは本物のタブで区切られて
いなければならず、スペースで区切られた行は黙って無視されます。

レコードの形は 2 種類あります。セクションレコードは 3 フィールド(-E では 4)、
ラベルレコードは 2 フィールドです:

セクション名   開始アドレス   サイズ   [フラグ]
ラベル名       値

8.2 エクスポート (-e, -E)

アドレス、サイズ、値は 0x 接頭辞付きで書かれます。-E はセクションレコードに
ELF セクションフラグ (AX、WA、…) を保持する第 4 フィールドを追加します。-e は
それを省きます。ラベルは .export / .global が宣言した順に現れます。

axx x86_64.axx hello.s -E hello.tsv:

.text	0x401000	0x39	AX
_hello	0x401000
_start	0x401000
len	0xd

8.3 インポート (-i)

インポートファイルは同じ 2 つのレコード形を使い、混在させられます。
値は 16 進として読まれます。0x の接頭辞・符号(+ / -)・前後の空白は
あってもなくてもよく、数字は 0-9 a-f A-F だけです(下線や全角数字は読みません)。
絶対値は 2**192 未満です(6.4 節)。そのため -e / -E が書いたファイル
(-0x5 や 64 ビットを超える値を含む)はそのまま読み戻せます。読めない値の行は
黙って捨てられます。

  • 3 フィールドの行はセクションのアドレス範囲を宣言します。
  • 2 フィールドの行はインポートされるラベルを定義します。そのセクションは、アドレスが
    どの宣言済み範囲に入るかを、範囲の行をファイルに書かれた順に調べて推定されます。
    どれにも一致しなければ .text が仮定されます。

インポートされるラベルには :: で再配置タイプを付けられます:

.text	401000	39
mylabel	401010
otherlabel::pc32	401020

:: の後に受け付けられる名前は、ELF_MACHINES で選択されたマシンの named テーブルに
ある短縮名です。x86-64 の場合: abs64、abs32、abs32s、abs16、abs8、pc32、
rel32、plt32、pc16、pc8、pc64、got32、gotpcrel、got64。パターンファイルの
.elftype(3.7.6 節)で決めた名前もここに書けます。認識されない名前は警告を出して
無視されます。書き出し側では、名前表に名前が無い型番号に .elftype の名前が使われます。

同じ名前をパターンファイルの .reloc(3.7.5 節)も取ります。AArch64 の call26 の
ような命令フィールド型はそちらでしか意味を持ちません。シンボル単位では、どのオペランド
位置に当てるのかを言えないからです。

セクションレコードは省略可能です。ラベル値だけが必要なら:

label1	0
label2	1
label3	2

9. エラー

アセンブラ自身が発生させる診断:

条件 メッセージ
ラベルがパターンファイルのシンボルと衝突 is a pattern file symbol
ラベルが複数回定義されている label '名前' is already defined.
行をパースできない Syntax error(.passthru が有効なときは素通しされる。3.16 節)
参照されたラベルが定義されていない Label undefined
アセンブラ行またはパターン行の形式が不正 Illegal syntax in assemble line or pattern line.
EPIC テンプレートが設定されていない No vliw instruction-set defined.
VLIW パターンファイルの形式が不正 解釈中に報告される
出力(-b の生バイナリ、-o の ELF の中身)が 1 GiB を超える output size ... exceeds maximum(たいていは .org の誤り)

ラベルの定義に失敗した行(上の表の最初の 2 つ)は、ラベルの後ろに書かれた命令も
組みません。両実装はこの扱いをそろえており、エラーのあとに続く診断も一致します。

ソースの行を組んでいる最中に出る 1 行の error - / warning - には、末尾に
[ファイル:行] の形で場所が付きます(式の 0 除算・負のシフト・** の範囲、
.equ や .org の未定義ラベルなど)。行の番号は -v の一覧と同じ数え方で、
.include したファイルではそのファイルの行、マクロで展開された行ではその本体の行です。
.include したファイルを開けないときは、.include を書いた行の場所です。
パターンファイルを読んでいる間の診断と、出力の大きさやリラクゼーションのような全体に
ついての診断には付きません。マクロ層の診断は先頭に ファイル:行: を持つので、
ここでも付けません。1 つの行の中で場所まで同じ診断は 1 回だけ出します(式はパターンの
照合で何度も評価されるので、以前は同じ行が続けて並ぶことがありました)。

error_patterns が発生させ、; の後のコードで選ばれるエラー:

コード メッセージ
1 Invalid syntax.
2 Address out of range.
3 Value out of range.
4 (なし)
5 Register out of range.
6 Port number out of range.
7 以上 (なし)

本文のないコードも依然としてエラーを発生させ、出力ファイルの書き出しを妨げます。空白に
なるのはメッセージだけです。どちらの実装のソースにも手を触れずにパターンファイルから
メッセージを追加・上書きするには、.error::n::"メッセージ"(3.14 節)を使います。

axx ミニ言語の .raise n ディレクティブは、エラーコード n のエラーを発生させます。


10. 設計ノートと背景

この節は背景です。axx を使うのにここにあるものは何も必要ありません。

10.1 由来

axx は "Arbitrary eXtended X(cross) assembler" の略です。名前はまた、X — 未知の CPU —
を "ASM" に重ね合わせたことにも由来します。リファレンス実装が Python なので、その愛称は
Paxx です。

中心となるアイデア、名前、そして C によるプロトタイプは 1986 年に存在しており、大学時代
に東京電子設計でアルバイトをしながら着想されました。元のリストが 38 年後に再発見され、
今日公開されている動作コードは、それを 2024 年に Python で書き直したものです。
C 実装の Caxx が 2026 年に、Forth 実装の Faxx が同じ年の後半に加わりました。どちらも
Python 版と同じバイトを出すように書かれています。

10.2 メタ言語

instruction フィールドは手続き型アセンブリ言語のためのメタ言語です。固定の文法を持た
ない DSL — 文字列リテラル、シンボル、式から自分の文法を組み立てる自由構文のパターン言語
です。

最小限まで還元すると、手続き型アセンブリ言語は instruction :: binary_list です。
エラーチェックは追加であり、axx の binary_list が式の評価、アラインメント、; 修飾子
を加えているのは必要性からではなく実用のためです。

axx がしているのは、ノイマン型アーキテクチャの共通構造を抽出し、ISA をメタモデル化し、
その結果をパターンマッチングとして形式化することです。

10.3 なぜパターン言語はチューリング完全でないのか

プロセッサアーキテクチャは、そうしようと選べばいくらでも複雑にできます。チューリング
完全なパターン言語はそれにどこまでも追随できますが、axx のものはできません。それこそが
axx を万能 (universal) ではなく汎用 (general) アセンブラたらしめているものです。

この制限の理由は、チューリング完全な DSL はパターンファイルをプログラムにしてしまい、
パターンマッチングの停止性が保証されなくなるからです。その保証は、追加の射程よりも
価値があると判断されました。マクロ層は別の段階であり、このような制限を受けません。

パターンファイルはチューリング完全ではありませんが、計算が必要な場合は binary_list
から .call func() でチューリング完全な関数(ミニ言語)を呼び出せます。

パターンファイルは明示的な構造を持たないので、構造化されていない命令エンコーディングに
よく適合します。.check(3.6 節)は、望むときに構造を課すための手段です — たとえば
a、b、c がそれぞれ固定の集合を動く MOV a b c r,s のような命令です。


付録 A. 例

A.1 Z80

.setsym:: BC:: 0x00
.setsym:: DE:: 0x10
.setsym:: HL:: 0x20
LD s,!d:: (s&0xf!=0)||(s>>4)>3;9 :: s|0x01,d&0xff,d>>8

ld bc,0x1234、ld de,0x1234、ld hl,0x1234 はそれぞれ 0x01,0x34,0x12、
0x11,0x34,0x12、0x21,0x34,0x12 を出力します。

A.2 複数プロセッサの断片

テストフィクスチャです。エンコーディングは本物ではありません。

test.axx
/* test
.setsym ::a:: 7
.setsym ::b:: 1
.setsym ::%% ::7
.setsym ::||:: 8
LDF A,!Fx :: 0x1,x,*(x,1),*(x,2),*(x,3)
LDD A,!Dx :: 0x1,@@[8,*(x,%%)]
LDQ A,!Qx :: 0x1,@@[16,*(x,%%)]
LDR A,[ [ !x ] ]:: ~~0x3?3:0,x,x>>8
LD\! A,B::0xcd

/* ARM64
.setsym ::r1 :: 2
.setsym ::r2 :: 3
.setsym ::r3 :: 4
.setsym ::lsl:: 6
VMOV.F32 S!n,#!Fd::0x80|n,d>>24,d>>16,d>>8,d
ADD w, x, y z #!d :: 0x88,d
.check ::q::r1,r2
ADD q, y, !e :: 0x91,q,y,e
.clrcheck::q

/* A64FX
.setsym ::v0 :: 0
.setsym ::x0 :: 1
ST1 {x.4S},\[y\] :: 0x01,x,y,0

/* MIPS
.setsym ::$s5 ::21
.setsym ::$v0 ::2
.setsym ::$a0 ::4
ADDI x,y,!d :: @@[4,*(e:=(0x20000000|(y<<21)|(x<<16)|d&0xffff),(3-%%))]

/* x86_64
.setsym ::rax:: 0
.setsym ::rbx:: 3
.setsym ::rcx ::1
.setsym ::rep ::1
.setsym ::per::2
.clearsym::per

MMX A,B ::  ,0x12,0x13
LEAQ r,\[s,t,!d,!e\] :: 0x48,0x8d,0x04,((@d)-1)<<6|t<<3|s,e
LEAQ r, ( s+t*!h\+!i) :: 0x48,0x8d,0x04,((@h)-1)<<6|t<<3|s,i
[[z]]MOVSB :: ;z?0xf3:0,0xa4
TEST !a:: a==3?0xc0:4,0x12,0x13

/* ookakko test
LD (IX[[+!d]]),(IX[[+!e]]):: 0xfd,0x04,d,e 
NOP :: 0x01
LOAD A,[B] :: 0x43
REPEAT !n::@@[n,%%],%0@@[n,0x10+%%]
test.s
ldf a,3.14
ldf a,3.14*2+1
ldd a,3.14
ldd a,-inf
ldq a,3.14*2+1
leaq rax , [ rbx , rcx , 2 , 0x40]
leaq rax , ( rbx + rcx * (2+2) + 0x40 )
addi $v0,$a0,5
vmov.f32 s0,#3.14
st1 {v0.4s},[x0]
add r1, r2, r3 lsl #20
rep movsb
movsb
load a,[b]
repeat 10
ldf a,label
label: .equ flt{3.14}
ldf a,flt{enfloat(:label)*2}
$ axx test.axx test.s -v
0000000000000000 test.s 1 ldf a,3.14 // 0x01 0xc3 0xf5 0x48 0x40
0000000000000005 test.s 2 ldf a,3.14*2+1 // 0x01 0xc3 0xf5 0xe8 0x40
000000000000000a test.s 3 ldd a,3.14 // 0x01 0x1f 0x85 0xeb 0x51 0xb8 0x1e 0x09 0x40
0000000000000013 test.s 4 ldd a,-inf // 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0xf0 0xff
000000000000001c test.s 5 ldq a,3.14*2+1 // 0x01 0x1f 0x85 0xeb 0x51 0xb8 0x1e 0x85 0xeb 0x51 0xb8 0x1e 0x85 0xeb 0xd1 0x01 0x40
000000000000002d test.s 6 leaq rax , [ rbx , rcx , 2 , 0x40] // 0x48 0x8d 0x04 0x4b 0x40
0000000000000032 test.s 7 leaq rax , ( rbx + rcx * (2+2) + 0x40 ) // 0x48 0x8d 0x04 0x8b 0x40
0000000000000037 test.s 8 addi $v0,$a0,5 // 0x20 0x82 0x00 0x05
000000000000003b test.s 9 vmov.f32 s0,#3.14 // 0x80 0x40 0x48 0xf5 0xc3
0000000000000040 test.s 10 st1 {v0.4s},[x0] // 0x01 0x00 0x01 0x00
0000000000000044 test.s 11 add r1, r2, r3 lsl #20 // 0x88 0x14
0000000000000046 test.s 12 rep movsb // 0xf3 0xa4
0000000000000048 test.s 13 movsb // 0xa4
0000000000000049 test.s 14 load a,[b] // 0x43
000000000000004a test.s 15 repeat 10 // 0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x10 0x11 0x12 0x13 0x14 0x15 0x16 0x17 0x18 0x19
000000000000005e test.s 16 ldf a,label // 0x01 0xec 0x91 0x80 0x4e
0000000000000063 test.s 17 label: .equ flt{3.14} //
0000000000000063 test.s 18 ldf a,flt{enfloat(:label)*2} // 0x01 0xec 0x91 0x81 0x4e

A.3 AArch64 論理即値

おそらく単一のパターンで表現できる最も複雑なものです。このようなエンコーディングは
1 つのマクロにまとめられます(7.4 節)。

同梱の aarch64_logical_mini.axx は同じ命令グループを、代わりに
3.15 節のミニ言語でカバーしています。自分でこのような
ものを書くなら、そちらから始めるのがよい形式です。下の 1 行版は、宣言的コアの射程を
示すデモンストレーションとしてここに残してあります。

AND d,n,#!v ::v==0;3,v==0xFFFFFFFFFFFFFFFF;3 ::;(e:=((v&3)*0x5555555555555555==v)?2:((v&0xf)*0x1111111111111111==v)?4:((v&0xff)*0x0101010101010101==v)?8:((v&0xffff)*0x1000100010001==v)?16:((v&0xffffffff)*0x100000001==v)?32:64)*0,;(m:=(1<<e)-1)*0,;(y:=v&m)*0,;(t:=@(y^(y-1))-1)*0,;(u:=y>>t)*0,;(w:=(y^m)==0?1:y^m)*0,;(p:=@(w^(w-1))-1)*0,;(q:=w>>p)*0,;(c:=((u+1)&u)==0)*0,;(b:=c?@u:e-@q)*0,
 ;(r:=c?(e-t)&(e-1):(e-(p+@q))&(e-1))*0,;(s:=((-2*e)&0x7f)|(b-1))*0,;(z:=(1<<31)|(0x24<<23)|((((s>>6)&1)^1)<<22)|(r<<16)|((s&0x3f)<<10)|(n<<5)|d)*0,@@[4,z>>(%%*8)]

紙面の都合で 2 行に折っています。2 行目の先頭の空白を除いて 1 行につなぐか、1 行目の
末尾に \ を置き 2 行目を字下げせずに書きます(3.1 節の行の継続。2 行のまま写すと、
2 行目が「:: の無い行」として警告されます)。d と n はレジスタのシンボル(.setsym ::x0:: 0 など)です。
#0x5555555555555555・#0xff・#0xf0f0f0f0f0f0f0f0・#0x7ffffffffffffffe などの符号は
llvm-mc と一致します。

A.4 bf インタプリタを動かす — bfsh/

同梱の Brainfuck インタプリタ(asmsrc/ の bf_*.s)は、axx でアセンブルし、リンカで
実行ファイルにして、そのまま動かせます。この手順を 1 本ずつにまとめたシェルスクリプトが
bfsh/ にあります。名前は bf_<CPU>_<OS>.sh です。

スクリプト 組むソース パターンファイル 走らせ方
bf_x86_64_freebsd.sh bf_x86_64.s(!set OS = "freebsd") x86_64.axx そのまま
bf_x86_64_linux.sh bf_x86_64.s(!set OS = "linux") x86_64.axx そのまま(FreeBSD では Linuxulator)
bf_mips_freebsd.sh bf_mips_freebsd.s mips.axx / mipsel.axx qemu-mips / qemu-mipsel(bsd-user)
bf_mips_linux.sh bf_mips.s mips.axx / mipsel.axx qemu-mips / qemu-mipsel(linux-user)
bf_riscv64_freebsd.sh bf_riscv64_freebsd.s riscv64full.axx qemu-riscv64(bsd-user)
bf_riscv64_linux.sh bf_riscv64.s riscv64full.axx qemu-riscv64(linux-user)
bf_aarch64_linux.sh bf_aarch64.s aarch64.axx qemu-aarch64(linux-user)
bf_ppc64_linux.sh bf_ppc64.s ppc64.axx qemu-ppc64(linux-user)
bf_sparc_freebsd.sh bf_sparc.s(!set OS = "freebsd") sparc.axx qemu-sparc64(bsd-user)
bf_sparc_linux.sh bf_sparc.s(!set OS = "linux") sparc.axx qemu-sparc64(linux-user)
bf_x64_freebsd.sh / bf_x64_linux.sh bf_aarch64.s を x86_64 へ翻訳したもの a64tox64_axx.axx、x86_64.axx そのまま(3.18 節)

bf_aarch64.s と bf_ppc64.s には Linux 用しかないので、この 2 つには _freebsd の
スクリプトがありません。bf_x86_64.s と bf_sparc.s はマクロ層の !set OS で OS を
切り替えるので、スクリプトはその行を書き換えた写しを組みます。

使い方。 引数で、組み立てたあとに何を走らせるかを決めます。

./bfsh/bf_riscv64_freebsd.sh                # 組み立てるだけ。build_bf_riscv64_freebsd/bf ができる
./bfsh/bf_riscv64_freebsd.sh run            # 組み立てて、同梱の mandelbrot.bf を走らせる
./bfsh/bf_riscv64_freebsd.sh run hello.bf   # 組み立てて、指定した .bf を走らせる
./bfsh/bf_riscv64_freebsd.sh hello.bf       # run を省いても同じ

組み立て先はカレントディレクトリの build_bf_<CPU>_<OS>/(mipsel は
build_bf_mipsel_<OS>/、bf_x64_*.sh は build_bf_freebsd/ / build_bf_linux/)です。
スクリプトはどのディレクトリから呼んでも構いません。パターンファイルとソースは
スクリプトの一つ上のディレクトリから探すので、リポジトリの patfile/・asmsrc/ の配置
でも、すべてが同じ階層にある配置でも動きます。

環境変数。

変数 意味
AXX 使うアセンブラ。既定は caxx。AXX=paxx で Python 版。ディレクトリを指しているときは、その中の caxx を使う
LD 使うリンカ。既定は ld.lld(x86_64 は ld)
QEMU 実行に使う qemu。空(QEMU=)にすると qemu を通さずに走らせる。既定は下の規則で決まる
ENDIAN bf_mips_*.sh だけ。eb(既定、mips.axx)か el(mipsel.axx)

qemu の選び方。 ホストと同じ CPU なら qemu を通さずに走らせます。違うときは次の
ように選びます。qemu のユーザーモードは、自分と同じ OS の実行ファイルしか走らせません。

  • _freebsd のスクリプト: FreeBSD の qemu-<CPU>-static(bsd-user)、無ければ
    qemu-<CPU>。FreeBSD 以外のホストでは、組み立てたところで止まります。
  • _linux のスクリプトを Linux で使うとき: qemu-<CPU>-static(Debian などの
    qemu-user-static)、無ければ qemu-<CPU>。
  • _linux のスクリプトを FreeBSD で使うとき: /usr/local/bin の qemu は bsd-user で、
    Linux の実行ファイルを走らせません。そこで Linuxulator(linux64.ko)に入れた Linux の
    qemu-user、/compat/linux/usr/bin/qemu-<CPU> を使います。Rocky Linux 9 系の
    /compat/linux なら、el9 の qemu-user の rpm を rpm2cpio | bsdtar -x で展開して
    入れます。qemu 11.1.1 では、ほかに libcapstone.so.4(capstone)と libnuma.so.1
    (numactl-libs)が要ります。x86_64 の Linux 版は qemu を使わず、Linuxulator で直接
    走ります。

ブランド。 FreeBSD のカーネルは ELF ヘッダの OS/ABI を見ます。ld.lld は RISC-V の
実行ファイルの OS/ABI を System V にするので、_freebsd のスクリプトはリンクの後で
brandelf -t FreeBSD(無ければ elfedit --output-osabi FreeBSD)を付けます。逆に
FreeBSD の ld は x86_64 の出力に FreeBSD のブランドを付けるので、FreeBSD 上の
bf_x86_64_linux.sh と bf_x64_linux.sh は brandelf -t Linux を付け直します。

FreeBSD 14.3/amd64 で、どのスクリプトの実行ファイルも mandelbrot.bf を最後まで描き、
出力がすべて一致することを確かめてあります(qemu の上では 1 本 2〜5 分ほどかかります)。


付録 B. 同梱パターンファイル

x86_64.axx、x86_64m.axx、aarch64.axx、ppc64.axx、ppc64le.axx、68000.axx、
z80.axx、8080.axx、8048.axx、8051.axx、6502.axx、6800.axx、6809.axx、
4004.axx、riscv64full.axx、mips.axx、mipsel.axx、mips64.axx、mips64el.axx、
mipsr6.axx、mipsr6el.axx、mips64r6.axx、mips64r6el.axx、sparc.axx は実用向けです。riscv64.axx は RV64I の基本整数部分の範囲で、
aarch64_logical.axx と aarch64_logical_mini.axx はカバーする 1 つの命令グループの
範囲内で実用向けです。残りはテストフィクスチャです。

x86_64 パターンファイルは
https://github.com/fygar256/x86_64_pattern_file_for_axx でも別途メンテナンスされて
います。

パターンファイル サイズ :: 行数 ソース 備考
x86_64.axx 4.2 MB 28,659 hello.s、bsection.s、x86_64_reloc.s、x86_64_rex.s、x86_64_avx.s、x86_64_err.s、reloctype.s x86_64-v3: セグメントアドレッシング、AVX/AVX2、BMI1/BMI2、x87、EVEX/AVX-512。AVX 以降は llvm-mc と照合(表の後の注)
x86_64m.axx 1.0 MB 6,531(展開後 28,791) hello.s、x86_64_reloc.s、x86_64_rex.s、x86_64_avx.s、x86_64_err.s マクロで書かれた x86_64-v3。Brainfuck デモでも使用。展開結果は x86_64.axx と同じパターンの集合(重複行を除けば一致)
aarch64.axx 352 KB 2,112(展開後 9,431) aarch64.s、aarch64_reloc.s、aarch64_edge.s、aarch64_err.s AArch64 (A64): データ処理、分岐、例外生成、ヒント、バリア、システムレジスタと SYS 別名、ロード/ストア、LSE アトミック、スカラ浮動小数点、Advanced SIMD(LD1〜LD4 / ST1〜ST4 の構造アクセスを含む)、暗号、スカラ拡張(PAuth・MTE・MOPS・FCMA・ドット積・BFloat16・行列積・LS64)。さらに SVE・SVE2(算術、シフト、比較、述語、要素数、置換、リダクション、ギャザー/スキャッタを含むロード/ストア一式、拡幅・縮小群、複素演算、SVE2 暗号)、SME(ストリーミングモード、ZA 配列、整数・浮動小数点・BFloat16 の外積)、SME2(述語カウンタレジスタ、ZT0 参照表、Z レジスタのマルチベクタ演算、ZA への累算、連続形と跨ぎ形のマルチベクタロード/ストア)。GNU 式のリロケーション修飾子(:lo12:・:pg_hi21:・:abs_g0:〜:abs_g3:・:prel_g0:〜:prel_g3:・:got:/:got_lo12:)は -o でリンカ向けのリロケーションとして出し、-b では axx 自身が解決する。-o では -m なしで AArch64 のオブジェクトになり、同じセクションの局所ラベルへの分岐・adr・リテラルの ldr はその場で解決し、データの命令(.byte .hword .word .quad .xword など)は ABS / PREL のリロケーションを持つ(aarch64_reloc.s、llvm-mc 19 と照合)。マクロ層で記述
aarch64_logical.axx 9.5 KB 76(展開後 82) aarch64_logical_mini_demo.s 同じ AArch64 論理(即値)グループのマクロ層版。行を !def で生成し、ビットマスク即値は binary_list の式で符号化する
aarch64_logical_mini.axx 9.2 KB 86 aarch64_logical_mini_demo.s AArch64 論理(即値): AND/ORR/EOR/ANDS/TST、32 ビットと 64 ビット。ビットマスク即値をミニ言語(3.15 節)でエンコード
ppc64.axx 2.8 KB 53(+ ppc64_isa.axx) ppc64_test.s、ppc64_reloc2.s ほか PowerPC64 ビッグエンディアン (ELFv1)。バイト順と ELF 記述(.elftype/.elffield/.elfpcguess/.elfsection)を決めて ppc64_isa.axx を include する
ppc64le.axx 2.8 KB 54(+ ppc64_isa.axx) ppc64_test.s、ppc64_reloc2.s ほか 同じくリトルエンディアン (ELFv2)
ppc64_isa.axx 96 KB 454(展開後 4,776) — ppc64.axx / ppc64le.axx が共有する Power ISA v3.1 (POWER10) の命令セット本体。axx に直接渡さない。固定小数点、拡張ニーモニックを含む分岐、浮動小数点、十進浮動小数点、VMX、VSX、四倍精度、前置形マスク付きを含む MMA、前置命令(64 バイト境界を跨ぐ前置命令の前には nop を入れる)。マクロ層とミニ言語で記述
mips.axx 919 B 1(+ mips_isa.axx) mips.s、mips_ase.s、mips_reloc2.s、mips_err.s MIPS ビッグエンディアン、o32(ELF32、REL)、Release 5 まで。バイト順と ABI とリリースを決めて mips_isa.axx を include する
mipsel.axx 926 B 1(+ mips_isa.axx) mips.s、mips_ase.s、mips_reloc2.s 同じくリトルエンディアン、o32
mips64.axx 928 B 1(+ mips_isa.axx) mips.s、mips_ase.s、mips64_reloc2.s MIPS64 ビッグエンディアン、n64(ELF64、RELA)
mips64el.axx 935 B 1(+ mips_isa.axx) mips.s、mips_ase.s、mips64_reloc2.s 同じくリトルエンディアン、n64
mipsr6.axx 931 B 1(+ mips_isa.axx) mipsr6.s MIPS32 Release 6、ビッグエンディアン、o32
mipsr6el.axx 938 B 1(+ mips_isa.axx) mipsr6.s 同じくリトルエンディアン、o32
mips64r6.axx 938 B 1(+ mips_isa.axx) mipsr6.s MIPS64 Release 6、ビッグエンディアン、n64
mips64r6el.axx 945 B 1(+ mips_isa.axx) mipsr6.s 同じくリトルエンディアン、n64
mips_isa.axx 79 KB 155(展開後 約 5,000、Release 6 では約 3,570) — 上の 8 つが共有する MIPS の命令セット本体。axx に直接渡さない。MIPS I から MIPS64 Release 6 まで: 整数命令一式(Release 2 のビット欄・バイト入れ替え命令を含む)、特権命令(COP0、TLB)、FPU(S・D・W・L・PS の各形式、16 種の c.cond、COP1X)、COP2、MIPS I の COP3、GNU の疑似命令(li・dli・la・dla・move・b など、$at を使わない範囲)、リロケーション修飾子(%hi・%lo・%higher・%highest・%gp_rel・%got 系・%call16 系・TLS 系・%pcrel_hi / %pcrel_lo)。拡張は DSP(Release 1・2、R6 では Release 3)、MSA、MT、VZ、EVA、MIPS-3D、SmartMIPS、MCU、XPA、CRC、GINV。前置きファイルの R6() が 1 なら Release 6 で消えた命令(分岐 likely、HI / LO の乗除算、lwl 系、movz 系、FP の条件コード、PS、COP1X など)を外し、clz・ll / sc・cache / pref・lwc2 系・jr などを Release 6 の符号で出し、新命令(コンパクト分岐、aui 系、PC 相対の lwpc / auipc 系、3 オペランドの乗除算、cmp.cond.fmt、maddf などの FPU 命令)を足す。構文は .set noreorder / .set noat の GNU as。microMIPS / MIPS16e(圧縮符号)、MDMX、ベンダー拡張は含まない。-o では o32 は REL(加数を欄に書き戻す)、n64 は RELA(r_info に 3 つの型)で出し、Release 6 の PC 相対リロケーション(R_MIPS_PC21_S2・PC26_S2・PC19_S2・PC18_S3・PCHI16・PCLO16)も出す。マクロ層とミニ言語で記述
sparc.axx 55 KB 243(展開後 7,982) sparc_test.s、sparc_reloc.s、sparc_reloc2.s、bf_sparc.s、sparc_err.s SPARC V7 / V8 / V9 と VIS 1〜3。整数・シフト・sethi、Bicc / BPcc / FBfcc / FBPfcc / BPr / V8 の CBccc(,a と ,pt / ,pn)、call・jmpl・return・Tcc、movcc / movr / fmovcc / fmovr、整数と浮動小数点のロード/ストア一式(代替空間の ASI 番号・#ASI_* 名・%asi、casa / casxa、prefetch)、FPop1 / FPop2 の全命令(s・d・q、変換、fcmp、UltraSPARC Architecture 2007 の fnadd 系)、積和(fmadd 系)、rd / wr・rdpr / wrpr・V8 の %psr 系・UA2005 の rdhpr / wrhpr、membar(#StoreLoad などの名前)、V8 のコプロセッサ、LEON の umac / smac / pwr、合成命令(cmp・mov・set / setuw / setsw / setx・clr 系・inc 系など)、修飾子(%hi・%lo・%hh・%hm・%h44・%m44・%l44・%hix・%lox・%pc22・%pc10・GOT 系・TLS 系)。-o は ELF64 SPARCV9(RELA)。llvm-mc 19 とバイト単位で照合し、llvm-mc に無い行は仕様書の符号と照合した。マクロ層とミニ言語で記述
6809.axx 138 KB 1,950 6809.s、6809_edge.s、6809_err.s Motorola 6809
68000.axx 59 KB 457 68000.s、68000_reloc.s、68000_err.s Motorola 68000。-o は -m なしで ELF32 M68K(RELA)。型を書かない .extern は R_68K_32、同じセクションへの 16 / 8 ビットの PC 相対は axx が解決する
6800.axx 20 KB 271 6800.s、6800_edge.s、6800_err.s Motorola 6800
6502.axx 15 KB 202 6502.s、6502_edge.s、6502_err.s MOS 6502
z80.axx 8.8 KB 283 z80.s、z80_err.s、import_test.s、import_test_err.s、listinc.s、labelc_err.s、dirjunk_err.s Zilog Z80
8051.axx 9.1 KB 111 8051.s、8051_err.s Intel 8051
8080.axx 6.4 KB 113 8080.s、8080_err.s Intel 8080
8048.axx 6.5 KB 96 8048.s、8048_edge.s、8048_err.s Intel 8048
4004.axx 5.6 KB 53 4004.s、4004_edge.s、4004_err.s Intel 4004
test.axx 1.1 KB 40 test.s 複数 ISA の断片。テスト専用
8080toz80.axx 5.7 KB 117 hello8080.s Intel 8080 → Zilog Z80 のソース翻訳器。.textmode・!L・{{.exp()}}(3.18 節)の実例
textmode.axx 2.0 KB 13 textmode.s .textmode・!L・{{.exp()}}・; コメント(3.18 節)。テスト専用
callstr.axx 2.0 KB 12 callstr.s .textmode で .call が返す文字列がテキストとして出ること、-V が -b と同じバイト列(.emit の分も)を書くこと(3.18 節)。テスト専用
expcap.axx 2.8 KB 36 expcap.s どの捕捉子でも {{.exp()}} が綴りを出すこと(3.18 節)。テスト専用
exprmiss.axx 1.1 KB 8 exprmiss.s 式・因子のあるべきところに式・因子が無い行(空、1+、-、~、())は !・!!・!L・!F/!D/!Q のどれにも当たらず、.passthru で素通しされること(3.3 節)。テスト専用
arrindex.axx 860 B 14 arrindex.s 配列シンボルの素の名前・名前の添字・.index(3.6.1 節)。テスト専用
passthru.axx 686 B 6 passthru.s .passthru と .eol(3.16 / 3.17 節)。テスト専用
datadir.axx 1.0 KB 3 datadir.s、datadir_err.s .db / .dw / .dd / .dq / .do / .dy / .dz(5.3 節)。8 ビット、little、.eol 付き。テスト専用
datadirbe.axx 613 B 3 datadir.s 同じソースを 8 ビット、big で組む。テスト専用
datadirw.axx 764 B 3 datadir.s 同じソースを 16 ビットワードで組む。テスト専用
unordered.axx 1.7 KB 28 unordered.s .unordered と変数ごとの .map(3.19 節)。Z80 の C をレジスタとキャリーに使い分ける。テスト専用
symcap.axx 1.1 KB 12 symcap.s シンボル捕捉子 !Y<集合>[<変数>](3.6.3 節)。テスト専用
echo.axx 1.2 KB 8 echo.s 本文行に書く .echo(3.14.1 節)。テスト専用
ministr.axx 6.4 KB 27 ministr.s ミニ言語の文字列・文字列の配列・.for ... in 配列(3.15 節)。テスト専用
regress.axx 5.2 KB 23 regress.s、regresserr.s、regresscr.s(と z80.axx で regresself.s) 差分ファジングで見つけて直した Paxx と Caxx の食い違いの回帰テスト(入れ子の三項、桁の多い数値リテラル、pow の特別な場合、マクロ層の int()・hex()・書式指定、エラー後の診断、セクションの終わりのラベルを指す .equ、未定義を含む .equ の値、空白と文字定数の規則、マクロ層のバイト単位の文字列、CR だけの改行、UTF-8 でないバイトの一覧、-o で後ろへ戻す .org、error_patterns の整数での評価、** の結果の大きさ、非 ASCII の大文字化、式の後ろの文字と欠けた因子)。テスト専用
elftype.axx 1.5 KB 20 elftype.s .elftype で決めた型名を .reloc / .extern / .global に書く(3.7.6 節)。テスト専用
elfgen.axx 2.7 KB 32 elfgen.s 組み込みの表に無いマシン(EM_MSP430)の ELF 記述(3.7.7 節)。テスト専用
elfprio.axx 1.7 KB 21 elfprio.s リロケーション型の優先順位(既定 < パターンファイル < ソースファイル、3.7.8 節)。テスト専用
elfsec.axx 1.4 KB 8 elfsec.s .elfsection で宣言するセクションの属性と sh_addralign(3.7.7 節)。テスト専用
elfpair.axx 4.7 KB 39(+ riscv64.axx) elfpair.s 対になるリロケーションと添え物(.elfextra・.elfdiff、多項の式・型付きの差を含む)、セクショングループ(.elfgroup)、sh_link(.elflink)、リンカ緩和の機種の CFI。RISC-V。リロケーション・グループ・セクションヘッダは llvm-mc と一致(3.7.10・3.7.11 節)。テスト専用
elfcfi.axx 1.9 KB 29 elfcfi.s、cfiptr.s CFI(.cfi_* から .eh_frame、.elfcfi・.elfcfiinit・.elfcfireg)。x86-64。.eh_frame の表は llvm-mc と一致(3.7.11 節)。テスト専用
elfmips.axx 3.1 KB 31 elfmips.s REL の書き戻し関数(.elfencode、R_MIPS_HI16)。MIPS32。命令語・リロケーション・リンク後の .text は llvm-mc / ld.lld と一致(3.7.10 節)。テスト専用
elfmips64.axx 2.5 KB 28 elfmips64.s r_info を組む関数(.elfrinfo)。MIPS64 n64(3.7.10 節)。テスト専用
elfword.axx 1.6 KB 24 elfword.s 加数とシンボル値の単位(.elfunit::word)。1 ワード 16 ビットの架空の機種(3.7.10 節)。テスト専用
elfrel.axx 4.1 KB 41 elfrel.s .elfbuiltin::0 で組み込みの表を使わずに書いた ARM(EM_ARM)の記述と、REL の命令フィールド型(.elffield のシフトと補正、3.7.7・3.7.9 節)。命令語とリロケーションは llvm-mc と一致。テスト専用
elfsym.axx 2.8 KB 23 elfsym.s ソース側の ELF シンボル属性(.type・.size・.weak・.hidden・.protected・.internal・.other・.comm、5.6.1 節)と、2 の冪でない欄の幅(.elfwidth::3)・セクションの要素長(.elfsection の第 5 欄、3.7.7 節)。機種は組み込みの表に無い EM_MN10300。テスト専用
riscv64.axx 13 KB 137 riscv64.s、riscv64_reloc2.s RV64I の基本整数命令(U/I/S/B/J/R 形式、ロード/ストア、分岐、ジャンプ、call、li/mv/j/ret/nop、ecall/ebreak)。C・M・A・F/D 拡張、CSR、fence 群は含みません。組み込みの EM_RISCV 表はデータ型しか持たないので、CALL_PLT・BRANCH・JAL・HI20・LO12_I/_S・PCREL 対を .elftype/.elffield/.reloc で宣言する実例でもあります(3.7.5〜3.7.7 節)。ld -m elf64lriscv でリンクでき、動きます
riscv64full.axx 78 KB 281(展開後 3,585) riscv64full.s、riscv64full_reloc.s、riscv64full_reloc2.s、riscv64full_edge.s、riscv64full_err.s RISC-V RV64 の全体: I、M、A(Zabha・Zacas・Zawrs を含む)、F、D、Q、Zfh、Zfa、C(Zca・Zcd・Zcb・Zcmp・Zcmt・Zcmop)、Zba / Zbb / Zbc / Zbs、Zbkb / Zbkc / Zbkx、Zknd / Zkne / Zknh / Zksed / Zksh、Zicond、Zicbom / Zicboz / Zicbop、Zihintntl、Zimop、Zicfiss / Zicfilp、CSR 名つきの Zicsr、特権命令と H 拡張、V 1.0(Zvbb・Zvbc・Zvkg・Zvkned・Zvknh・Zvksed・Zvksh と bf16 の部分を含む)。GNU の疑似命令(任意の 64 ビット定数の li、call、tail、la、グローバルのロード/ストアなど)と、丸めモードや v0.t マスクの省略可能な指定にも対応します。riscv64.axx の上位版で、命令が持つ RISC-V psABI のリロケーションを宣言します。llvm-mc 18 とバイト単位で照合し、-o のリロケーションとリンク後のイメージも LLVM のものと照合しました。LLVM 18 に無い部分(Q、Zabha、vwsll、mnret、c.ntl.*、c.sspush)は仕様書から起こしています。riscv64full.s は各行の実行例、riscv64full_reloc.s と riscv64full_reloc2.s(la / lla とグローバルのロード/ストア、PC 相対のデータ、ラベル差。llvm-mc 19 と照合)は -o 用
endsub.axx 1.2 KB 20 endsub.s .sub ブロックを .endsub で閉じる(3.7.2 節)。テスト専用
intel2att.axx 12 KB 60(展開後 3,437) intel2att.s x86-64 Intel 記法 → AT&T 記法 のソース翻訳器。.textmode・!Y・!L・マクロ層でのパターン生成(3.18 節)。翻訳結果は GNU as に通る
a64tox64_axx.axx 32 KB 152(展開後 1,903) bf_aarch64.s AArch64 → x86_64 のソース翻訳器。出力は x86_64.axx でアセンブルできる記法。ランタイム a64rt_axx.s(Linux)・a64rt_axx_freebsd.s(FreeBSD)と宣言 a64ext.s を使う(3.18 節)
itanium.axx 281 B 12 vliw.s Itanium (EPIC) のスケッチ。未完成
vliw.axx 192 B 10 vliw.s、vliw_err.s 非 EPIC VLIW。テスト専用
bf.axx 128 B 9 bf.s Brainfuck 仮想 CPU。hello-world デモ

:: 行数は、ファイルに書かれている :: を含む行の数です。マクロ層で行を生成して
いるファイルには、括弧内に展開後の行数を添えています(展開後は
caxx <パターンファイル> -p <出力> で書き出せます)。

x86_64.axx が対になるのは hello.s(と、-b で先頭でないセクションの分岐を見る
bsection.s)であって、x86_64.s という名前のファイルではないことに注意してください。ppc64.axx と ppc64le.axx は ppc64_test.s(1 行 1
パターン行、GNU as とバイト単位で照合)・ppc64_reloc_test.s(-o のリロケーション)・
ppc64_reloc2.s(加数のビット 2〜3 が立つ DS / DQ 形式の欄と、label-$$ と書いた
データ。llvm-mc 19 と ld.lld 19 で照合)・hello_ppc64.s(ビッグエンディアンの
hello world)と対になり、ppc64_isa.axx は
その 2 つから include されるので直接は渡しません。mips.axx・mipsel.axx・mips64.axx・
mips64el.axx はどれも mips.s(基本命令セットの全行、GNU as 2.42 の n64 出力と
バイト単位で照合)と mips_ase.s(拡張の全行、llvm-mc 19 の出力とバイト単位で照合)
と対になり、mipsr6.axx・mipsr6el.axx・mips64r6.axx・mips64r6el.axx は
mipsr6.s(Release 6 で符号の変わった命令と新命令、llvm-mc 19 とリロケーションまで
照合)と対になります。mips_reloc2.s(o32)と mips64_reloc2.s(n64)は -o 用で、
la / dla と PC 相対のデータを、8 つの前置きファイルすべてで llvm-mc 19 と ld.lld 19
と照合しています。mips_isa.axx はその 8 つから include されるので直接は
渡しません。sparc.axx は sparc_test.s(1 行 1 パターン行、llvm-mc 19 とバイト単位で
照合)・sparc_reloc.s(-o のリロケーション、llvm-mc 19 と照合)・sparc_reloc2.s
(ラベルの set / setx、セクション内で解決する分岐、PC 相対のデータ。llvm-mc 19 と
ld.lld 19 と照合)・bf_sparc.s
(Brainfuck インタプリタ、qemu-sparc64 で実行)と対になります。itanium.axx も vliw.s を使い、
aarch64_logical_mini.axx は aarch64_logical_mini_demo.s と対になります。

x86_64.axx と x86_64m.axx は、全パターン行を乱数のオペランドで具体化した命令を、
llvm-mc 19 の逆アセンブルと照合しています(x86_64.axx の書き方は GNU as と違うので、
組んだバイト列を逆アセンブルして比べます)。VEX・EVEX の行(AVX・AVX2・FMA・F16C・
AES・PCLMUL・BMI1 / BMI2・K マスク・AVX-512)は、各命令の符号の欄(map・pp・W・L・
オペコード、どのオペランドが ModRM.reg / VEX.vvvv / ModRM.rm に入るか、EVEX の disp8*N の N)
を llvm-mc から取り出して作り直したもので、その抜粋が x86_64_avx.s です。
汎用レジスタ・x87・SSE の範囲は、x86_64_rex.s で直した REX の誤りのほかは一致しました。
書き方の約束は次のとおりです。

  • *256 は 256 ビット(YMM)、*512 は 512 ビットの EVEX(ZMM)、*_E は EVEX で書いた
    スカラー命令です。XMM16〜31 は ZMM16〜31 の名前で書きます。
  • EVEX の [b+!o]B の変位は書いたバイト数で、axx が disp8*N に詰めます。N の倍数でない
    ときや範囲を超えるときは「Value out of range」です。
  • VBLENDVPS / VBLENDVPD / VPBLENDVB の第 4 オペランドはレジスタです。
  • ギャザーは x,y,[b+索引*s+!o] と書き、y がマスク、索引はベクトルレジスタです。
  • 文字列命令の REP / REPE / REPNE は省略可能な接頭辞 [[rep]] です(3.8 節)。
  • VEX に無い形(即値シフトのメモリ形、索引の無いギャザー、3 オペランドのメモリ形の
    VMOVSS / VMOVSD)は持ちません。

即値は範囲を検査します。8 ビットは -128〜255(ADD8・IMUL8・PUSH8 のように符号拡張
されるものは -128〜127)、16 ビットは -32768〜65535、32 ビットは -2³¹〜2³²-1(64 ビットへ
符号拡張されるものは -2³¹〜2³¹-1)で、外れれば「Value out of range」です。AH・CH・DH・BH は
REX の要る命令(R8〜R15 や SPL〜DIL と組む、REX.W が付くなど)では使えないので、
「Register out of range」になります。境界の値は x86_64_rex.s の末尾に、エラーになる行は
x86_64_err.s にあります。

-o の再配置は GNU as・llvm-mc と同じ型にしています。シンボルを指す 32 ビットの即値は
R_X86_64_32(64 ビットへ符号拡張されるものは R_X86_64_32S)、メモリの 32 ビット変位は
R_X86_64_32S です(行ごとの .reloc)。ADD / OR / ADC / SBB / AND / SUB / XOR / CMP の
「レジスタ, 即値」は、数が -128〜127 なら imm8 の形、シンボル(.islabel)なら値の大きさに
よらず 0x81 /r の imm16 / imm32 の形を選びます(ミニ言語の alulab() / alunum() / alub()。
何も出さない .call が読んだラベル参照は捨てられるので、ラベルのときは即値の欄のバイト
だけがラベルを読み、再配置はその欄に付きます)。3 オペランドの IMUL の即値形と
MOV の RIP 相対は、32 / 16 / 8 ビットの形もあります。

test1 は 114 組を Paxx と Caxx で実行し、-b の生バイナリを比較します。
.textmode を使う 6 組(textmode.axx / 8080toz80.axx / intel2att.axx / a64tox64_axx.axx / expcap.axx / callstr.axx)と、
.passthru で素通しした行を見る exprmiss.axx については、-V で
標準出力へ流した翻訳テキストどうしも比較します。elftype.axx / elftype.s と
elfgen.axx / elfgen.s、型の優先順位を見る elfprio.axx / elfprio.s、
セクションヘッダを見る elfsec.axx / elfsec.s、シンボル表の属性を見る
elfsym.axx / elfsym.s、宣言した命令フィールド型を見る riscv64.axx /
riscv64.s、REL の命令フィールド型を見る elfrel.axx / elfrel.s、
3.7.10 節の宣言を見る elfpair・elfmips・elfmips64・elfword、CFI を見る
elfcfi の 12 組は
リロケーションと ELF のヘッダ・シンボル表を見るものなので、-o の ELF
オブジェクトどうしを比較します。aarch64.axx(-m 183)・elfpair.axx・riscv64full.axx は
--elfdesc の出力(記述を宣言に書き直したもの)どうしも比較します。
echo.axx / echo.s と ministr.axx / ministr.s の組は標準エラーへ出た .echo の行どうしも比較します。
回帰テストの regress.axx は、regress.s を -V のテキストで、regresserr.s を標準エラーの
診断で比較します(後者はエラーになる行だけを集めたものです)。regresscr.s(改行が CR
だけのファイル)は -v の一覧で、regresself.s は z80.axx で組んだ -o の標準エラーの
診断で比較します。
MIPS の 12 組(mips.axx・mipsel.axx・mips64.axx・mips64el.axx と mips.s・
mips_ase.s、R6 の 4 つと mipsr6.s)は、-b に加えて -o の ELF オブジェクト
(o32 は ELF32 の REL、n64 は ELF64 の RELA)どうしも比較します。SPARC の組のうち
sparc_test.s・sparc_reloc.s・bf_sparc.s の 3 組では、後ろの 2 組(sparc_reloc.s と bf_sparc.s)が -o の ELF オブジェクトどうしを比較します。
PowerPC64 の 2 組(ppc64.axx と ppc64le.axx に ppc64_reloc2.s)は -o の ELF
オブジェクトどうしを比較します。DS / DQ 形式の欄(.reloc のマスクの欄)と
.elfpcguess の PC 相対のデータを見る組です。RISC-V の 2 組(riscv64full.axx に
riscv64full_reloc2.s、riscv64.axx に riscv64_reloc2.s)も -o の ELF
オブジェクトどうしを比較します。.reloc の追加の再配置と .elfanchor、label-$$ の
データ、.elfrelax::0 のラベル差を見る組です。MIPS の 2 組(mips.axx に
mips_reloc2.s(o32、REL、ビッグエンディアン)、mips64el.axx に mips64_reloc2.s
(n64、RELA、リトルエンディアン))も -o の ELF オブジェクトどうしを比較します。
la / dla のリロケーションと PC 相対のデータを見る組です。SPARC の組(sparc.axx に
sparc_reloc2.s)も -o の ELF オブジェクトどうしを比較します。.islabel・
.elfresolve・PC 相対のデータを見る組です。AArch64 の組(aarch64.axx に
aarch64_reloc.s)は -m なしの -o の ELF オブジェクトを、x86_64.axx に
bsection.s の組は -b の像を比較します。x86-64 の 2 組(x86_64.axx・
x86_64m.axx にそれぞれ x86_64_reloc.s)も -o の ELF オブジェクトどうしを
比較します。PLT32・PC32・PC8・ABS32・ABS32S(シンボルを指す 32 ビットの即値と変位を含む)と、セクション内の局所の分岐・
RIP 相対参照の解決を見る組です。同じ 2 つのパターンファイルに x86_64_rex.s の 2 組は
-b の像を比較します。R8〜R15 の REX([disp+index]・CR / DR・VMREAD / VMWRITE・
PEXTRB / PEXTRD / PEXTRQ・MOVDG / MOVQG)と LOOP 系・JRCXZ の 8 ビットの範囲を
見る組です。x86_64_avx.s の 2 組も -b の像を比較します。VEX・EVEX の全命令名と、
[[rep]] の文字列命令を見る組です。x86_64_err.s の 2 組は、範囲外の即値と REX の要る行の
AH / CH / DH / BH がエラーになることを、標準エラーの診断で比較します。
68000.axx に 68000_reloc.s の組は -o の ELF32 M68K オブジェクトどうしを比較
します。型を書かない .extern の R_68K_32、値で見分ける R_68K_PC16 / R_68K_PC8、
裸の分岐の欄に付く参照、同じセクションへの分岐の解決、.org 0x10000 の後の加数を
見る組です。68000_err.s・z80_err.s・6502_err.s・6800_err.s・6809_err.s・
8080_err.s・8051_err.s・8048_err.s・4004_err.s の 9 組は、それぞれのパターンファイルで、
欄に収まらない即値・番地・変位がエラーになる(黙って切り詰めない)ことを標準エラーの
診断で比較します。6502_edge.s・6800_edge.s・6809_edge.s・8048_edge.s・4004_edge.s
の 5 組は、範囲の境目で組めるべき行を -b の像で比較します。負の番地(16 ビットの 2 の補数)・
即値の下限(-0x80 / -0x8000)・< > の強制形と、8048 と 4004 の条件分岐のページです
(8048 は 2 バイト目 $$+1 のページ、4004 は次の命令 $$+2 のページへ飛ぶ)。
import_test.s(-i import_test.tsv)は -i の値の読み方(符号・0x・前後の空白・64 ビット超え)を
-b の像で、import_test_err.s(-i import_test_err.tsv)は読めない値の行が捨てられて
ラベルが未定義になることを標準エラーの診断で比較します。listinc.s は -v の一覧で
.include の行と include 先の行が 1 行ずつに分かれることと、.section を書かないときの
-o の .text が末尾の .org まで届くことを、一覧と ELF オブジェクトで比較します。
aarch64_edge.s と riscv64full_edge.s は llvm-mc 19 と照合した範囲の境目で組めるべき行
(SVE の dup / mov / mul / smax の即値、c.lui の -32 / 0xfffe0 など)を -b の像で、
aarch64_err.s は 4 の倍数でない PC 相対・範囲外の adrp・SVE の符号付きバイトの範囲外が
エラーになることを標準エラーの診断で比較します。riscv64full_err.s・mips_err.s・sparc_err.s は、値の収まらない
データ定義(db・half・word・quad など。以前は黙って切り詰めていた)がエラーになることを
標準エラーの診断で比較します。relaxchain.s(z80.axx)は 16 段を超える前方参照の .equ の
連鎖が組めることを -b の像と -d の収束の回数で、relaxosc_err.s(6502.axx)は連鎖で延びた
pass 1 の中でも配置の振動が同じ周期・同じ反復の番号で報告されることを標準エラーの診断で比較します。
contin.s(z80.axx、./ を付けたパスで渡す)は行末の \ の継続(!include 先を含む)と
.include / !include 先の名前を -v の一覧で比較します。/dev/full の組は標準出力へ書けないときの
報告を、-v と -P の両方で比較します。cfiptr.s(elfcfi.axx)は .cfi_personality /
.cfi_lsda の 2・4・8 バイトの絶対と PC 相対の符号化を -o で比較します(絶対の符号化は
llvm-mc と同じく絶対のデータ型のリロケーションになります)。最後の組は regresscr.s を標準入力
(ソースの名前 stdin)から読んで -v の一覧を比較し、CR だけの改行や UTF-8 でないバイトが
ファイルから読むときと同じに扱われることを見ます。reloctype.s(x86_64.axx)は .reloctype で選んだ型が -o の
リロケーションに出ることを比較します。labelc_err.s(z80.axx)は .labelc が書いた行より前のラベルに
効かないことを標準エラーの診断で比較します。vliw_err.s(vliw.axx)は空のスロットと入りきらないパケットの
診断を比較します。dirjunk_err.s(z80.axx)は指令の引数の後ろに
残った文字の診断を比較します。datadir.s は .db などのデータディレクティブ(5.3 節)を、
バイト順とワード幅の違う 3 つのパターンファイル(datadir.axx・datadirbe.axx・
datadirw.axx)で組んだ -v の一覧と、datadir.axx で組んだ -o の ELF を比較し、
datadir_err.s(datadir.axx)はその誤りの診断を比較します。

さらに中核の 16 組(4004 z80 6502 6800 6809 8080 8048 8051
68000 vliw itanium x86_64 x86_64m bf 8080toz80 aarch64)は、
-b だけでは一度も比較されない経路を通すために、-o(ELF64)、-m 3 -f 32 -o
(ELF32)、-g -o(DWARF 付き)、-v(リスティング)、-V(テキスト出力)
でも走らせて突き合わせます(-o の ELF はパターンの機種のもので、.elfmachine が無ければ x86-64 の ELF64)。elfcfi は ELF32(-m 3 -f 32、REL)でも比較します。
比較は全部で 256 組です。

-g を比較するときは、両実装を必ず同じディレクトリで走らせてください。DWARF は
DW_AT_comp_dir にカレントディレクトリを埋めるので、別の場所で走らせると中身が
同じでも食い違います。

aarch64.axx / aarch64.s の組と mips.s・mips_ase.s の MIPS の 8 組が飛び抜けて
重く、どれも 1 回あたり Python 実装で 20 秒ほど、C 実装で 1 秒ほどかかります。ソースの
1 行ごとに大きなパターン集合と照合するためです(MIPS は組ごとに -b と -o の 2 通りで
走らせるので計 16 回)。sparc.axx / sparc_test.s の組はさらに重く、Python 実装で
90 秒ほど、C 実装で 4 秒ほどかかります。test1 の所要時間はほぼこれらの組で決まります。
test.axx / test.s は同梱の対のうち唯一カバーされていないものです。

現在実装されているものの大半は x86_64 とレガシー CPU ですが、これは作業が向けられた
先を反映しているだけで、axx が記述できる範囲の限界ではありません。


付録 C. 関連資料

C.1 このリポジトリ内の文書

ファイル 内容
MACRO.md / macro_en.md マクロ層リファレンス(日本語 / 英語)。7 節と同じ内容
MINI.md / mini_en.md ミニ言語リファレンス(日本語 / 英語)。3.15 節と同じ内容
axx_introduction_paper.md / _en.md 紹介論文: 自由構文パターン言語の設計根拠、特異度スコア、宣言的コアからの計算能力の分離
elf_generalization.md / _en.md ELF 出力の一般化(日本語 / 英語): -o がどの CPU にもリンクできるオブジェクトを作る仕組み、パターンファイルで宣言するマシン側とソースで宣言するシンボル側、実例。3.7.5〜3.7.11 節と 5.6 節と同じ内容
axx_ai_pattern_guide_ja.md / _en.md AI でパターンファイルを作る手順書(日本語 / 英語): 命令表の書き写しは AI に任せ、人は範囲を決め、別のアセンブラとのバイト単位の照合で確かめる
axxsemantics axx の表示的意味論による形式化。ラベル環境上の不動点として読むリラクゼーションを含む。そこにある数式はその文書独自の構成であり、公式仕様ではない
axx_promo.md 紹介記事(日本語)
README.md 概要、すぐ試す手順、デモ
FILE_DESCRIPTION 全ファイルの説明(ディレクトリ別)
format_of_exp_imp_file エクスポート/インポートファイル形式
axx.1.gz man ページ

test1 は同梱の 114 組のパターン/ソースの対を Paxx と Caxx でアセンブルし、結果を比較します
(比較は全部で 256 組。何を比べるかは付録 B にあります)。

C.2 外部

テスト環境: FreeBSD、Linux ターミナル。


付録 D. ロードマップ

D.1 未実装

パターンファイルに加えて高度な構造化マクロと最適化があれば、これはかなり高性能な
システムになるでしょうが、構造化アセンブリのマクロ構成要素の全範囲をカバーするのは
一人の手に余ります。引き受けてくださる方がいれば、喜んで拝見します。

D.2 axx2 構想

パターンファイル用のより記述的なメタ言語は、可読性を高め、評価順序への依存をなくし、
制御文を書きやすくし、プロセッサ記述ファイルをデバッグしやすくするでしょう。パターン
データのほうが直感的なので、これは純粋な利得ではなくトレードオフです。

さらに一般化して — 記述的メタ言語、現在の binary_list における文字列リテラルと文字列
操作、加えて制御文 — があれば、中間言語の生成とアセンブリ言語間の変換が可能になります。
binary_list は object_list になり、パターンファイルはパターンデータではなく複数行の
言語で記述されるプロセッサ仕様ファイルになるでしょう。これは実現可能で、どうやら
axx をもとに取り組んでいる方がいるようです。

現在のパターンファイルでも、コマンド文字列を変数に代入して — a='MOV b,c' — それを
binary_list で参照することでマクロが書けます。1 文字の小文字変数を完全なシンボルに
拡張し、展開用の expand(a) を追加し(a='b ; c'、b='MOV AX,d'、c='JMPC e' で
'MOV AX,d ; JMPC e' が得られる)、評価用の expression(a) と定義用の label: を
加えれば、かなりのところまで行けるでしょう。

axx 自体の中にループ構造があると無限ループのデバッグが難しくなります。評価をパターン
ファイルに閉じ込めておけば、自己参照チェックとともに、ループと分岐を許しつつデバッグを
扱いやすく保てます。チューリング完全性はあらゆるプロセッサアーキテクチャを可能にする
でしょう — 原理的には LISP マシンも含めて。パターンファイルのラベルをアセンブリ
ファイルのものと分離しておけば、同じラベルが両方に現れる心配はなくなります。EPIC 流の
メタ処理は変数の列挙で解決されます。

その代償は大幅な書き直しであり、より複雑なプロセッサ記述ファイルは汎用逆アセンブラ
との互換性を難しくします。


付録 E. プロジェクトノート

E.1 ノート

  • 慣例的でない記法についてはご容赦ください。
  • axx は量子コンピュータと LISP マシンをサポートしません。量子コンピュータが実行するの
    は量子アセンブリであり、LISP マシンが実行するのはそもそもアセンブリ言語ではありません。
  • 自作プロセッサからスーパーコンピュータまで、どうぞご自由にお使いください。
  • axx を評価し、拡張し、改変してください。構造は複雑ですがリファレンス実装は Python
    なので、拡張は容易です。C 版と Forth 版はそれに合わせます。
  • 定数は現在 4 倍精度に制限されており、これは Python 3 の制限です。Python 4 が 4 倍
    精度をネイティブに扱ってくれるとよいのですが。
  • マクロ層は組み込みですが、あらゆるアセンブリ言語をカバーするにはより強力なマクロ
    プロセッサ — 関数型・構造化アセンブリの構成要素を手続き型に落とすもの — が必要です。
  • アセンブラはもともと機械語を人間に読めるようにするために作られました。AI がコードを
    書くようになった今、アセンブリ言語とマシンの両方をカバーする汎用アセンブラは持つ価値
    があるように思えます — そして大きな ISA 用のパターンファイルの生成は、まさに AI が
    やるべき種類の仕事です。最近の AI はそれができます。

E.2 バグ報告

バグを見つけたら、何が動かないか教えてください。

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?