مصفوفات التوافق

يصف هذا القسم إطار العمل ومصفوفات توافق الأجهزة ومخطّط مصفوفة التوافق. للاطّلاع على قواعد المطابقة، يُرجى الاطّلاع على قواعد المطابقة.

مصفوفة التوافق مع الإطار (FCM)

تصف مصفوفة توافق الإطار (FCM) متطلبات الإطار على الجهاز الذي يتم تشغيله عليه. تتألّف مصفوفة توافق إطار العمل من مصفوفة توافق النظام ومصفوفة توافق المنتج ومصفوفة توافق system_ext. يجب أن يستوفي بيان الجهاز متطلبات خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" (متطلبات يتم فرضها في وقت الإنشاء ووقت التشغيل وفي اختبار VTS).

إنّ نظامَي FCM‏ system_ext وFCM للمنتجات هما مكملان لنظام FCM الخاص بالأجهزة (الذي يتم تثبيته في قسم النظام).

• يجب أن يعكس إطار عمل FCM للأجهزة متطلبات الوحدات في قسم النظام.
• يجب أن يعكس نظام FCM في نظام التشغيل system_ext المتطلبات حسب الوحدات في قسم system_ext.
• يجب أن يعكس تنسيق FCM للمنتج المتطلبات حسب الوحدات في قسم المنتج.

يجب أن تكون جميع ملفات FCM متوافقة مع تعديلات المصنّع الأصلي للجهاز على إطار العمل في أقسام system وproduct وsystem_ext. على سبيل المثال، إذا كان أحد التطبيقات المثبَّتة في قسم المنتج يستخدم إضافة مورِّد لواجهة HAL، يجب الإفصاح عن متطلبات واجهة HAL في ملف بيان إدارة الخدمات في السحابة الإلكترونية (FCM) الخاص بالمنتج.

مثال على ملف مصفوفة توافق النظام:

<?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>

لمزيد من التفاصيل، يُرجى الاطّلاع على دورة حياة Firebase Cloud Messaging.

مصفوفة توافق المنتجات

ملف FCM الخاص بالمنتج هو ملف مصفوفة توافق إطار العمل في القسم المخصّص للمنتج. يربط عنصر VINTF وحدة تحكّم في حدود الجلسة (FCM) الخاصة بالمنتج بوحدات تحكّم في حدود الجلسة في قسمَي system وsystem_ext أثناء التشغيل.

مثال على ملف "المراسلة من خلال السحابة الإلكترونية من Firebase" الخاص بالمنتج:

<?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>

مصفوفة التوافق System_ext

ملف FCM في نظام_الملف_الإضافي هو ملف مصفوفة توافق إطار العمل في القسم system_ext. يُدمج عنصر VINTF وحدة التحكّم في حدود الجلسة (FCM) system_ext مع وحدات التحكّم في حدود الجلسة في أقسام النظام والمنتجات أثناء التشغيل. اطّلِع على مصفوفة توافق المنتجات للاطّلاع على مثال على ملف system_ext في إطار عمل "إشعارات Google من خادم Firebase".

مصفوفة توافق الأجهزة (DCM)

توضِّح مصفوفة توافق الأجهزة مجموعة من المتطلبات التي يتوقعها الجهاز من إطار العمل (المتطلبات المفروضة عند الإطلاق وعند التحديث عبر الهواء).

مثال على ملف DCM:

<?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>

مخطّط مصفوفة التوافق

يصف هذا القسم معنى علامات XML هذه. قد لا تتوفّر بعض العلامات "المطلوبة" في ملف المصدر ضمن شجرة مصدر Android، وقد يكتبها assemble_vintf في وقت الإنشاء. يجب أن تكون العلامات "المطلوبة" متوفّرة في الملفات المقابلة على الجهاز.

?xml

اختياري. ولا يوفّر سوى معلومات لمعترِف XML.

compatibility-matrix.version

مطلوبة. الإصدار الأساسي لمصفوفة التوافق هذه. يصف العناصر المتوقّعة في مصفوفة التوافق. لا علاقة له بإصدار XML.

compatibility-matrix.type

مطلوبة. نوع مصفوفة التوافق هذه:

• "device": مصفوفة توافق الأجهزة
• "framework": مصفوفة توافق الإطارات

manifest.level

مطلوبة لمصفوفة توافق إطار العمل في الإصدار 12 من Android والإصدارات الأحدث، يُسمح باستخدامها في ملفات مصفوفة توافق إطار العمل في قسمَي product وsystem_ext. تُحدِّد إصدار "مصفوفة توافق إطار العمل" (إصدار FCM) لهذا الملف. لا تذكر ذلك في مصفوفة توافق إطار العمل الخاصة بالأجهزة (أي DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE).

compatibility-matrix.hal

اختياري ويمكن تكراره. يسرد واجهة HAL واحدة (HIDL أو واجهة برمجة تطبيقات أصلية) يطلب مالك مصفوفة التوافق (إطار العمل أو الجهاز) أن تكون متوفرة. يتم تمييز إدخالات HAL بعنصر <name>، ويمكن أن تكون هناك عدة إدخالات HAL تحمل الاسم نفسه (يشير ذلك إلى شرط "و").

compatibility-matrix.hal.format

اختياري. يمكن أن تكون القيمة إحدى القيم التالية:

• ‫"hidl": واجهات HIDL HAL هذا هو الخيار التلقائي.
• "aidl": واجهات برمجة التطبيقات لـ AIDL صالح فقط للإصدار 2.0 من النسخة الوصفية لمصفوفة التوافق.
• "native": واجهات برمجة التطبيقات لمستوى الحِزم الأساسية

compatibility-matrix.hal.optional (إصدار Android 15 أو الإصدارات الأقدم)

السمة

اختيارية وتكون قيمتها التلقائية خطأ. يشير إلى ما إذا كان HAL هذا اختياريًا لمالك مصفوفة التوافق (الإطار أو الجهاز). إذا تم وضع علامة "اختياري" على إدخال <hal>، يعني ذلك أنّه يمكن للمالك استخدام HAL هذا، في حال توفّره، ولكنّه لا يتطلّب توفّره.

تحذير: يتم إيقاف هذه السمة نهائيًا بعد الإصدار 15 من Android ولم تعُد لها أي تأثير. إذا كان يجب تثبيت أيّ HAL، يجب فرض هذا الشرط في الاختبارات.

compatibility-matrix.hal.name

مطلوبة. اسم الحزمة الكامل لواجهة HAL هذه. أمثلة:

• ‫android.hardware.camera (HIDL أو AIDL HAL)
• ‫GLES (HAL أصلي، يتطلب الاسم فقط)

compatibility-matrix.hal.version

قائمة بنطاقات الإصدارات (راجِع مطابقات HAL) التي تحدّد الإصدارات التي يتوقّعها مالك مصفوفة التوافق (الإطار أو الجهاز)

بالنسبة إلى HIDL وواجهات HAL الأصلية، تكون مطلوبة ويمكن تكرارها بدون نُسخ طبق الأصل. التنسيق هو أحد الخيارات التالية:

• MAJOR.MINOR_MIN-MINOR_MAX
• MAJOR.MINOR (ما يعادل MAJOR.MINOR-MINOR)

بالنسبة إلى واجهات برمجة التطبيقات لواجهة HAL لذكاء الاصطناعي (AIDL)، يجب ألا تكون متوفّرة على الأجهزة التي تعمل بالإصدار 11 من نظام التشغيل Android والإصدارات الأقدم. اختياري على الأجهزة التي تعمل بإصدارات أحدث إذا تم تحديده، يكون التنسيق أحد التنسيقات التالية:

• VERSION_MIN-VERSION_MAX
• VERSION (ما يعادل VERSION-VERSION)

إذا لم يتم تحديد قيمة، تكون القيمة التلقائية هي 1.

compatibility-matrix.hal.interface

اختياري، يمكن تكراره. قائمة الواجهات المطلوبة لواجهة HAL هذه

compatibility-matrix.hal.interface.name

مطلوبة. اسم الواجهة

compatibility-matrix.hal.interface.instance

اختياري، يمكن تكراره. قائمة بالمثيلات المطلوبة لهذه الواجهة

compatibility-matrix.hal.interface.regex-instance

اختياري، يمكن تكراره. قائمة بأنماط أسماء النماذج المطلوبة في هذه الواجهة استخدِم تنسيق التعبير العادي الموسّع.

compatibility-matrix.kernel

اختياري، يمكن تكراره. حدِّد قائمة بإعدادات kernel التي يتطلبها الإطار العملي في كل إصدار من kernel.
يمكن أن تتعلّق عدة <kernel> بال<version> نفسه للإشارة إلى علاقة "و". كل <kernel> هو "جزء" من المتطلبات التي لا يتم تفعيلها إلا عند استيفاء <conditions>.

compatibility-matrix.kernel.version

مطلوبة. إصدار النواة التنسيق هو VERSION.MAJOR_REVISION.MINOR_REVISION. يجب أن يتطابق الإصدار مع المراجعة الرئيسية تمامًا. تحدِّد المراجعة الثانوية الحد الأدنى لإصدار الدعم الطويل الأمد للنواة الذي يتوقّعه إطار العمل.

compatibility-matrix.kernel.condition

اختياري. يجب ألا تكون متوفّرة في أول <kernel> من كل إصدار. تُحدِّد قائمة بالشروط. عند استيفاء الشروط، يتم تفعيل المتطلبات الواردة في هذا المقتطف <kernel>.

compatibility-matrix.kernel.config

اختياري، يمكن تكراره. يسرد CONFIG عنصرًا يجب مطابقتها لإصدار kernel هذا. كل عنصر من عناصر CONFIG هو زوج مفتاح وقيمة، ويتم تمييز عناصر الضبط حسب المفتاح.

compatibility-matrix.kernel.config.key

مطلوبة. اسم مفتاح عنصر CONFIG. يبدأ بحرف CONFIG_.

compatibility-matrix.kernel.config.value

مطلوبة. قيمة عنصر CONFIG يعتمد التنسيق على النوع:

• string. يتم حذف علامات الاقتباس.
• int. يتم قبول القيم العشرية والسداسية العشرية (يجب أن تبدأ بـ 0x أو 0X)). يتم تفسيره على أنّه عدد صحيح 64 بت، ويؤدي تجاوز الحدّ الأقصى إلى اقتطاعه. (يقبل المحلل اللغوي القيم من -2⁶⁴ + 1 إلى 2⁶⁴ - 1، ويتم اقتطاع وحدة البت 65. للاطّلاع على التفاصيل، يُرجى الرجوع إلى صفحة رجل الأحرف.)
• range. التنسيق هو [int]-[int]، على سبيل المثال: 10-20. يتم قبول القيم الست عشرية ويجب أن تبدأ بحرف 0x أو 0X. يجب أن يكون الحدّان عددَين صحيحَين بدون إشارة ومقدارهما 64 بت.
• tristate. القيم الصالحة هي y وm n.

compatibility-matrix.kernel.config.value.type

مطلوبة. نوع قيمة عنصر CONFIG، أحد الخيارَين التاليَين:

• string
• int
• range
• tristate

compatibility-matrix.sepolicy

مطلوبة. يحتوي على جميع الإدخالات ذات الصلة بسياسات الأمان. لا يتم استخدامه إلا من قِبل مصفوفة التوافق مع إطار العمل.

compatibility-matrix.sepolicy.sepolicy-version

مطلوبة، ويمكن تكرارها. يصف المتطلّبات المتعلقة بإصدار sepolicy. يتوافق مع manifest.sepolicy.version. وتحدِّد كلّ نسخة من العنصر نطاقًا من إصدارات سياسة الأمان.

compatibility-matrix.sepolicy.kernel-sepolicy-version

مطلوبة. يُستخدَم لتحديد إصدار policydb الذي يعمل معه الإطار العمل.

compatibility-matrix.avb.vbmeta-version

اختياري، ولا يتم استخدامه إلا من خلال مصفوفة توافق إطار العمل. يُعلن عن إصدار AVB المستخدَم لتوقيع system.img. تم إيقافه نهائيًا في Android 10.

compatibility-matrix.vendor-ndk

اختياري، لا يستخدمه سوى مصفوفة توافق الأجهزة. يُعلن عن متطلّبات لقطة المورّد لـ VNDK. في حال عدم توفّر حزمة VNDK، لن يتم فرض أي متطلبات عليها في صورة النظام.

compatibility-matrix.vendor-ndk.version

مطلوبة. عدد صحيح موجب يُعلن عن إصدار VNDK المطلوب من صورة المورّد

compatibility-matrix.vendor-ndk.library

اختياري، يمكن تكراره. يُعلن عن مجموعة من مكتبات VNDK المطلوبة من صورة المورّد. الدلالات نفسها مثل manifest.vendor-ndk.library

compatibility-matrix.system-sdk.version

اختياري، يمكن تكراره، ولا يستخدمه سوى مصفوفة توافق الأجهزة. توضيح المتطلبات التي تفرضها تطبيقات المورّدين على إصدارات حِزم SDK للنظام في حال عدم توفّر حزمة تطوير البرامج (SDK) للنظام، لن يتم فرض أي متطلبات على صورة النظام.