#Adapt it to your device

hakios is built so that a new phone is a new device repository, not a fork. You describe the phone, boot a kernel with nothing of the phone's in it, then turn its hardware on one driver at a time. This page is the whole path; the exact formats are in the reference: Port a device, How the repositories fit, Writing a driver.

#Can my phone run it?

You also need: a UEFI for the phone (a Mu-Silicium port, or HakiOS U-Boot), the phone's device tree, and a computer that builds the kernel (see Run it in QEMU).

#The plan

1  describe the phone        tools/hakios-device.py new        → devices/<name>/ passes `check`
2  boot with nothing of it   make phone SECS=120               → the run reaches launchd and ends by itself
3  turn hardware on          one driver at a time, in order    → each one seen working
4  write down what works     device.conf status lines          → the site's device table
5  publish                   your repository + a manifest PR   → anyone can `sync` your phone

#1. Describe the phone

Pull the phone's own device tree while it runs Android, then let the tool make the repository:

adb pull /sys/firmware/fdt device-tree.dtb
tools/hakios-device.py new mydevice --soc sc7280 --title "My Phone" --vendor Someone --maintainer "you" --fdt device-tree.dtb
make mydevice_defconfig
make config

What you get in devices/mydevice/:

device.conf                  who the phone is, and what works on it
configs/mydevice_defconfig   three lines: common_defconfig + <soc>.config + mydevice.config
configs/mydevice.config      CONFIG_DEVICE="mydevice", every phone driver off to begin with
soc/                         the chip layer: soc.conf and configs/<soc>.config
soc.args                     the chip's addresses (soc_*), read from your device tree
README.md                    the checklist of what is the phone's own

Done when tools/hakios-device.py check mydevice passes.

#device.conf

device mydevice
	title       My Phone
	vendor      Someone
	soc         sc7280
	defconfig   mydevice_defconfig
	firmware    pull-firmware.sh
	maintainer  you
	status      display     partial   UEFI's framebuffer, through the loader (to be checked)

• One status <area> works|partial|missing <note> line per area. Areas: display touch buttons cpu gpu storage audio battery haptic camera torch wifi bluetooth cellular network thermal usb sensors.
• Only what you have seen on the phone is works. Written but not yet seen is partial, with a note saying what is missing.
• The site's device pages are generated from this file (python3 tools/docs-gen.py): never edit them by hand.

#Files you will edit

#2. Boot with nothing of the phone's

make kernel
make loader
make phone SECS=120          # the arguments come from your .config

Look in logs/last.log for, in this order: the loader's banner, kernel.ver=, hakios-kernel: N drivers built in (...), then launchd. Done when a run reaches launchd, ends by itself and the phone comes back.

#3. Turn the hardware on, one driver at a time

Every driver does nothing until its boot argument is given, and a failing step writes one line to the log and stops, so a wrong address costs you a log line, not a phone. Go in this order; each step needs the ones before it.

For each driver:

1. Read the comment at the top of its file in drivers/: it says where every address and number came from on the reference phone.
2. Find the same node in your device tree.
3. Put what differs where it belongs: a chip fact in the chip layer's fragment, a phone fact in configs/mydevice.config as a boot argument.
4. Turn it on, run, read the log, repeat.

Hardware the common tree does not cover (another touch controller, eMMC instead of UFS, another Wi-Fi chip) gets its own driver: a hakios.<name>.c file and a block in drivers/<subsystem>/conf. Writing a driver is the recipe; python3 tools/drivers-check.py checks it.

#4. Write down what works

Update the status lines, then:

python3 tools/docs-gen.py               # the device page, from device.conf
tools/hakios-device.py check mydevice

#5. Publish

tools/hakios-device.py split mydevice ../hakios-device-mydevice

Push it as hakios-device-mydevice (or hakios-soc-<soc> for a shared chip layer), then open a pull request on the main repository that adds your block to devices/manifest.conf. tools/hakios-device.py lock mydevice writes the revision into it. From then on anyone can tools/hakios-device.py sync mydevice.

#Rules every port keeps

• No vendor firmware, no Apple files and no real serial numbers in any repository. Firmware is pulled from the user's own phone into fw-*/, which git ignores.
• A port that copies the chip layer must keep it identical to every other copy; the tools refuse two different copies and name both.
• Ask in the Telegram channel before you start: someone may already be on your phone.