Jump to content

QCDT: Difference between revisions

From postmarketOS Wiki
K-laus (talk | contribs)
m Compare the appended dtb files: bugfixed directory path
update to gitlab.postmarketos.org
 
(12 intermediate revisions by 7 users not shown)
Line 9: Line 9:
If this prints <code>deviceinfo_bootimg_qcdt="true"</code>, then you have a QCDT device.
If this prints <code>deviceinfo_bootimg_qcdt="true"</code>, then you have a QCDT device.


== Properly package a QCDT device ==
== Packaging a QCDT device ==
The easiest way is using <code>pmbootstrap init</code> to generate a new device, and let it analyze the boot.img file in the process. It will adjust the device and linux package as necessary. But if you want to do it manually:
 
* Set <code>deviceinfo_bootimg_qcdt="true"</code> in the [[deviceinfo]]
Running bootimg_analyze should print the option <code>deviceinfo_bootimg_qcdt_type</code>, which defines what kind of dt.img is supported in your device. It should be either <code>qcom</code>, <code>exynos</code>, or <code>sprd</code>. This option should be present in your deviceinfo, with <code>deviceinfo_bootimg_qcdt="true"</code>.
* Adjust your <code>linux-</code> APKBUILD to generate the <code>/boot/dt.img</code> (look at other QCDT devices to see how it's done, grep for qcdt in aports)
 
Along with the aforementioned option, you also need to include <code>deviceinfo_dtb</code> with the path to the dtb. This option currently supports
only one devicetree.
 
 
<b>For devices with <code>deviceinfo_bootimg_qcdt_type="qcom"</code></b>
 
* Add <code>dtbtool</code> to <code>depends</code> in your <b>device APKBUILD</b>.
 
 
<b>For devices with <code>deviceinfo_bootimg_qcdt_type="sprd"</code></b>
 
* Add <code>dtbtool-sprd</code> to <code>depends</code> in your <b>device APKBUILD</b>.
 
 
<b>For devices with <code>deviceinfo_bootimg_qcdt_type="exynos"</code></b>
 
* Add <code>dtbtool-exynos</code> to <code>depends</code> in your <b>device APKBUILD</b>.
 
 
Reference implementation: [https://gitlab.postmarketos.org/postmarketOS/pmaports/-/tree/master/device/testing/device-samsung-on7xelte samsung-on7xelte]
 
=== Packaging in the kernel ===
 
Usually, dt.img contains multiple devicetrees (for instance, for multiple revisions of the same device) which enables the bootloader to select the suitable devicetree. Here, the above method won't work as it imposes a limitation of only one dtb.
 
Instead, the dt.img generation can be manually implemented in the kernel package.
 
* Set <code>deviceinfo_bootimg_qcdt="true"</code> in the deviceinfo.
* Remove all references of <code>deviceinfo_bootimg_qcdt_type</code>. Otherwise, boot-deploy will revert to using the previously mentioned method.
* Add the following in <code>prepare()</code> in your <b>kernel APKBUILD</b>.
<pre>
install -Dm644 "$_outdir/arch/$_carch/boot"/dt.img "$pkgdir"/boot/dt.img
</pre>
* Follow the instructions specific to your device to edit the <b>kernel APKBUILD</b> given below.
 
 
<b>For devices with <code>deviceinfo_bootimg_qcdt_type="qcom"</code></b>
 
* Add <code>dtbtool</code> to <code>makedepends</code>.
* Add the following in <code>build()</code>
<pre>
dtbTool -s 2048 -p "scripts/dtc/" -o "$_outdir/arch/$_carch/boot"/dt.img \
"$_outdir/arch/$_carch/boot/"
</pre>
 
 
<b>For devices with <code>deviceinfo_bootimg_qcdt_type="sprd"</code></b>
 
* Add <code>dtbtool-sprd</code> to <code>makedepends</code>.
* Add the following in <code>build()</code>
<pre>
dtbTool-sprd -s 2048 -p "scripts/dtc/" -o "$_outdir/arch/$_carch/boot"/dt.img \
"$_outdir/arch/$_carch/boot/dts/"
</pre>
 
 
<b>For devices with <code>deviceinfo_bootimg_qcdt_type="exynos"</code></b>
 
* Add <code>dtbtool-exynos</code> to <code>makedepends</code>.
* Add the following in <code>build()</code>
<pre>
dtbTool-exynos -o "$_outdir/arch/$_carch/boot"/dt.img \
$(find "$_outdir/arch/$_carch/boot/dts/" -name *.dtb)
</pre>
 
 
{{note | Do note that these values don't necessarily have a correlation with their SoC. For example, here's a [https://wiki.postmarketos.org/wiki/Samsung_Galaxy_Grand_Prime_Plus_(samsung-grandpplte) device with a Mediatek chipset] requiring <code>dtbtool-exynos</code>.}}
 
Moreover, there are a lot of devices in pmaports using this method. They may also be studied for implementation.


== Debugging ==
== Debugging ==
Line 38: Line 107:


=== Repack procedure ===
=== Repack procedure ===
{{note|Please update these instructions when trying them out as they seem outdated, check the <code>--help</code> pages of the tools for help.}}
You need <code>mkbootimg</code> and <code>unpackbootimg</code> tools which are already packaged in pmbootstrap.
You need <code>mkbootimg</code> and <code>unpackbootimg</code> tools which are already packaged in pmbootstrap.


<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
$ ./pmbootstrap build mkbootimg unpackbootimg
$ sudo mkdir -p ~/.local/var/pmbootstrap/chroot_native/tmp/bootimg_repack
$ ./unpackbootimg -i $SOMEDIR/boot.img-$vendor-$name -o pmos
$ sudo cp pmos-boot.img ~/.local/var/pmbootstrap/chroot_native/tmp/bootimg_repack/
$ ./unpackbootimg -i $OTHERDIR/boot.img -o other
$ sudo cp other-.img ~/.local/var/pmbootstrap/chroot_native/tmp/bootimg_repack/
$ pmbootstrap chroot --add=mkbootimg-osm0sis
# cd /tmp/bootimg_repack
# unpackbootimg -i pmos-boot.img -o pmos
# unpackbootimg -i other-boot.img -o other
$ cp other/boot.img-dt pmos/boot.img-$vendor-$name-dt
$ cp other/boot.img-dt pmos/boot.img-$vendor-$name-dt
$ ./mkbootimg -o boot.repack.img -r pmos/boot.img-$vendor-$name-
$ mkbootimg-osm0sis -o boot.repack.img -r pmos/boot.img-$vendor-$name-
</syntaxhighlight>
</syntaxhighlight>
You can also get these from https://github.com/efidroid/build/tree/master/tools
You can also get these from https://github.com/efidroid/build/tree/master/tools
Line 53: Line 127:
== See also ==
== See also ==
* [[dtbtool]]
* [[dtbtool]]
* {{github|323}} related discussion
* {{issue|323}} related discussion
* {{github|356}} first implementation
* {{MR|356}} first implementation
* [https://github.com/s0be/dtimgextract dtimgextract]
* {{issue|1206}} debugging session for "FAILED (remote: dtb not found)" (contains a [https://gitlab.postmarketos.org/postmarketOS/pmbootstrap/issues/1206#note_85244905 workaround])
 
[[Category:Technical Reference]]

Latest revision as of 09:30, 3 November 2024

Some Androids only accept boot.img files in the QCDT format, which means the dtb is appended to the end of it (and not at the end of the kernel, as with most other Android devices).

Does my device need a QCDT boot.img file?

Analyze a known working boot.img file with pmbootstrap to find out, if it has the QCDT format or not. You can get such a file from downloading a TWRP image (it is directly in the boot.img format!) or by downloading a full Android ROM for your device and extracting the boot.img file.

$ pmbootstrap bootimg_analyze /path/to/boot.img

If this prints deviceinfo_bootimg_qcdt="true", then you have a QCDT device.

Packaging a QCDT device

Running bootimg_analyze should print the option deviceinfo_bootimg_qcdt_type, which defines what kind of dt.img is supported in your device. It should be either qcom, exynos, or sprd. This option should be present in your deviceinfo, with deviceinfo_bootimg_qcdt="true".

Along with the aforementioned option, you also need to include deviceinfo_dtb with the path to the dtb. This option currently supports only one devicetree.


For devices with deviceinfo_bootimg_qcdt_type="qcom"

  • Add dtbtool to depends in your device APKBUILD.


For devices with deviceinfo_bootimg_qcdt_type="sprd"

  • Add dtbtool-sprd to depends in your device APKBUILD.


For devices with deviceinfo_bootimg_qcdt_type="exynos"

  • Add dtbtool-exynos to depends in your device APKBUILD.


Reference implementation: samsung-on7xelte

Packaging in the kernel

Usually, dt.img contains multiple devicetrees (for instance, for multiple revisions of the same device) which enables the bootloader to select the suitable devicetree. Here, the above method won't work as it imposes a limitation of only one dtb.

Instead, the dt.img generation can be manually implemented in the kernel package.

  • Set deviceinfo_bootimg_qcdt="true" in the deviceinfo.
  • Remove all references of deviceinfo_bootimg_qcdt_type. Otherwise, boot-deploy will revert to using the previously mentioned method.
  • Add the following in prepare() in your kernel APKBUILD.
install -Dm644 "$_outdir/arch/$_carch/boot"/dt.img "$pkgdir"/boot/dt.img
  • Follow the instructions specific to your device to edit the kernel APKBUILD given below.


For devices with deviceinfo_bootimg_qcdt_type="qcom"

  • Add dtbtool to makedepends.
  • Add the following in build()
dtbTool -s 2048 -p "scripts/dtc/" -o "$_outdir/arch/$_carch/boot"/dt.img \
	"$_outdir/arch/$_carch/boot/"


For devices with deviceinfo_bootimg_qcdt_type="sprd"

  • Add dtbtool-sprd to makedepends.
  • Add the following in build()
dtbTool-sprd -s 2048 -p "scripts/dtc/" -o "$_outdir/arch/$_carch/boot"/dt.img \
	"$_outdir/arch/$_carch/boot/dts/"


For devices with deviceinfo_bootimg_qcdt_type="exynos"

  • Add dtbtool-exynos to makedepends.
  • Add the following in build()
dtbTool-exynos -o "$_outdir/arch/$_carch/boot"/dt.img \
	$(find "$_outdir/arch/$_carch/boot/dts/" -name *.dtb)


Note Do note that these values don't necessarily have a correlation with their SoC. For example, here's a device with a Mediatek chipset requiring dtbtool-exynos.

Moreover, there are a lot of devices in pmaports using this method. They may also be studied for implementation.

Debugging

  • Hook up the serial UART and see what kind of debug output the bootloader provides
  • Repack the boot image with a working dt.img from another distribution (stock, Lineage, recovery, etc.)

Compare the appended dtb files

$ pmbootstrap install
$ pmbootstrap chroot -r -- mkdir -p /tmp/extract-dtb-known-working
$ sudo cp known_working_boot.img ~/.local/var/pmbootstrap/chroot_rootfs_*/tmp/extract-dtb-known-working/boot.img
$ pmbootstrap chroot -r
# apk add extract-dtb
# mkdir -p /tmp/extract-dtb-pmOS
# ls /boot/
# cp /boot/boot.img-* /tmp/extract-dtb-pmOS/boot.img
# cd /tmp/extract-dtb-pmOS
# extract-dtb boot.img
# cd /tmp/extract-dtb-known-working
# extract-dtb boot.img
Now compare the output in both temp folders.
Is there the same amount of dtb files, and are the files the same?
If not, then the QCDT generation went wrong.

Repack procedure

Note Please update these instructions when trying them out as they seem outdated, check the --help pages of the tools for help.

You need mkbootimg and unpackbootimg tools which are already packaged in pmbootstrap.

$ sudo mkdir -p ~/.local/var/pmbootstrap/chroot_native/tmp/bootimg_repack
$ sudo cp pmos-boot.img ~/.local/var/pmbootstrap/chroot_native/tmp/bootimg_repack/
$ sudo cp other-.img ~/.local/var/pmbootstrap/chroot_native/tmp/bootimg_repack/
$ pmbootstrap chroot --add=mkbootimg-osm0sis
# cd /tmp/bootimg_repack
# unpackbootimg -i pmos-boot.img -o pmos
# unpackbootimg -i other-boot.img -o other
$ cp other/boot.img-dt pmos/boot.img-$vendor-$name-dt
$ mkbootimg-osm0sis -o boot.repack.img -r pmos/boot.img-$vendor-$name-

You can also get these from https://github.com/efidroid/build/tree/master/tools

abootimg is packaged for postmarketOS as well, which allows to repackage the boot.img files without extracting them.

See also