Ma trận tương thích

Phần này mô tả khung và ma trận tương thích của thiết bị cũng như giản đồ ma trận tương thích. Để biết các quy tắc so khớp, hãy xem phần Quy tắc so khớp.

Ma trận tương thích khung (FCM)

Ma trận tương thích khung (FCM) mô tả các yêu cầu của khung trên thiết bị mà khung đó chạy. Ma trận tương thích khung bao gồm ma trận tương thích hệ thống, ma trận tương thích sản phẩm và ma trận tương thích system_ext. Tệp kê khai thiết bị phải đáp ứng các yêu cầu của FCM (các yêu cầu được thực thi tại thời điểm tạo bản dựng, thời gian chạy và trong VTS).

FCM system_ext và FCM sản phẩm là phần bổ sung của FCM dành riêng cho thiết bị (được cài đặt trong phân vùng hệ thống).

  • FCM của thiết bị phải phản ánh các yêu cầu của các mô-đun trong phân vùng hệ thống.
  • FCM system_ext phải phản ánh các yêu cầu theo mô-đun trong phân vùng system_ext.
  • FCM của sản phẩm phải phản ánh các yêu cầu theo mô-đun trong phân vùng sản phẩm.

Tất cả FCM phải phù hợp với nội dung sửa đổi của OEM đối với khung trong các phân vùng hệ thống, sản phẩm và system_ext. Ví dụ: nếu một ứng dụng được cài đặt trong phân vùng sản phẩm sử dụng tiện ích của nhà cung cấp giao diện HAL, thì yêu cầu về giao diện HAL phải được khai báo trong FCM của sản phẩm.

Tệp ma trận tương thích với hệ thống mẫu:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<compatibility-matrix version="1.0" type="framework" level="3">
    <hal>
        <name>android.hardware.camera</name>
        <version>1.0</version>
        <version>3.1-4</version>
        <interface>
            <name>ICameraProvider</name>
            <instance>default</instance>
            <regex-instance>[a-z_]+/[0-9]+</regex-instance>
        </interface>
    </hal>
    <hal>
        <name>android.hardware.nfc</name>
        <version>1.0</version>
        <interface>
            <name>INfc</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal optional="true">
        <name>android.hardware.graphics.composer</name>
        <version>2.1</version>
        <interface>
            <name>IComposer</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal format="aidl" optional="true">
        <name>android.hardware.light</name>
        <version>1-2</version>
        <interface>
            <name>ILights</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal format="native">
        <name>GL</name>
        <version>1.1</version>
        <version>3.0</version>
    </hal>
    <hal format="native">
        <name>EGL</name>
        <version>1.1</version>
    </hal>
    <kernel version="3.18.51">
        <!-- common configs -->
    </kernel>
    <kernel version="3.18.51">
        <!-- arm specific configs -->
        <condition>
            <config>
                <key>CONFIG_ARM</key>
                <value type="tristate">y</value>
            </config>
        <condition>
        <config>
            <key>CONFIG_A</key>
            <value type="string"></value>
        </config>
        <config>
            <key>CONFIG_B</key>
            <value type="tristate">y</value>
        </config>
    </kernel>
    <kernel version="4.1.22">
        <!-- common configs -->
        <config>
            <key>CONFIG_A</key>
            <value type="string">foo</value>
        </config>
        <config>
            <key>CONFIG_B2</key>
            <value type="int">1024</value>
        </config>
    </kernel>
    <sepolicy>
        <kernel-sepolicy-version>30</kernel-sepolicy-version>
        <sepolicy-version>25.0</sepolicy-version>
        <sepolicy-version>26.0-3</sepolicy-version>
    </sepolicy>
    <avb>
        <vbmeta-version>2.1</vbmeta-version>
    </avb>
    <xmlfile format="dtd">
        <name>media_profile</name>
        <version>1.0</version>
        <path>/system/etc/media_profile_V1_0.dtd</path>
    </xmlfile>
</compatibility-matrix>

Để biết thêm thông tin, hãy xem phần Vòng đời của FCM.

Ma trận khả năng tương thích của sản phẩm

FCM của sản phẩm là tệp ma trận tương thích khung trong phân vùng sản phẩm. Đối tượng VINTF kết hợp FCM của sản phẩm với FCM trong các phân vùng hệ thống và system_ext trong thời gian chạy.

Tệp FCM mẫu của sản phẩm:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<compatibility-matrix version="1.0" type="framework">
    <hal>
        <name>vendor.foo.camera</name>
        <version>1.0</version>
        <interface>
            <name>IBetterCamera</name>
            <instance>default</instance>
        </interface>
    </hal>
</compatibility-matrix>

Ma trận tương thích System_ext

FCM system_ext là tệp ma trận tương thích khung trong phân vùng system_ext. Đối tượng VINTF kết hợp FCM system_ext với các FCM trong hệ thống và các phân vùng sản phẩm trong thời gian chạy. Hãy xem ma trận khả năng tương thích của sản phẩm để biết ví dụ về tệp FCM system_ext.

Ma trận khả năng tương thích với thiết bị (DCM)

Ma trận khả năng tương thích của thiết bị mô tả một tập hợp các yêu cầu mà thiết bị yêu cầu từ khung (các yêu cầu được thực thi tại thời điểm khởi chạy và thời gian OTA).

Tệp DCM mẫu:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<compatibility-matrix version="1.0" type="device">
    <hal>
        <name>android.hidl.manager</name>
        <version>1.0</version>
        <interface>
            <name>IServiceManager</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal>
        <name>android.hidl.memory</name>
        <version>1.0</version>
        <interface>
            <name>IMemory</name>
            <instance>ashmem</instance>
        </interface>
    </hal>
    <hal>
        <name>android.hidl.allocator</name>
        <version>1.0</version>
        <interface>
            <name>IAllocator</name>
            <instance>ashmem</instance>
        </interface>
    </hal>
    <hal>
        <name>android.framework.sensor</name>
        <version>1.0</version>
        <interface>
            <name>ISensorManager</name>
            <instance>default</instance>
        </interface>
    </hal>
    <vendor-ndk>
        <version>27</version>
    </vendor-ndk>
    <system-sdk>
        <version>27</version>
    </system-sdk>
</compatibility-matrix>

Giản đồ ma trận tương thích

Phần này mô tả ý nghĩa của các thẻ XML này. Một số thẻ "bắt buộc" có thể bị thiếu trong tệp nguồn trong cây nguồn Android và do assemble_vintf ghi vào thời gian tạo bản dựng. Thẻ "Bắt buộc" phải có trong các tệp tương ứng trên thiết bị.

?xml
Không bắt buộc. Trình phân tích cú pháp này chỉ cung cấp thông tin cho trình phân tích cú pháp XML.
compatibility-matrix.version
Bắt buộc. Phiên bản siêu dữ liệu của ma trận tương thích này. Mô tả các phần tử dự kiến trong ma trận tương thích. Không liên quan đến phiên bản XML.
compatibility-matrix.type
Bắt buộc. Loại của ma trận tương thích này:
  • "device": Ma trận khả năng tương thích với thiết bị.
  • "framework": Ma trận khả năng tương thích của khung.
manifest.level
Bắt buộc đối với ma trận tương thích khung. Trong Android 12 trở lên, được phép trong các tệp ma trận khả năng tương thích khung trong các phân vùng sản phẩm và system_ext. Chỉ định Phiên bản ma trận tương thích khung (Phiên bản FCM) của tệp này. Đừng khai báo điều này trong ma trận tương thích khung dành riêng cho thiết bị (tức là DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE).
compatibility-matrix.hal
Không bắt buộc và có thể lặp lại. Liệt kê một HAL (HIDL hoặc gốc) mà chủ sở hữu của ma trận tương thích (khung hoặc thiết bị) bắt buộc phải có. Các mục nhập HAL được phân biệt bằng phần tử <name>; có thể có nhiều mục nhập HAL có cùng tên (ngụ ý điều kiện "và").
compatibility-matrix.hal.format
Không bắt buộc. Giá trị có thể là một trong những giá trị sau:
  • "hidl": HIDL HAL. Đây là tuỳ chọn mặc định.
  • "aidl": HAL AIDL. Chỉ hợp lệ trên phiên bản siêu dữ liệu của ma trận tương thích 2.0.
  • "native": HAL gốc.
compatibility-matrix.hal.optional (Android 15 trở xuống)
Thuộc tính
là không bắt buộc và mặc định sẽ được đặt là false. Cho biết liệu HAL này có là tuỳ chọn đối với chủ sở hữu ma trận tương thích (khung hoặc thiết bị) hay không. Nếu mục nhập <hal> được đánh dấu là không bắt buộc, thì tức là chủ sở hữu có thể làm việc với HAL này (nếu có) nhưng không bắt buộc phải có HAL này.
Cảnh báo: Thuộc tính này không còn được dùng nữa sau Android 15 và không còn hiệu lực nữa. Nếu cần cài đặt bất kỳ HAL nào, bạn phải thực thi yêu cầu này trong các bài kiểm thử.
compatibility-matrix.hal.name
Bắt buộc. Tên gói đầy đủ của HAL này. Ví dụ:
  • android.hardware.camera (HIDL hoặc AIDL HAL)
  • GLES (HAL gốc, chỉ yêu cầu tên)
compatibility-matrix.hal.version
Danh sách các dải phiên bản (xem phần Khớp HAL) xác định những phiên bản mà chủ sở hữu của ma trận tương thích (khung hoặc thiết bị) mong đợi.

Đối với HIDL và HAL gốc, bắt buộc, có thể lặp lại mà không trùng lặp. Định dạng là một trong những định dạng sau:
  • MAJOR.MINOR_MIN-MINOR_MAX
  • MAJOR.MINOR (tương đương với MAJOR.MINOR-MINOR)

Đối với các HAL AIDL, không được có trên các thiết bị chạy Android 11 trở xuống. Không bắt buộc trên các thiết bị chạy phiên bản mới hơn. Nếu được chỉ định, định dạng sẽ là một trong những định dạng sau:
  • VERSION_MIN-VERSION_MAX
  • VERSION (tương đương với VERSION-VERSION)
Nếu không được chỉ định, giá trị mặc định sẽ là 1.
compatibility-matrix.hal.interface
Không bắt buộc, có thể lặp lại. Danh sách các giao diện bắt buộc của HAL này.
compatibility-matrix.hal.interface.name
Bắt buộc. Tên của giao diện.
compatibility-matrix.hal.interface.instance
Không bắt buộc, có thể lặp lại. Danh sách các thực thể bắt buộc của giao diện này.
compatibility-matrix.hal.interface.regex-instance
Không bắt buộc, có thể lặp lại. Danh sách các mẫu tên thực thể bắt buộc trên giao diện này. Sử dụng định dạng Biểu thức chính quy mở rộng.
compatibility-matrix.kernel
Không bắt buộc, có thể lặp lại. Chỉ định danh sách cấu hình hạt nhân mà khung yêu cầu trên mỗi phiên bản hạt nhân.
Nhiều <kernel> có cùng <version> có thể tồn tại để ngụ ý mối quan hệ "và". Mỗi <kernel> là một "mảnh" của các yêu cầu chỉ được bật khi <conditions> được đáp ứng.
compatibility-matrix.kernel.version
Bắt buộc. Phiên bản kernel. Định dạng là VERSION.MAJOR_REVISION.MINOR_REVISION. Phiên bản và bản sửa đổi lớn phải khớp chính xác. Bản sửa đổi nhỏ xác định phiên bản LTS tối thiểu của hạt nhân mà khung này yêu cầu.
compatibility-matrix.kernel.condition
Không bắt buộc. Không được tồn tại đối với <kernel> đầu tiên của mỗi phiên bản. Chỉ định danh sách các điều kiện. Khi đáp ứng các điều kiện, các yêu cầu nêu trong mảnh <kernel> này sẽ được bật.
compatibility-matrix.kernel.config
Không bắt buộc, có thể lặp lại. Liệt kê các mục CONFIG phải được so khớp với phiên bản hạt nhân này. Mỗi mục CONFIG là một cặp khoá-giá trị; các mục cấu hình được phân biệt theo khoá.
compatibility-matrix.kernel.config.key
Bắt buộc. Tên khoá của mục CONFIG. Bắt đầu bằng CONFIG_.
compatibility-matrix.kernel.config.value
Bắt buộc. Giá trị của mục CONFIG. Định dạng phụ thuộc vào loại:
  • string. Bỏ qua dấu ngoặc kép.
  • int. Giá trị thập phân và thập lục phân (phải bắt đầu bằng 0x hoặc 0X)). Được diễn giải dưới dạng số nguyên 64 bit; tình trạng tràn sẽ dẫn đến việc cắt bớt. (Trình phân tích cú pháp chấp nhận các giá trị từ -264 + 1 đến 264 - 1, bit thứ 65 bị cắt bớt; để biết thông tin chi tiết, hãy tham khảo trang thông tin strtoull.)
  • range. Định dạng là [int]-[int], ví dụ: 10-20. Giá trị thập lục phân được chấp nhận và phải bắt đầu bằng 0x hoặc 0X. Hai ranh giới phải là số nguyên 64 bit chưa ký.
  • tristate. Các giá trị hợp lệ là y, m và n.
compatibility-matrix.kernel.config.value.type
Bắt buộc. Loại giá trị của mục CONFIG, một trong các loại sau:
  • string
  • int
  • range
  • tristate
compatibility-matrix.sepolicy
Bắt buộc. Chứa tất cả các mục nhập liên quan đến sepolicy. Chỉ được ma trận tương thích khung sử dụng.
compatibility-matrix.sepolicy.sepolicy-version
Bắt buộc, có thể lặp lại. Mô tả yêu cầu về phiên bản sepolicy. Tương ứng với manifest.sepolicy.version. Mỗi thực thể của một phần tử xác định một phạm vi phiên bản sepolicy.
compatibility-matrix.sepolicy.kernel-sepolicy-version
Bắt buộc. Khai báo phiên bản policydb mà khung này hoạt động.
compatibility-matrix.avb.vbmeta-version
Không bắt buộc; chỉ được ma trận tương thích khung sử dụng. Khai báo phiên bản AVB dùng để ký system.img. Không dùng nữa trong Android 10.
compatibility-matrix.vendor-ndk
Không bắt buộc; chỉ được ma trận tương thích thiết bị sử dụng. Khai báo yêu cầu của ảnh chụp nhanh nhà cung cấp VNDK. Nếu thiếu, hệ thống sẽ không đưa ra yêu cầu về VNDK trên hình ảnh hệ thống.
compatibility-matrix.vendor-ndk.version
Bắt buộc. Một số nguyên dương khai báo phiên bản VNDK mà hình ảnh nhà cung cấp yêu cầu.
compatibility-matrix.vendor-ndk.library
Không bắt buộc, có thể lặp lại. Khai báo một tập hợp thư viện VNDK mà hình ảnh nhà cung cấp yêu cầu. Có cùng ngữ nghĩa với manifest.vendor-ndk.library.
compatibility-matrix.system-sdk.version
Không bắt buộc, có thể lặp lại; chỉ được ma trận khả năng tương thích với thiết bị sử dụng. Khai báo yêu cầu của ứng dụng nhà cung cấp đối với các phiên bản SDK hệ thống. Nếu thiếu, sẽ không có yêu cầu nào về SDK hệ thống trên hình ảnh hệ thống.