Mengompilasi dan memverifikasi

Anda dapat menggunakan compiler device tree (DTC) untuk mengompilasi file sumber device tree (DTS). Namun, sebelum menerapkan overlay device tree (DT) pada DT utama target, Anda juga harus memverifikasi hasilnya dengan menyimulasikan perilaku overlay device tree (DTO).

Mengompilasi dengan DTC

Saat menggunakan dtc untuk mengompilasi .dts, Anda harus menambahkan opsi -@ untuk menambahkan node __symbols__ di .dtbo yang dihasilkan. Node __symbols__ berisi daftar semua node yang ditandai dengan label, yang dapat digunakan oleh library DTO untuk referensi.

Contoh perintah untuk membangun DT utama .dts:

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

Contoh perintah untuk membangun DT overlay .dts:

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

Memverifikasi hasil DTO di host

Verifikasi dapat membantu Anda mengidentifikasi error yang mungkin terjadi saat menempatkan DT overlay pada DT utama. Sebelum memperbarui target, Anda dapat memverifikasi hasil overlay DT di host dengan menyimulasikan perilaku DTO menggunakan /include/ di .dts.

Gambar 1. Gunakan sintaksis /include/ untuk menyimulasikan DTO di host.

1. Buat salinan overlay .dts. Dalam salinan, hapus header baris pertama. Contoh:

   /dts-v1/;
   /plugin/;
   

   Simpan file sebagai my_overlay_dt_wo_header.dts (atau nama file apa pun yang Anda inginkan).
2. Buat salinan .dts utama. Di salinan, setelah baris terakhir, tambahkan sintaksis include untuk file yang Anda buat di langkah 1. Contoh:

   /include/ "my_overlay_dt_wo_header.dts"
   

   Simpan file sebagai my_main_dt_with_include.dts (atau nama file apa pun yang Anda inginkan).
3. Gunakan dtc untuk mengompilasi my_main_dt_with_include.dts untuk mendapatkan DT gabungan, yang seharusnya menghasilkan hasil yang sama dengan DTO. Contoh:

   dtc -@ -O dtb -o my_merged_dt.dtb my_main_dt_with_include.dts
   

4. Gunakan dtc untuk membuat dump my_merged_dt.dto.

   dtc -O dts -o my_merged_dt.dts my_merged_dt.dtb
   

Memverifikasi DTO di Android 9

Android 9 memerlukan partisi overlay blob tree perangkat (DTBO). Untuk menambahkan node atau membuat perubahan pada properti di DT SoC, bootloader harus secara dinamis menempatkan DT khusus perangkat di atas DT SoC.

Menunjukkan overlay yang diterapkan

Untuk mengaktifkan Vendor Test Suite (VTS) guna menilai kebenaran aplikasi overlay, vendor harus menambahkan parameter command line kernel baru androidboot.dtbo_idx yang menunjukkan overlay yang dipilih dari partisi DTBO. Di Android 12 yang menggunakan kernel versi 5.10 atau yang lebih baru, parameter ini diteruskan melalui bootconfig. Misalnya, parameter androidboot.dtbo_idx=x,y,z melaporkan x, y, dan z sebagai indeks berbasis nol dari DTO dari partisi DTBO yang diterapkan (dalam urutan tersebut) oleh bootloader ke DT dasar.

Overlay dapat diterapkan ke node dari DT utama atau menambahkan node baru, tetapi tidak dapat merujuk ke node yang ditambahkan di overlay sebelumnya. Pembatasan ini diperlukan karena aplikasi overlay tidak menggabungkan tabel simbol DT overlay dengan tabel simbol DT utama (tidak menggabungkan menghindari konflik dalam nama simbol dan komplikasi dependensi antara overlay).

Contoh: Overlay tidak valid

Dalam contoh ini, overlay_2.dts merujuk ke node e , yang ditambahkan oleh overlay_1.dts. Setelah overlay_1 diterapkan ke DT utama, jika ada upaya untuk menerapkan overlay_2 ke DT yang dihasilkan, aplikasi overlay akan gagal dengan error bahwa simbol e tidak ada dalam tabel simbol untuk DT dasar.

[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>;
};

Contoh: Overlay yang valid

Dalam contoh ini, overlay_2.dts hanya merujuk ke node b dari DTS utama. Jika overlay_1 diterapkan ke DT dasar, lalu diikuti dengan aplikasi overlay_2, nilai properti prop di node e (ditetapkan oleh overlay_1.dts) akan ditimpa oleh nilai yang ditetapkan oleh 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>;
      };
};

Menerapkan partisi DTBO

Untuk mengimplementasikan partisi DTBO yang diperlukan, pastikan bootloader dapat melakukan hal berikut:

1. Identifikasi papan tempatnya berjalan dan pilih overlay yang sesuai untuk diterapkan.
2. Tambahkan parameter androidboot.dtbo_idx ke command line kernel.
   • Parameter harus menunjukkan indeks berbasis nol DTO dari image partisi DTBO yang diterapkan ke DT dasar (dengan urutan yang sama).
   • Indeks harus merujuk ke posisi overlay di partisi DTBO.

Untuk mengetahui detail struktur partisi DTBO, lihat Overlay pohon perangkat.

Memvalidasi partisi DTBO

Anda dapat menggunakan VTS untuk memverifikasi hal berikut:

• Keberadaan parameter command line kernel androidboot.dtbo_idx (dengan memeriksa apakah Init telah menyiapkan properti sistem ro.boot.dtbo_idx yang sesuai secara otomatis).
• Validitas properti sistem ro.boot.dtbo_idx (dengan memeriksa bahwa properti menentukan setidaknya satu indeks gambar DTBO yang valid).
• Validitas partisi DTBO (juga memverifikasi overlay di partisi DTBO yang diterapkan ke DT dasar).
• Perubahan properti atau node tambahan dalam DT yang dihasilkan akan ditampilkan ke kernel Linux.

Misalnya, dalam overlay dan DT akhir berikut, menambahkan androidboot.dtbo_idx=5,3 ke baris perintah kernel akan lulus validasi, tetapi menambahkan androidboot.dtbo_idx=3,5 ke baris perintah kernel tidak akan lulus validasi.

[overlay_1.dts]

/dts-v1/;
/plugin/;

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

[overlay_2.dts]

/dts-v1/;
/plugin/;

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

/dts-v1/;
/ {

	a {
		phandle = <0x1>;
	};

	b {
		phandle = <0x2>;
	};

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

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