インラインアセンブリ

Rustはasm!マクロによってインラインアセンブリをサポートしています。コンパイラが生成するアセンブリに、手書きのアセンブリを埋め込むことができます。一般的には必要ありませんが、要求されるパフォーマンスやタイミングを達成するために必要な場合があります。カーネルコードのような、低レベルなハードウェアの基本要素にアクセスする場合にも、この機能が必要でしょう。

注意: 以下の例はx86/x86-64アセンブリで書かれていますが、他のアーキテクチャもサポートされています。

インラインアセンブリは現在以下のアーキテクチャでサポートされています。

x86とx86-64
ARM
AArch64
RISC-V

基本的な使い方

最も単純な例から始めましょう。


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

unsafe {
    asm!("nop");
}
}
}

これは、コンパイラが生成したアセンブリに、NOP（no operation）命令を挿入します。すべてのasm!呼び出しは、unsafeブロックの中になければいけません。インラインアセンブリは任意の命令を挿入でき、不変条件を壊してしまうからです。挿入される命令は、文字列リテラルとしてasm!マクロの第一引数に列挙されます。

入力と出力

何もしない命令を挿入しても面白くありません。実際にデータを操作してみましょう。


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let x: u64;
unsafe {
    asm!("mov {}, 5", out(reg) x);
}
assert_eq!(x, 5);
}
}

これはu64型の変数xに5の値を書き込んでいます。命令を指定するために利用している文字列リテラルが、実はテンプレート文字列になっています。これはRustのフォーマット文字列と同じルールに従います。ですが、テンプレートに挿入される引数は、みなさんがよく知っているものとは少し違っています。まず、変数がインラインアセンブリの入力なのか出力なのかを指定する必要があります。上記の例では出力となっています。outと書くことで出力であると宣言しています。また、アセンブリが変数をどの種類のレジスタに格納するかについても指定する必要があります。上の例では、regを指定して任意の汎用レジスタに格納しています。コンパイラはテンプレートに挿入する適切なレジスタを選び、インラインアセンブリの実行終了後、そのレジスタから変数を読みこみます。

入力を利用する別の例を見てみましょう。


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let i: u64 = 3;
let o: u64;
unsafe {
    asm!(
        "mov {0}, {1}",
        "add {0}, 5",
        out(reg) o,
        in(reg) i,
    );
}
assert_eq!(o, 8);
}
}

この例では、変数iの入力に5を加え、その結果を変数oに書き込んでいます。このアセンブリ特有のやり方として、はじめにiの値を出力にコピーし、それから5を加えています。

この例はいくつかのことを示します。

まず、asm!では複数のテンプレート文字列を引数として利用できます。それぞれの文字列は、改行を挟んで結合されたのと同じように、独立したアセンブリコードとして扱われます。このおかげで、アセンブリコードを容易にフォーマットできます。

つぎに、入力はoutではなくinと書くことで宣言されています。

そして、他のフォーマット文字列と同じように引数を番号や名前で指定できます。インラインアセンブリのテンプレートでは、引数が2回以上利用されることが多いため、これは特に便利です。より複雑なインラインアセンブリを書く場合、この機能を使うのが推奨されます。可読性が向上し、引数の順序を変えることなく命令を並べ替えることができるからです。

上記の例をさらに改善して、mov命令をやめることもできます。


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let mut x: u64 = 3;
unsafe {
    asm!("add {0}, 5", inout(reg) x);
}
assert_eq!(x, 8);
}
}

inoutで入力でもあり出力でもある引数を指定しています。こうすることで、入力と出力を個別に指定する場合と違って、入出力が同じレジスタに割り当てられることが保証されます。

inoutのオペランドとして、入力と出力それぞれに異なる変数を指定することも可能です。


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let x: u64 = 3;
let y: u64;
unsafe {
    asm!("add {0}, 5", inout(reg) x => y);
}
assert_eq!(y, 8);
}
}

遅延出力オペランド

Rustコンパイラはオペランドの割り当てに保守的です。outはいつでも書き込めるので、他の引数とは場所を共有できません。しかし、最適なパフォーマンスを保証するためには、できるだけ少ないレジスタを使うことが重要です。そうすることで、インラインアセンブリブロックの前後でレジスタを保存したり再読み込みしたりする必要がありません。これを達成するために、Rustはlateout指定子を提供します。全ての入力が消費された後でのみ書き込まれる出力に利用できます。この指定子にはinlateoutという変化形もあります。

以下は、releaseモードやその他の最適化された場合に、inlateoutを利用 できない 例です。


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let mut a: u64 = 4;
let b: u64 = 4;
let c: u64 = 4;
unsafe {
    asm!(
        "add {0}, {1}",
        "add {0}, {2}",
        inout(reg) a,
        in(reg) b,
        in(reg) c,
    );
}
assert_eq!(a, 12);
}
}

In unoptimized cases (e.g. Debug mode), replacing inout(reg) a with inlateout(reg) a in the above example can continue to give the expected result. However, with release mode or other optimized cases, using inlateout(reg) a can instead lead to the final value a = 16, causing the assertion to fail.

というのも、最適化されている場合、コンパイラはbとcが同じ値だと知っているので、bとcの入力に同じレジスタを割り当てる場合があります。もしinlateoutが使われていたら、aとcに同じレジスタが割り当てられ、最初のadd命令によってcの値が上書きされるでしょう。inout(reg) aの使用によりaに対する独立したレジスタ割り当てが保証されるのとは対照的です。

しかし、次の例では、全ての入力レジスタが読み込まれた後でのみ出力が変更されるので、inlateoutを利用できます。


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let mut a: u64 = 4;
let b: u64 = 4;
unsafe {
    asm!("add {0}, {1}", inlateout(reg) a, in(reg) b);
}
assert_eq!(a, 8);
}
}

このアセンブリコードは、aとbが同じレジスタに割り当てられても、正しく動作します。

明示的なレジスタオペランド

いくつかの命令では、オペランドが特定のレジスタにある必要があります。したがって、Rustのインラインアセンブリでは、より具体的な制約指定子を提供しています。regは一般的にどのアーキテクチャでも利用可能ですが、明示的レジスタはアーキテクチャに強く依存しています。たとえば、x86の汎用レジスタであるeax、ebx、ecx、edx、ebp、esi、ediなどは、その名前で指定できます。


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let cmd = 0xd1;
unsafe {
    asm!("out 0x64, eax", in("eax") cmd);
}
}
}

この例では、out命令を呼び出して、cmd変数の中身を0x64ポートに出力しています。out命令はeaxとそのサブレジスタのみをオペランドとして受け取るため、eaxの制約指定子を使わなければなりません。

注意: 他のオペランドタイプと異なり、明示的なレジスタオペランドはテンプレート文字列中で利用できません。{}を使えないので、レジスタの名前を直接書く必要があります。また、オペランドのリストの中で他のオペランドタイプの一番最後に置かれなくてはなりません。

x86のmul命令を使った次の例を考えてみましょう。


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

fn mul(a: u64, b: u64) -> u128 {
    let lo: u64;
    let hi: u64;

    unsafe {
        asm!(
            // x86のmul命令はraxを暗黙的な入力に取り、
            // 128ビットの乗算結果をrax:rdxに書き込みます。
            "mul {}",
            in(reg) a,
            inlateout("rax") b => lo,
            lateout("rdx") hi
        );
    }

    ((hi as u128) << 64) + lo as u128
}
}
}

mul命令を使って2つの64ビットの入力を128ビットの結果に出力しています。唯一の明示的なオペランドはレジスタで、変数aから入力します。2つ目のオペランドは暗黙的であり、raxレジスタである必要があります。変数bからraxレジスタに入力します。計算結果の下位64ビットはraxレジスタに保存され、そこから変数loに出力されます。上位64ビットはrdxレジスタに保存され、そこから変数hiに出力されます。

クロバーレジスタ

多くの場合、インラインアセンブリは出力として必要のない状態を変更することがあります。これは普通、アセンブリでスクラッチレジスタを利用する必要があったり、私たちがこれ以上必要としていない状態を命令が変更したりするためです。この状態を一般的に"クロバー"（訳注：上書き）と呼びます。私たちはコンパイラにこのことを伝える必要があります。なぜならコンパイラは、インラインアセンブリブロックの前後で、この状態を保存して復元しなくてはならない可能性があるからです。


use std::arch::asm;

#[cfg(target_arch = "x86_64")]
fn main() {
    // 4バイトのエントリー3つ
    let mut name_buf = [0_u8; 12];
    // 文字列はasciiとしてebx, edx, ecxの順に保存されています。
    // ebxは予約されているので、アセンブリはebxの値を維持する必要があります。
    // 従ってメインのアセンブリの前後でプッシュおよびポップを行います。
    // （以下は64ビットプロセッサの64ビットモードの場合。32ビットプロセッサはebxを利用します。）

    unsafe {
        asm!(
            "push rbx",
            "cpuid",
            "mov [rdi], ebx",
            "mov [rdi + 4], edx",
            "mov [rdi + 8], ecx",
            "pop rbx",
            // いくつかのアセンブリ命令を追加してRustのコードを単純化するために
            // 値を格納する配列へのポインタを利用します。
            // しかし、`out("ecx") val`のような明示的なレジスタの出力とは違い、
            // アセンブリの動作をより明示的にします。
            // *ポインタそのもの* は後ろに書かれていても入力にすぎません。
            in("rdi") name_buf.as_mut_ptr(),
            // cpuid 0を選択し、eaxをクロバーに指定します。
            inout("eax") 0 => _,
            // cpuidは以下のレジスタもクロバーします。
            out("ecx") _,
            out("edx") _,
        );
    }

    let name = core::str::from_utf8(&name_buf).unwrap();
    println!("CPU Manufacturer ID: {}", name);
}

#[cfg(not(target_arch = "x86_64"))]
fn main() {}

上の例では、cpuid命令を使い、CPUベンタIDを読み込んでいます。この命令はeaxにサポートされている最大のcpuid引数を書き込み、ebx、edx、ecxの順にCPUベンダIDをASCIIコードとして書き込みます。

eaxは読み込まれることはありません。しかし、コンパイラがアセンブリ以前にこれらのレジスタにあった値を保存できるように、レジスタが変更されたことをコンパイラに伝える必要があります。そのために、変数名の代わりに_を用いて出力を宣言し、出力の値が破棄されるということを示しています。

このコードはebxがLLVMによって予約されたレジスタであるという制約を回避しています。LLVMは、自身がレジスタを完全にコントロールし、アセンブリブロックを抜ける前に元の状態を復元しなくてはならないと考えています。そのため、コンパイラがin(reg)のような汎用レジスタクラスを満たすために使用する場合 を除いて ebxを入力や出力として利用できません。つまり、予約されたレジスタを利用する場合に、regオペランドは危険なのです。入力と出力が同じレジスタを共有しているので、知らないうちに入力や出力を破壊してしまうかもしれません。

これを回避するために、rdiを用いて出力の配列へのポインタを保管し、pushでebxを保存し、アセンブリブロック内でebxから読み込んで配列に書き込み、popでebxを元の状態に戻しています。pushとpopは完全な64ビットのrbxレジスタを使って、レジスタ全体を確実に保存しています。32ビットの場合、pushとpopにおいてebxがかわりに利用されるでしょう。

アセンブリコード内部で利用するスクラッチレジスタを獲得するために、汎用レジスタクラスとともに使用することもできます。


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

// シフト演算と加算を利用してxに6をかけます。
let mut x: u64 = 4;
unsafe {
    asm!(
        "mov {tmp}, {x}",
        "shl {tmp}, 1",
        "shl {x}, 2",
        "add {x}, {tmp}",
        x = inout(reg) x,
        tmp = out(reg) _,
    );
}
assert_eq!(x, 4 * 6);
}
}

シンボル・オペランドとABIクロバー

デフォルトでは、asm!は、出力として指定されていないレジスタはアセンブリコードによって中身が維持される、と考えます。asm!に渡されるclobber_abi引数は、与えられた呼び出し規約のABIに従って、必要なクロバーオペランドを自動的に挿入するようコンパイラに伝えます。そのABIで完全に保存されていないレジスタは、クロバーとして扱われます。複数の clobber_abi 引数を指定すると、指定されたすべてのABIのクロバーが挿入されます。


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

extern "C" fn foo(arg: i32) -> i32 {
    println!("arg = {}", arg);
    arg * 2
}

fn call_foo(arg: i32) -> i32 {
    unsafe {
        let result;
        asm!(
            "call {}",
            // 呼び出す関数ポインタ
            in(reg) foo,
            // 最初の引数はrdiにあります。
            in("rdi") arg,
            // 戻り値はraxにあります。
            out("rax") result,
            // "C"の呼び出し規約で保存されていないすべてのレジスタをクロバーに指定。
            clobber_abi("C"),
        );
        result
    }
}
}
}

レジスタテンプレート修飾子

テンプレート文字列に挿入されるレジスタの名前のフォーマット方法について、細かい制御が必要な場合があります。アーキテクチャのアセンブリ言語が、同じレジスタに別名を持っている場合です。典型的な例としては、レジスタの部分集合に対する"ビュー"があります（例：64ビットレジスタの下位32ビット）。

デフォルトでは、コンパイラは常に完全なレジスタサイズの名前を選択します（例：x86-64ではrax、x86ではeax、など）。

この挙動は、フォーマット文字列と同じように、テンプレート文字列のオペランドに修飾子を利用することで上書きできます。


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let mut x: u16 = 0xab;

unsafe {
    asm!("mov {0:h}, {0:l}", inout(reg_abcd) x);
}

assert_eq!(x, 0xabab);
}
}

この例では、reg_abcdレジスタクラスを用いて、レジスタアロケータを4つのレガシーなx86レジスタ（ax, bx, cx, dx）に制限しています。このうち最初の2バイトは独立して指定できます。

レジスタアロケータがxをaxレジスタに割り当てることにしたと仮定しましょう。h修飾子はそのレジスタの上位バイトのレジスタ名を出力し、l修飾子は下位バイトのレジスタ名を出力します。したがって、このアセンブリコードはmov ah, alに展開され、値の下位バイトを上位バイトにコピーします。

より小さなデータ型（例：u16）をオペランドに利用し、テンプレート修飾子を使い忘れた場合、コンパイラは警告を出力し、正しい修飾子を提案してくれます。

メモリアドレスオペランド

アセンブリ命令はオペランドがメモリアドレスやメモリロケーション経由で渡される必要なこともあります。そのときは手動で、ターゲットのアーキテクチャによって指定されたメモリアドレスのシンタックスを利用しなくてはなりません。例えば、Intelのアセンブリシンタックスを使うx86/x86_64の場合、入出力を[]で囲んで、メモリオペランドであることを示さなくてはなりません。


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

fn load_fpu_control_word(control: u16) {
    unsafe {
        asm!("fldcw [{}]", in(reg) &control, options(nostack));
    }
}
}
}

ラベル

名前つきラベルの再利用は、ローカルかそうでないかに関わらず、アセンブラやリンカのエラーを引き起こしたり、変な挙動の原因となります。名前つきラベルの再利用は以下のようなケースがあります。

明示的再利用：同じラベルを1つのasm!ブロック中で、または複数のブロック中で2回以上利用する場合です。
インライン化による暗黙の再利用：コンパイラはasm!ブロックの複数のコピーをインスタンス化する場合があります。例えば、asm!ブロックを含む関数が複数箇所でインライン化される場合です。
LTO（訳注：Link Time Optimizationの略）による暗黙の再利用：LTOは 他のクレート のコードを同じコード生成単位に配置するため、同じ名前のラベルを持ち込む場合があります。

そのため、インラインアセンブリコードの中では、GNUアセンブラの 数値型ローカルラベルのみ使用してください。アセンブリコード内でシンボルを定義すると、シンボル定義の重複により、アセンブラやリンカのエラーが発生する可能性があります。

さらに、x86でデフォルトのIntel構文を使用する場合、LLVMのバグによって、0、11、101010といった0と1だけで構成されたラベルは、バイナリ値として解釈されてしまうため、使用してはいけません。options(att_syntax)を使うと曖昧さを避けられますが、asm!ブロック全体の構文に影響します。（optionsについては、後述のオプションを参照してください。）


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let mut a = 0;
unsafe {
    asm!(
        "mov {0}, 10",
        "2:",
        "sub {0}, 1",
        "cmp {0}, 3",
        "jle 2f",
        "jmp 2b",
        "2:",
        "add {0}, 2",
        out(reg) a
    );
}
assert_eq!(a, 5);
}
}

このコードは、{0}のレジスタの値を10から3にデクリメントし、2を加え、aにその値を保存します。

この例は、以下のことを示しています。

まず、ラベルとして同じ数字を複数回、同じインラインブロックで利用できます。
つぎに、数字のラベルが参照として(例えば、命令のオペランドに)利用された場合、"b"（"後方"）や"f"（"前方"）の接尾辞が数字のラベルに追加されなくてはなりません。そうすることで、この数字の指定された方向の最も近いラベルを参照できます。

オプション

デフォルトでは、インラインアセンブリブロックは、カスタム呼び出し規約をもつ外部のFFI関数呼び出しと同じように扱われます:メモリを読み込んだり書き込んだり、観測可能な副作用を持っていたりするかもしれません。しかし、多くの場合、アセンブリコードが実際に何をするかという情報を多く与えて、より最適化できる方が望ましいでしょう。

先ほどのadd命令の例を見てみましょう。


#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let mut a: u64 = 4;
let b: u64 = 4;
unsafe {
    asm!(
        "add {0}, {1}",
        inlateout(reg) a, in(reg) b,
        options(pure, nomem, nostack),
    );
}
assert_eq!(a, 8);
}
}

オプションはasm!マクロの最後の任意引数として渡されます。ここでは3つのオプションを利用しました：

pureは、アセンブリコードが観測可能な副作用を持っておらず、出力は入力のみに依存することを意味します。これにより、コンパイラオプティマイザはインラインアセンブリの呼び出し回数を減らしたり、インラインアセンブリを完全に削除したりできます。
nomemは、アセンブリコードがメモリの読み書きをしないことを意味します。デフォルトでは、インラインアセンブリはアクセス可能なメモリアドレス（例えばオペランドとして渡されたポインタや、グローバルなど）の読み書きを行うとコンパイラは仮定しています。
nostackは、アセンブリコードがスタックにデータをプッシュしないことを意味します。これにより、コンパイラはx86-64のスタックレッドゾーンなどの最適化を利用し、スタックポインタの調整を避けることができます。

これにより、コンパイラは、出力が全く必要とされていない純粋なasm!ブロックを削除するなどして、asm!を使ったコードをより最適化できます。

利用可能なオプションとその効果の一覧はリファレンスを参照してください。

Rust By Example