Cómo trabajar con listas de símbolos

Para reducir la superficie de símbolos y tipos que se deben mantener 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 los 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 android/abi_gki_aarch64_virtual_device.

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

El destino kernel_abi genera las listas de símbolos. Agrega este objetivo al BUILD.bazel del dispositivo con las siguientes opciones:

  • name

    Debe tener el formato <kernel_build>_abi.

  • kernel_build

    Debe contener el nombre del objetivo kernel_build del dispositivo.

También puedes usar las siguientes opciones:

  • kernel_modules

    Es la lista de los destinos de los módulos fuera del árbol. No se deben incluir aquí los módulos dentro del árbol. 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 estabilización de la KMI 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 a ellos. 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, por 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.

Cómo preparar 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 objetivo kernel_build. Consulta _VIRT_COMMON_MODULES y su uso para ver un ejemplo. No incluyas módulos de GKI en esta lista.

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

# CONFIG_MODULE_SIG_ALL is not set

Consulta common-modules/virtual-device/virtual_device_core.fragment, por ejemplo.

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

Agrega el atributo kmi_symbol_list al objetivo kernel_build definido en el dispositivo BUILD.bazel. El nombre de la lista de símbolos debe tener el formato //common:android/abi_gki_<arch>_<device>. Consulta common-modules/virtual-device/BUILD.bazel, por ejemplo:

kernel_build(
    name = "virtual_device_aarch64",
    base_kernel = "//common:kernel_aarch64",
    kmi_symbol_list = "//common:android/abi_gki_aarch64_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/android/abi_gki_<arch>_<device>. Para el ejemplo anterior, el comando sería el siguiente:

touch common/android/abi_gki_aarch64_virtual_device

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

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

Cómo actualizar una lista de símbolos de dispositivos

Todos los símbolos del kernel principal 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 a Gerrit de Android Common Kernel para que los símbolos nuevos formen parte del KMI.

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

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

Versiones anteriores (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 ser parte de la lista FILES. Para ello, incluye build.config.aarch64.

  • KMI_SYMBOL_LIST

    Se debe configurar y apuntar a la lista de símbolos de KMI para actualizar.

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