用於 Linux 測試的 Machina 執行階段

本指南提供操作說明，說明如何使用 Machina，針對 Linux 環境執行及偵錯 Starnix 測試。

Machina 會在 Linux 虛擬機器中執行測試，並使用目標核心版本提供獨立的標準化環境。請注意，執行 Machina 需要 Intel CPU，以及本機可用的 Debian 客戶端映像檔。Google 員工預設可使用這類圖片，外部開發人員則須自行提供。外部開發人員應參閱「虛擬化入門」指南，進一步瞭解如何建構自己的 Debian 映像檔。

在本機執行現有的 Machina 測試

環境設定

  1. 請務必使用高效能的 Intel 機器，並具備虛擬化功能。對於 Googler 而言，專屬 Cloudtop 將提供理想環境。如果不確定電腦的 CPU，可以使用 lscpu，如下所示：

    lscpu | grep "Vendor ID"
Vendor ID: GenuineIntel

  2. 設定支援虛擬化的產品設定。只要主機板是 x64，大多數產品都能正常運作。設定範例如下：

    fx set fuchsia.x64 --main-pb workbench_eng.x64

  3. 新增 linux_vm_tests 目標：

    fx add-test //src/starnix/tests:linux_vm_tests

  4. 使用標準的 fx build 和 ffx emu start 工作流程啟動模擬器。

執行測試

測試套件與原始系統呼叫相同，但會加上 linux_ 前置字串。以下列舉一些常見的目標納入條件：

  • 執行整個套件：

    fx test linux_syscalls_cpp_tests

  • 執行個別測試：

    fx test linux_fcntl_test

  • 在 Starnix 和 Linux 上執行：指定測試的基本名稱，這會執行環境可能設定執行的所有變體 (Starnix、Machina、主機)：

    fx test mount_test

偵錯失敗的 Machina 系統呼叫測試

瞭解記錄

系統呼叫測試是 gTest 套件，輸出內容會透過測試架構管道傳輸。換句話說，如果測試失敗，gTest 呼叫的輸出內容會顯示在 stdout 中。您可以在 fx test 叫用中使用 --output arg，查看所有 gTest 記錄，不論結果為何。

與 Machina 執行階段相關的記錄會輸出至系統記錄 (ffx log)，且通常與識別標記相關聯。目前，所有系統呼叫測試都採用一個執行階段，並使用 linux_guest 標記。但與核心端虛擬化相關的系統記錄除外，例如 Zircon 管理程序發出的記錄。這些記錄不會有與訪客相關聯的專屬 ID。

以下文件記錄與一般流程相關的系統記錄。

  1. 初始訪客啟動程序：

    在下列記錄中，您會看到 starnix_test_runner 元件要求使用 linux_guest 標記的 Machina 訪客。starnix_test_runner 會記錄兩行有關互動要求的內容。第三行是來自 interactive-debian-guest 元件，可視為正在執行的 Machina 客戶元件。會接收要求並開始啟動程序。您可以看到系統中的所有記錄都標記了 ID (linux_guest)。如記錄所示，Machina 客戶端會延遲啟動。這個初始啟動程序通常需要 60 秒才能準備好進行互動，但只有在第一次執行時才需要。

    [00043.071313][starnix_test_runner][linux_guest] INFO: Pushing data to guest (destination: /data/tests/deps/clone_exec_helper)
[00043.071321][starnix_test_runner][linux_guest] INFO: Interaction requested, lazily starting the guest instance.
[00046.686157][interactive-debian-guest][linux_guest] INFO: [interactive_debian_guest_impl.cc(110)] Start requested for an interactive Debian guest.

  2. 推送測試依附元件和二進位檔：

    啟動客體後，初步資料就會開始推送至客體。以下是系統呼叫測試的必要依附元件，後面接著測試二進位檔本身：

    [00439.934416][starnix_test_runner.cm][linux_guest,starnix_test_runner] INFO: Pushing data to guest (destination: /data/tests/deps/simple_ext4.img)
[00441.040568][starnix_test_runner.cm][linux_guest,starnix_test_runner] INFO: Successfully pushed data to guest (destination: /data/tests/deps/simple_ext4.img)
[00444.834216][starnix_test_runner.cm][linux_guest,starnix_test_runner] INFO: Pushing data to guest (destination: /starnix_linux_fuse_test_fuse_test_bin)
[00448.652779][starnix_test_runner.cm][linux_guest,starnix_test_runner] INFO: Successfully pushed data to guest (destination: /starnix_linux_fuse_test_fuse_test_bin)

  3. 測試執行和處理：

    完成環境設定步驟後，您應該會看到發出的執行指令。這是在訪客上執行 gTest 二進位檔。同樣地，這個二進位檔的執行輸出內容會透過管道傳送至終端機上的 stdout，這與您對 gTest 套件的任何其他 fx test 叫用行為相同。執行完成後，結果檔案會複製回主機進行處理：

    [00448.653126][starnix_test_runner.cm][linux_guest,starnix_test_runner] INFO: Executing command on guest: /starnix_linux_fuse_test_fuse_test_bin --gtest_output=json:/test_result-ccde95ca-acb3-4b84-af4d-f371b9582d20.json)
[00448.848658][starnix_test_runner.cm][linux_guest,starnix_test_runner] INFO: Command '/starnix_linux_fuse_test_fuse_test_bin --gtest_output=json:/test_result-ccde95ca-acb3-4b84-af4d-f371b9582d20.json'
...terminated with status Status(OK), return code 0
[00448.849066][starnix_test_runner.cm][linux_guest,starnix_test_runner] INFO: Fetching file from guest (remote_path: /test_result-ccde95ca-acb3-4b84-af4d-f371b9582d20.json)

瞭解執行階段

Starnix 測試執行元件負責協調測試，可視為 Fuchsia 測試框架和 Machina 執行階段之間的黏著劑。與執行階段相關的重要事項有兩項：

  1. 系統會透過 CML 中的 [syscalls_cpp_test.cml][syscalls-cml] 程式標記，識別系統呼叫測試。test_type: "syscall"
  2. 處理套件要求時，Starnix 執行元件會尋找這個標記，並相應地分支邏輯來處理這些測試。核心處理邏輯位於 [syscalls.rs][syscalls-rs]，主要進入點為 run_syscall_tests。

雖然執行階段的內容遠不只這兩點，但要將所有內容都記錄下來會非常困難。希望這兩個系統核心元件能為您自己的調查和偵錯作業提供穩固的錨點。

進階偵錯

詳細記錄 Linux 核心記錄

如果懷疑 Linux 核心本身發生問題，可以設定下列 GN 引數，啟用更詳細的 Linux 核心記錄：

redirect_guest_serial_logs = true

這會將 Linux 核心記錄導向標準系統輸出，也就是說，您可以查看 ffx log 發出的訪客核心記錄。記錄會在 vmm 元件下發出，並標上 (guest klog)，為求明確瞭解來源。例如：

[00352.454169][vmm.cm][vmm] INFO: [vmm.cc(491)] (guest klog): [    0.000000] Linux version 6.6.13-amd64 (debian-kernel@lists.debian.org) (gcc-13 (Debian 13.2.0-10) 13.2.0, GNU ld (GNU Binutils for Debian) 2.41.90.20240115) #1 SMP PREEMPT_DYNAMIC Debian 6.6.13-1 (2024-01-20)

在這個記錄範例中，您會看到 vmm 元件發出 Linux 核心記錄行。vmm 在系統正常運作時間 00352.454169 發出這項記錄。(guest klog) 表示 Linux 核心在 [ 0.000000] 發出該行，或從其角度來看，這是正常運作的第零秒。

Shelling into Machina

您可以存取執行中 Linux 客戶端的標準指令列介面。請注意，根據預設，測試二進位檔和構件不會出現在映像檔中，因為測試執行元件架構會動態推送這些項目。如要進一步瞭解如何將測試二進位檔和構件匯入訪客，請參閱下列各節。如要存取這個殼層，請按照下列步驟操作：

  1. 請按照「虛擬化入門」指南操作，瞭解如何設定本機 GN 引數，啟用虛擬化工具。

  2. 啟動模擬器並連線至殼層：

    fx shell

  3. 啟動 Debian 客體：

    guest launch debian

    系統會將你帶往 Debian Shell。

請注意，殼層行為可能會造成混淆：

  • exit 不會結束訪客殼層。
  • CTRL+C「不會」終止正在執行的程式，而是會退出 Debian 殼層，返回 Fuchsia。

提示：如果意外按下 Ctrl+C 鍵，從 Linux 訪客環境返回 Fuchsia，可以使用 guest attach debian 返回殼層。

修改 Debian 映像檔

有時您可能需要變更預設的 Debian 映像檔 (例如新增二進位檔或偵錯程式)。由於無法輕鬆推送構件，您必須直接修改映像檔。

  1. 掛接映像檔：在 Linux 主機上安裝工具並掛接映像檔：

    sudo apt-get install libguestfs-tools
sudo mkdir /mnt/machina_guest_img
sudo guestmount -a prebuilt/virtualization/packages/debian_guest/images/x64/rootfs.qcow2 -m /dev/vda /mnt/machina_guest_img/

  2. 與圖片互動：你現在可以將檔案複製到已掛接的目錄。舉例來說，如要複製掛接測試二進位檔和依附元件，請執行下列操作：

    sudo cp ./out/core.x64-balanced/linux_x64/linux_mount_test_bin /mnt/machina_guest_img/home/
sudo mkdir -p /mnt/machina_guest_img/home/data/tests/deps/
sudo cp src/starnix/tests/syscalls/cpp/data/* /mnt/machina_guest_img/home/data/tests/deps/

  3. 卸載映像檔：

    sudo guestunmount /mnt/machina_guest_img

卸載後，映像檔會包含您所做的變更。接著，您就可以進入環境 (如上詳述)，並視需要執行二進位檔。