Trabalhar com listas de símbolos

Para reduzir a superfície de símbolos e tipos que precisam ser mantidos estáveis, o kernel do GKI tem recursos para limitar os símbolos exportados apenas àqueles que são necessários pelos módulos. Para módulos compilados externamente, você precisa ter uma lista de símbolos usados para permitir que eles sejam exportados pelo kernel do GKI. Por exemplo, os símbolos usados por módulos para Cuttlefish são armazenados em android/abi_gki_aarch64_virtual_device.

Adicionar um destino para a geração da lista de símbolos

As listas de símbolos são geradas pelo destino kernel_abi. Adicione esse destino ao BUILD.bazel do dispositivo com as seguintes opções:

  • name

    Precisa estar no formato <kernel_build>_abi.

  • kernel_build

    Deve conter o nome do destino kernel_build do dispositivo.

Você também pode usar as seguintes opções:

  • kernel_modules

    Lista de destinos para módulos fora da árvore. Os módulos In-tree não podem ser incluídos aqui. Consulte Preparar módulos em árvore para extração de símbolos.

  • kmi_symbol_list_add_only

    Essa opção impede a remoção de símbolos não usados. A remoção de símbolos só é permitida em momentos específicos durante a estabilização da KMI e não é permitida quando a KMI é congelada.

    Isso também é útil quando você usa a mesma lista de símbolos para vários dispositivos diferentes. Dessa forma, os símbolos usados pelo dispositivo A não serão removidos, mas os do dispositivo B serão.

  • module_grouping

    Se True ou não especificado, a lista de símbolos agrupa símbolos com base nos módulos do kernel que fazem referência ao símbolo. Caso contrário, a lista de símbolos é uma lista classificada de símbolos usados por todos os módulos do kernel.

Consulte common-modules/virtual-device/BUILD.bazel para conferir um exemplo:

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

Consulte também a documentação de referência do alvo kernel_abi no Kleaf.

Preparar módulos em árvore para extração de símbolos

Para preparar módulos em árvore para extração de símbolos, liste módulos em árvore específicos do fornecedor em um atributo module_outs do destino kernel_build. Consulte _VIRT_COMMON_MODULES e seu uso para conferir um exemplo. Não inclua módulos de GKI nesta lista.

Configure esses módulos para serem não assinados. Caso contrário, a lista de símbolos poderá ficar vazia. Para fazer isso, adicione esta linha aos fragmentos de configuração do kernel:

# CONFIG_MODULE_SIG_ALL is not set

Consulte common-modules/virtual-device/virtual_device_core.fragment para conferir um exemplo.

Adicionar uma lista de símbolos do dispositivo ao build do kernel do dispositivo

Adicione o atributo kmi_symbol_list ao destino kernel_build definido no dispositivo BUILD.bazel. O nome da lista de símbolos precisa estar no formato //common:android/abi_gki_<arch>_<device>. Consulte common-modules/virtual-device/BUILD.bazel para conferir um exemplo:

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

Criar e enviar uma lista inicial de símbolos

Crie uma lista de símbolos vazia em common/android/abi_gki_<arch>_<device>. No exemplo acima, o comando seria:

touch common/android/abi_gki_aarch64_virtual_device

Adicione esse arquivo a additional_kmi_symbol_lists do build do kernel da GKI. Por exemplo, //common:android/abi_gki_aarch64_virtual_device é adicionado ao grupo de arquivos aarch64_additional_kmi_symbol_lists, declarado em common/BUILD.bazel.

Atualize a lista de símbolos do dispositivo para preencher a nova lista de símbolos e enviar ao repositório do kernel comum do Android.

Atualizar uma lista de símbolos de dispositivo

Todos os símbolos do kernel principais usados por módulos em module_outs de kernel_build e kernel_modules de kernel_abi precisam ser incluídos na lista de símbolos. Para isso, execute o destino kernel_abi com o sufixo _update_symbol_list. Por exemplo, o comando a seguir atualiza a 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

Enviar uma atualização da lista de símbolos para ACK

Envie um patch com a mudança na lista de símbolos para o kernel comum do Android gerrit para incluir os novos símbolos no KMI.

A mensagem de confirmação precisa incluir uma lista de símbolos adicionados ou removidos. É possível escrever essa lista manualmente para uma pequena atualização da lista de símbolos ou usar o relatório $DIST_DIR/abi.report.short depois de atualizar a representação da ABI de referência.

Embora atualizar a representação ABI de referência antes de enviar uma atualização da lista de símbolos não seja necessário, isso pode eliminar etapas adicionais de pré-envio e deixar a mudança pronta para envio mais rápido. Em qualquer caso, ele é verificado e atualizado, se necessário, durante a pré-envio.

Versões mais antigas (Android 12 e versões anteriores)

Use a ferramenta build_abi.sh da seguinte maneira:

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

Neste exemplo, build.config.device precisa incluir estas opções de configuração:

  • vmlinux

    Precisa fazer parte da lista FILES. Isso pode ser feito incluindo build.config.aarch64.

  • KMI_SYMBOL_LIST

    Precisa ser definido e apontado para a lista de símbolos do KMI para atualizar.

Depois de atualizar a lista de símbolos do dispositivo, você também precisa refletir essas mudanças no build do GKI (common/build.config.gki.aarch64):

  • Copie a lista de símbolos atualizada para common/android/abi_gki_aarch64_<device>.

  • Verifique se android/abi_gki_aarch64_<device> está incluído em ADDITIONAL_KMI_SYMBOL_LISTS em common/build.config.gki.aarch64.

  • Enviar atualização da lista de símbolos para ACK.