کار کردن با فهرست‌های نماد

برای کاهش سطح نمادها و انواع که باید به‌عنوان پایدار حفظ شوند، هسته GKI قابلیت‌هایی برای محدود کردن نمادهای صادرشده به فقط آن‌هایی که توسط ماژول‌ها نیاز است دارد. برای واحدهای کامپایل‌شده خارجی، باید فهرستی از نمادهای استفاده‌شده داشته باشید تا به آن‌ها اجازه دهید توسط هسته GKI صادر شوند. برای مثال، نمادهای استفاده‌شده توسط واحدها برای Cuttlefish در gki/aarch64/symbols/virtual_device ذخیره می‌شوند.

هدفی برای تولید فهرست نماد اضافه کنید

فهرست‌های نماد توسط هدف kernel_abi تولید می‌شوند. این هدف را با گزینه‌های زیر به دستگاه BUILD.bazel اضافه کنید:

  • name

    باید در قالب <kernel_build>_abi باشد.

  • kernel_build

    باید حاوی نام دستگاه kernel_build هدف باشد.

همچنین می‌توانید از گزینه‌های زیر استفاده کنید:

  • kernel_modules

    فهرست هدف‌های واحدهای خارج از درخت. واحدهای درون‌درختی نباید در اینجا گنجانده شوند. به آماده کردن واحدهای درون‌درختی برای استخراج نماد مراجعه کنید.

  • kmi_symbol_list_add_only

    این گزینه از برداشتن نمادهای استفاده‌نشده جلوگیری می‌کند. حذف نماد فقط در زمان‌های خاصی درطول تثبیت KMI مجاز است و پس‌از ثابت شدن KMI مجاز نیست.

    این کار همچنین زمانی مفید است که از فهرست نماد یکسانی برای چندین دستگاه مختلف استفاده می‌کنید. به این ترتیب، نمادهایی که دستگاه A استفاده می‌کند اما دستگاه B استفاده نمی‌کند برداشته نخواهد شد.

  • module_grouping

    اگر True یا نامشخص باشد، فهرست نمادها نمادها را براساس واحدهای هسته‌ای که به نماد ارجاع می‌دهند گروه‌بندی می‌کند. درغیراین‌صورت، فهرست نمادها فهرستی مرتب‌شده از نمادهای مورداستفاده همه واحدهای هسته است.

برای مثال، common-modules/virtual-device/BUILD.bazel را ببینید:

kernel_abi(
    name = "virtual_device_aarch64_abi",
    kernel_build = ":virtual_device_aarch64",
    kernel_modules = [":virtual_device_aarch64_external_modules"],
    kmi_symbol_list_add_only = True,
)

همچنین اسناد مرجع درباره kernel_abi هدف در Kleaf را ببینید.

آماده کردن واحدهای درون‌درختی برای استخراج نماد

برای آماده کردن واحدهای درون‌درختی برای استخراج نماد، واحدهای درون‌درختی مختص فروشنده را در مشخصه module_outs هدف kernel_build فهرست کنید. برای مثال، _VIRT_COMMON_MODULES و کاربرد آن را ببینید. واحد‌های GKI را در این فهرست قرار ندهید.

این واحدها را پیکربندی کنید تا بدون امضا باشند، درغیراین‌صورت فهرست نماد ممکن است خالی باشد. برای انجام این کار، این خط را به قطعه‌های پیکربندی هسته اضافه کنید:

# CONFIG_MODULE_SIG_ALL is not set

برای مثال، common-modules/virtual-device/virtual_device_core.fragment را ببینید.

افزودن فهرست نماد دستگاه به ساختار هسته دستگاه

مشخصه kmi_symbol_list را به هدف kernel_build تعریف‌شده در دستگاه BUILD.bazel اضافه کنید. نام فهرست نماد باید در قالب //common:gki/<arch>/symbols/<device> باشد.

برای مثال، common-modules/virtual-device/BUILD.bazel را ببینید:

kernel_build(
    name = "virtual_device_aarch64",
    base_kernel = "//common:kernel_aarch64",
    kmi_symbol_list = "//common:gki/aarch64/symbols/virtual_device",
    ...
    module_outs = _VIRT_COMMON_MODULES + _VIRT_AARCH64_MODULES,
)

ایجاد و ارسال فهرست نماد اولیه

فهرست نماد خالی در common/gki/<arch>/symbols/<device> ایجاد کنید. برای مثال بالا، فرمان این‌گونه خواهد بود:

touch common/gki/aarch64/symbols/virtual_device

این فایل را به additional_kmi_symbol_lists از ساخت هسته GKI پایه اضافه کنید. برای مثال، //common:gki/aarch64/symbols/virtual_device به گروه فایل aarch64_additional_kmi_symbol_lists اضافه شده است که در common/BUILD.bazel اعلام شده است.

فهرست نماد دستگاه را به‌روز کنید تا فهرست نماد جدید را تکمیل کنید و آن را به مخزن «هسته مشترک Android» ارسال کنید.

به‌روزرسانی فهرست نمادهای دستگاه

همه نمادهای هسته اصلی که توسط ماژول‌ها در module_outs از kernel_build و kernel_modules از kernel_abi استفاده می‌شوند باید در فهرست نمادها گنجانده شوند. این کار را می‌توان با اجرای هدف kernel_abi با پسوند _update_symbol_list انجام داد. برای مثال، فرمان زیر فهرست نماد را برای //common-modules/virtual-device:virtual_device_aarch64 به‌روز می‌کند:

tools/bazel run //common-modules/virtual-device:virtual_device_aarch64_abi_update_symbol_list

ارسال به‌روزرسانی فهرست نماد به ACK

وصله‌ای با تغییر فهرست نمادها به Android Common Kernel gerrit ارسال کنید تا نمادهای جدید بخشی از KMI شوند.

پیام تعهد باید شامل فهرستی از نمادهای اضافه یا حذف‌شده باشد. می‌توانید این فهرست را به‌صورت دستی برای به‌روزرسانی فهرست نماد کوچک بنویسید یا از گزارش $DIST_DIR/abi_stgdiff/abi.report.short پس‌از به‌روزرسانی نمایش ABI مرجع استفاده کنید.

اگرچه به‌روزرسانی نمایش ABI مرجع قبل‌از ارسال به‌روزرسانی فهرست نماد الزامی نیست، اما ممکن است مراحل اضافی پیش‌از ارسال را حذف کند و تغییر را برای ارسال سریع‌تر آماده کند. در هر صورت، درطول پیش‌ارسال بررسی می‌شود و درصورت لزوم به‌روز می‌شود.

کار با فهرست‌های نماد (Android 13)

‫Android 13 از هر دو دستورگان ساخت Kleaf و قدیمی پشتیبانی می‌کند، بنابراین می‌توانید فهرست‌های نماد را هم طبق آنچه در بخش‌های قبلی توضیح داده شده است و هم طبق آنچه در بخش زیر توضیح داده شده است مدیریت کنید.

کار با فهرست‌های نماد (Android 12 و پایین‌تر)

از ابزار build_abi.sh به‌صورت زیر استفاده کنید:

BUILD_CONFIG=path/to/build.config.device build/build_abi.sh --update-symbol-list

در این مثال، build.config.device باید شامل این گزینه‌های پیکربندی باشد:

  • vmlinux

    باید بخشی از فهرست FILES باشد. این کار را می‌توان با گنجاندن build.config.aarch64 انجام داد.

  • KMI_SYMBOL_LIST

    باید تنظیم شود و به فهرست نماد KMI برای به‌روزرسانی اشاره کند.

پس‌از به‌روزرسانی فهرست نمادهای دستگاه، باید این تغییرات را در ساختار GKI (common/build.config.gki.aarch64) نیز منعکس کنید: