Estabilidad del ITB

La estabilidad de la interfaz binaria de la aplicación (ABI) es un requisito previo de las actualizaciones solo del marco porque los módulos del proveedor pueden depender de las bibliotecas compartidas del kit de desarrollo nativo del proveedor (VNDK) que residen en la partición del sistema. Dentro de una versión de Android, las bibliotecas compartidas de VNDK recién creadas deben ser compatibles con ABI con las bibliotecas compartidas de VNDK lanzadas anteriormente para que los módulos del proveedor puedan trabajar con esas bibliotecas sin volver a compilar y sin errores de tiempo de ejecución. Entre las versiones de Android, las bibliotecas de VNDK se pueden cambiar y no hay garantías de ABI.

Para ayudar a garantizar la compatibilidad con ABI, Android 9 incluye un verificador de encabezado ABI, como se describe en las siguientes secciones.

Acerca del cumplimiento de VNDK y ABI

El VNDK es un conjunto restrictivo de bibliotecas a las que se pueden vincular los módulos de los proveedores y que permiten actualizaciones solo del marco. El cumplimiento de ABI se refiere a la capacidad de una versión más nueva de una biblioteca compartida para funcionar como se espera con un módulo que está vinculado dinámicamente a ella (es decir, funciona como lo haría una versión anterior de la biblioteca).

Acerca de los símbolos exportados

Un símbolo exportado (también conocido como símbolo global ) se refiere a un símbolo que cumple con todo lo siguiente:

• Exportado por los encabezados públicos de una biblioteca compartida.
• Aparece en la tabla .dynsym del archivo .so correspondiente a la biblioteca compartida.
• Tiene enlace DÉBIL o GLOBAL.
• La visibilidad es PREDETERMINADA o PROTEGIDA.
• El índice de la sección no está SIN DEFINIR.
• El tipo es FUNC u OBJECT.

Los encabezados públicos de una biblioteca compartida se definen como los encabezados disponibles para otras bibliotecas/binarios a través de los export_include_dirs , export_header_lib_headers , export_static_lib_headers , export_shared_lib_headers y export_generated_headers en las definiciones de Android.bp del módulo correspondiente a la biblioteca compartida.

Acerca de los tipos accesibles

Un tipo accesible es cualquier tipo integrado de C/C++ o definido por el usuario al que se puede acceder directa o indirectamente a través de un símbolo exportado Y exportado a través de encabezados públicos. Por ejemplo, libfoo.so tiene la función Foo , que es un símbolo exportado que se encuentra en la tabla .dynsym . La biblioteca libfoo.so incluye lo siguiente:

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 : [
    "include"
  ],
}

En cuanto a Foo , los tipos accesibles directos/indirectos incluyen:

Se puede dar una explicación similar para los tipos a los que se puede acceder a través de especificadores de clase base y también de parámetros de plantilla.

Garantizar el cumplimiento de ABI

Se debe garantizar el cumplimiento de ABI para las bibliotecas marcadas vendor_available: true y vndk.enabled: true en los archivos Android.bp correspondientes. Por ejemplo:

cc_library {
    name: "libvndk_example",
    vendor_available: true,
    vndk: {
        enabled: true,
    }
}

Para los tipos de datos accesibles directa o indirectamente por una función exportada, los siguientes cambios en una biblioteca se clasifican como ruptura de ABI:

* Las funciones de miembros públicas y privadas no deben cambiarse ni eliminarse porque las funciones en línea públicas pueden hacer referencia a funciones de miembros privadas. Las referencias de símbolos a funciones de miembros privados se pueden mantener en binarios de llamantes. Cambiar o eliminar funciones de miembros privados de bibliotecas compartidas puede generar archivos binarios incompatibles con versiones anteriores.

** Las compensaciones para miembros de datos públicos o privados no deben cambiarse porque las funciones en línea pueden hacer referencia a estos miembros de datos en el cuerpo de su función. Cambiar los desplazamientos de los miembros de datos puede generar archivos binarios incompatibles con versiones anteriores.

*** Si bien estos no cambian el diseño de la memoria del tipo, existen diferencias semánticas que podrían hacer que las bibliotecas no funcionen como se esperaba.

Uso de las herramientas de cumplimiento de ABI

Cuando se compila una biblioteca VNDK, la ABI de la biblioteca se compara con la referencia ABI correspondiente para la versión del VNDK que se está compilando. Los volcados ABI de referencia se encuentran en:

${ANDROID_BUILD_TOP}/prebuilts/abi-dumps/(v)ndk/<${PLATFORM_VNDK_VERSION}>/<BINDER_BITNESS>/<ARCH_ARCH-VARIANT>/source-based

Por ejemplo, al libfoo para el nivel de API 27 del VNDK, el ABI inferido de libfoo se compara con su referencia en:

${ANDROID_BUILD_TOP}/prebuilts/abi-dumps/(v)ndk/27/64/<ARCH_ARCH-VARIANT>/source-based/libfoo.so.lsdump

Error de rotura de ABI

En roturas de ABI, el registro de compilación muestra advertencias con el tipo de advertencia y una ruta al informe abi-diff. Por ejemplo, si la ABI de libbinder tiene un cambio incompatible, el sistema de compilación arroja un error con un mensaje similar al siguiente:

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

Compilación de verificaciones ABI de la biblioteca VNDK

Cuando se crea una biblioteca VNDK:

1. header-abi-dumper procesa los archivos fuente compilados para crear la biblioteca VNDK (los archivos fuente propios de la biblioteca, así como los archivos fuente heredados a través de dependencias transitivas estáticas), para producir archivos .sdump que correspondan a cada fuente.
   
2. header-abi-linker luego procesa los archivos .sdump (usando un script de versión proporcionado o el archivo .so correspondiente a la biblioteca compartida) para producir un archivo .lsdump que registra toda la información ABI correspondiente a la biblioteca compartida.
   
3. header-abi-diff compara el archivo .lsdump con un archivo .lsdump de referencia para generar un informe de diferencias que describe las diferencias en los ABI de las dos bibliotecas.
   

encabezado-abi-dumper

La herramienta header-abi-dumper analiza un archivo fuente C/C++ y vuelca el ABI inferido de ese archivo fuente en un archivo intermedio. El sistema de compilación ejecuta header-abi-dumper en todos los archivos de origen compilados al mismo tiempo que crea una biblioteca que incluye los archivos de origen de las dependencias transitivas.

Actualmente, los archivos .sdump tienen el formato Protobuf TextFormatted , que no garantiza que sea estable en versiones futuras. Como tal, el formato de archivo .sdump debe considerarse un detalle de implementación del sistema de compilación.

Por ejemplo, libfoo.so tiene el siguiente archivo fuente 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;
}

Puede usar header-abi-dumper para generar un archivo .sdump intermedio que represente el ABI presentado por el archivo fuente usando:

$ header-abi-dumper foo.cpp -I exported -o foo.sdump -- -x c++

Este comando le dice header-abi-dumper que foo.cpp y emita la información ABI que se expone en los encabezados públicos en el directorio exported . Este es un extracto (no una representación completa) de foo.sdump generado por header-abi-dumper :

record_types {
  type_info {
    name: "foo"
    size: 12
    alignment: 4
    referenced_type: "type-1"
    source_file: "foo/include/foo_exported.h"
    linker_set_key: "foo"
    self_type: "type-1"
  }
  fields {
    referenced_type: "type-2"
    field_offset: 0
    field_name: "m1"
    access: public_access
  }
  fields {
    referenced_type: "type-3"
    field_offset: 32
    field_name: "m2"
    access: public_access
  }
  fields {
    referenced_type: "type-5"
    field_offset: 64
    field_name: "mPfoo"
    access: public_access
  }
  access: public_access
  record_kind: struct_kind
  tag_info {
    unique_id: "_ZTS3foo"
  }
}
record_types {
  type_info {
    name: "bar"
    size: 12
    alignment: 4
    referenced_type: "type-6"
…
pointer_types {
  type_info {
    name: "bar *"
    size: 4
    alignment: 4
    referenced_type: "type-6"
    source_file: "foo/include/foo_exported.h"
    linker_set_key: "bar *"
    self_type: "type-8"
  }
}
builtin_types {
  type_info {
    name: "int"
    size: 4
    alignment: 4
    referenced_type: "type-2"
    source_file: ""
    linker_set_key: "int"
    self_type: "type-2"
  }
  is_unsigned: false
  is_integral: true
}
functions {
  return_type: "type-7"
  function_name: "Foo"
  source_file: "foo/include/foo_exported.h"
  parameters {
    referenced_type: "type-2"
    default_arg: false
  }
  parameters {
    referenced_type: "type-8"
    default_arg: false
  }
  linker_set_key: "_Z3FooiP3bar"
  access: public_access
}

foo.sdump contiene información ABI expuesta por el archivo fuente foo.cpp , por ejemplo:

• record_types . Haga referencia a estructuras, uniones o clases expuestas por los encabezados públicos. Cada tipo de registro tiene información sobre sus campos, su tamaño, especificador de acceso, el archivo de encabezado en el que se expuso, etc.
• pointer_types . Haga referencia a los tipos de puntero referenciados directa o indirectamente por registros o funciones expuestos por encabezados públicos, junto con el tipo al que apunta el puntero (a través del campo referenced_type en type_info ). Se registra información similar en el archivo .sdump para tipos calificados, tipos integrados de C/C++, tipos de matriz y tipos de referencia lvalue y rvalue (dicha información de registro sobre tipos permite la diferenciación recursiva).
• functions Representa funciones expuestas por encabezados públicos. También tienen información sobre el nombre alterado de la función, el tipo de devolución, los tipos de parámetros, el especificador de acceso, etc.

encabezado-abi-enlazador

La herramienta header-abi-linker toma los archivos intermedios producidos por header-abi-dumper como entrada y luego vincula esos archivos:

La herramienta combina los gráficos de tipos en todos los archivos intermedios que se le proporcionan, teniendo en cuenta las diferencias de una definición (los tipos definidos por el usuario en diferentes unidades de traducción con el mismo nombre completo, pueden ser semánticamente diferentes) entre las unidades de traducción. Luego, la herramienta analiza un script de versión o la tabla .dynsym de la biblioteca compartida (archivo .so ) para hacer una lista de los símbolos exportados.

Por ejemplo, cuando libfoo agrega el archivo bar.cpp (que expone una bar de función C) a su compilación, se puede invocar header-abi-linker para crear el volcado ABI vinculado completo de libfoo de la siguiente manera:

header-abi-linker -I exported foo.sdump bar.sdump \
                  -o libfoo.so.lsdump \
                  -so libfoo.so \
                  -arch arm64 -api current

Ejemplo de salida de comando en libfoo.so.lsdump :

record_types {
  type_info {
    name: "foo"
    size: 24
    alignment: 8
    referenced_type: "type-1"
    source_file: "foo/include/foo_exported.h"
    linker_set_key: "foo"
    self_type: "type-1"
  }
  fields {
    referenced_type: "type-2"
    field_offset: 0
    field_name: "m1"
    access: public_access
  }
  fields {
    referenced_type: "type-3"
    field_offset: 64
    field_name: "m2"
    access: public_access
  }
  fields {
    referenced_type: "type-4"
    field_offset: 128
    field_name: "mPfoo"
    access: public_access
  }
  access: public_access
  record_kind: struct_kind
  tag_info {
    unique_id: "_ZTS3foo"
  }
}
record_types {
  type_info {
    name: "bar"
    size: 24
    alignment: 8
...
builtin_types {
  type_info {
    name: "void"
    size: 0
    alignment: 0
    referenced_type: "type-6"
    source_file: ""
    linker_set_key: "void"
    self_type: "type-6"
  }
  is_unsigned: false
  is_integral: false
}
functions {
  return_type: "type-19"
  function_name: "Foo"
  source_file: "foo/include/foo_exported.h"
  parameters {
    referenced_type: "type-2"
    default_arg: false
  }
  parameters {
    referenced_type: "type-20"
    default_arg: false
  }
  linker_set_key: "_Z3FooiP3bar"
  access: public_access
}
functions {
  return_type: "type-6"
  function_name: "FooBad"
  source_file: "foo/include/foo_exported_bad.h"
  parameters {
    referenced_type: "type-2"
    default_arg: false
  }
parameters {
    referenced_type: "type-7"
    default_arg: false
  }
  linker_set_key: "_Z6FooBadiP3foo"
  access: public_access
}
elf_functions {
  name: "_Z3FooiP3bar"
}
elf_functions {
  name: "_Z6FooBadiP3foo"
}

La herramienta header-abi-linker :

• Vincula los archivos .sdump que se le proporcionan ( foo.sdump y bar.sdump ), filtrando la información ABI que no está presente en los encabezados que residen en el directorio: exported .
• Analiza libfoo.so y recopila información sobre los símbolos exportados por la biblioteca a través de su tabla .dynsym .
• Agrega _Z3FooiP3bar y Bar .

libfoo.so.lsdump es el volcado ABI final generado de libfoo.so .

encabezado-abi-diff

La herramienta header-abi-diff compara dos archivos .lsdump que representan el ABI de dos bibliotecas y genera un informe de diferencias que indica las diferencias entre los dos ABI.

El archivo ABI diff está diseñado para ser lo más detallado y legible posible. El formato está sujeto a cambios en versiones futuras. Por ejemplo, tiene dos versiones de libfoo : libfoo_old.so y libfoo_new.so . En libfoo_new.so , en bar_t , cambia el tipo de mfoo de foo_t a foo_t * . Dado que bar_t es un tipo accesible directamente, debe marcarse como un cambio de ruptura de ABI por header-abi-diff .

Para ejecutar header-abi-diff :

header-abi-diff -old libfoo_old.so.lsdump \
                -new libfoo_new.so.lsdump \
                -arch arm64 \
                -o libfoo.so.abidiff \
                -lib libfoo

Ejemplo de salida de comando en 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
    }
  }
}

El libfoo.so.abidiff contiene un informe de todos los cambios importantes de ABI en libfoo . El mensaje record_type_diffs indica que un registro ha cambiado y enumera los cambios incompatibles, que incluyen:

• El tamaño del registro cambia de 24 bytes a 8 bytes.
• El tipo de campo de mfoo cambia de foo a foo * (todas las definiciones de tipo se eliminan).

El campo type_stack indica cómo header-abi-diff alcanzó el tipo que cambió ( bar ). Este campo puede interpretarse como que Foo es una función exportada que toma bar * como parámetro, que apunta a bar , que fue exportado y modificado.

Aplicación de ABI/API

Para hacer cumplir la ABI/API de las bibliotecas compartidas VNDK y LLNDK, las referencias de ABI deben verificarse en ${ANDROID_BUILD_TOP}/prebuilts/abi-dumps/(v)ndk/ . Para crear estas referencias, ejecute el siguiente comando:

${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py

Después de crear las referencias, cualquier cambio realizado en el código fuente que resulte en un cambio de ABI/API incompatible en una biblioteca VNDK o LLNDK ahora genera un error de compilación.

Para actualizar las referencias de ABI para bibliotecas principales de VNDK específicas, ejecute el siguiente comando:

${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l <lib1> -l <lib2>

Por ejemplo, para actualizar las referencias ABI de libbinder , ejecute:

${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l libbinder

Para actualizar las referencias de ABI para bibliotecas LLNDK específicas, ejecute el siguiente comando:

${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l <lib1> -l <lib2> --llndk

Por ejemplo, para actualizar las referencias libm ABI, ejecute:

${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l libm --llndk