Compila y verifica

Puedes usar el compilador de árbol de dispositivos (DTC) para compilar los archivos fuente del árbol de dispositivos (DTS). Sin embargo, antes de aplicar el árbol de dispositivos de superposición (DT) en el DT principal de destino, también debes verificar el resultado simulando el comportamiento de la superposición del árbol de dispositivos (DTO).

Compila con DTC

Cuando usas dtc para compilar .dts, debes agregar la opción -@ para agregar un nodo __symbols__ en el .dtbo resultante. El nodo __symbols__ contiene una lista de todos los nodos marcados con una etiqueta, que la biblioteca de DTO puede usar para referencias.

Comando de muestra para compilar la DT principal .dts:

dtc -@ -O dtb -o my_main_dt.dtb my_main_dt.dts

Comando de muestra para compilar la superposición DT .dts:

dtc -@ -O dtb -o my_overlay_dt.dtbo my_overlay_dt.dts

Verifica los resultados de DTO en el host

La verificación puede ayudarte a identificar errores que podrían ocurrir cuando colocas el DT de superposición en el DT principal. Antes de actualizar el destino, puedes verificar el resultado de superponer DT en el host simulando el comportamiento de DTO con /include/ en .dts.

Figura 1: Usa la sintaxis /include/ para simular DTO en el host.

  1. Crea una copia de la superposición .dts. En el texto, quita el encabezado de la primera línea. Por ejemplo: 
    /dts-v1/;
/plugin/;
    Guarda el archivo como my_overlay_dt_wo_header.dts (o el nombre de archivo que desees).
  2. Crea una copia del .dts principal. En la copia, después de la última línea, agrega la sintaxis de inclusión del archivo que creaste en el paso 1. Por ejemplo: 
    /include/ "my_overlay_dt_wo_header.dts"
    Guarda el archivo como my_main_dt_with_include.dts (o cualquier nombre de archivo que desees).
  3. Usa dtc para compilar my_main_dt_with_include.dts y obtener el DT combinado, que debería ser el mismo resultado que DTO. Por ejemplo: 
    dtc -@ -O dtb -o my_merged_dt.dtb my_main_dt_with_include.dts
  4. Usa dtc para volcar my_merged_dt.dto. 
    dtc -O dts -o my_merged_dt.dts my_merged_dt.dtb

Verifica el DTO en Android 9

Android 9 requiere una partición de superposición de BLOB del árbol de dispositivos (DTBO). Para agregar nodos o realizar cambios en las propiedades del DT de SoC, el bootloader debe superponer dinámicamente un DT específico para dispositivos sobre el DT de SoC.

Indica las superposiciones aplicadas

Para permitir que el Paquete de pruebas del proveedor (VTS) evalúe la exactitud de la app superpuesta, los proveedores deben agregar un nuevo parámetro de línea de comandos del kernel androidboot.dtbo_idx que indique las superposiciones seleccionadas de la partición DTBO. En Android 12 con la versión de kernel 5.10 o posterior, este parámetro pasa por bootconfig. Por ejemplo, el parámetro androidboot.dtbo_idx=x,y,z informa x, y y z como los índices basados en cero de los DTO de la partición de DTBO aplicados (en ese orden) por el bootloader al DT base.

Las superposiciones se pueden aplicar a nodos de la DT principal o agregar nodos nuevos, pero no pueden hacer referencia a un nodo agregado en una superposición anterior. Esta restricción es necesaria porque la app de superposición no combina la tabla de símbolos de superposición con la tabla de símbolos de DT principal (no combinar evita conflictos en los nombres de símbolos y complicaciones de dependencias entre superposiciones).

Ejemplo: superposiciones no válidas

En este ejemplo, overlay_2.dts hace referencia al nodo e , que agregó overlay_1.dts. Después de aplicar overlay_1 a la DT principal, si se intenta aplicar overlay_2 a la DT resultante, la app de superposición falla con un error que indica que el símbolo e no está presente en la tabla de símbolos de la DT base.

main.dts overlay_1.dts superposición_2.dts 
[main.dts]

/dts-v1/;

/ {
  a: a {};
  b: b {};
  c: c {};
};

[overlay_1.dts]

/dts-v1/;
/plugin/;

&b { ref1 =  <&a>;
    e: e {
        prop = <0x0a>;
        phandle = <0x04>;
    };
};

[overlay_2.dts]

/dts-v1/;
/plugin/;

/* invalid! */
&e {
    prop = <0x0b>;
};

Ejemplo: Superposiciones válidas

En este ejemplo, overlay_2.dts solo hace referencia al nodo b del DTS principal. Cuando se aplica overlay_1 a la DT base y, luego, la app de overlay_2 lo sigue, el valor de la propiedad prop del nodo e (configurado por overlay_1.dts) se reemplaza por el valor establecido por overlay_2.dts.

main.dts overlay_1.dts overlay_2.dts 
[final.dts]

/dts-v1/;

/ {
  a: a {};
  b: b {};
  c: c {};
};

[overlay_1.dts]

/dts-v1/;
/plugin/;


&b { ref1 =  <&a>;
     e {
          prop = <0x0c>;
      };
};

[overlay_2.dts]

/dts-v1/;
/plugin/;

/* valid */
&b { ref1 =  <&c>;
     e {
          prop = <0x0d>;
      };
};

Implementa la partición de DTBO

Para implementar la partición de DTBO requerida, asegúrate de que el bootloader pueda hacer lo siguiente:

  1. Identifica la placa en la que se ejecuta y selecciona las superposiciones correspondientes que se aplicarán.
  2. Agrega el parámetro androidboot.dtbo_idx a la línea de comandos del kernel.
    • El parámetro debe indicar los índices basados en cero de los DTO de la imagen de partición de DTBO que se aplicó a la DT base (en el mismo orden).
    • Los índices deben hacer referencia a la posición de la superposición en la partición de DTBO.

Para obtener detalles sobre la estructura de la partición de DTBO, consulta Superposiciones del árbol de dispositivos.

Valida la partición de DTBO

Puedes usar VTS para verificar lo siguiente:

  • Existencia del parámetro de línea de comandos del kernel androidboot.dtbo_idx (verificando que Init haya configurado automáticamente la propiedad del sistema ro.boot.dtbo_idx correspondiente)
  • Validez de la propiedad del sistema ro.boot.dtbo_idx (comprobando que la propiedad especifique al menos un índice de imagen de DTBO válido).
  • Validez de la partición de DTBO (también verifica las superposiciones en la partición de DTBO que se aplican al DT base).
  • Los nodos adicionales o los cambios de propiedad en el DT resultante se presentan al kernel de Linux.

Por ejemplo, en las siguientes superposiciones y el DT final, agregar androidboot.dtbo_idx=5,3 a la línea de comandos del kernel pasa la validación, pero agregar androidboot.dtbo_idx=3,5 a la línea de comandos del kernel no pasa la validación.

Superposición de DT en el índice 3 Superposición de DT en el índice 5 
[overlay_1.dts]

/dts-v1/;
/plugin/;

&c { prop = <0xfe>; };

[overlay_2.dts]

/dts-v1/;
/plugin/;

&c { prop = <0xff>; };
DT final 

/dts-v1/;
/ {

	a {
		phandle = <0x1>;
	};

	b {
		phandle = <0x2>;
	};

	c {
		phandle = <0x3>;
		prop = <0xfe>;
	};

	__symbols__ {
		a = "/a";
		b = "/b";
		c = "/c";
	};
};