Cómo trabajar con listas de símbolos

Para reducir la superficie de símbolos y tipos que deben mantenerse estables, el kernel de GKI tiene capacidades para limitar los símbolos exportados solo a aquellos que necesitan los módulos. En el caso de los módulos compilados de forma externa, debes tener una lista de símbolos usados para permitir que el kernel de GKI los exporte. Por ejemplo, los símbolos que usan los módulos para Cuttlefish se almacenan en gki/aarch64/symbols/virtual_device.

Agrega un destino para la generación de la lista de símbolos

Las listas de símbolos se generan con el destino kernel_abi. Agrega este destino al BUILD.bazel del dispositivo con las siguientes opciones:

  • name

    Debe tener el formato <kernel_build>_abi.

  • kernel_build

    Debe contener el nombre del destino kernel_build del dispositivo.

También puedes usar las siguientes opciones:

  • kernel_modules

    Es una lista de los destinos para módulos externos. Los módulos dentro del árbol no deben incluirse aquí. Consulta Cómo preparar módulos dentro de un árbol para la extracción de símbolos.

  • kmi_symbol_list_add_only

    Esta opción evita la eliminación de símbolos sin usar. La eliminación de símbolos solo se permite en momentos específicos durante la KMI estabilización y no se permite una vez que la KMI está congelada.

    Esto también es útil cuando usas la misma lista de símbolos para varios dispositivos diferentes. De esta manera, no se quitarán los símbolos que usa el dispositivo A, pero no el dispositivo B.

  • module_grouping

    Si es True o no se especifica, la lista de símbolos agrupa los símbolos según los módulos del kernel que hacen referencia al símbolo. De lo contrario, la lista de símbolos es una lista ordenada de símbolos que usan todos los módulos del kernel.

Consulta common-modules/virtual-device/BUILD.bazel como ejemplo:

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,
)

Consulta también la documentación de referencia sobre el destino kernel_abi en Kleaf.

Prepara módulos dentro de un árbol para la extracción de símbolos

Para preparar módulos dentro de un árbol para la extracción de símbolos, enumera los módulos dentro de un árbol específicos del proveedor en un atributo module_outs del destino kernel_build. Consulta _VIRT_COMMON_MODULES y su uso como ejemplo. No incluyas módulos de GKI en esta lista.

Configura estos módulos para que no estén firmados. De lo contrario, la lista de símbolos podría estar vacía. Para ello, agrega esta línea a tus fragmentos de configuración del kernel:

# CONFIG_MODULE_SIG_ALL is not set

Consulta common-modules/virtual-device/virtual_device_core.fragment como ejemplo.

Agrega una lista de símbolos del dispositivo a la compilación del kernel del dispositivo

Agrega el atributo kmi_symbol_list al destino kernel_build definido en el BUILD.bazel del dispositivo. El nombre de la lista de símbolos debe tener el formato de //common:gki/<arch>/symbols/<device>.

Consulta common-modules/virtual-device/BUILD.bazel, como ejemplo:

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,
)

Crea y envía una lista de símbolos inicial

Crea una lista de símbolos vacía en common/gki/<arch>/symbols/<device>. Para el ejemplo anterior, el comando sería el siguiente:

touch common/gki/aarch64/symbols/virtual_device

Agrega este archivo a additional_kmi_symbol_lists de la compilación del kernel de GKI base. Por ejemplo, //common:gki/aarch64/symbols/virtual_device se agrega al aarch64_additional_kmi_symbol_lists grupo de archivos, declarado en common/BUILD.bazel.

Actualiza la lista de símbolos del dispositivo para completar la nueva lista de símbolos y envíala al repositorio del kernel común de Android.

Actualiza una lista de símbolos del dispositivo

Todos los símbolos principales del kernel que usan los módulos en module_outs de kernel_build y kernel_modules de kernel_abi deben incluirse en la lista de símbolos. Para ello, ejecuta el destino kernel_abi con el sufijo _update_symbol_list. Por ejemplo, el siguiente comando actualiza la lista de símbolos para //common-modules/virtual-device:virtual_device_aarch64:

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

Envía una actualización de la lista de símbolos a ACK

Envía un parche con el cambio de la lista de símbolos al gerrit del kernel común de Android para que los símbolos nuevos formen parte de la KMI.

El mensaje de confirmación debe incluir una lista de símbolos agregados o quitados. Puedes escribir esta lista de forma manual para una pequeña actualización de la lista de símbolos o usar $DIST_DIR/abi_stgdiff/abi.report.short informe después de actualizar la representación de ABI de referencia.

Si bien no es obligatorio actualizar la representación de ABI de referencia antes de enviar una actualización de la lista de símbolos, puede eliminar pasos adicionales de envío previo y hacer que el cambio esté listo para enviarse más rápido. En cualquier caso, se verifica y actualiza si es necesario durante el envío previo.

Trabaja con listas de símbolos (Android 13)

Android 13 admite Kleaf y secuencias de comandos de compilación heredadas, por lo que puedes administrar listas de símbolos como se describe en las secciones anteriores o como se describe en la siguiente sección.

Trabaja con listas de símbolos (Android 12 y versiones anteriores)

Usa la herramienta build_abi.sh de la siguiente manera:

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

En este ejemplo, build.config.device debe incluir estas opciones de configuración:

  • vmlinux

    Debe formar parte de la lista FILES. Para ello, incluye build.config.aarch64.

  • KMI_SYMBOL_LIST

    Debe configurarse y apuntar a la lista de símbolos de KMI para actualizarse.

Después de actualizar la lista de símbolos del dispositivo, también debes reflejar estos cambios en la compilación de GKI (common/build.config.gki.aarch64):