Compilar e verificar

Você pode usar o compilador da árvore de dispositivos (DTC, na sigla em inglês) para compilar os arquivos de origem da árvore de dispositivos (DTS). No entanto, antes de aplicar a árvore de dispositivos de sobreposição (DT, na sigla em inglês) na DT principal de destino, você também precisa verificar o resultado simulando o comportamento da sobreposição da árvore de dispositivos (DTO).

Compilar com DTC

Ao usar dtc para compilar .dts, é necessário adicionar a opção -@ para adicionar um nó __symbols__ no .dtbo resultante. O nó __symbols__ contém uma lista de todos os nós marcados com um rótulo, que a biblioteca DTO pode usar para referências.

Exemplo de comando para criar o .dts principal do DT:

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

Exemplo de comando para criar a sobreposição da DT .dts:

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

Verificar os resultados da DTO no host

A verificação pode ajudar a identificar erros que podem ocorrer ao colocar o DT de sobreposição no DT principal. Antes de atualizar o destino, é possível verificar o resultado da sobreposição de DT no host simulando o comportamento de DTO usando /include/ em .dts.

Figura 1. Use a sintaxe /include/ para simular DTO no host.

  1. Crie uma cópia da sobreposição .dts. Na cópia, remova o cabeçalho da primeira linha. Exemplo: 
    /dts-v1/;
/plugin/;
    Salve o arquivo como my_overlay_dt_wo_header.dts (ou qualquer nome de arquivo que você quiser).
  2. Crie uma cópia do .dts principal. Na cópia, depois da última linha, anexe a sintaxe de inclusão do arquivo que você criou na etapa 1. Por exemplo: 
    /include/ "my_overlay_dt_wo_header.dts"
    Salve o arquivo como my_main_dt_with_include.dts (ou qualquer nome de arquivo que você quiser).
  3. Use dtc para compilar my_main_dt_with_include.dts e receber o DT mesclado, que deve ser o mesmo resultado do DTO. Por exemplo: 
    dtc -@ -O dtb -o my_merged_dt.dtb my_main_dt_with_include.dts
  4. Use dtc para fazer o dump de my_merged_dt.dto. 
    dtc -O dts -o my_merged_dt.dts my_merged_dt.dtb

Verificar DTO no Android 9

O Android 9 exige uma partição de sobreposição de blob da árvore de dispositivos (DTBO, na sigla em inglês). Para adicionar nós ou fazer alterações nas propriedades no SoC DT, o carregador de inicialização precisa sobrepor dinamicamente um DT específico do dispositivo sobre o SoC DT.

Indicar sobreposições aplicadas

Para permitir que o conjunto de testes do fornecedor (VTS, na sigla em inglês) avalie a correção do app de sobreposição, os fornecedores precisam adicionar um novo parâmetro de linha de comando do kernel androidboot.dtbo_idx que indique as sobreposições selecionadas na partição DTBO. No Android 12 com a versão 5.10 ou mais recente do kernel, esse parâmetro é transmitido pelo bootconfig. Por exemplo, o parâmetro androidboot.dtbo_idx=x,y,z relata x, y e z como os índices baseados em zero das DTOs da partição de DTBO aplicadas (nessa ordem) pelo carregador de inicialização à DT de base.

As sobreposições podem ser aplicadas a nós do DT principal ou adicionar novos nós, mas não podem se referir a um nó adicionado em uma sobreposição anterior. Essa restrição é necessária porque o app de sobreposição não mescla a tabela de símbolos de sobreposição com a tabela principal de símbolos de DT. Não mesclar evita conflitos nos nomes de símbolos e complicação de dependências entre sobreposições.

Exemplo: sobreposições inválidas

Neste exemplo, overlay_2.dts se refere ao nó e , que foi adicionado por overlay_1.dts. Depois que overlay_1 for aplicado à DT principal, se for feita uma tentativa de aplicar overlay_2 à DT resultante, o app de sobreposição falhará com um erro informando que o símbolo e não está presente na tabela de símbolos da DT base.

main.dts overlay_1.dts overlay_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>;
};

Exemplo: sobreposições válidas

Neste exemplo, overlay_2.dts se refere apenas ao nó b do DTS principal. Quando overlay_1 é aplicado ao DT base, seguido pelo app de overlay_2, o valor da propriedade prop no nó e (definido por overlay_1.dts) é substituído pelo valor definido 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>;
      };
};

Implementar a partição DTBO

Para implementar a partição DTBO necessária, verifique se o carregador de inicialização pode fazer o seguinte:

  1. Identifique a placa em que ele está sendo executado e selecione as sobreposições correspondentes a serem aplicadas.
  2. Anexe o parâmetro androidboot.dtbo_idx à linha de comando do kernel.
    • O parâmetro precisa indicar os índices baseados em zero dos DTOs da imagem de partição da DTBO aplicada à DT de base (na mesma ordem).
    • Os índices precisam se referir à posição da sobreposição na partição DTBO.

Para saber mais sobre a estrutura da partição DTBO, consulte Sobreposições da árvore de dispositivos.

Validar a partição DTBO

É possível usar VTS para verificar o seguinte:

  • Existência do parâmetro de linha de comando do kernel androidboot.dtbo_idx (verificando se Init configurou automaticamente a propriedade do sistema ro.boot.dtbo_idx correspondente).
  • Validade da propriedade do sistema ro.boot.dtbo_idx (verificando se a propriedade especifica pelo menos um índice de imagem DTBO válido).
  • Validade da partição DTBO (também verifica as sobreposições na partição DTBO que são aplicadas à DT de base).
  • Outros nós ou alterações de propriedade na DT resultante são apresentados ao kernel do Linux.

Por exemplo, nas sobreposições e na DT final a seguir, adicionar androidboot.dtbo_idx=5,3 à linha de comando do kernel passa na validação, mas adicionar androidboot.dtbo_idx=3,5 à linha de comando do kernel não passa na validação.

DT de sobreposição no índice 3 DT de sobreposição no í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";
	};
};