Chạy tính năng giám sát ABI

Trang này mô tả cách tạo các bản trình bày ABI của nhân Android và chạy tính năng giám sát ABI. Tính năng này áp dụng cho Android 16 trở lên. Đối với các phiên bản thấp hơn, hãy tham khảo ABI monitor previous kernel versions (Giám sát ABI của các phiên bản kernel trước).

Bạn cũng có thể xem tài liệu tham khảo về Kleaf: Hỗ trợ tính năng giám sát ABI (GKI) và Hỗ trợ tính năng giám sát ABI (Thiết bị).

Tạo nhân và biểu diễn ABI của nhân

Sau khi tải các nguồn GKI xuống, hãy chạy lệnh sau để tạo nhân GKI và các cấu phần phần mềm ABI:

tools/bazel run //common:kernel_aarch64_abi_dist

Lệnh này tạo bản trình bày ABI hiện tại và sao chép bản trình bày đó vào $DIST_DIR/abi.stg cùng với hạt nhân và các mô-đun đã tạo. $DIST_DIR mặc định là out_abi/kernel_aarch64_abi_dist/dist.

Bạn có thể chỉ định các đối số bổ sung cho công cụ ABI ở cuối lệnh sau --. Ví dụ: để thay đổi đích đến cho ABI và tạo các cấu phần phần mềm, bạn có thể dùng lựa chọn --destdir:

tools/bazel run //common:kernel_aarch64_abi_dist -- --destdir=out/dist

Phân tích sự khác biệt về ABI giữa bản dựng và một bản trình bày tham chiếu

Mục tiêu //common:kernel_aarch64_abi_dist, được thực thi trong lệnh trước đó, sẽ phân tích và báo cáo mọi điểm khác biệt về ABI được tìm thấy giữa bản dựng và bản trình bày tham chiếu nằm tại common/gki/aarch64/abi.stg (được xác định trong BUILD.bazel). Những điểm khác biệt này sẽ được in ra ở cuối bản dựng, như minh hoạ trong ví dụ sau:

INFO: From [stg] Comparing Kernel ABI @//common:kernel_aarch64_abi_diff:
INFO: ABI DIFFERENCES HAVE BEEN DETECTED!

Báo cáo in được lấy từ cấu phần phần mềm nằm tại $DIST_DIR/abi_stgdiff/abi.report.short cùng với các báo cáo ở định dạng khác.

Quy trình tự động hoá nên sử dụng mã thoát của lệnh tạo. Mã này khác 0 nếu tìm thấy sự khác biệt.

Xin lưu ý rằng các nhánh giai đoạn phát triển, bao gồm cả android-mainline, không có biểu diễn ABI tham chiếu. Nếu không có, //common:kernel_aarch64_abi_dist sẽ không phát hiện thấy bất kỳ điểm khác biệt nào.

Cập nhật biểu diễn ABI tham chiếu

Mọi thay đổi ảnh hưởng đến ABI của nhân (chẳng hạn như bản cập nhật danh sách biểu tượng) đều cần được phản ánh trong biểu diễn ABI tham chiếu (common/gki/aarch64/abi.stg, được xác định trong BUILD.bazel). Để thực hiện việc này, bạn cần chạy lệnh sau:

tools/bazel run //common:kernel_aarch64_abi_update

Lệnh này thực hiện mọi thao tác trong bước Phân tích sự khác biệt về ABI và cập nhật thêm biểu diễn tham chiếu trong các nguồn. Sau đó, bạn có thể tải ABI đã cập nhật lên cùng một cam kết với thay đổi. Đưa sự khác biệt về ABI trong báo cáo từ $DIST_DIR/abi_stgdiff/abi.report.short vào thông báo cam kết.

Giám sát ABI và mục tiêu thiết bị

Bạn chỉ cần định cấu hình tính năng giám sát ABI cho các mục tiêu tạo hạt nhân cốt lõi. Các cấu hình bản dựng hỗn hợp (những cấu hình xác định base_kernel) biên dịch trực tiếp bằng nhân GKI chỉ cần thêm chế độ hỗ trợ để theo dõi danh sách biểu tượng thiết bị. Bạn nên cập nhật định nghĩa ABI bằng bản dựng GKI.

Ngoài ra, hãy xem tài liệu tham khảo cho Kleaf: Hỗ trợ tính năng giám sát ABI (Thiết bị).

Trình giám sát ABI của các phiên bản kernel trước đó (Android 15 trở xuống)

Đối với các phiên bản kernel trước đây, hướng dẫn theo dõi và tạo ABI sẽ khác như sau.

Android 15 và 14

Hướng dẫn này hầu hết giống với hướng dẫn dành cho Android 16, ngoại trừ việc biểu diễn ABI tham chiếu là common/android/abi_gki_aarch64.stg và $DIST_DIR mặc định là out_abi/kernel_aarch64/dist.

Android 13

Android 13 có thể được tạo bằng Kleaf hoặc bằng các tập lệnh tạo cũ.

Đối với Kleaf, các hướng dẫn này giống như hướng dẫn dành cho Android 14, ngoại trừ việc định dạng ABI là XML và biểu diễn ABI tham chiếu là common/android/abi_gki_aarch64.xml.

Đối với các tập lệnh cũ, hướng dẫn này giống như hướng dẫn dành cho Android 12.

Android 12 trở xuống

Định dạng ABI là XML và biểu diễn ABI tham chiếu là common/android/abi_gki_aarch64.xml

Các nhân này sử dụng build.sh thay vì Kleaf. Để theo dõi ABI, bạn nên sử dụng build_abi.sh. Lệnh này chấp nhận các biến môi trường tương tự để tuỳ chỉnh bản dựng như build.sh. Ví dụ:

BUILD_CONFIG=common/build.config.gki.aarch64 build/build_abi.sh

Thao tác này sẽ tạo nhân và trích xuất biểu diễn ABI vào thư mục con OUT_DIR (theo mặc định là out_abi) và tương đương với mục tiêu //common:kernel_aarch64_abi_dist của Kleaf (xem Tạo nhân và cấu phần phần mềm ABI).

Biểu diễn ABI tham chiếu được lưu trữ trong android/abi_gki_aarch64.xml như được xác định bởi biến ABI_DEFINITION trong common/build.config.gki.aarch64.

Nếu cần cập nhật biểu thị ABI của nhân, cách thuận tiện nhất là sử dụng các lựa chọn --update và --print-report:

BUILD_CONFIG=common/build.config.gki.aarch64 build/build_abi.sh --update --print-report

--print-report in ABI differences between the file as it exists and a newly-generated ABI.

Tuỳ chọn --update sẽ ghi đè biểu thị ABI tham chiếu. Thao tác này cũng sẽ cập nhật danh sách biểu tượng khi bạn dùng BUILD_CONFIG cho một thiết bị có KMI_SYMBOL_LIST được định cấu hình.