A estabilidade da Application Binary Interface (ABI) é um pré-requisito para atualizações somente de estrutura porque os módulos do fornecedor podem depender das bibliotecas compartilhadas Vendor Native Development Kit (VNDK) que residem na partição do sistema. Em uma versão do Android, as bibliotecas compartilhadas VNDK recém-construídas devem ser compatíveis com ABI para bibliotecas compartilhadas VNDK lançadas anteriormente, para que os módulos do fornecedor possam trabalhar com essas bibliotecas sem recompilação e sem erros de tempo de execução. Entre as versões do Android, as bibliotecas do VNDK podem ser alteradas e não há garantias de ABI.
Para ajudar a garantir a compatibilidade com ABI, o Android 9 inclui um verificador de cabeçalho ABI, conforme descrito nas seções a seguir.
Sobre conformidade com VNDK e ABI
O VNDK é um conjunto restritivo de bibliotecas às quais os módulos do fornecedor podem se vincular e que permitem atualizações somente de estrutura. A conformidade com a ABI refere-se à capacidade de uma versão mais recente de uma biblioteca compartilhada funcionar conforme o esperado com um módulo vinculado dinamicamente a ela (ou seja, funciona como uma versão mais antiga da biblioteca).
Sobre símbolos exportados
Um símbolo exportado (também conhecido como símbolo global ) refere-se a um símbolo que satisfaz todos os itens a seguir:
- Exportado pelos cabeçalhos públicos de uma biblioteca compartilhada.
- Aparece na tabela
.dynsym
do arquivo.so
correspondente à biblioteca compartilhada. - Tem ligação FRACA ou GLOBAL.
- A visibilidade é PADRÃO ou PROTEGIDA.
- O índice da seção não é INDEFINIDO.
- O tipo é FUNC ou OBJECT.
Os cabeçalhos públicos de uma biblioteca compartilhada são definidos como os cabeçalhos disponíveis para outras bibliotecas/binários por meio dos atributos export_include_dirs
, export_header_lib_headers
, export_static_lib_headers
, export_shared_lib_headers
e export_generated_headers
nas definições Android.bp
do módulo correspondente à biblioteca compartilhada.
Sobre os tipos alcançáveis
Um tipo alcançável é qualquer tipo C/C++ interno ou definido pelo usuário que pode ser acessado direta ou indiretamente por meio de um símbolo exportado E exportado por meio de cabeçalhos públicos. Por exemplo, libfoo.so
tem a função Foo
, que é um símbolo exportado encontrado na tabela .dynsym
. A biblioteca libfoo.so
inclui o seguinte:
foo_exported.h | foo.private.h |
---|---|
typedef struct foo_private foo_private_t; typedef struct foo { int m1; int *m2; foo_private_t *mPfoo; } foo_t; typedef struct bar { foo_t mfoo; } bar_t; bool Foo(int id, bar_t *bar_ptr); | typedef struct foo_private { int m1; float mbar; } foo_private_t; |
Android.bp |
---|
cc_library { name : libfoo, vendor_available: true, vndk { enabled : true, } srcs : ["src/*.cpp"], export_include_dirs : [ "exported" ], } |
tabela .dynsym | |||||||
---|---|---|---|---|---|---|---|
Num | Value | Size | Type | Bind | Vis | Ndx | Name |
1 | 0 | 0 | FUNC | GLOB | DEF | UND | dlerror@libc |
2 | 1ce0 | 20 | FUNC | GLOB | DEF | 12 | Foo |
Olhando para Foo
, os tipos alcançáveis direto/indireto incluem:
Tipo | Descrição |
---|---|
bool | Tipo de retorno de Foo . |
int | Tipo do primeiro parâmetro Foo . |
bar_t * | Tipo do segundo parâmetro Foo. Por meio de bar_t * , bar_t é exportado através de foo_exported.h .bar_t contém um membro mfoo , do tipo foo_t , que é exportado através de foo_exported.h , o que resulta na exportação de mais tipos:
No entanto, foo_private_t NÃO pode ser acessado porque não é exportado por meio de foo_exported.h . ( foo_private_t * é opaco, portanto alterações feitas em foo_private_t são permitidas.) |
Uma explicação semelhante pode ser fornecida para tipos acessíveis por meio de especificadores de classe base e parâmetros de modelo também.
Garantir a conformidade com a ABI
A conformidade com ABI deve ser garantida para as bibliotecas marcadas como vendor_available: true
e vndk.enabled: true
nos arquivos Android.bp
correspondentes. Por exemplo:
cc_library { name: "libvndk_example", vendor_available: true, vndk: { enabled: true, } }
Para tipos de dados acessíveis direta ou indiretamente por uma função exportada, as seguintes alterações em uma biblioteca são classificadas como quebra de ABI:
Tipo de dados | Descrição |
---|---|
Estruturas e Classes |
|
sindicatos |
|
Enumerações |
|
Símbolos Globais |
|
* As funções de membro públicas e privadas não devem ser alteradas ou removidas porque as funções inline públicas podem se referir a funções de membro privadas. Referências de símbolo para funções de membro privadas podem ser mantidas em binários do chamador. Alterar ou remover funções de membros privados de bibliotecas compartilhadas pode resultar em binários incompatíveis com versões anteriores.
** Os deslocamentos para membros de dados públicos ou privados não devem ser alterados porque as funções embutidas podem se referir a esses membros de dados em seu corpo de função. A alteração dos deslocamentos do membro de dados pode resultar em binários incompatíveis com versões anteriores.
*** Embora eles não alterem o layout de memória do tipo, existem diferenças semânticas que podem fazer com que as bibliotecas não funcionem conforme o esperado.
Usando ferramentas de conformidade ABI
Quando uma biblioteca VNDK é construída, a ABI da biblioteca é comparada com a referência ABI correspondente para a versão do VNDK que está sendo construída. Os despejos de ABI de referência estão localizados em:
${ANDROID_BUILD_TOP}/prebuilts/abi-dumps/vndk/<PLATFORM_VNDK_VERSION>/<BINDER_BITNESS>/<ARCH>/source-based
Por exemplo, ao criar libfoo
para x86 no nível de API 27, a ABI inferida de libfoo
é comparada com sua referência em:
${ANDROID_BUILD_TOP}/prebuilts/abi-dumps/vndk/27/64/x86/source-based/libfoo.so.lsdump
Erro de quebra ABI
Nas quebras de ABI, o log de compilação exibe avisos com o tipo de aviso e um caminho para o relatório abi-diff. Por exemplo, se a ABI de libbinder
tiver uma alteração incompatível, o sistema de compilação lançará um erro com uma mensagem semelhante à seguinte:
***************************************************** error: VNDK library: libbinder.so's ABI has INCOMPATIBLE CHANGES Please check compatibility report at: out/soong/.intermediates/frameworks/native/libs/binder/libbinder/android_arm64_armv8-a_cortex-a73_vendor_shared/libbinder.so.abidiff ****************************************************** ---- Please update abi references by running platform/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l libbinder ----
Construindo verificações ABI da biblioteca VNDK
Quando uma biblioteca VNDK é construída:
-
header-abi-dumper
processa os arquivos de origem compilados para construir a biblioteca VNDK (os próprios arquivos de origem da biblioteca, bem como os arquivos de origem herdados por meio de dependências transitivas estáticas), para produzir arquivos.sdump
que correspondem a cada origem.Figura 1. Criando os arquivos .sdump
-
header-abi-linker
então processa os arquivos.sdump
(usando um script de versão fornecido a ele ou o arquivo.so
correspondente à biblioteca compartilhada) para produzir um arquivo.lsdump
que registra todas as informações ABI correspondentes à biblioteca compartilhada.Figura 2. Criando o arquivo .lsdump
-
header-abi-diff
compara o arquivo.lsdump
com um arquivo.lsdump
de referência para produzir um relatório diff que descreve as diferenças nas ABIs das duas bibliotecas.Figura 3. Criando o relatório de diferenças
header-abi-dumper
A ferramenta header-abi-dumper
analisa um arquivo de origem C/C++ e despeja a ABI inferida desse arquivo de origem em um arquivo intermediário. O sistema de compilação executa header-abi-dumper
em todos os arquivos de origem compilados enquanto também cria uma biblioteca que inclui os arquivos de origem de dependências transitivas.
entradas |
|
---|---|
Saída | Um arquivo que descreve a ABI do arquivo de origem (por exemplo, foo.sdump representa a ABI de foo.cpp ). |
Atualmente, os arquivos .sdump
estão no formato JSON, que não tem garantia de estabilidade em versões futuras. Como tal, a formatação do arquivo .sdump
deve ser considerada um detalhe de implementação do sistema de construção.
Por exemplo, libfoo.so
tem o seguinte arquivo fonte foo.cpp
:
#include <stdio.h> #include <foo_exported.h> bool Foo(int id, bar_t *bar_ptr) { if (id > 0 && bar_ptr->mfoo.m1 > 0) { return true; } return false; }
Você pode usar header-abi-dumper
para gerar um arquivo .sdump
intermediário que representa a ABI apresentada pelo arquivo de origem usando:
$ header-abi-dumper foo.cpp -I exported -o foo.sdump -- -I exported -x c++
Este comando informa ao header-abi-dumper
para analisar foo.cpp
com os sinalizadores do compilador a seguir --
e emitir as informações ABI que são exportadas pelos cabeçalhos públicos no diretório exported
. O seguinte é foo.sdump
gerado por header-abi-dumper
:
{ "array_types" : [], "builtin_types" : [ { "alignment" : 4, "is_integral" : true, "linker_set_key" : "_ZTIi", "name" : "int", "referenced_type" : "_ZTIi", "self_type" : "_ZTIi", "size" : 4 } ], "elf_functions" : [], "elf_objects" : [], "enum_types" : [], "function_types" : [], "functions" : [ { "function_name" : "FooBad", "linker_set_key" : "_Z6FooBadiP3foo", "parameters" : [ { "referenced_type" : "_ZTIi" }, { "referenced_type" : "_ZTIP3foo" } ], "return_type" : "_ZTI3bar", "source_file" : "exported/foo_exported.h" } ], "global_vars" : [], "lvalue_reference_types" : [], "pointer_types" : [ { "alignment" : 8, "linker_set_key" : "_ZTIP11foo_private", "name" : "foo_private *", "referenced_type" : "_ZTI11foo_private", "self_type" : "_ZTIP11foo_private", "size" : 8, "source_file" : "exported/foo_exported.h" }, { "alignment" : 8, "linker_set_key" : "_ZTIP3foo", "name" : "foo *", "referenced_type" : "_ZTI3foo", "self_type" : "_ZTIP3foo", "size" : 8, "source_file" : "exported/foo_exported.h" }, { "alignment" : 8, "linker_set_key" : "_ZTIPi", "name" : "int *", "referenced_type" : "_ZTIi", "self_type" : "_ZTIPi", "size" : 8, "source_file" : "exported/foo_exported.h" } ], "qualified_types" : [], "record_types" : [ { "alignment" : 8, "fields" : [ { "field_name" : "mfoo", "referenced_type" : "_ZTI3foo" } ], "linker_set_key" : "_ZTI3bar", "name" : "bar", "referenced_type" : "_ZTI3bar", "self_type" : "_ZTI3bar", "size" : 24, "source_file" : "exported/foo_exported.h" }, { "alignment" : 8, "fields" : [ { "field_name" : "m1", "referenced_type" : "_ZTIi" }, { "field_name" : "m2", "field_offset" : 64, "referenced_type" : "_ZTIPi" }, { "field_name" : "mPfoo", "field_offset" : 128, "referenced_type" : "_ZTIP11foo_private" } ], "linker_set_key" : "_ZTI3foo", "name" : "foo", "referenced_type" : "_ZTI3foo", "self_type" : "_ZTI3foo", "size" : 24, "source_file" : "exported/foo_exported.h" } ], "rvalue_reference_types" : [] }
foo.sdump
contém informações ABI exportadas pelo arquivo de origem foo.cpp
e os cabeçalhos públicos, por exemplo,
-
record_types
. Consulte estruturas, uniões ou classes definidas nos cabeçalhos públicos. Cada tipo de registro possui informações sobre seus campos, seu tamanho, especificador de acesso, o arquivo de cabeçalho no qual está definido e outros atributos. -
pointer_types
. Consulte os tipos de ponteiro referenciados direta/indiretamente pelos registros/funções exportados nos cabeçalhos públicos, juntamente com o tipo para o qual o ponteiro aponta (através do camporeferenced_type
emtype_info
). Informações semelhantes são registradas no arquivo.sdump
para tipos qualificados, tipos C/C++ integrados, tipos de matriz e tipos de referência lvalue e rvalue. Tal informação permite a diferenciação recursiva. -
functions
. Representa funções exportadas por cabeçalhos públicos. Eles também têm informações sobre o nome desconfigurado da função, o tipo de retorno, os tipos de parâmetros, o especificador de acesso e outros atributos.
header-abi-linker
A ferramenta header-abi-linker
usa os arquivos intermediários produzidos pelo header-abi-dumper
como entrada e vincula esses arquivos:
entradas |
|
---|---|
Saída | Um arquivo que descreve a ABI de uma biblioteca compartilhada (por exemplo, libfoo.so.lsdump representa a ABI de libfoo ). |
A ferramenta mescla os gráficos de tipo em todos os arquivos intermediários fornecidos a ela, levando em conta diferenças de uma definição (tipos definidos pelo usuário em diferentes unidades de tradução com o mesmo nome totalmente qualificado, podem ser semanticamente diferentes) entre as unidades de tradução. A ferramenta então analisa um script de versão ou a tabela .dynsym
da biblioteca compartilhada (arquivo .so
) para fazer uma lista dos símbolos exportados.
Por exemplo, libfoo
consiste em foo.cpp
e bar.cpp
. header-abi-linker
pode ser invocado para criar o despejo ABI vinculado completo de libfoo
da seguinte forma:
header-abi-linker -I exported foo.sdump bar.sdump \ -o libfoo.so.lsdump \ -so libfoo.so \ -arch arm64 -api current
Exemplo de saída de comando em libfoo.so.lsdump
:
{ "array_types" : [], "builtin_types" : [ { "alignment" : 1, "is_integral" : true, "is_unsigned" : true, "linker_set_key" : "_ZTIb", "name" : "bool", "referenced_type" : "_ZTIb", "self_type" : "_ZTIb", "size" : 1 }, { "alignment" : 4, "is_integral" : true, "linker_set_key" : "_ZTIi", "name" : "int", "referenced_type" : "_ZTIi", "self_type" : "_ZTIi", "size" : 4 } ], "elf_functions" : [ { "name" : "_Z3FooiP3bar" }, { "name" : "_Z6FooBadiP3foo" } ], "elf_objects" : [], "enum_types" : [], "function_types" : [], "functions" : [ { "function_name" : "Foo", "linker_set_key" : "_Z3FooiP3bar", "parameters" : [ { "referenced_type" : "_ZTIi" }, { "referenced_type" : "_ZTIP3bar" } ], "return_type" : "_ZTIb", "source_file" : "exported/foo_exported.h" }, { "function_name" : "FooBad", "linker_set_key" : "_Z6FooBadiP3foo", "parameters" : [ { "referenced_type" : "_ZTIi" }, { "referenced_type" : "_ZTIP3foo" } ], "return_type" : "_ZTI3bar", "source_file" : "exported/foo_exported.h" } ], "global_vars" : [], "lvalue_reference_types" : [], "pointer_types" : [ { "alignment" : 8, "linker_set_key" : "_ZTIP11foo_private", "name" : "foo_private *", "referenced_type" : "_ZTI11foo_private", "self_type" : "_ZTIP11foo_private", "size" : 8, "source_file" : "exported/foo_exported.h" }, { "alignment" : 8, "linker_set_key" : "_ZTIP3bar", "name" : "bar *", "referenced_type" : "_ZTI3bar", "self_type" : "_ZTIP3bar", "size" : 8, "source_file" : "exported/foo_exported.h" }, { "alignment" : 8, "linker_set_key" : "_ZTIP3foo", "name" : "foo *", "referenced_type" : "_ZTI3foo", "self_type" : "_ZTIP3foo", "size" : 8, "source_file" : "exported/foo_exported.h" }, { "alignment" : 8, "linker_set_key" : "_ZTIPi", "name" : "int *", "referenced_type" : "_ZTIi", "self_type" : "_ZTIPi", "size" : 8, "source_file" : "exported/foo_exported.h" } ], "qualified_types" : [], "record_types" : [ { "alignment" : 8, "fields" : [ { "field_name" : "mfoo", "referenced_type" : "_ZTI3foo" } ], "linker_set_key" : "_ZTI3bar", "name" : "bar", "referenced_type" : "_ZTI3bar", "self_type" : "_ZTI3bar", "size" : 24, "source_file" : "exported/foo_exported.h" }, { "alignment" : 8, "fields" : [ { "field_name" : "m1", "referenced_type" : "_ZTIi" }, { "field_name" : "m2", "field_offset" : 64, "referenced_type" : "_ZTIPi" }, { "field_name" : "mPfoo", "field_offset" : 128, "referenced_type" : "_ZTIP11foo_private" } ], "linker_set_key" : "_ZTI3foo", "name" : "foo", "referenced_type" : "_ZTI3foo", "self_type" : "_ZTI3foo", "size" : 24, "source_file" : "exported/foo_exported.h" } ], "rvalue_reference_types" : [] }
A ferramenta header-abi-linker
:
- Vincula os arquivos
.sdump
fornecidos a ele (foo.sdump
ebar.sdump
), filtrando as informações ABI não presentes nos cabeçalhos residentes no diretório:exported
. - Analisa
libfoo.so
e coleta informações sobre os símbolos exportados pela biblioteca por meio de sua tabela.dynsym
. - Adiciona
_Z3FooiP3bar
e_Z6FooBadiP3foo
.
libfoo.so.lsdump
é o dump ABI gerado final de libfoo.so
.
cabeçalho-abi-diff
A ferramenta header-abi-diff
compara dois arquivos .lsdump
que representam a ABI de duas bibliotecas e produz um relatório diff informando as diferenças entre as duas ABIs.
entradas |
|
---|---|
Saída | Um relatório de comparação informando as diferenças nas ABIs oferecidas pelas duas bibliotecas compartilhadas. |
O arquivo diff ABI está no formato de texto protobuf . O formato está sujeito a alterações em versões futuras.
Por exemplo, você tem duas versões de libfoo
: libfoo_old.so
e libfoo_new.so
. Em libfoo_new.so
, em bar_t
, você muda o tipo de mfoo
de foo_t
para foo_t *
. Como bar_t
é um tipo alcançável, isso deve ser sinalizado como uma alteração de quebra de ABI por header-abi-diff
.
Para executar header-abi-diff
:
header-abi-diff -old libfoo_old.so.lsdump \ -new libfoo_new.so.lsdump \ -arch arm64 \ -o libfoo.so.abidiff \ -lib libfoo
Exemplo de saída de comando em libfoo.so.abidiff
:
lib_name: "libfoo" arch: "arm64" record_type_diffs { name: "bar" type_stack: "Foo-> bar *->bar " type_info_diff { old_type_info { size: 24 alignment: 8 } new_type_info { size: 8 alignment: 8 } } fields_diff { old_field { referenced_type: "foo" field_offset: 0 field_name: "mfoo" access: public_access } new_field { referenced_type: "foo *" field_offset: 0 field_name: "mfoo" access: public_access } } }
O libfoo.so.abidiff
contém um relatório de todas as alterações de quebra de ABI em libfoo
. A mensagem record_type_diffs
indica que um registro foi alterado e lista as alterações incompatíveis, que incluem:
- O tamanho do registro mudando de
24
bytes para8
bytes. - O tipo de campo de
mfoo
mudando defoo
parafoo *
(todos os typedefs são removidos).
O campo type_stack
indica como header-abi-diff
atingiu o tipo que mudou ( bar
). Este campo pode ser interpretado como Foo
é uma função exportada que recebe como parâmetro bar *
, que aponta para bar
, que foi exportado e alterado.
Aplicação de ABI/API
Para impor a ABI/API das bibliotecas compartilhadas VNDK, as referências ABI devem ser verificadas em ${ANDROID_BUILD_TOP}/prebuilts/abi-dumps/vndk/
. Para criar essas referências, execute o seguinte comando:
${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py
Depois de criar as referências, qualquer alteração feita no código-fonte que resulte em uma alteração ABI/API incompatível em uma biblioteca VNDK agora resulta em um erro de compilação.
Para atualizar as referências ABI para bibliotecas específicas, execute o seguinte comando:
${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l <lib1> -l <lib2>
Por exemplo, para atualizar as referências ABI libbinder
, execute:
${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l libbinder