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 (DT, na sigla em inglês) de sobreposição à DT principal de destino, você também precisa verificar o resultado simulando o comportamento da sobreposição da árvore de dispositivos (DTO, na sigla em inglês).

Compilar com o DTC

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

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

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

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

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

Verifique 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, você pode verificar o resultado da sobreposição da DT no host simulando o comportamento da 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, após a última linha, anexe a sintaxe de inclusão do arquivo criado na etapa 1. 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 para acessar a DT mesclada, que precisa ser o mesmo resultado da DTO. 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
    

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 mudanças 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 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 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 de símbolos de DT principal. A não mesclagem evita conflitos nos nomes de símbolos e complicações de dependências entre as 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 ao DT principal, se uma tentativa de aplicar overlay_2 ao DT resultante for feita, o app de sobreposição vai falhar com um erro informando que o símbolo e não está presente na tabela de símbolos do DT base.

main.dts sobreposição_1.dts sobreposição_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 sobreposição_1.dts sobreposição_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 de 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 ela está sendo executada e selecione as sobreposições correspondentes que serão 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 fazer referência à posição da sobreposição na partição de DTBO.

Para detalhes sobre a estrutura da partição de 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 definiu 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>; };
Transferência de dados final

/dts-v1/;
/ {

 a {
 phandle = <0x1>;
 };

 b {
 phandle = <0x2>;
 };

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

 };

 __b= "símbolo";