Compilando e Verificando

Você pode usar o Device Tree Compiler (DTC) para compilar os arquivos de origem da árvore de dispositivos. Porém, antes de aplicar o DT de sobreposição no DT principal destino, você também deve verificar o resultado simulando o comportamento do DTO.

Compilando com DTC

Ao usar dtc para compilar .dts , você deve 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 construir o DT principal .dts :

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

Exemplo de comando para construir o DT de sobreposição .dts :

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

Verifique os resultados do 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, você pode verificar o resultado da sobreposição do DT no host simulando o comportamento do 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 desejado).
  2. Crie uma cópia do .dts principal. Na cópia, após a última linha, anexe a sintaxe de inclusão do arquivo criado 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 desejado).
  3. Use dtc para compilar my_main_dt_with_include.dts para obter 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 despejar my_merged_dt.dto . 
    dtc -O dts -o my_merged_dt.dts my_merged_dt.dtb

Verificando DTO no Android 9

O Android 9 requer uma partição Device Tree Blob Overlay (DTBO). Para adicionar nós ou fazer alterações nas propriedades no SoC DT, o bootloader deve sobrepor dinamicamente um DT específico do dispositivo sobre o SoC DT.

Indicando sobreposições aplicadas

Para permitir que o Vendor Test Suite (VTS) avalie a correção do aplicativo de sobreposição, os fornecedores devem adicionar um novo parâmetro de linha de comando do kernel androidboot.dtbo_idx que indica as sobreposições selecionadas na partição DTBO. No Android 12 usando kernel versão 5.10 ou superior, esse parâmetro passa 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 sobreposições de árvore de dispositivos (DTOs) da partição DTBO aplicada (nessa ordem) pelo bootloader à base Árvore de dispositivos (DT).

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

Exemplo: sobreposições inválidas

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

principal.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 refere-se apenas ao nó b do DTS principal. Quando overlay_1 é aplicado ao DT base, seguido pela aplicação 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 .

principal.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>;
      };
};

Implementando a partição DTBO

Para implementar a partição DTBO necessária, certifique-se de que o bootloader possa fazer o seguinte:

  1. Identifique a placa em que ela está sendo executada 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 deve indicar os índices baseados em zero dos DTOs da imagem da partição DTBO que aplicou ao DT base (na mesma ordem).
    • Os índices devem referir-se à posição da sobreposição na partição DTBO.

Para obter detalhes sobre a estrutura da partição DTBO, consulte Sobreposições de árvore de dispositivos em source.android.com.

Validando a partição DTBO

Você pode usar o 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 de sistema ro.boot.dtbo_idx correspondente).
  • Validade da propriedade de 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 ao DT base).
  • Nós adicionais ou alterações de propriedade no DT resultante são apresentados ao kernel do Linux.

Por exemplo, nas sobreposições a seguir e no DT final, 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.

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