Estabilidade ABI

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:

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;

cc_library {
  name : libfoo,
  vendor_available: true,
  vndk {
    enabled : true,
  }
  srcs : ["src/*.cpp"],
  export_include_dirs : [
    "exported"
  ],
}

Olhando para Foo , os tipos alcançáveis ​​direto/indireto incluem:

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:

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

1. 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.
   
2. 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.
   
3. 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.
   

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.

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 campo referenced_type em type_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:

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 e bar.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.

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 para 8 bytes.
• O tipo de campo de mfoo mudando de foo para foo * (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