overlayed-dts.txt

In this guide we will learn about writing overlayed dtsi.

It will involve changing OEM dtsi commit (https://github.com/stormbreaker-project/kernel_asus_X01AD/commit/d4fd8d9a664672056e4b68a31da298a4d4bc79ac)

to a fully overlayed dts (https://github.com/stormbreaker-project/kernel_asus_X01AD/commit/85b3cb884acf30831a4185327a19a2c4268e457a)

1.)
First check the initial dts import of your device .
For example my device initial dts imports -> 

https://github.com/stormbreaker-project/kernel_asus_X01AD/commit/d4fd8d9a664672056e4b68a31da298a4d4bc79ac (SDM632)

As we can see , most changes are additions as they are changes done by the OEM.
Now from your stock kernel take a dmesg and find the name of the dtb your stock kernel use, we will need it as our initial base dts.
You will find something like this in your dmesg (start the dmesg from 0)

`Machine: Qualcomm Technologies, Inc. SDM632 PMI632 QRD SKU3`
which implies that our bootloader loads the dtb which points out to the same.

2.) 
Now, let's make a clean base of your kernel which would just boot.
In a clean base of kernel, we only add the required changes in base CAF or ALS kernel source which is enough to boot our device.
The minimal changes depends on device to device, some devices might just boot on device trees imports but some devices might need changes in power or video drivers, so we will add all these as per requirement.

3.) 
Before starting to write overlayed dts, I will consider that you have succeeded in (3).
For example :- My base source needed quite much changes to bootup, https://github.com/stormbreaker-project/kernel_asus_X01AD/tree/423c09527a97e55cca9a9ccfca247b1b179e3ebc .

4.) 
Now stalk your dtsi imports for quite a while so that you can know about the file names and the additions.

5.) 
Rename the dts which we booted in point (3) to your choice like mine was sdm632.dts so I renamed to sdm632-X01AD.dts. 

This is the dts which will include our other overlayed dts, we renamed sdm632.dts to ours because the dtb is called by our bootloader and we will add our dts changes over it.

6.)
Our next step is to make our kernel build our dts
You need to include the dts in the Makefile of dts directory (arch/arm64/boot/dts/qcom/Makefile).
You can call our dts by writing our dtsname.dtb in the required architecture conditions (as here https://github.com/stormbreaker-project/kernel_asus_X01AD/commit/85b3cb884acf30831a4185327a19a2c4268e457a#diff-6ef2edc037b112b898a8ae8cf2e368a6cbc75dda5cc8a5dc9be6b1146ca4569dR10).

7.) 
Now create a directory as you wish to (mine is X01AD/), you can also create sub-directories if you want (mainly to differentiate between display-panel dts and batterydata dts).

7.5.)
This step is for those who cannot recognise which dtsi are for dsi panels or batterydata,
To find the same you can either check names of dtsi in your OEM import(works in most of cases), 

Display panel dtsi will start with dsi-panel-"name-of-driver"-"resolution"-video.dtsi
Battery data dtsi are different as per devices so we will find them accordingly.

For me, I found out these (dsi-panel-ili9881h-720p-video.dtsi for panel 
Huaqin_QL1830scud_4000mAh_averaged_MasterSlave_Sept25th2018_PMI632.dtsi for batterydata).

8.)
Now move those dtsi to your required sub-directories (display, battery or anything else).

9.)
Now create a base dtsi in your directory and include it at the end of our .dts which we created in (5.)

You can include it as 
#include "your-directory-name/base.dtsi"

My base dtsi was X01AD-base.dtsi and is included (https://github.com/stormbreaker-project/kernel_asus_X01AD/commit/85b3cb884acf30831a4185327a19a2c4268e457a#diff-abc3be0451bc6bc9e957cd04db3f9bae2b34fbe57cd748e53adb8404d2aa57d2R31) here.

(The base dtsi is created to bind up includes in one directory, which is a good thing.)

9.5.)
You can try to build kernel and check if it goes fine, you can skip this step, this is just to confirm if our includes are correct and kernel builds it fine. You will find your dtb built in (out/arch/arm64/boot/dts)

**Till now The work is not even 10% so no need to enjoy.
The batterydata and dsi panel are just additions so that's the easiest part.**

10.) 
Checkout the additions and deletions in your dtsi import commit.

For example let's take my msm8953.dtsi

https://github.com/stormbreaker-project/kernel_asus_X01AD/commit/d4fd8d9a664672056e4b68a31da298a4d4bc79ac#diff-e8966e9b69f2736b98f83b94f0850b361f5c3c01b12d71ec162dbefc02d732bd

Create a similar dtsi in your overlayed dir. Which would make it easy for you and others to recall.
like X01AD-msm8953.dtsi.
Now include this in your base overlay dtsi you created in your device dir.

11.)
After stalking your dts OEM change, check the syntax of your dtsi.
In our case, dtsi starts with "/ {".
(Dtsi can start with braces or nodes(&node))

In my 71th line (https://github.com/stormbreaker-project/kernel_asus_X01AD/commit/d4fd8d9a664672056e4b68a31da298a4d4bc79ac#diff-e8966e9b69f2736b98f83b94f0850b361f5c3c01b12d71ec162dbefc02d732bdR72), address of other_ext region is changed.

So to write that in our overlayed, we will start our dtsi with "/ {" and follow up till that address (other_ext_region),
no need to write up other regions or adresses or nodes, as our OEM has not done any changes to them, leaving them as it is.

This is an important step as if it goes wrong you will end up in wierd errors from dtc
Our purpose can be to add, remove, overwrite, add a new node, delete a node, change regions, add properties, remove properties.

If you understood the above your dtsi should look like,

/ {
	reserved-memory {
		other_ext_mem: other_ext_region@0 {
		
After you have reached to that node just write the updated property (reg = <0x0 0x84a00000 0x0 0x1e00000>;),
now its just time to close those brackets and build 

in the end your dtsi should look like

/ {
	reserved-memory {
		other_ext_mem: other_ext_region@0 {
			reg = <0x0 0x84a00000 0x0 0x1e00000>;
		};
	};
};

Voila you made your first overlayed dtsi.
others will also involve the same process and you might need to delete properties or nodes, to do that you can just write,
/delete-property/ property-name; (example:- https://github.com/stormbreaker-project/kernel_asus_X01AD/commit/85b3cb884acf30831a4185327a19a2c4268e457a#diff-c7c6dacf6c6f713797447bf43699cfa3563f0a325f7261d7b35a64e263537db8R39}

/delete-node/ node-name; (example:- https://github.com/stormbreaker-project/kernel_asus_X01AD/commit/85b3cb884acf30831a4185327a19a2c4268e457a#diff-f83bf9884826447f814c8633637a4755595ee0daee9c0354a37c32a9880b8680R16)

If all goes good then you will enjoy it,
Else feel free to leave a comment if you have doubts.