Jump to content

Hybris: Difference between revisions

From postmarketOS Wiki
Nergzd723 (talk | contribs)
add halium-9 hybrisOS info
Tags: mobile edit mobile web edit
No edit summary
 
(24 intermediate revisions by 10 users not shown)
Line 1: Line 1:
[https://en.wikipedia.org/wiki/Hybris_(software) Libhybris] is an Android compatibility layer, allowing libraries compiled with bionic libc to be loaded by applications built with different libc (originally glibc, musl in postmarketOS case). It allows to run proprietary Android userspace drivers on top of a downstream kernel by running parts of Android in a container. The upsides and downsides of this approach are discussed in {{issue|703|pmaports}}.
{{note|'''libhybris has been dropped from postmarketOS, and hybrisOS is no longer in development.''' This page is left for historic purposes.}}


There were some efforts with limited success to make it work in postmarketOS. But due to lack of maintenance, it was decided to drop it from pmaports in August of 2020.
[https://en.wikipedia.org/wiki/Hybris_(software) Libhybris] is an Android compatibility layer, allowing libraries compiled with bionic (Android) libc to be loaded by applications built with different libc (originally glibc, musl in postmarketOS case). It allows a device to run proprietary Android userspace drivers on top of a downstream kernel by running parts of Android in a container. The upsides and downsides of this approach are discussed in {{issue|703|pmaports}}.


Later in August of 2020, hybrisOS project was created to bring Halium-related packages to postmarketOS. Unfortunately, it was decided not to merge Halium packages back on pmOS team meeting. Currently hybris-related packages are stored on hybrisOS project GitLab.
Currently, libhybris for postmarketOS exists in the form of the [https://gitlab.com/hybrisos/hybrisaports hybrisaports repo], and exists as an unofficial method of running postmarketOS without having to work on mainline or kernel drivers (assuming your kernel is compatible).  


The aim is for the [https://gitlab.com/hybrisos hybrisOS project] to coexist with postmarketOS and ideally make it possible for users to experience postmarketOS on devices that otherwise wouldn't be able to run it (due to missing mainline support or poor quality kernels).


== Introduction ==
= Booting hybris on your device =


The main steps are:
== Get in touch ==
* prepare pmOS kernel for it to be able to use lxc
* create device-specific device-vendor-codename-hybris package


For help, you may want to join #hybrisos:kde.org on Matrix.
For help, feel free to come chat with us in #hybrisos:kde.org on Matrix, or [https://t.me/hybrisos @hybrisOS] on Telegram!


= Halium 9 based ports =
== Requirements ==
== Requirements ==


Line 21: Line 21:


* armv7 or aarch64 architecture
* armv7 or aarch64 architecture
* Linux 3.17 or newer(need getrandom and memfd_create syscalls)
* Linux 3.17 or newer(need getrandom and memfd_create syscalls) - it is possible to backport these to 3.4 and perhaps 3.10
* Project Treble support and Android 9 /vendor partition OR official Halium-9 port without Treble
* Project Treble support and Android 9 /vendor partition OR official Halium-9 port without Treble [http://docs.halium.org/en/latest/supplementary/devices/index.html halium devices list].


== Preparing kernel ==
== Preparing kernel ==


For preparing kernel, you need to clone https://github.com/Halium/halium-boot repo:
For preparing kernel, you need to clone your device kernel repo (Lineage OS kernel is recommended), as well as the halium-boot repo:


<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
Line 34: Line 34:
Then, check kernel config with this command:
Then, check kernel config with this command:
<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
$ ./halium-boot/check-kernel-config path/to/my/defconfig -w
$ ./halium-boot/check-kernel-config path/to/defconfig -w
</syntaxhighlight>
</syntaxhighlight>
{{note|You can find out which defconfig your device uses by finding a lineageOS device tree and looking in the BoardConfig.mk file for the TARGET_KERNEL_CONFIG variable}}


Your defconfig is located at <code>$(pmbootstrap config aports)/device/testing/linux-vendor-codename/config-vendor-codename.arch</code>.
It is recommended to run the command twice to make sure everything got fixed. Then run the command again without <code>-w</code> flag to check that it was able to find and enable all needed config options.
You may run that command twice to make sure everything got fixed. Then run the command again without <code>-w</code> flag to check if everything is fine.


If everything is fixed, make sure you update the version of kernel package:
You should now push your defconfig changes up to a public git repository and follow [https://wiki.postmarketos.org/wiki/Porting_to_a_new_device#Kernel_package the porting guide] to create your kernel package using the kernel you just modified (don't forget to come back here after!).
 
=== pmaports ===
 
To add hybris packages to pmaports run the following:
 
<syntaxhighlight lang="shell-session">
$ cd $(pmbootstrap config aports)
$ git submodule add https://gitlab.com/hybrisos/hybrisaports hybris
</syntaxhighlight>
 
== Building ==
 
Make sure your kernel package is up to date:
<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
$ pmbootstrap pkgrel_bump linux-vendor-codename
$ pmbootstrap build linux-$(pmbootstrap config device) # e.g. linux-oneplus-enchilada-hybris
</syntaxhighlight>
</syntaxhighlight>


Then, rebuild the kernel:
== Generate udev rules ==
 
Similarly to the ubports GSI, you will need to generate udev rules to make sure android device nodes and files all get the right permissions. Boot your device into TWRP and get a shell, then run:
<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
$ pmbootstrap build linux-vendor-codename
# cat /vendor/ueventd*.rc /system_root/ueventd*.rc /system/ueventd*.rc | grep ^/dev | sed -e 's/^\/dev\///' | awk '{printf "ACTION==\"add\", KERNEL==\"%s\", OWNER=\"%s\", GROUP=\"%s\", MODE=\"%s\"\n",$1,$3,$4,$2}' | sed -e 's/\r//' > /sdcard/70-halium.rules
</syntaxhighlight>
</syntaxhighlight>


If you have any errors, search for patches or enter Matrix room for assistance.
{{note|Adapted from [https://github.com/ubports/porting-notes/wiki/Halium-9#generating-udev-rules ubports halium 9 porting notes]}}
 
Then from your host:
<syntaxhighlight lang="shell-session">
$ adb pull /sdcard/70-halium.rules
</syntaxhighlight>


== Make device-specific hybris package ==
== Make device-specific hybris package ==


To make Halium installation automatic, fork your device package:
Devices wishing to use hybris packages must use a slightly modified device package in order to make sure all the hybris packages get installed.


<syntaxhighlight>
=== From an existing device package ===
$ cp -r $(pmbootstrap config aports)/device/testing/device-vendor-codename \
If you already have a device package, you can simply make a copy - don't forget to change the device codename in the <code>deviceinfo</code> file!
$(pmbootstrap config aports)/device/testing/device-vendor-codename-hybris
<syntaxhighlight lang="shell-session">
$ cp -r $(pmbootstrap config aports)/device/testing/device-$(pmbootstrap config device) \
      $(pmbootstrap config aports)/device/testing/device-$(pmbootstrap config device)-hybris
</syntaxhighlight>
</syntaxhighlight>


Then modify its APKBUILD, adding these functions:
=== Apply needed modifications for hybris ===
<syntaxhighlight>
Copy the <code>70-halium.rules</code> file you generated above to the new device package.
 
Use the [https://gitlab.com/kalube/pmaports/-/tree/7ae101e5f83697c551294a3ade401e97d3662c61/device/testing/device-oneplus-enchilada-hybris OnePlus 6 device repo] as an example to add the following changes to your APKBUILD.
<pre>
source="
    ...
    70-halium.rules
    ...
"
subpackages="
$pkgname-nonfree-userland:nonfree_userland
$pkgname-hybris
$pkgname-hybris-x11:hybris_x11
$pkgname-hybris-phosh:hybris_phosh
$pkgname-hybris-quirks:hybris_quirks
"
 
 
nonfree_userland() {
nonfree_userland() {
pkgdesc="Pull in libhybris (Android 9) hardware adaptation packages"
pkgdesc="Libhybris (Android 9) hardware adaptation packages"
depends="$pkgname-hybris"
depends="$pkgname-hybris"
mkdir "$subpkgdir"
mkdir "$subpkgdir"
Line 86: Line 125:
install_if="$pkgname-hybris postmarketos-ui-phosh"
install_if="$pkgname-hybris postmarketos-ui-phosh"
depends="wlroots-hwc2"
depends="wlroots-hwc2"
        mkdir $subpkgdir
}
}


</syntaxhighlight>
# Any quirks or extra packages needed for this port
 
hybris_quirks() {
Also modify packages submodules, adding these options:
pkgdesc="Fixes for this libhybris adaptation specific quirks"
<syntaxhighlight>
depends="hexdump hostapd dnsmasq"
$pkgname-nonfree-userland:nonfree_userland
install_if="$pkgname-hybris"
$pkgname-hybris
mkdir $subpkgdir
$pkgname-hybris-x11:hybris_x11
}
$pkgname-hybris-phosh:hybris_phosh
</pre>
</syntaxhighlight>
 
{{note| TODO: explain udev rules(/me has no idea)}}
 
After that's done, you should be ready to proceed to installing postmarketOS with Halium packages!


== Installing postmarketOS with Halium adaptation ==
You can now follow the postmarketOS install guide as normal from [https://wiki.postmarketos.org/wiki/Porting_to_a_new_device#Installation the installation section].


Choose codename-hybris as device's codename in <code>pmbootstrap init</code>.
= Halium 7 based ports =


Follow Installation guide(https://wiki.postmarketos.org/wiki/Installation_guide).
{{todo|Halium 7 is theoretically supported, but requires a lot more work as Android 7 devices don't have a vendor partition. This section will be updated when we have more devices to work with, if you want to get postmarketOS booting with halium on your Android 7 device definitely come chat!}}


== See also ==
= See also =
* [https://gitlab.com/postmarketOS/pmaports/-/tree/cb22119c3d62c2d1bfbe79e1b6b67f82be31b8eb/hybris Old hybris pmaports]
* [https://gitlab.postmarketos.org/postmarketOS/pmaports/-/tree/cb22119c3d62c2d1bfbe79e1b6b67f82be31b8eb/hybris Old hybris pmaports]
* [https://wiki.postmarketos.org/index.php?title=Hybris&oldid=11809 Previous version of this wiki page] (before libhybris support was dropped from postmarketOS)
* [https://wiki.postmarketos.org/index.php?title=Hybris&oldid=11809 Previous version of this wiki page] (before libhybris support was dropped from postmarketOS)
* {{MR|1144|pmaports}} WIP Android 9 support for pmaports
* {{MR|1144|pmaports}} WIP Android 9 support for pmaports
* {{github|1402}} Initial packaging of libhybris
* {{MR|1402}} Initial packaging of libhybris
* [[Motorola_Droid_4_(motorola-maserati)|Droid 4]]: the device for which NotKit originally made the libhybris support
* [[Motorola_Droid_4_(motorola-maserati)|Droid 4]]: the device for which NotKit originally made the libhybris support
* [[Planet_Computers_Gemini_PDA_(planet-geminipda)|Gemini PDA]]: NotKit also made it work with libhybris
* [[Planet_Computers_Gemini_PDA_(planet-geminipda)|Gemini PDA]]: NotKit also made it work with libhybris
Line 120: Line 155:
* [https://gitlab.com/hybrisos/hybrisaports halium-related packages]
* [https://gitlab.com/hybrisos/hybrisaports halium-related packages]
* [https://gitlab.com/hybrisos hybrisOS project page]
* [https://gitlab.com/hybrisos hybrisOS project page]
 
<!-- less useful stuff mostly here for legacy reasons -->
[[Category:Technical Reference]]
* [https://gitlab.postmarketos.org/postmarketOS/pmaports/-/tree/cb22119c3d62c2d1bfbe79e1b6b67f82be31b8eb/hybris Old hybris pmaports]
 
== See also ==
* [https://gitlab.com/postmarketOS/pmaports/-/tree/cb22119c3d62c2d1bfbe79e1b6b67f82be31b8eb/hybris Old hybris pmaports]
* [https://wiki.postmarketos.org/index.php?title=Hybris&oldid=11809 Previous version of this wiki page] (before libhybris support was dropped from postmarketOS)
* [https://wiki.postmarketos.org/index.php?title=Hybris&oldid=11809 Previous version of this wiki page] (before libhybris support was dropped from postmarketOS)
* {{MR|1144|pmaports}} WIP Android 9 support for pmaports
* {{MR|1144|pmaports}} WIP Android 9 support for pmaports
* {{github|1402}} Initial packaging of libhybris
* [[Motorola_Droid_4_(motorola-maserati)|Droid 4]]: the device for which NotKit originally made the libhybris support
* [[Motorola_Droid_4_(motorola-maserati)|Droid 4]]: the device for which NotKit originally made the libhybris support
* [[Planet_Computers_Gemini_PDA_(planet-geminipda)|Gemini PDA]]: NotKit also made it work with libhybris
* [[Planet_Computers_Gemini_PDA_(planet-geminipda)|Gemini PDA]]: NotKit also made it work with libhybris
Line 133: Line 164:
* [https://postmarketos.org/blog/2017/12/31/219-days-of-postmarketOS/#libre-drivers-and-libhybris 219 days of postmarketOS: libre drivers and libhybris]
* [https://postmarketos.org/blog/2017/12/31/219-days-of-postmarketOS/#libre-drivers-and-libhybris 219 days of postmarketOS: libre drivers and libhybris]


[[Category:Technical Reference]]
[[Category:Software]]

Latest revision as of 15:16, 17 November 2024

Note libhybris has been dropped from postmarketOS, and hybrisOS is no longer in development. This page is left for historic purposes.

Libhybris is an Android compatibility layer, allowing libraries compiled with bionic (Android) libc to be loaded by applications built with different libc (originally glibc, musl in postmarketOS case). It allows a device to run proprietary Android userspace drivers on top of a downstream kernel by running parts of Android in a container. The upsides and downsides of this approach are discussed in pmaports#703.

Currently, libhybris for postmarketOS exists in the form of the hybrisaports repo, and exists as an unofficial method of running postmarketOS without having to work on mainline or kernel drivers (assuming your kernel is compatible).

The aim is for the hybrisOS project to coexist with postmarketOS and ideally make it possible for users to experience postmarketOS on devices that otherwise wouldn't be able to run it (due to missing mainline support or poor quality kernels).

Booting hybris on your device

Get in touch

For help, feel free to come chat with us in #hybrisos:kde.org on Matrix, or @hybrisOS on Telegram!

Halium 9 based ports

Requirements

Target Device

For Halium adaptation to work, your device must have:

  • armv7 or aarch64 architecture
  • Linux 3.17 or newer(need getrandom and memfd_create syscalls) - it is possible to backport these to 3.4 and perhaps 3.10
  • Project Treble support and Android 9 /vendor partition OR official Halium-9 port without Treble halium devices list.

Preparing kernel

For preparing kernel, you need to clone your device kernel repo (Lineage OS kernel is recommended), as well as the halium-boot repo:

$ git clone https://github.com/Halium/halium-boot

Then, check kernel config with this command:

$ ./halium-boot/check-kernel-config path/to/defconfig -w
Note You can find out which defconfig your device uses by finding a lineageOS device tree and looking in the BoardConfig.mk file for the TARGET_KERNEL_CONFIG variable

It is recommended to run the command twice to make sure everything got fixed. Then run the command again without -w flag to check that it was able to find and enable all needed config options.

You should now push your defconfig changes up to a public git repository and follow the porting guide to create your kernel package using the kernel you just modified (don't forget to come back here after!).

pmaports

To add hybris packages to pmaports run the following:

$ cd $(pmbootstrap config aports)
$ git submodule add https://gitlab.com/hybrisos/hybrisaports hybris

Building

Make sure your kernel package is up to date:

$ pmbootstrap build linux-$(pmbootstrap config device) # e.g. linux-oneplus-enchilada-hybris

Generate udev rules

Similarly to the ubports GSI, you will need to generate udev rules to make sure android device nodes and files all get the right permissions. Boot your device into TWRP and get a shell, then run:

# cat /vendor/ueventd*.rc /system_root/ueventd*.rc /system/ueventd*.rc | grep ^/dev | sed -e 's/^\/dev\///' | awk '{printf "ACTION==\"add\", KERNEL==\"%s\", OWNER=\"%s\", GROUP=\"%s\", MODE=\"%s\"\n",$1,$3,$4,$2}' | sed -e 's/\r//' > /sdcard/70-halium.rules
Note Adapted from ubports halium 9 porting notes

Then from your host:

$ adb pull /sdcard/70-halium.rules

Make device-specific hybris package

Devices wishing to use hybris packages must use a slightly modified device package in order to make sure all the hybris packages get installed.

From an existing device package

If you already have a device package, you can simply make a copy - don't forget to change the device codename in the deviceinfo file!

$ cp -r $(pmbootstrap config aports)/device/testing/device-$(pmbootstrap config device) \
      $(pmbootstrap config aports)/device/testing/device-$(pmbootstrap config device)-hybris

Apply needed modifications for hybris

Copy the 70-halium.rules file you generated above to the new device package.

Use the OnePlus 6 device repo as an example to add the following changes to your APKBUILD.

source="
    ...
    70-halium.rules
    ...
"
subpackages="
	$pkgname-nonfree-userland:nonfree_userland
	$pkgname-hybris
	$pkgname-hybris-x11:hybris_x11
	$pkgname-hybris-phosh:hybris_phosh
	$pkgname-hybris-quirks:hybris_quirks
"


nonfree_userland() {
	pkgdesc="Libhybris (Android 9) hardware adaptation packages"
	depends="$pkgname-hybris"
	mkdir "$subpkgdir"
}

hybris() {
	pkgdesc="Metapackage for libhybris (Android 9) adaptation"
	depends="hybris-gsi-9.0 pulseaudio-modules-droid-9.0 bluebinder"
	mkdir "$subpkgdir"
}

hybris_x11() {
	pkgdesc="X11 modules for libhybris (Android 9) adaptation"
	depends="hybris-base-9.0-x11"
	install_if="$pkgname-hybris libx11"
	mkdir $subpkgdir
}

hybris_phosh() {
	pkgdesc="Phosh configuration for libhybris adaptation"
	install_if="$pkgname-hybris postmarketos-ui-phosh"
	depends="wlroots-hwc2"
        mkdir $subpkgdir
}

# Any quirks or extra packages needed for this port
hybris_quirks() {
	pkgdesc="Fixes for this libhybris adaptation specific quirks"
	depends="hexdump hostapd dnsmasq"
	install_if="$pkgname-hybris"
	mkdir $subpkgdir
}

You can now follow the postmarketOS install guide as normal from the installation section.

Halium 7 based ports

TODO TODO: Halium 7 is theoretically supported, but requires a lot more work as Android 7 devices don't have a vendor partition. This section will be updated when we have more devices to work with, if you want to get postmarketOS booting with halium on your Android 7 device definitely come chat!

See also