diff --git a/Jenkinsfile b/Jenkinsfile index 9da2dbfd3..97c875753 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -2,6 +2,7 @@ pipeline { agent { docker { image "python:3.12" + args '-u root:root' // Run as root to allow package installation } } options { @@ -19,6 +20,19 @@ pipeline { sh 'pip install --quiet --no-cache-dir --user --upgrade -r requirements.txt' } } + stage("Setup Mermaid") { + steps { + script { + try { + def setup = load 'Jenkinsfile.setup-mermaid' + setup.call() + } catch (Exception e) { + echo "Setup Mermaid failed with error: ${e.getMessage()}" + throw e + } + } + } + } stage("Build docs"){ steps { sh 'python3 -m sphinx -Wab html . _build/html/' @@ -29,9 +43,13 @@ pipeline { stage('Fix git ref for non-master builds') { when { not { branch 'master' } } steps { - // Workaround to create the master branch since Jenkins - // refuses to do it on PR builds - sh 'git show-ref --verify --quiet master || git branch master `git show-ref -s origin/master`' + sh ''' + # Add workspace to safe.directory + git config --global --add safe.directory "${WORKSPACE}" + + # Original command + git show-ref --verify --quiet master || git branch master `git show-ref -s origin/master` + ''' } } stage('Check redirects') { @@ -45,4 +63,4 @@ pipeline { cleanWs() } } -} +} \ No newline at end of file diff --git a/Jenkinsfile.setup-mermaid b/Jenkinsfile.setup-mermaid new file mode 100644 index 000000000..7b6a8f9e7 --- /dev/null +++ b/Jenkinsfile.setup-mermaid @@ -0,0 +1,39 @@ +def call() { + sh ''' + set -x + set -e + + echo "Adding NodeSource repository..." + curl -fsSL https://deb.nodesource.com/setup_20.x | bash - + + echo "Updating package lists..." + apt-get update + + echo "Installing Node.js..." + apt-get install -y nodejs + + echo "Installing Chrome dependencies..." + apt-get install -y ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0 \ + libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 \ + libgbm1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 \ + libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 \ + libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 \ + libxss1 libxtst6 wget xdg-utils + + echo "Installing mermaid-cli..." + npm install -g @mermaid-js/mermaid-cli + + echo "Installing Chrome headless shell..." + npx puppeteer browsers install chrome-headless-shell + + echo "Configuring Puppeteer to run with --no-sandbox..." + mkdir -p /root/.config + echo '{ + "args": ["--no-sandbox"] + }' > /root/.config/mmdc-config.json + + echo "Setup completed successfully" + ''' +} + +return this \ No newline at end of file diff --git a/conf.py b/conf.py index d37e61334..724a28c39 100644 --- a/conf.py +++ b/conf.py @@ -32,9 +32,15 @@ # ones. extensions = [ 'sphinx.ext.todo', - 'sphinxext.rediraffe' + 'sphinxext.rediraffe', + 'sphinxcontrib.mermaid' ] +# Mermaid configuration for static image generation +mermaid_output_format = 'svg' +mermaid_cmd = 'mmdc -p /root/.config/mmdc-config.json' +mermaid_verbose = True + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/fundamentals.txt b/fundamentals.txt new file mode 100644 index 000000000..e69de29bb diff --git a/index.rst b/index.rst index c0cb9928a..2bc968448 100644 --- a/index.rst +++ b/index.rst @@ -7,7 +7,7 @@ Welcome to the official documentation of the UBports project! UBports develops the mobile phone operating system Ubuntu Touch. Ubuntu Touch is a mobile operating system focused on ease of use, privacy, and convergence. -On this website you find guides to :doc:`install Ubuntu Touch on your mobile phone `, :doc:`use Ubuntu Touch `, :doc:`develop Ubuntu Touch apps `, :doc:`port Ubuntu Touch to an Android handset ` and :doc:`learn more about system components `. If this is your first time here, please consider reading our :doc:`introduction `. +On this website you find guides to :doc:`install Ubuntu Touch on your mobile phone `, :doc:`use Ubuntu Touch `, :doc:`develop Ubuntu Touch apps `, :doc:`port Ubuntu Touch to an Android handset ` and :doc:`learn more about system components `. If this is your first time here, please consider reading our :doc:`introduction `. If you want to help improving this documentation, :doc:`the Documentation contribute page ` will get you started. @@ -67,11 +67,16 @@ You may view this documentation in the following languages: :caption: Porting :name: sec-porting - porting/introduction/index.rst - porting/build_and_boot/index.rst - porting/configure_test_fix/index.rst - porting/finalize/index.rst - porting/UpdatePortsFor2004.rst + porting/index.rst + porting/fundamentals/index + porting/quick-start/index + porting/preparation/index + porting/modern-porting/index + porting/debugging/index + porting/finalize/index + porting/vendor-specific/index + porting/legacy-porting/index + porting/resources/index .. toctree:: :maxdepth: 1 diff --git a/porting/README.md b/porting/README.md new file mode 100644 index 000000000..319e96fca --- /dev/null +++ b/porting/README.md @@ -0,0 +1,65 @@ +# Ubuntu Touch Porting Guide Development + +This repository contains the development version of the modernized Ubuntu Touch porting guide. +The guide is being reworked by Ari Börde Kröyer, based on the current guide and the Halium Generic +Adaptation Build Tools, and using AI assistance. + +# Notes to the Reader + +My end goal is that this version of the guide can become a drop-in replacement for the current +version of the guide, and serve to help and promote the porting effort. This will require a +coordinated community effort, as I am not sufficiently technically knowledgeable and skilled to +complete this task on my own. + +I therefore ask the reader to keep in mind that what you are seeing is an unfinished product which +may very well contain factual mistakes and errors, and that your ideas and feedback are both welcome +and needed. + +I am making the first version available on November 21, 2024. In an early phase, I encourage readers +to discuss this project on Telegram, in the UBports Porting group (https://t.me/ubports_porting). Feel +free to tag me there when proposing ideas, pointing out errors, etc. Please keep in mind that I have +limited time to spend on this project, so my responses might come with some delay. + + +## Setup Instructions + +1. Install dependencies: +```bash +pip install sphinx furo sphinxext-rediraffe sphinxcontrib-mermaid +``` + +2. Clone the repository: +```bash +git clone https://github.com/abkro/docs.ubports.com porting-guide/ +cd porting-guide +``` + +3. Build the documentation: +```bash +cd porting-guide-work +make html +``` + +4. View the documentation: +- In the `porting-guide-work/` folder, find and open `_build/html/index.html` in your web browser +- Navigate through sections using the sidebar + +## Review Guidelines + +Please review: +- Technical accuracy +- Clarity of instructions +- Logical flow between sections +- Completeness of each section +- Cross-references and navigation + +Submit feedback through: +- Telegram, in the UBports Porting group (https://t.me/ubports_porting) + +## Building Troubleshooting + +If you encounter build errors: +- Ensure all dependencies are installed +- Check Python version (3.6+ required) +- Verify directory structure matches repository +- Check console output for specific error messages diff --git a/porting/UpdatePortsFor2004.rst b/porting/UpdatePortsFor2004.rst deleted file mode 100644 index b157ba279..000000000 --- a/porting/UpdatePortsFor2004.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _UpdatePortsFor2004: - -Update ports for Ubuntu Touch 20.04 -=================================== - -Ubuntu Touch 20.04 introduces a lot of changes underneath, which requires changes from the porters. This document is intended to serve as an overview on how to make your port run on Ubuntu Touch 20.04. However, every port is different, and may require more than what is outlined in this document. We'll be available in `the UBports porting Telegram group `_ to answer any question that might occur during process. - -For GitLab CI-based ports: switch to shared building script & GitLab CI configuration -------------------------------------------------------------------------------------- - -Because of changes in how Ubuntu Touch 20.04's rootfs is made, we need to changes the way device tarballs are built. Instead of cherry-picking script changes from other port's repository, we recommend transitioning to the shared building script. By using the shared script, your port will receive the latest changes in device tarball building as rootfs continues to evolve (e.g. for 22.04 or newer). To transition to the shared script, remove the whole ``build/`` directory, and replace the content of ``build.sh`` with: - -.. code-block:: bash - - #!/bin/bash - set -xe - - [ -d build ] || git clone https://gitlab.com/ubports/community-ports/halium-generic-adaptation-build-tools build - ./build/build.sh "$@" - -You may want to add ``build/`` into your ``.gitignore``. - -And for the same reason, we recommend using the shared GitLab CI configuration so that when the shared script has its requirement changes, your port will not be broken. Using the shared config can be done by replacing the content of ``.gitlab-ci.yml`` with: - -.. code-block:: yaml - - include: - - https://gitlab.com/ubports/porting/community-ports/halium-generic-adaptation-build-tools/-/raw/main/gsi-port-ci.yml - - variables: - BUILD_DEVEL_FLASHABLE_FOCAL: "1" - -The ``variables`` section enables building the flashable partition image from the Focal rootfs, which you might want to leave out for intial porting. - -.. note:: - The script currently doesn't handle the single repository which builds for multiple devices. If your port needs this feature, please upvote `this issue `_. - -If you have custom changes in the build script or in the GitLab CI configuration, you may need to carefully inspect the changes to make sure that your port will still work. Note that you can add additional steps to the GitLab CI configuration and order it after the device tarball building steps, or even overriding some steps (not recommended). - -For GitLab CI-based ports: inspect your overlay in Android partitions ---------------------------------------------------------------------- - -Many ports overlay the files in Android partitions to makes the port work. This is often achived by overlaying the ``mount-android.conf`` Upstart job to either contain the code itself, or to call another script. Since Ubuntu Touch 20.04 no longers use Upstart (see below), the code will no longer run. If your port ships your overlay files under ``/opt/halium-overlay`` or ``/usr/share/halium-overlay``, the new overlay system will take care of it automatically, except when the new file is added in which case you may need ``.halium-overlay-dir`` (see :ref:`Overlay`). - -Alternatively, you may want to consider moving your port completely to use the `overlaystore` system. However the migration is not straight forward and it will make your port incompatible with 16.04 (unless you have another branch). Contact @peat-psuwit in the UBports porting group for more info. - -For Halium 7 ports or older: update bluetooth-touch script ----------------------------------------------------------- - -The way bluetooth-touch script used to work is inherently tied to Upstart. In Ubuntu Touch 20.04, bluetooth-touch is migrated to use Systemd. So, instead of overlaying ``bluetooth-touch-android.conf`` Upstart job, you'll have to overlay ``/usr/share/bluetooth-touch/android.sh``. Note that the script will be run by ``/bin/sh``, so avoid Bash-ism here. - -Halium 9 ports doesn't require this, as Bluebinder replaces ``bluetooth-touch`` by directly talking to HIDL service to provide Bluetooth host interface. - -For everyone: configure usb-moded ---------------------------------- - -usb-moded replaces ``setupusb`` script in setting and managing USB modes. We've written a specific page for that. See :ref:`USBModed`. - -For everyone: check custom Upstart jobs ---------------------------------------- - -Some ports has custom Upstart jobs to do certain things on boot. Those jobs has to be converted to Systemd units in order to run at all in Ubuntu Touch 20.04. One may find `Ubuntu's guide on this topic ` useful. - -Alternatively, instead of writing custom Systemd units, use ``devicehack`` script which will run on every boot after the Android container runs. The path is ``/usr/libexec/lxc-android-config/device-hacks``, and the script will be run with ``/bin/sh``. diff --git a/porting/_static/css/ubports.css b/porting/_static/css/ubports.css new file mode 100644 index 000000000..0304c0877 --- /dev/null +++ b/porting/_static/css/ubports.css @@ -0,0 +1,4 @@ +.parameter-details { + margin-left: 2em; + margin-bottom: 2em; +} \ No newline at end of file diff --git a/porting/_static/images/logo-dark.svg b/porting/_static/images/logo-dark.svg new file mode 100644 index 000000000..e69de29bb diff --git a/porting/_static/images/logo-light.svg b/porting/_static/images/logo-light.svg new file mode 100644 index 000000000..e69de29bb diff --git a/porting/build_and_boot/Boot_debug.rst b/porting/build_and_boot/Boot_debug.rst deleted file mode 100644 index e71271a86..000000000 --- a/porting/build_and_boot/Boot_debug.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _Boot: - -Booting -======= - -In the previous sections you completed building and installing Ubuntu Touch on your device. The next step is to boot the device, gain remote access and debug as necessary. - -What is a successful boot? --------------------------- - -When you boot your build for the first time you will normally not get anything on the screen. This is not necessarily an indication of something gone wrong. Your system may well have booted successfully and this can be ascertained by gaining remote access. - -If your system booted successfully, you will be able to connect to your device from your host using ssh and continue debugging and configuring from there. - -If something went wrong, you should normally be offered a telnet connection through which you can proceed with debugging. If you don't get either of these, the problem might be more difficult to determine. If you get stuck don't hesitate to seek help. - -Gaining remote access ---------------------- - -When your device boots it will likely stay at the bootloader screen. However, you should also get a new network connection on the computer you have it plugged in to. To determine if this is the case, and what type of connection you have been offered, proceed as described below. - -ssh connection -^^^^^^^^^^^^^^ - -To confirm that your device has booted correctly, on your host computer, run dmesg -w and watch for “GNU/Linux device” in the output. This confirms that you can establish an ssh connection to the device (see below). If you instead get something similar to “Halium initrd Failed to boot”, skip to :ref:`telnet`. - -Establish an ssh connection to your device as follows: - -Your computer should now have a newly connected RNDIS interface. Check the output of ``ip link show`` for the device name. The device name will most likely resemble ``enp0s29u1u1``. Assign this device a fake MAC address (if the default one is all 00s) and an IP of 10.15.19.100:: - - ip link set address 02:11:22:33:44:55 - ip address add 10.15.19.100/24 dev - ip link set up - -Once finished, you should be able to login with the following:: - - ssh phablet@10.15.19.82 - -The password will be the one you set when you ran the halium-install script. - -.. _telnet: - -telnet connection -^^^^^^^^^^^^^^^^^ - -If you have been offered a telnet connection the rootfs and system image have likely not been found and mounted at boot time. This may indicate that one or more partitions have not been mounted as they should. Connect to your device with the following command:: - - telnet 192.168.2.15 - -From here you can start debugging to find out what went wrong. Please :ref:`seek help ` to find out how to proceed. diff --git a/porting/build_and_boot/H7_build.rst b/porting/build_and_boot/H7_build.rst deleted file mode 100644 index 4652c10cb..000000000 --- a/porting/build_and_boot/H7_build.rst +++ /dev/null @@ -1,96 +0,0 @@ -Halium-7.1 - Building -===================== - -For Halium-7.1 porting it is necessary to build both halium-boot.img and system.img. - -Initializing the build environment -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -First you need to initialize the environment using the envsetup.sh tool included in your source tree. Enter your BUILDDIR and issue the command:: - - source build/envsetup.sh - -The output will look like this:: - - including device/lge/bullhead/vendorsetup.sh - including vendor/cm/vendorsetup.sh - including sdk/bash_completion/adb.bash - including vendor/cm/bash_completion/git.bash - including vendor/cm/bash_completion/repo.bash - -The ``breakfast`` command is used to set up the build environment for a specific device. From the root of your BUILDDIR run the following, replacing [CODENAME] with your device's specific codename:: - - breakfast [CODENAME] - -Breakfast will attempt to find your device, set up all of the environment variables needed for building, and give you a summary at the end. - -.. _H7_edit-kernel-config: - -Modify the kernel configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The default LineageOS/Halium kernel configuration file needs modifications as Ubuntu Touch requires a slightly different kernel config than Halium, including enabling Apparmor. A script that does this job is provided in your Halium source tree: ``BUILDDIR/halium/halium-boot/check-kernel-config``. - -Locate your configuration file. It should be at ``arch/arm/configs/`` or ``arch/arm64/configs/`` depending on the architecture of your device. If you have trouble finding it, run ``grep "TARGET_KERNEL_CONFIG" device///BoardConfig.mk`` to determine the location. - -Then, from the root of your BUILDDIR, run:: - - ./halium/halium-boot/check-kernel-config path/to/my/defconfig -w - -You may have to do this twice. It will likely fix things both times. Then, run the script without the ``-w`` flag to see if there are any more errors. If there are, fix them manually. Once finished, run the script without the ``-w`` flag one more time to make sure everything is correct. - -Ubuntu Touch requires setting console=tty0 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The halium-boot initramfs expects ``/dev/console`` to be a console device and will not start init if it is not available. This is commonly the case on recent devices, because they either have UART disabled or ``console=`` is not specified (null) by default. This can be fixed by supplying ``console=tty0`` as the last argument in the kernel cmdline. To achieve this, proceed as follows: - -It should be done in the makefile named ``BoardConfig.mk`` (or ``BoardConfigCommon.mk``) located in the root directory of your device tree, e.g. ``~/halium/device///BoardConfig.mk`` - -Add the following line:: - - BOARD_KERNEL_CMDLINE += console=tty0 - -If your makefile already includes a line beginning with ``BOARD_KERNEL_CMDLINE``, you may add it just below that to keep things tidy. - -.. Note:: - The above method, although the preferred one, may not work for some Samsung devices. The result will be that you cannot get access to the device through ssh after boot, and Unity 8 will not be able to start. If you run into this problem, you can specify the setting in your device's kernel config file instead. Add the following lines:: - - CONFIG_CMDLINE="console=tty0" - CONFIG_CMDLINE_EXTEND=y - -.. Note:: - In rare cases the bootloader overwrites the kernel command line argument, rendering the setting above useless. This is the case for the Google Pixel 3a (sargo). To deal with this issue, replicate `this commit `_. - -Build -^^^^^ - -Halium will use the mkbootimg tool for creating the boot image. In most cases it is not on the local harddisk, so it can be built by issuing:: - - mka mkbootimg - -Now build the ``halium-boot.img`` using the commands:: - - export USE_HOST_LEX=yes - mka halium-boot - -.. Note:: - - If you prefer ``make`` instead of ``mka`` you should set ``-j[num]`` for parallel building, which reduces build time. Replace ``[num]`` with the number of threads in your system plus 2. - -Build errors -^^^^^^^^^^^^ - -There are a number of known build errors which you might encounter, depending first of all upon how rigorous you have been in following the steps outlined, but you may also run into unforeseen issues. If your build fails at first, make sure you have done exactly as described, then go through the list of `known errors in the Halium guide `_. - -I your particular error is not listed, you will need to do some research of your own. If you end up here, know that there is a community of porters, developers and enthusiasts who might be able to help you. Refer to :ref:`Getting-community-help`. - -.. _H7_system: - -Building the system image (system.img) --------------------------------------- - -Once you have successfully built halium-boot.img you can proceed to directly to building system.img:: - - mka systemimage - -Likelier than not, you will run into one or more errors along the way when building the system image. A number of possible errors are documented in `the Halium guide `_. If yours is not listed, :ref:`seek community help `. diff --git a/porting/build_and_boot/H7_setup_sources.rst b/porting/build_and_boot/H7_setup_sources.rst deleted file mode 100644 index bb01db03b..000000000 --- a/porting/build_and_boot/H7_setup_sources.rst +++ /dev/null @@ -1,123 +0,0 @@ -Halium-7.1 - Setting up the sources -=================================== - -The sources necessary for the **full system image build** for Halium-7.1. Halium 7 requires a **full system image build**. - -Setting up the sources for Halium-7.1 builds --------------------------------------------- - -Create a directory for your Halium source tree:: - - mkdir halium && cd halium - -This directory will be referred to as BUILDDIR throughout the remainder of this guide. - -First, initialize your source to the correct version of Halium:: - - repo init -u https://github.com/Halium/android -b halium-7.1 --depth=1 - -Then download the code by issuing the command:: - - repo sync -c -j 16 - -The download will take some time as it counts several gigabytes. If you have a fast internet connection, you may set an extra JOBS=[number] environment variable at the beginning of the command to open more parallel downloading jobs. Generally, 12 is recommended, which is the default. When it completes, your BUILDDIR will contain a copy of the Halium source tree, but important parts are still missing. - -Adding your device-specific source ----------------------------------- - -The next step is to add the device-specific sources that need to be integrated into the source tree before you can attempt to build. The missing sources are those required to build the kernel as well as a host of other hardware-specific components of the port. - -The necessary sources need to be located and specified by creating a device manifest file (or editing an existing one) in the directory ``BUILDDIR/halium/devices/manifests``. - -.. Note:: - A correct device manifest is crucial to the success of your port. - -Locating the sources -^^^^^^^^^^^^^^^^^^^^ - -Locate your device repository on `LineageOS’s GitHub organization `_. This is done by typing your device’s codename into the search box. The device repository follows the naming convention: android_device_[manufacturer]_[device]. Make a note of this name. - -Open the device repository on Github. It will contain a ``lineage.dependencies`` (or ``cm.dependencies``) file which specifies all other repositories that your device is reliant upon. - -.. _Note: - During the course of the porting process you will need to make modifications to the device repository as well as one or more of the others specified in ``lineage.dependencies`` (or ``cm.dependencies``). It is therefore adviseable to create a Github account and save your own copy of these by forking them to your account. - -Creating the device manifest file -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Now create (or edit) the file ``BUILDDIR/halium/devices/manifests/[manufacturer]_[device].xml``. (The description below presupposes that you are creating the file from scratch.) - -Paste the following into the file:: - - - - - - -The device repository -""""""""""""""""""""" - -Your sources must now be entered into the manifest. Start with your device repository. Between the and tags, create the line below, making sure to replace the information inside the square brackets with your own:: - - - -'path' specifies the target path (subdirectory of your BUILDDIR) where the source code from repository 'name', which is found at 'remote', will be placed. The repository may contain a number of branches and it is important to secure the correct branch with 'revision=' - -.. Note:: - The revision attribute may be omitted if the default revision for this remote is the one that you wish to use. - -If you are unsure of your remote, refer to :ref:`H7_remotes`. - -Dependencies -"""""""""""" - -Now create more lines like the previous one, using the ``lineage.dependencies`` (or ``cm.dependencies``) file you found earlier in your device repository. This file lists all the remaining repositories needed to build for your selected device. Create one line for each entry in this file, using the following template:: - - - -The target path is found in the repository’s name. The preceding “android” or “proprietary” is omitted and underscores are replaced with slashes. For example, ``android_device_lge_bullhead`` goes in ``device/lge/bullhead``. - -Vendor blobs -"""""""""""" - -Vendor blobs go in the ``vendor/`` folder of your ``BUILDDIR``. - -The first place to search for your device’s vendor blobs is in `'TheMuppets' GitHub organization `_. Enter your device’s codename into the search field and see if you get a match. If you are unable to find your device in TheMuppets, you will need to search elsewhere. - -It may also be possible to extract the vendor blobs from the device itself by following instructions for your device on `the LineageOS wiki `_ as applicable. - -.. _H7_remotes: - -Remotes -""""""" - -A remote entry specifies the name, location (fetch) prefix, code review server, and default revision (branch/tag) for the source. - -You can create a remote by adding a remote tag to your manifest as shown in the following example:: - - - -Only the name, fetch, and revision attributes are required. The review attribute specifies a Gerrit Code Review server, which probably won’t be useful for initial porting purposes. - -For example, let’s say that you have a bunch of repositories at https://github.com/SomeUserName/ and your desired branch name is los-14.1 in each. You would create a remote as follows and place it into your local manifest:: - - - -There are also some remotes available to you by default, though they differ between Halium versions. The following tables will help you identify these. See more information on these remotes can be found at the top of the file ``BUILDDIR/halium/.repo/manifests/default.xml``. - -The following remotes are available by default in Halium 7.1: - -=========== ======================= -Remote Name Remote Description, URL ------------ ----------------------- -aosp Android Open Source Project, https://android.googlesource.com -los LineageOS, http://github.com/LineageOS -hal Halium (link to GitHub root for legacy reasons), http://github.com -them TheMuppets, http://github.com/TheMuppets -them2 TheMuppets (for some xiaomi vendor repos) https://gitlab.com/the-muppets -=========== ======================= diff --git a/porting/build_and_boot/H9_build.rst b/porting/build_and_boot/H9_build.rst deleted file mode 100644 index c635fa456..000000000 --- a/porting/build_and_boot/H9_build.rst +++ /dev/null @@ -1,129 +0,0 @@ -Halium-9.0 - Building -===================== - -When doing a Halium 9.0 port, you first need to build ``halium-boot.img``. This boot image can then either be combined with the GSI, or you can build your own, device-specific ``system.img`` as well. - -Building the boot image (halium-boot.img) ------------------------------------------ - -Initializing the build environment -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -First you need to initialize the environment using the ``envsetup.sh`` tool included in your source tree. Enter your ``BUILDDIR`` and issue the command:: - - source build/envsetup.sh - -The output should resemble this:: - - including device/lge/bullhead/vendorsetup.sh - including vendor/cm/vendorsetup.sh - including sdk/bash_completion/adb.bash - including vendor/cm/bash_completion/git.bash - including vendor/cm/bash_completion/repo.bash - -The ``breakfast`` command is used to set up the build environment for a specific device. From the root of your ``BUILDDIR`` run the following command, replacing [CODENAME] with your device's specific codename:: - - breakfast [CODENAME] - -Breakfast will attempt to find your device, set up all of the environment variables needed for building, and give you a summary at the end. - -.. _H9_edit-kernel-config: - -Modify the kernel configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The default LineageOS/Halium kernel configuration file needs modifications as Ubuntu Touch requires a slightly different kernel config than Halium, including enabling Apparmor. A script that does this job is provided in your Halium source tree: ``BUILDDIR/halium/halium-boot/check-kernel-config``. - -Locate your configuration file. It should be at ``arch/arm/configs/`` or ``arch/arm64/configs/`` depending on the architecture of your device. If you have trouble finding it, run ``grep "TARGET_KERNEL_CONFIG" device///BoardConfig.mk`` to determine the location. - -Then, from the root of your ``BUILDDIR``, run:: - - ./halium/halium-boot/check-kernel-config path/to/my/defconfig -w - -You may have to do this twice. It will likely fix things both times. Then, run the script without the ``-w`` flag to see if there are any more errors. If there are, fix them manually. Once finished, run the script without the ``-w`` flag one more time to make sure everything is correct. - -Ubuntu Touch requires setting console=tty0 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The halium-boot initramfs expects ``/dev/console`` to be a console device and will not start init if it is not available. This is commonly the case on recent devices, because they either have UART disabled or ``console=`` is not specified (null) by default. This can be fixed by supplying ``console=tty0`` as the last argument in the kernel cmdline. To achieve this, proceed as follows: - -It should be done in the makefile named ``BoardConfig.mk`` (or ``BoardConfigCommon.mk``) located in the root directory of your device tree, e.g. ``~/halium/device///BoardConfig.mk`` - -Add the following line:: - - BOARD_KERNEL_CMDLINE += console=tty0 - -If your makefile already includes a line beginning with ``BOARD_KERNEL_CMDLINE``, you may add it just below that to keep things tidy. - -.. Note:: - The above method, although the preferred one, may not work for some Samsung devices. The result will be that you cannot get access to the device through ssh after boot, and Unity 8 will not be able to start. If you run into this problem, you can specify the setting in your device's kernel config file instead. Add the following lines:: - - CONFIG_CMDLINE="console=tty0" - CONFIG_CMDLINE_EXTEND=y - -.. Note:: - In rare cases the bootloader overwrites the kernel command line argument, rendering the setting above useless. This is the case for the Google Pixel 3a (sargo). To deal with this issue, replicate `this commit `_. - -Setting system as root -^^^^^^^^^^^^^^^^^^^^^^ - -For Halium 9, we need the system image to be built as system-as-root (for treble devices it should already be there). Please check your ``boardconfig.mk`` for the following line, if it's there you can skip this step:: - - BOARD_BUILD_SYSTEM_ROOT_IMAGE := true - -If the above is not there, we have to add it. - -As this change makes the android root read-only, we may have to ship mount points for some important partitions like ``firmware``, ``persist`` with the system image, for this we can use the line:: - - BOARD_ROOT_EXTRA_FOLDERS := \ - /firmware \ - /dsp \ - /persist - -.. Note:: - For now this is enough, but you may need to add more mount points depending on your device. After successful boot do ``ls -la /`` and add folders corresponding to broken symlinks. - -These changes may also bring in some context errors,please refer `this commit to fix them `_. - - -Build -^^^^^ - -Halium will use the ``mkbootimg`` tool for creating the boot image. In most cases it is not on the local harddisk, so it can be built by issuing:: - - mka mkbootimg - -Now build the ``halium-boot.img`` using the commands:: - - export USE_HOST_LEX=yes - mka halium-boot - -.. Note:: - - If you prefer ``make`` instead of ``mka`` you should set ``-j[num]`` for parallel building, which reduces build time. Replace ``[num]`` with the number of threads in your system plus 2. - -Build errors -^^^^^^^^^^^^ - -There are a number of known build errors which you might encounter, depending first of all upon how rigorous you have been in following the steps outlined, but you may also run into unforeseen issues. If your build fails at first, make sure you have done exactly as described, then go through the list of `known errors in the Halium guide `_. - -If your particular error is not listed, you will need to do some research of your own. If you end up here, know that there is a community of porters, developers and enthusiasts who might be able to help you. Refer to :ref:`Getting-community-help`. - -.. _H9_system: - -Building the system image (system.img) --------------------------------------- - -If you are using the **Halium-boot** method, you can skip this step. -If you are following the **Full system image** method, this step is required. - -Halium will use the ``e2fsdroid`` tool for creating the system image. In most cases it is not on the local harddisk, so it can be built by issuing:: - - mka e2fsdroid - - -To build the system image:: - - mka systemimage - -It's likely that you will run into one or more errors when building the system image. A number of possible errors and known solutions are documented in `the Halium guide `_. If yours is not listed, :ref:`seek community help `. diff --git a/porting/build_and_boot/H9_setup_sources.rst b/porting/build_and_boot/H9_setup_sources.rst deleted file mode 100644 index a84b6a0ab..000000000 --- a/porting/build_and_boot/H9_setup_sources.rst +++ /dev/null @@ -1,145 +0,0 @@ -Halium-9.0 - Setting up the sources -=================================== - -Initializing and downloading the Halium source ----------------------------------------------- - -Create a directory for your Halium source tree:: - - mkdir halium && cd halium - -This directory will be referred to as BUILDDIR throughout the remainder of this guide. - -First, initialize your source to the correct version of Halium, depending on your device. If in doubt, refer to :ref:`Android-and-Halium-versions`. - -For Halium 9.0:: - - repo init -u https://github.com/Halium/android -b halium-9.0 --depth=1 - -With the Halium tree initialized you are ready to download the code by issuing the command:: - - repo sync -c -j 16 - -The download will take some time as it counts several gigabytes. If you have a fast internet connection, you may set an extra JOBS=[number] environment variable at the beginning of the command to open more parallel downloading jobs. Generally, 12 is recommended, which is the default. When it completes, your BUILDDIR will contain a copy of the Halium source tree, but important parts are still missing. - -Adding your device-specific source ----------------------------------- - -The next step is to add the device-specific sources that need to be integrated into the source tree before you can attempt to build. The missing sources are those required to build the kernel as well as a host of other hardware-specific components of the port. - -The necessary sources need to be located and specified by creating a device manifest file (or editing an existing one) in the directory ``BUILDDIR/halium/devices/manifests``. - -.. Note:: - A correct device manifest is crucial to the success of your port. - -Locating the sources -^^^^^^^^^^^^^^^^^^^^ - -Locate your device repository on `LineageOS’s GitHub organization `_. This is done by typing your device’s codename into the search box. The device repository follows the naming convention: android_device_[manufacturer]_[device]. Make a note of this name. - -Open the device repository on Github. It will contain a ``lineage.dependencies`` (or ``cm.dependencies``) file which specifies all other repositories that your device is reliant upon. - -.. _Note: - During the course of the porting process you will need to make modifications to the device repository as well as one or more of the others specified in ``lineage.dependencies`` (or ``cm.dependencies``). It is therefore adviseable to create a Github account and save your own copy of these by forking them to your account. - -Creating the device manifest file -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Now create (or edit) the file ``BUILDDIR/halium/devices/manifests/[manufacturer]_[device].xml``. (The description below presupposes that you are creating the file from scratch.) - -Paste the following into the file:: - - - - - - -The device repository -""""""""""""""""""""" - -Your sources must now be entered into the manifest. Start with your device repository. Between the ```` and ```` tags, create the line below, making sure to replace the information inside the square brackets with your own:: - - - -'path' specifies the target path (subdirectory of your BUILDDIR) where the source code from repository 'name', which is found at 'remote', will be placed. The repository may contain a number of branches and it is important to secure the correct branch with 'revision=' - -.. Note:: - The revision attribute may be omitted if the default revision for this remote is the one that you wish to use. - -If you are unsure of your remote, refer to :ref:`H9_remotes`. - -Dependencies -"""""""""""" - -Now create more lines like the previous one, using the ``lineage.dependencies`` (or ``cm.dependencies``) file you found earlier in your device repository. This file lists all the remaining repositories needed to build for your selected device. Create one line for each entry in this file, using the following template:: - - - -The target path is found in the repository’s name. The preceding “android” or “proprietary” is omitted and underscores are replaced with slashes. For example, android_device_lge_bullhead goes in device/lge/bullhead. - -Vendor blobs -"""""""""""" - -Vendor blobs go in the vendor/ folder of your BUILDDIR. - -The first place to search for your device’s vendor blobs is in `'TheMuppets' GitHub organization `_. Enter your device’s codename into the search field and see if you get a match. If you are unable to find your device in TheMuppets, you will need to search elsewhere. - -It may also be possible to extract the vendor blobs from the device itself by following instructions for your device on `the LineageOS wiki `_ as applicable. - -.. _H9_remotes: - -Remotes -""""""" - -A remote entry specifies the name, location (fetch) prefix, code review server, and default revision (branch/tag) for the source. - -You can create a remote by adding a remote tag to your manifest:: - - - -(Note: The above is merely an example and cannot be used as such for Halium-9.0) - -Only the name, fetch, and revision attributes are required. The review attribute specifies a Gerrit Code Review server, which probably won’t be useful for initial porting purposes. - -For example, let’s say that you have a bunch of repositories at https://github.com/SomeUserName/ and your desired branch name is los-16.0 in each. You would create a remote as follows and place it into your local manifest:: - - - -There are also some remotes available to you by default, though they differ between Halium versions. The following tables will help you identify these. See more information on these remotes can be found at the top of the file BUILDDIR/halium/.repo/manifests/default.xml. - -The following remotes are available by default in Halium 9.0: - -=========== ======================= -Remote Name Remote Description, URL ------------ ----------------------- -github LineageOS, https://github.com/ -gitlab Gitlab, https://about.gitlab.com/ -aosp Android Open Source Project, https://android.googlesource.com -=========== ======================= - -If you do not specify a remote, aosp is assumed. - -Sync and apply hybris patches -""""""""""""""""""""""""""""" - -With your manifest now complete, go to the root of your ``BUILDDIR`` and issue the following command (replace DEVICE with your device’s codename) to bring the device-specific source code into your source tree:: - - ./halium/devices/setup DEVICE - -This will first link your manifest from Halium devices to ``.repo/local_manifests/device.xml`` and then sync all repositories. - -Once complete you can now run a script to apply hybris patches. These are mainly used for building the system image and can be omitted if your goal is to only build ``halium-boot.img``. However, if you run into build errors, it might be worthwhile to try applying these patches all the same. - -From the root of your BUILDDIR, run the following command:: - - hybris-patches/apply-patches.sh --mb - -Document -"""""""" - -After completing the relevant steps above (according to your chosen, create a pull request containing your device manifest on the Halium devices repository. Also, create a device page on the UBports page under devices. You should link the manifest on Halium devices in your UBports device page. \ No newline at end of file diff --git a/porting/build_and_boot/Halium_install.rst b/porting/build_and_boot/Halium_install.rst deleted file mode 100644 index b43da6c5c..000000000 --- a/porting/build_and_boot/Halium_install.rst +++ /dev/null @@ -1,74 +0,0 @@ -Installing Halium-based builds -============================== - -With the necessary compontents built, you are now ready to install them on your device and check whether they function as intended. There are only minor differences between Halium versions when it comes to the installation process. In all cases, the system image and rootfs are installed together on the userdata partition of the device. This is done for practical reasons, as it makes the installation process simpler to manage during the first phases of the porting process. Once the port reaches the level of maturity required for it to be offered through the UBports installer (see :ref:`Finalize`), this must be changed in order to reserve a maximum of possible space for userdata. - -In brief: - - * **Halium-7.1** requires installing the boot image and system image you have built, together with the UBports rootfs, which you need to download. - * **Halium-9.0 and newer** require installing the boot image you have built together with the GSI and the UBports rootfs. Both the GSI and the rootfs are available for download. Note: If you chose to build your own system.img, then you must use this instead of the GSI when installing. - -In order to install Ubuntu Touch, you need a recovery image with Busybox, such as TWRP, installed on your phone. If you have not done so yet, refer to section :ref:`Install-TWRP-recovery` and install it now. - -You will also need to ensure the ``/data`` partition is formatted with ``ext4`` and is not encrypted. Boot into recovery, check and adjust as necessary. - -.. _Flash-boot: - -Flashing halium-boot.img ------------------------- - -To install halium-boot, reboot your phone into fastboot mode. Then do the following from the root of your ``BUILDDIR``:: - - cout - fastboot flash boot halium-boot.img - -If you have trouble accessing your device in fastboot mode, but are able to access it in TWRP recovery mode using adb, then boot into recovery mode and try the following alternative method:: - - cout - adb push halium-boot.img /tmp/ - -On your device, choose *Install* in the TWRP menu, navigate to the ``/tmp`` directory, choose *Image*, select your image file, select *Boot* and swipe to flash. - -.. Note:: - Samsung devices: Flashing halium-boot.img on Samsung devices is done using the Heimdall flashing utility (on Linux) or the Odin utility (on Windows) after first bringing the device into 'download mode'. See more information on these utilities `here `_. Follow the instructions for the utility you choose, including the specific flashing command for flashing the boot partition. Install system.img and rootfs (below) with the device in recovery mode. - -.. _Inst-sys: - -Installing system image and rootfs ----------------------------------- - -**Read carefully** and perform only the steps which apply to your Halium version and the files you will be flashing! - -Download the appropriate rootfs -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Start by downloading the appropriate rootfs for your device. You need a rootfs corresponding to your device's architecture and the Halium version you have built. At the moment there are two available versions for Halium 7.1, an armhf (32 bit) version and an arm64 (64 bit) version. For Halium 9.0 there is only an arm64 rootfs available. Follow the appropriate link below to download the one you need. - - * Halium 7.1, armhf (32 bit): `ubports-touch.rootfs-xenial-armhf.tar.gz `_ - * Halium 7.1, arm64 (64 bit): `ubuntu-touch-hybris-xenial-arm64-rootfs.tar.gz `_ - * Halium 9.0, armhf (32 bit): `ubuntu-touch-android9-armhf.tar.gz `_ - * Halium 9.0, arm64 (64 bit): `ubuntu-touch-android9-arm64.tar.gz `_ - -Download the halium-install script -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Clone or download the `halium-install repository `_. This repository contains tools that can be used to install a Halium system image and distribution rootfs. -Reboot your device to recovery (e.g. TWRP), to get adb access again. Now use the ``halium-install`` script to install Ubuntu Touch on your device. - -Perform the installation -^^^^^^^^^^^^^^^^^^^^^^^^ - -For **Halium 7.1 ports** use the following command:: - - path/to/halium-install -p ut path/to/rootfs.tar.gz path/to/system.img - -For **Halium 9.0 ports**, use this command:: - - path/to/halium-install -p ut -s path/to/ubuntu-touch-android9-arm64.tar.gz path/to/[SYSTEM_IMAGE] - -where [SYSTEM_IMAGE] will be the file ``android-rootfs.img`` you downloaded and extracted, or alternatively the file ``system.img`` you built yourself. - -The script will copy and extract the files to their proper places, then allow you to set the user password for your device (the *phablet* user's password). - -.. Note:: - halium-install might fail due to unconfigured bintfmt-support for qemu throwing errors such as 'chroot: failed to run command ‘passwd’: Exec format error'. To fix this, ``/proc/sys/fs/binfmt_misc/register`` should be updated. `binfmt-manager `_ by `@mikkeloscar `_ can provide quickfix. diff --git a/porting/build_and_boot/index.rst b/porting/build_and_boot/index.rst deleted file mode 100644 index 32cbfdb23..000000000 --- a/porting/build_and_boot/index.rst +++ /dev/null @@ -1,47 +0,0 @@ -Building and booting -==================== - -Now it's time to download and configure the necessary source code. -Then we'll build it and get it to boot. -Firstly follow the **Building** steps for your Halium version and porting method. -Secondly, proceed with the final **Install and boot** section. - - -Building --------- - -Full system image method or Halium-boot method -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you are using either of the **Full system image** method (for Halium 7.1 or 9.0), -or the **Halium-boot** method (for Halium 9.0), -then please pick the two steps below matching your Halium version. - -.. toctree:: - :maxdepth: 1 - - H7_setup_sources - H7_build - H9_setup_sources - H9_build - -Standalone kernel method -^^^^^^^^^^^^^^^^^^^^^^^^ - -If you are using the **Standalone kernel** method, then please pick the step below. - -.. toctree:: - :maxdepth: 1 - - standalone_kernel_build - -Install and boot ----------------- - -Afterwards, proceed with these steps for any porting method. - -.. toctree:: - :maxdepth: 1 - - Halium_install - Boot_debug diff --git a/porting/build_and_boot/standalone_kernel_build.rst b/porting/build_and_boot/standalone_kernel_build.rst deleted file mode 100644 index 919f452dd..000000000 --- a/porting/build_and_boot/standalone_kernel_build.rst +++ /dev/null @@ -1,486 +0,0 @@ -.. _Gitlab-CI: - -Standalone Kernel Method (Halium 9 and newer) -============================================= - -Starting from Halium 9, it is possible to port a device using only the kernel. This involves a number of scripts that build the kernel, download the generic container image and rootfs, and create flashable images. - -This guide expects you to have some mandatory git knowledge, like cloning and pushing, and creating repos. - -Setting up your build environment ---------------------------------- - - -Assuming you have already installed the tools specified in the section on :ref:`Setting-up`, there are just a few more to add before your build environment is complete. Run this commmand to add them:: - - sudo apt install bc bison build-essential \ - ca-certificates cpio curl flex git kmod libssl-dev libtinfo5 python2 \ - sudo unzip wget xz-utils img2simg jq - -If you use a RPM based distro such as Mageia, you run:: - - sudo urpmi gcc make glibc-devel bc bison \ - rootcerts cpio curl flex git kmod libopenssl-devel libncurses5 python3 \ - unzip wget xz img2simg jq - -Setting up and configuring a device source ------------------------------------------- - -Creating the device source -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Clone an existing repo for a device from https://gitlab.com/ubports/community-ports. Ideally choose a device with similar SoC/Android version as base. - -deviceinfo contains the configuration used during device build process (kernel, boot, dtb/dtbo if needed + recovery on later porting stages). To craft your own deviceinfo, follow the guide further. - -Getting device kernel source code -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -First thing to check is if your device has an official or unofficial LineageOS port, as the porter may have already done the cleaning up bits needed for the device vendor kernel sources or incorporated out-of-tree kernel modules back into kernel tree, which makes life easier for us. - -If not, check if device manufacturer provides kernel source at all: -ASUS, Lenovo, Samsung, ZTE usually provide kernel source code tarballs at their website. -Motorola, Realme, OnePlus, Xiaomi usually upload kernel source to their official GitHub account. - -After you have acquired the kernel source, you need to upload it somewhere else for making modifications and commits for Ubuntu Touch. GitLab is preferred since when you'll get the port pulled into the UBports org, it can be easily copied from there. - -Finding your correct kernel config -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -There are two ways to find your correct kernel config, naming some below: -1. Getting your config on device from /proc/config.gz -2. Getting your defconfig in kernel source - -Getting your config from device -""""""""""""""""""""""""""""""" - -It is possible to pull your current kernel config from device, if the configuration is present as ``/proc/config.gz`` on device. To pull this config, copy the ``/proc/config.gz`` file from your device to your computer. -Then, run ``zcat`` on the file to get its output. Save this as ``.config`` in your kernel source. -After this, run ``ARCH= make savedefconfig``, which will convert your fully fledged config into a defconfig. -Copy ``defconfig`` to ``arch//configs/_defconfig``, or something weird like ``k61v64_debug_defconfig``. -If you got your kernel source from an OEM, sometimes it includes a ``build.sh`` script which references the defconfig required. -Otherwise if you got your kernel source from somewhere like LineageOS, their device tree's reference the defconfig too. - -After finding your defconfig, proceed with the guide to patch it. - - -Applying minimal patches to your defconfig -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In order for Ubuntu Touch to successfully boot, we need to enable some configs required by the OS. -Start by browsing into your kernel directory, and into the ``arch//configs``, where you will have to add a new file called ``halium.config``. -In this file, add the following content: - -| CONFIG_DEVTMPFS=y -| CONFIG_FHANDLE=y -| CONFIG_SYSVIPC=y -| CONFIG_IPC_NS=y -| CONFIG_NET_NS=y -| CONFIG_PID_NS=y -| CONFIG_USER_NS=y -| CONFIG_UTS_NS=y -| CONFIG_VT=y - -After this, save and close this file. Commit it into your kernel repo if you wish, because this config name will be added in deviceinfo. - -At this point you've almost completed the initial setup for the kernel, move on to configuring ``deviceinfo`` and building. - -After you have booted the OS successfully, you can move on to patching the defconfig fully in later stages. - -Filling in your deviceinfo -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* Full device name, like Redmi 9C or Redmi Note 10S. Replace as necessary. - -``deviceinfo_name="Redmi 9C"`` - - -* The name of the device's manufacturer. Change as needed. - -``deviceinfo_manufacturer="Xiaomi"`` - - -* The codename of the phone. This can be obtained by googling for it like: " codename". Replace device name with your phone's full name. Replace the codename below with your own too. - -``deviceinfo_codename="angelica"`` - - -* The architecture of your kernel. Most devices released after 2015 have an ARM64 CPU, but some oddities in between can still be armhf. For ARM64 devices, set the config to "aarch64". For armhf devices, set the config to "armv7". - -``deviceinfo_arch="aarch64"`` - - -* This defines the git repo where your kernel is located. You already should have this link at hand if you followed section 1, if not go through it again. Replace below link with your own. - -``deviceinfo_kernel_source="https://github.com/muhammad23012009/android_kernel_xiaomi_dandelion"`` - - -* The branch of the kernel comes next. This can be easily obtained by looking at the tab under the Code tab on GitHub or the tab on the top left side in GitLab. Replace as necessary. - -``deviceinfo_kernel_source_branch="halium10-new"`` - - -* Defconfig is a vital part of the kernel compilation process. Most of the times you can find this defconfig in your kernel source, the path to which is "arch//configs". The defconfig's name is often built up like "_defconfig". After finding your defconfig, replace it as necessary. - You also need to add ``halium.config`` in this field, due to adding the kernel config patches above. - (If you still can't find the defconfig refer to section "Finding your defconfig") - -``deviceinfo_kernel_defconfig="angelica_defconfig halium.config"`` - - -* The kernel cmdline is one of the key things that is required to make the kernel boot. It has special parameters that allow the kernel to determine which features/things need to be enabled, and which need to be disabled. The Ubuntu Touch rootfs also relies on some key cmdlines which is required to boot, most specifically "console=tty0". To adapt this to your device, try unpacking your boot image (section 8.3) and copying the cmdline from there, or take the help of a LineageOS device tree if it is available. "console=tty0" is a must for cmdline and should not be removed no matter what. Rest of the things can be removed and you can adjust these to your device. - ``console=tty0`` is a requirement for the rootfs to properly boot. ``systempart`` is added if you want to boot your rootfs from your system partition. It is supposed to point to your system partition. - -``deviceinfo_kernel_cmdline="console=tty0 bootopt=64S3,32N2,64N2 systempart=/dev/mapper/system"`` - - -* Add this to your deviceinfo if you wish to compile your kernel with clang. Most devices released with and after Android 10 build their kernels with clang. If you don't want to build with clang, omit this entry entirely. - -``deviceinfo_kernel_clang_compile="true"`` - - -* Only required if you wish to use LLD as your linker and enable LTO. For most old kernels LTO is broken. - If you do want to use it add this entry to your deviceinfo, else omit it. - -``deviceinfo_kernel_use_lld="true"`` - - -* This config allows you to compile your kernel with LLVM and LTO, granted that it's supported by it. - This is a neat way of specifying ``clang`` and ``ld.lld`` together. - Usually needed by GKI devices. - (Once enabled, you do not needed to specify ``deviceinfo_kernel_use_lld``) - -``deviceinfo_kernel_llvm_compile="true"`` - - -* Use this to enable 'dtc_ext' for compiling your dtb/dtbo's. Use only if you know what you're doing. The default compiler works most of the times. - -``deviceinfo_kernel_use_dtc_ext="true"`` - - -* Use this option to specify the kernel image name after kernel compiles. More than often this option is simply not required, so you can drop it from your deviceinfo. If you do need it, adjust image name as necessary. - -``deviceinfo_kernel_image_name="Image.gz"`` - - -* In order to specify your ramdisk compression algorithm, use the below option. It is set to gzip by default. - Mostly useful for GKI devices. - -``deviceinfo_ramdisk_compression="lz4"`` - - -* Add this option to specify your Halium version. Up to Halium 13 is supported at this moment. - -``deviceinfo_halium_version="11"`` - - -* This option defines the boot image header version. It is important you get this right, else your device may not boot. Devices launching with Android versions below 8 (Oreo) use header 0, Android 9 (Pie) uses version 1, Android 10 uses version 2, and GKI devices use version 3/4 (depending on Android version which they were released, Android 12 with GKI uses version 4). - -``deviceinfo_bootimg_header_version="2"`` - - -* Use this option to define a prebuilt dtb that you have sourced. Path is relative to your directory where you are editing the deviceinfo file. Edit the dtb name according to what you have. - If your header version is greater than or equal to 3 (GKI device), this will include dtb in your vendor_boot. - -``deviceinfo_bootimg_prebuilt_dtb="mt6765.dtb"`` - - -* This option uses the dtb's created by your kernel while compiling, multiple dtb's can be specified here like: - "mediatek/mt6765.dtb mediatek/angelica.dtb" - The path in which the scripts look for the dtb's with this option enabled is "KERNEL_OBJ/arch//boot/dts" where will either be arm64 or arm depending on what you set in deviceinfo_arch (aarch64 is arm64 in kernel speak) - If your header version is greater than or equal to 3 (GKI device), this will include dtb in your vendor_boot. - -``deviceinfo_dtb="mediatek/mt6765.dtb"`` - - -* Selecting this will build a DT image that you selected into the boot image. Path is relative to your current directory in which you're editing deviceinfo. (Note: This is only really required in Samsung/Exynos devices.) - -``deviceinfo_bootimg_prebuilt_dt="exynos8890-dt.img"`` - - -* Use this to ship a prebuilt dtbo in your OTAs and to build your recovery with this dtbo if it isn't already being compiled. Path is once again relative to your build directory. Edit as desired. - -``deviceinfo_prebuilt_dtbo="angelica-dtbo.img"`` - - -* In case you do not want to ship the DTBO image in an OTA, selecting this will only remove the dtbo from the OTA package but recovery will still be compiled with this dtbo, if dtbo isn't already being compiled. - -``deviceinfo_skip_dtbo_partition="true"`` - - -* If you want to compile your DTBO from kernel, use this option to select the dtbo files compiled in kernel out directory. The path in which this option will search is KERNEL_OBJ/arch//boot/dts. - Multiple dtbo's can be supplied like shown in the example. Adapt the names as per your requirements. The resulting dtbo image will be shipped in the OTA if the skip_dtbo_partition option isn't selected, and in any case recovery will also be built with this dtbo. This option is incompatible with the prebuilt dtbo option. - -``deviceinfo_dtbo="mediatek/galahad.dtbo mediatek/lancelot.dtbo"`` - - -* Using this will define the board name in your boot image, which some bootloaders require to boot the image successfully. Only use this option if your stock boot image has this flag set in its header. Edit as you wish if necessary. - -``deviceinfo_bootimg_board="EXYNOS4412"`` - - -* Use this option to pad your boot image to a specific size. Also required if you want to append a vbmeta image or append a hash footer to your image. Change the size to your stock boot image size. (Note: The size is declared in bytes). - -``deviceinfo_bootimg_partition_size="67713847"`` - - -* Pretty self-explanatory. Set it to true if your device requires a vbmeta image appended (Not the case for most devices with a dedicated vbmeta partition.) - -``deviceinfo_bootimg_append_vbmeta="true"`` - - -* Use this option when you want to create a recovery.img for booting UBports recovery (Only really required when you're finalizing the port). In most cases you'll want to omit this in the start of your port and add it as you try to get it in installer. Setting to true builds the recovery and setting to false or omitting the entry entirely will cause it to not build at all. - -``deviceinfo_has_recovery_partition="true"`` - - -* Use this to pad your recovery image to a specific size. Also a requirement if you want to add a hash footer to your image. Replace the size from your stock recovery image. (Will only work if you're building recovery!) - -``deviceinfo_recovery_partition_size="67713847"`` - - -* This is only really required for some old/new Samsung that check for an "SEAndroid" footer on their boot images to check whether or not the boot images are official. If the bootloader doesn't find it it results in an ugly looking red line on the top of the screen. Adding this to your deviceinfo will append this string to the boot image. (Beware! Using this on other devices may cause it to not boot the image!) - -``deviceinfo_bootimg_tailtype="SEAndroid"`` - - -* This config determines whether modules should be compiled and installed into rootfs or not. Omitting this config results in the default behaviour, i.e., modules get compiled and installed into rootfs. Adding this option to your deviceinfo and setting it to true (like shown) will disable modules compilation. Only really needed in case you're doing something advanced. - -``deviceinfo_kernel_disable_modules="true"`` - - -* This option installs all overlay files (in overlay/ directory) into /system/opt/halium-overlay, therefore overlaying the files onto the files present in rootfs instead of completely replacing them. This is necessary for 20.04 and onwards, but not applicable for 16.04. - -``deviceinfo_use_overlaystore="true"`` - - -* This option is mostly used on some Qualcomm devices. Adding this to your deviceinfo will combine all your dtbo's with your dtbs. Only use if you are sure you need this. - -``deviceinfo_kernel_apply_overlay="true"`` - - -* Add this configuration to your deviceinfo when you need to specify a fixed size for your rootfs being flashed to system image. Default is 3000M when option is not set. Only use if you need it. - -``deviceinfo_system_partition_size="4000M"`` - - -* This config is only relevant for newer devices launched with UFS storage - -``deviceinfo_rootfs_image_sector_size="4096"`` - - -* Next up are flash offsets. You can ignore these if you're building only boot.img for a GKI device, but are required if you want to build vendor_boot.img. These offsets will automatically apply for vendor_boot if your header version is greater than or equal to 3. - A guide to extract them is as follows: - -Extracting values from stock boot.img/vendor_boot.img -""""""""""""""""""""""""""""""""""""""""""""""""""""" - -For any port to boot, some values must be pulled from the stock boot.img. First and foremost, try to get your stock firmware. Some manufacturers like Samsung like to encrypt their firmwares, but still some tools are available to get them. Others like Xiaomi provide the firmware, but you need to use Google to search it. And then there's the good guy Google, who provide full firmware binaries easily accessible. Long story short, you need to at least find your stock firmware, and then get the boot.img. Once you have the boot.img acquired, follow the following steps: - - - * Make a directory in which you'll store all your unpacked data. It can be anywhere, and can have any name. For now, we'll call it `temp`. - - * Run "mkdir ~/temp" to create the directory and "cd ~/temp" to go to it. - - * Now to unpack the boot image there are several utilities to do so. One of them is the python script provided by Android. For now we'll use this. To download it into your current working directory run "wget https://raw.githubusercontent.com/LineageOS/android_system_tools_mkbootimg/lineage-19.1/unpack_bootimg.py" This will download the unpack_bootimg.py script, which you'll now use to pull your kernel offsets and other values alike - - * Bring your boot.img into the temp directory. - - * Now run the script. The usual syntax is "python3 unpack_bootimg.py --boot_img --out out" This will unpack the boot image, store the output files in the out directory, and it will also print the offsets on screen. - - -A sample output for boot.img will look like this: - - boot magic: ANDROID! - - kernel_size: 11399060 - - kernel load address: 0x40080000 - - ramdisk size: 6576255 - - ramdisk load address: 0x51b00000 - - second bootloader size: 0 - - second bootloader load address: 0xc0ff0000 - - kernel tags load address: 0x47880000 - - page size: 2048 - - os version: 10.0.0 - - os patch level: None - - boot image header version: 2 - - product name: - - command line args: bootopt=64S3,32N2,64N2 buildvariant=user systempart=/dev/mapper/system:ro - - additional command line args: - - recovery dtbo size: 0 - - recovery dtbo offset: 0x0000000000000000 - - boot header size: 1660 - - dtb size: 216417 - - dtb address: 0x0000000047880000 - - -whereas for vendor_boot.img, will look like this: - - boot magic: VNDRBOOT - - vendor boot image header version: 4 - - page size: 0x00001000 - - kernel load address: 0x10008000 - - ramdisk load address: 0x10000000 - - vendor ramdisk total size: 13685168 - - vendor command line args: bootconfig loop.max_part=7 - - kernel tags load address: 0x10000000 - - product name: SRPUK23A007 - - vendor boot image header size: 2128 - - dtb size: 231604 - - dtb address: 0x0000000011f00000 - - vendor ramdisk table size: 216 - - vendor bootconfig size: 28 - - - * Here's where this will get interesting. - - * "kernel load address" is the kernel offset. The value after the colon is what you need, for example, 0x40080000. This will be different in your case. - - * "ramdisk load address" will be your ramdisk offset. Take the value next to it. For example, 0x51b00000. - - * "second bootloader load address" is mostly unnecessary by today's standards. But if your boot image does spit this value, make sure to take it. For example, 0xc0ff0000. - - * "kernel tags load address" is a special one. It's used for both kernel tags and dtb, but in some cases these values can be different. Take the value as well. For example, 0x47880000. - - * "dtb address" is sometimes the same as "kernel tags load address". But if it's different, you should use this for dtb and tags for tags. - - * "page size" is required for the ramdisk to know what your flash chip uses for page sizes. Value after colon is what you need. For example, 2048. - - * "os version" is the value which determines which Android version this boot.img has. Some bootloaders enforce this. For example, 10.0. - - * "os patch level" is a similar story. You'll also want to grab this value, for example, 2021-11. - - * "command line args" go straight into deviceinfo_kernel_cmdline. Make sure to keep "console=tty0" in there. No examples here :( - - * If you're building vendor_boot, this command will also output a ``bootconfig`` file in your output directory. Move this to your source tree's root. - - * Apart from these mentioned values, you'll want to skip everything else. - - -Now according to said guide, fill in your offsets: - - -* Put the value from "page size" into this config. - -``deviceinfo_flash_pagesize="2048"`` - - -* Base offset will always remain 0x00000000. - -``deviceinfo_flash_offset_base="0x00000000"`` - - -* Fill this in from "kernel load address". - -``deviceinfo_flash_offset_kernel="0x40080000"`` - - -* This gets its value from "ramdisk load address". - -``deviceinfo_flash_offset_ramdisk="0x51b00000"`` - - -* Although not mission critical, if you did get its value, fill it in from "second bootloader load address". - -``deviceinfo_flash_offset_second="0xc0ff0000"`` - - -* Tags should be filled in from "kernel tags load address". - -``deviceinfo_flash_offset_tags="0x47880000"`` - - -* DTB offset comes from "dtb load address". - -``deviceinfo_flash_offset_dtb="0x47880000"`` - - -* This comes from "os version". Not exactly required but some OEMs enforce it. - -``deviceinfo_bootimg_os_version="10.0"`` - - -* You'll want to put the "os patch level" value here. - -``deviceinfo_bootimg_os_patch_level="2021-11"`` - - -* If you're building a vendor_boot and you have moved the ``bootconfig`` file to your tree's root, add the following: - -``deviceinfo_vendor_bootconfig_path="bootconfig"`` - - -And just like that, you've filled in your deviceinfo properly and can now get on with the port! - - -Building, installing and running --------------------------------- - -After you've completed your deviceinfo and filled in all needed stuff, its time you get to the main part, the build. For this just run: -``./build.sh -b workdir`` - -That should download all the needed toolchains and then the kernel, and finally build everything. This process may take about 5 to 50 minutes to build the kernel. - -After your kernel is done building, you will have to build the rootfs. For this, just execute this: - -``./build/prepare-fake-ota.sh out/device__usrmerge.tar.xz ota`` -This will download the rootfs, extract it and pack it into tarballs for our final script to create flashable images. - -Next up, run: - -``./build/system-image-from-ota.sh ota/ubuntu_command images`` -This will convert the tarballs into flashable images, and your images will be stored in the `images/` directory. There will be a number of files depending on how you configured your deviceinfo. -But the basic file structure will be as given: - -| images/ -| ├── boot.img -| ├── rootfs.img -| └── system.img - - -The ``boot.img`` will be flashed onto the boot partition of the phone. -The ``system.img`` and ``rootfs.img`` are interchangable. ``rootfs.img`` is pushed to the data partition as ``ubuntu.img`` if you didn't include ``systempart`` in deviceinfo's cmdline. -Otherwise, ``system.img`` is flashed to your system partition. - -Notes -^^^^^ - -For a lot of kernel-related commands, you'll need the ARCH variable's value, this is either arm or arm64 depending on where you found your defconfig. A thing to keep in mind for kernel patches. diff --git a/porting/configure_test_fix/Apparmor.rst b/porting/configure_test_fix/Apparmor.rst deleted file mode 100644 index 88ff64255..000000000 --- a/porting/configure_test_fix/Apparmor.rst +++ /dev/null @@ -1,38 +0,0 @@ - -.. _AppArmor: - -AppArmor -======== - -Without AppArmor a number of device features will not function properly and most apps will crash when launched. For more information on AppArmor, refer to the `Ubuntu Wiki. `_ - -AppArmor is added through a combination of integrating the necessary code into the kernel source tree and setting necessary kernel configuration. The process is slightly different on Halium-7.1, compared to newer Halium versions. - -AppArmor for Halium-7.1 ports ------------------------------ - -Start by downloading the backported `AppArmor patch `_ corresponding to your device's kernel version. Your kernel version is specified at the beginning of your kernel defconfig file, i.e. the one you edited in section :ref:`H7_edit-kernel-config` above. (For more information on backporting, see the :ref:`bluetooth ` section below.) - -You now need to delete your entire BUILDDIR/kernel/VENDOR/MODEL/security/apparmor subdirectory and replace it with the one you downloaded. Then rebuild ``halium-boot.img``. - -If you get errors when building, resolve them one at a time, modifying your source code as needed. Note that you should only modify the code in the AppArmor subdirectory if at all possible. Modifying code elsewhere will more than likely just compound your problems. - -Seek help as needed from one of the sources mentioned in the subsection on :ref:`getting community help `. - -Once you have successfully rebuilt ``halium-boot.img``, flash it to your device. If keyboard vibration works, this is a good indication that AppArmor has been successfully applied. Also, check if apps launch normally. - -AppArmor for Halium-9.0 ports ------------------------------ - -When doing Halium-9.0 (and later) ports, it is generally sufficient to cherry pick certain commits to the kernel source rather than replacing the whole ``apparmor`` directory in the kernel source tree. Follow the link below which corresponds to your device's kernel version and select the most recent block of commits (i.e. all the commits that were added on the same and most recent date): - - * `3.18 AppArmor patches `_ - * `4.4 AppArmor patches `_ - * `4.9 AppArmor patches `_ - * `4.14 AppArmor patches `_ - -Make sure your kernel defconfig has the setting:: - - CONFIG_DEFAULT_SECURITY="apparmor" - -Now rebuild the boot image following your chosen build method, and flash it onto your device. Check if keyboard vibration works. This is a good indication that AppArmor has been successfully applied. Also, check if apps launch normally. \ No newline at end of file diff --git a/porting/configure_test_fix/Bluetooth.rst b/porting/configure_test_fix/Bluetooth.rst deleted file mode 100644 index 5fb25498e..000000000 --- a/porting/configure_test_fix/Bluetooth.rst +++ /dev/null @@ -1,229 +0,0 @@ -.. _Bluetooth: - -Bluetooth -========= - -Halium-7.1 porting to devices with kernels predating 4.2 will or may require backporting drivers from a newer kernel version, whereas Halium-9.0 based ports can skip this step. - -Bluetooth backporting to older kernel versions ----------------------------------------------- - -When porting to devices running older kernel versions (mainly version 3.x found in Android 7/ Halium-7.1 devices), it is necessary to replace the kernel bluetooth stack with a newer one. This is because the newer bluetooth hardware in today's bluetooth peripheral devices often has trouble talking to the older bluetooth drivers. This can be fixed by bringing in driver code from newer Linux kernel versions. The process is called *backporting*. - -.. _Backports: - -Backporting has been greatly facilitated by the `Linux Backports Project `_ which has existed for some time. This project is aimed at mainline Linux kernels and the tools (scripts) therein are not specifically tailored to Ubuntu Touch. They will consequently abort at some point during the process. However, they are the best option available, and can provide significant help all the same. The method below is based on the use of a version of these scripts which has been specially prepared by Canonical. - -.. Note:: - - Although there are `other kernel versions besides v4.2 available `_, the backports script is specifically tailored to backporting from version 4.2 and thus effectively limits you to this option. - -Bluetooth backporting steps -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The steps are as follows: - -#. Record bluetooth driver and settings -#. Download backports script -#. Download 4.2 kernel source -#. Run backports script and fix errors -#. Apply security patch -#. Apply new settings -#. Build and flash halium-boot.img -#. Build and flash system.img - -These steps will bring in bluetooth driver source from the mainline 4.2 kernel and place it in a directory named ``backports`` in your device's kernel source tree. It will also modify Makefiles and Kconfigs as necessary, thereby disabling the original ``drivers/bluetooth`` directory of your kernel source. The mainline kernel may not contain all bluetooth drivers required for the device being ported. For this reason it is important to make sure to first record all necessary drivers, as any ones missing in the mainline kernel will have to be migrated from their original location (``drivers/bluetooth``) into the ``backports/drivers/bluetooth`` directory as described :ref:`later in this section ` before rebuilding halium-boot.img. - -.. _BT-driver: - -Record bluetooth driver and settings -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By the time you reach this point in the porting process, you will have completed building halium-boot (probably a number of times). Your kernel defconfig will contain bluetooth settings including one that designates the driver used by your device. These must be recorded before proceeding. - -The experienced developer will likely be able to determine the relevant settings manually by searching through the defconfig file. Many of them will appear next to each other in one place in the file. Some may be spread elsewhere making them difficult to locate. When searching manually, help can be found by consulting the `Kconfig` files in relevant subdirectories of your kernel source tree. - -If you do not have extensive experience, use the ``menuconfig`` tool instead, taking care to use it ONLY for reference, *i.e.* without making any changes. - -.. Important:: - - Modifications done with ``menuconfig`` will not affect your kernel defconfig file, but may still corrupt your build. - -After completing a build of halium-boot.img:: - - cd out/target/product/[DEVICE]/obj/KERN_OBJ - ARCH=arm64 make menuconfig - -(If your device is armhf, use ``ARCH=arm`` instead.) - -Navigate to the bluetooth drivers submenu and note down all activated settings and what they do. Also note which other settings they depend on (found under Help). - -Example: -"""""""" - - For the Samsung Galaxy S7 (herolte) the original defconfig file contains a number of CONFIG_BT settings, none of which actually designate the bluetooth driver used by this device. The setting for the driver itself is CONFIG_BCM4359=y. This was not one of the drivers brought in by the backporting steps below. It therefore had to be :ref:`added afterwards `. - -Download backports script -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Clone the backports scripts into a directory outside your halium source tree by issuing this command from your home (~) directory:: - - git clone https://github.com/ubuntu-phonedations/backports.git -b for-ubuntu backport-scripts - -This downloads the backports scripts prepared by Canonical based on the `Backports Project `_ mentioned above, and places them in the directory ``~/backport-scripts``. The scripts are specifically written to backport from kernel version 4.2. - -Download 4.2 kernel sources -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Create a directory (outside your halium source tree) for the kernel source from which you will pull the newer drivers:: - - mkdir ~/kernel-backports - -Now clone the kernel source for v4.2:: - - cd ~/kernel-backports - git clone https://kernel.googlesource.com/pub/scm/linux/kernel/git/next/linux-next -b v4.2 - -Run backports script and fix errors -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Navigate to your backports scripts directory and issue the command below (using Python2 as shown):: - - python2 ./gentree.py --copy-list ./copy-list --integrate --clean --git-revision v4.2 ~/kernel-backports/linux-next ~/halium/kernel/[VENDOR]/[MODEL_NAME] - -It is to be expected that there are errors during this step. You will then have to determine the cause, fix it and retry. The last error message concerns the Makefile and includes info about having generated a file named ``Makefile.rej``, this means you will find information in this file about changes that did not complete successfully, but which you can apply yourself. These need to be completed before proceeding with the build. - -Apply security patch -^^^^^^^^^^^^^^^^^^^^ - -An additional `generic security patch `_ needs to be applied. - -Apply new settings -^^^^^^^^^^^^^^^^^^ - -Your kernel config file (defconfig) needs to be modified in order for the backported driver and protocol code to be activated. - -Start by locating all lines beginning with ``CONFIG_BT_`` and move these to the end of the file. Collecting them there makes the subsequent steps somewhat easier by helping to keep track of the changes you make. - -Next, deactivate all that are activated, *i.e.* do not have a leading ``#``, by inserting this leading ``#``. At the same time, for each one, add a corresponding one beginning with ``CONFIG_BACKPORT_BT_``, *e.g.*:: - - CONFIG_BT=y - -becomes:: - - #CONFIG_BT=y - -and then insert the corresponding line for backports:: - - CONFIG_BACKPORT_BT=y - -Now add these settings:: - - #Depending options for new stuff from backports - #CONFIG_CRC16=y - CONFIG_CRYPTO=y - CONFIG_CRYPTO_BLKCIPHER=y - CONFIG_CRYPTO_AES=y - CONFIG_CRYPTO_CMAC=y - CONFIG_CRYPTO_HMAC=y - CONFIG_CRYPTO_ECB=y - CONFIG_CRYPTO_SHA256=y - CONFIG_CRYPTO_USER_API=y - CONFIG_CRYPTO_USER_API_HASH=y - CONFIG_CRYPTO_USER_API_SKCIPHER=y - #CONFIG_TTY=y - -.. _Missing-drivers: - -At this point, check for any remaining settings you :ref:`recorded from your original defconfig `, which were dependent upon ``CONFIG_BT=y`` and have not been replaced by a corresponding ``CONFIG_BACKPORT_BT_XXXX=y`` setting, making sure not to forget your device's bluetooth driver. Such settings will no longer have any effect and must be pulled into the build in the following manner: - -The corresponding source file(s) will have to be migrated from their original location to the corresponding location under ``backports/drivers/bluetooth/``. The files ``Makefile`` and ``Kconfig`` need to be edited to include this missing setting or else they will not be built. Check the corresponding files in the original location for the necessary settings. - -Once the above is complete, add the following lines and edit as necessary, following the directions below:: - - CONFIG_BACKPORT_DIR="backports/" - CONFIG_BACKPORT_INTEGRATE=y - # CONFIG_BACKPORT_KERNEL_3_5=y #disable for kernel > 3.4 - # CONFIG_BACKPORT_KERNEL_3_6=y #disable for kernel > 3.4 - # CONFIG_BACKPORT_KERNEL_3_7=y #disable for kernel > 3.4 - # CONFIG_BACKPORT_KERNEL_3_8=y #disable for kernel > 3.4 - # CONFIG_BACKPORT_KERNEL_3_9=y #disable for kernel > 3.4 - # CONFIG_BACKPORT_KERNEL_3_10=y #disable for kernel > 3.10 - # CONFIG_BACKPORT_KERNEL_3_11=y #disable for kernel > 3.10 - # CONFIG_BACKPORT_KERNEL_3_12=y #disable for kernel > 3.10 - # CONFIG_BACKPORT_KERNEL_3_13=y #disable for kernel > 3.10 - # CONFIG_BACKPORT_KERNEL_3_14=y #disable for kernel > 3.10 - # CONFIG_BACKPORT_KERNEL_3_15=y #disable for kernel > 3.10 - # CONFIG_BACKPORT_KERNEL_3_16=y #disable for kernel > 3.10 - # CONFIG_BACKPORT_KERNEL_3_17=y #disable for kernel > 3.10 - # CONFIG_BACKPORT_KERNEL_3_18=y #disable for kernel = 3.18 - CONFIG_BACKPORT_KERNEL_3_19=y - CONFIG_BACKPORT_KERNEL_4_0=y - CONFIG_BACKPORT_KERNEL_4_1=y - CONFIG_BACKPORT_KERNEL_4_2=y - CONFIG_BACKPORT_KERNEL_NAME="Linux" - CONFIG_BACKPORT_KERNEL_VERSION="v4.2" - CONFIG_BACKPORT_LINUX=y - CONFIG_BACKPORT_VERSION="v4.2" - CONFIG_BACKPORT_BPAUTO_USERSEL_BUILD_ALL=y - -As an example, the lines above have been edited to conform with backporting from kernel 4.2 to a device with kernel version 3.18. For devices running lower kernel versions enable each line specifying a version above the device's kernel version by removing the leading ``#`` on these lines. - -You are now ready to build. - -Build and flash halium-boot.img -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Return to the root of your BUILDDIR and build:: - - mka halium-boot - -Build errors may occur and will vary depending on device. Handle them one at a time, :ref:`seeking help ` as necessary. - -After building and flashing halium-boot, check the output of ``dmesg`` on the device to see that bluetooth has been enabled:: - - dmesg | grep tooth - -Your output should resemble the following (from the Samsung Galaxy S7):: - - phablet@ubuntu-phablet:~$ dmesg | grep tooth - [ 2.219667] lucky-audio sound: moon-aif3 <-> lucky-ext bluetooth sco mapping ok - [ 2.252591] Bluetooth: RFCOMM TTY layer initialized - [ 2.252601] Bluetooth: RFCOMM socket layer initialized - [ 2.252613] Bluetooth: RFCOMM ver 1.11 - [ 2.252626] Bluetooth: BNEP (Ethernet Emulation) ver 1.3 - [ 2.252631] Bluetooth: BNEP filters: protocol multicast - [ 2.252639] Bluetooth: BNEP socket layer initialized - [ 2.252646] Bluetooth: HIDP (Human Interface Emulation) ver 1.2 - [ 2.252654] Bluetooth: HIDP socket layer initialized - [ 2.252661] Bluetooth: Virtual HCI driver ver 1.5 - [ 2.252736] Bluetooth: HCI UART driver ver 2.3 - [ 2.252743] Bluetooth: HCI UART protocol H4 registered - [ 2.252749] Bluetooth: HCI UART protocol BCSP registered - [ 2.252754] Bluetooth: HCI UART protocol LL registered - [ 2.252760] Bluetooth: HCI UART protocol ATH3K registered - [ 2.252765] Bluetooth: HCI UART protocol Three-wire (H5) registered - [ 2.252771] Bluetooth: HCI UART protocol BCM registered - [ 2.252876] Bluetooth: Generic Bluetooth SDIO driver ver 0.1 - [ 2.253388] [BT] bcm4359_bluetooth_probe. - [ 2.253630] [BT] bcm4359_bluetooth_probe End - [ 5.376110] [BT] Bluetooth Power On. - [ 7.499943] [BT] Bluetooth Power On. - [ 8.051620] [BT] Bluetooth Power On. - -If you do not get similar output, something has gone wrong. Check that you completed all steps above as described and seek help as needed. - -You have now rebuilt your halium-boot.img to include updated bluetooth drivers and only one final step remains. - -Build and flash system.img -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The system image needs to be rebuilt with a configuration script for bluetooth adapted to your device. On the completed build, this file is located at:: - - /etc/init/bluetooth-touch-android.conf - -`An example script can be found here `_. Make sure to adapt as necessary. - -Place this script in your ``device/[VENDOR]/[DEVICE]/ubuntu`` directory and inject it using the :ref:`overlay file method `. - -Rebuild and flash your ``system.img``. \ No newline at end of file diff --git a/porting/configure_test_fix/Display.rst b/porting/configure_test_fix/Display.rst deleted file mode 100644 index 8e85a8dcd..000000000 --- a/porting/configure_test_fix/Display.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. _Display: - -Display settings -================ - -There are two variables that set the content scaling for Lomiri and Ubuntu Touch applications: ``GRID_UNIT_PX`` and ``QTWEBKIT_DPR``. - -There are also other options available that may be useful for you depending on your device's form factor. These are mentioned below and explained in depth :ref:`in the section on display settings`. - -All of these settings are guessed by Unity 8 if none are set. There are many cases, however, where the guess is wrong (for example, very high resolution phone displays will be identified as desktop computers). To manually set a value for these variables, simply edit the file at ``etc/ubuntu-touch-session.d/android.conf`` specifying them. For example, this is the file for the Nexus 7 tablet:: - - $ cat /etc/ubuntu-touch-session.d/flo.conf - GRID_UNIT_PX=18 - QTWEBKIT_DPR=2.0 - NATIVE_ORIENTATION=landscape - FORM_FACTOR=tablet - -The method for deriving values for these variables :ref:`is explained below. ` - -Once you have adjusted the ``android.conf`` file to the display settings needed for your device, this file should be incorporated into your build. Follow :ref:`the overlay file method ` corresponding to your Halium version. - -.. note:: - This way of configuration is considered legacy and will be replaced by :ref:`DeviceInfo ` in the future. - For migration purposes please set both configurations (``android.conf`` as well as :ref:`DeviceInfo `). - -.. _Display-settings: - -Determining the correct display settings ----------------------------------------- - -Display scaling -^^^^^^^^^^^^^^^ - -``GRID_UNIT_PX`` (Pixels per Grid Unit or Px/GU) is specific to each device. Its goal is to make the user interface of the system and its applications the same *perceived* size regardless of the device they are displayed on. It is primarily dependent on the pixel density of the device’s screen and the distance to the screen the user is at. The latter value cannot be automatically detected and is based on heuristics. We assume that tablets and laptops are the same distance and that they are held at 1.235 times the distance phones tend to be held at. - -``QTWEBKIT_DPR`` sets the display scaling for the Oxide web engine, so changes to this value will affect the scale of the browser and webapps. - -A reference device has been chosen from which we derive the values for all other devices. The reference device is a laptop with a 120ppi screen. However, there is no exact formula since these options are set for *perceived* size rather than *physical* size. Here are some values for other devices so you may derive the correct one for yours: - -============================== ========== ============ ======= ===== ============ -Device Resolution Display Size PPI Px/GU QtWebKit DPR -============================== ========== ============ ======= ===== ============ -'Normal' density laptop N/A N/A 96-150 8 1.0 -ASUS Nexus 7 1280x800 7" 216 12 2.0 -'High' density laptop N/A N/A 150-250 16 1.5 -Samsung Galaxy Nexus 1280x720 4.65" 316 18 2.0 -LG Nexus 4 1280x768 4.7" 320 18 2.0 -Samsung Nexus 10 2560x1600 10.1" 299 20 2.0 -Fairphone 2 1080x1920 5" 440 23 2.5 -LG Nexus 5 1080x1920 4.95" 445 23 2.5 -============================== ========== ============ ======= ===== ============ - -Experiment with a few values to find one that feels good when compared to the Ubuntu Touch experience on other devices. If you are unsure of which is the best, share some pictures (including some object for scale) along with the device specs with us. - -There are two other settings that may be of interest to you: - -Form factor -^^^^^^^^^^^ - -``FORM_FACTOR`` specifies the device's form factor. This value is set as the device's Chassis, which you can find by running ``hostnamectl``. The acceptable values are ``handset``, ``tablet``, ``laptop`` and ``desktop``. Apps such as the gallery use this information to change their functionality. For more information on the Chassis, see the freedesktop.org hostnamed specification. - -Native orientation -^^^^^^^^^^^^^^^^^^ - -``NATIVE_ORIENTATION`` sets the display orientation for the device's built-in screen. This value is used whenever autorotation isn't working correctly or when an app wishes to be locked to the device's native orientation. Acceptable values are ``landscape``, which is normally used for tablets, laptops, and desktops; and ``portrait``, which is usually used for phone handsets. \ No newline at end of file diff --git a/porting/configure_test_fix/Lomiri.rst b/porting/configure_test_fix/Lomiri.rst deleted file mode 100644 index 3d62ca595..000000000 --- a/porting/configure_test_fix/Lomiri.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _Lomiri: - -Lomiri - the graphical UI -========================= - -Now that you have gained access to your newly booted device, there remain a number of things to be configured before Ubuntu Touch will be fully functional on your device. The first is to add udev rules which are required for the graphical UI to be able to launch. - -What are udev rules? --------------------- - -On your running system there is a continuously running udev daemon which governs how the system handles events on peripheral devices, *e.g.* connecting the device to a PC via USB cable. This daemon needs a set of rules, *the udev rules*, to tell it what to do for each possible event. These rules must observe a specific format and they are stored in a file which needs to be generated for each specific device. - -Add udev rules --------------- - -The correct way to do this is by storing these settings in overlay files (:ref:`Overlay`), and not by making the root directory writeable, as described below. However, in order to quickly set up udev rules which are necessary to complete subsequent steps, you can use the method detailed here for first time setup. - -Make / (root) writable -^^^^^^^^^^^^^^^^^^^^^^ - -Before you make any changes to the rootfs (which will be required for the next steps), you'll need to remount your root directory (/) with write permissions. Do this by running the following command:: - - sudo mount -o remount,rw / - -Create and add udev rules -^^^^^^^^^^^^^^^^^^^^^^^^^ - -You must create some udev rules to allow Ubuntu Touch software to access your hardware. - -If you are building a Halium-7.1 based port, run the following command, replacing [CODENAME] with your device's codename:: - - sudo -i # And enter your password - cat /var/lib/lxc/android/rootfs/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//' >/usr/lib/lxc-android-config/70-[CODENAME].rules - -For a Halium-9.0 based port you should use the commands below, again replacing [CODENAME] with your device's codename:: - - sudo -i # And enter your password - DEVICE=[CODENAME] - cat /var/lib/lxc/android/rootfs/ueventd*.rc /vendor/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//' >/etc/udev/rules.d/70-$DEVICE.rules - -.. Note:: - If you are building a Halium-9.0 based port for a non-treble device, i.e. a device without a separate vendor partition, the command above will give an error. Simply edit and remove the following string from the command: ``/vendor/ueventd*.rc``. - -Now, reboot the device. If all has gone well, you will eventually see the Ubuntu Touch spinner followed by Unity 8. Your lock password is the same as you set for SSH. - -When Unity 8 is first brought up on your device, you will probably notice that everything is very small. The :ref:`Display` section describes how to deal with this. diff --git a/porting/configure_test_fix/Overlay.rst b/porting/configure_test_fix/Overlay.rst deleted file mode 100644 index 86eb86158..000000000 --- a/porting/configure_test_fix/Overlay.rst +++ /dev/null @@ -1,167 +0,0 @@ -.. _Overlay: - -Overlay file method -=================== - -Overview --------- - -The UBports root filesystem image provides a set of default configuration files for a number of features such as display scaling, sound, bluetooth and more. These files may not be tailored to the device-specific features of the porting target and may therefore have to be adjusted. Furthermore, it may be also be necessary to add additional configuration files as well as scripts for specific needs. Overlay files provide a solution for replacing existing or adding new files to the file system. - -The way how overlay files are implemented and their limitations vary across build methods and different versions of Ubuntu Touch. Use of the halium-install script to install a build based on the downloaded GSI and root filesystem image precludes the use of overlay files since it does not provide a mechanism for that. - -In general, there are two methods of implementing overlay files, one is to directly copy them to the destination path potentially overwriting existing files, the other is to place them in a designated base directory from where they are then mounted onto their destination path during the boot process. The former is only possible when doing builds using the GitLab CI scripts. In case of Ubuntu Touch 16.04 it is the only available overlay mechanism. While the ``system.img`` build process allows overwriting files on the built Android system partition it has no means of doing so on the root filesystem. Ubuntu Touch 16.04 does however offer limited support of mount-based overlay files. Starting from Ubuntu Touch 20.04, the implementation of mount-based overlay files has become more powerful in terms of overlaying both files and directories in vendor and Android images regardless of the build method. The use of mount-based overlay files is generally preferable as it allows for delta OTA updates. Both mechanisms will be discussed in detail below before describing how overlay files are included into the build process in full system image builds and builds based on GitLab CI scripts. - -.. Note:: - - Some ports of Ubuntu Touch 16.04 using the GitLab CI-based build method add custom scripts or configuration files (e.g. in ``/usr/sbin/mount-android.sh``, ``/etc/init/mount-android.conf``, or a file in ``/etc/init/``) in order to overlay files below ``/android/system`` which would otherwise not be possible using this build method. This practice is strongly discouraged for a several reasons: - - - overwriting a system script prevents the port from receiving future updates of that script - - different ports coming up with custom solutions creates confusion among new porters and contributors - - Porters which are in need of overlaying files inside a GSI-based ``/android/system.img`` may want to consider using the full ``system.img`` build method instead. - -The implementations and limitations can be summarized as follows: - -+---------------------------+-------------------------------------------------+--------------------------------------------------------------------------------+ -| Build method | Ubuntu Touch 16.04 | Ubuntu Touch 20.04 | -+===========================+=================================================+================================================================================+ -| full ``system.img`` build | - add/overwrite files below ``/android/system`` | - add/overwrite files below ``/android/system`` | -| | - overlay existing files on the root filesystem | - overlay existing files on the root filesystem, android and vendor filesystem | -| | - no new files on the root filesystem | - new files and directories via merged or replaced overlay directories | -+---------------------------+-------------------------------------------------+--------------------------------------------------------------------------------+ -| GitLab CI-based build | - add/overwrite files on the root file system | - add/overwrite files on the root file system (use overlays instead) | -| | | - overlay mounts for existing files on the root, android and vendor filesystem | -| | | - new files and directories via merged or replaced overlay directories | -+---------------------------+-------------------------------------------------+--------------------------------------------------------------------------------+ - -How mount-based overlay files work ----------------------------------- - -Ubuntu Touch 16.04 -^^^^^^^^^^^^^^^^^^ - -Ubuntu Touch 16.04 only offers mount-based overlay files in case of full ``system.img``-based builds with the limitation that the overlayed files must actually exist on the root filesystem partition, adding new files is not possible. - -Overlay files need to be placed on the android system partition below the designated base directory which is mounted at ``/android/system/halium`` on the device. The directory tree with overlay files below that base directory mirrors the structure of the root filesystem, that is the destination path of an overlay file on the root filesystem is derived from its location relative to the base directory. For example, in order to overlay the udev rules file ``/lib/udev/rules.d/70-android.rules`` created in the last step it needs to exist in the directory ``/android/system/halium/lib/udev/rules.d/``. The specifics on how an overlay file can be placed there by the build system will be described below. - -Ubuntu Touch 20.04 and later -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Ubuntu Touch 20.04 and later provide a much more flexible implementation which is available both to full ``system.img``-based builds as well as GitLab CI script-based builds. It not only allows overlaying individual files but also replacing or merging existing directories without actually modifying the underlying filesystem. Furthermore, it is not restricted to the Ubuntu Touch root partition but can also overlay files and directories in vendor and Android partitions. - -Depending on the build method the designated base directory is either ``/opt/halium-overlay`` or ``/android/system/halium`` on the device. The directory tree below the base directory mirrors the root filesystem and destination paths are derived based on the relative location of a directory or file to the base directory. Note that the files or directories under the destination path must neither be writable nor mount points themselves. The overlay directory tree will be traversed in depth-first order during boot according to the following rules: - -- If a subdirectory contains a special file named ``.halium-override-dir`` that directory will replace the destination directory tree, i.e. the contents of the underlying directory and its descendants will no longer be accessible. - -- If a subdirectory contains a special file named ``.halium-overlay-dir`` it will be merged with with the destination directory. Any file in the underlying directory or descendants thereof remain accessible if no file with the same destination path exists in the overlaying directory tree. Files and whole directories which only exist in the overlay are made accessible in their respective destination paths. This is implemented using the overlayfs filesystem (see the `overlayfs documentation `_ for the technical details). - -- Files in directories containing none of the above special files are bind-mounted over files with an absolute path derived by stripping the above prefix. Subdirectories will be further traversed and evaluated according to the outlined rules. - -The specifics on how an overlay file or directory can be placed there depends on the used build system and will be described below. - -Example -""""""" - -Contents of ``overlay/system/halium``:: - - overlay - └── system - └── halium - └── etc - ├── foo - │ ├── .halium-overlay-dir - │ ├── conf.d - │ │ ├── 50-drivers.conf - │ │ └── 90-local.conf - │ └── foo.conf - ├── bar - │ ├── .halium-override-dir - │ └── bar.conf - └── bazrc - -Contents of the underlying filesystem image:: - - /etc - ├── foo - │ ├── conf.d - │ │ ├── 10-global.conf - │ │ ├── 20-system.conf - │ │ └── 90-local.conf - │ └── foo.conf - ├── bar - │ ├── bar.conf - │ └── baz.conf - └── bazrc - -The resulting combined filesystem the looks as follows:: - - /etc - ├── foo - │ ├── .halium-overlay-dir - │ ├── conf.d - │ │ ├── 10-global.conf - │ │ ├── 20-system.conf - │ │ ├── 50-drivers.conf (added) - │ │ └── 90-local.conf (replaced) - │ └── foo.conf (replaced) - ├── bar (replaced) - │ ├── .halium-override-dir - │ └── bar.conf - └── bazrc (replaced) - -The directory ``/etc/foo`` has been merged, whereas the ``/etc/bar`` directory and the file ``/etc/bazrc`` have been replaced. - -.. _Overlay-steps: - -Overlay files in full system.img builds ---------------------------------------- - -In the case of full ``system.img``-based builds all supported Halium versions allow for copying overlay files to the Android system filesystem image during the build process by adding entries to the ``PRODUCT_COPY_FILES`` macro. Each entry consists of the source and destination path of a file, seperated by a “``:``”. As a matter of convention, all overlay files should be placed in a directory ``ubuntu`` below the root path of the repository. This directory can be referred to as ``$(LOCAL_PATH)/ubuntu``. The destination directory should be specified relative to its default mountpoint ``/android/system`` referred to as ``$(TARGET_COPY_OUT_SYSTEM)``. - -It is thus only possible to add or overwrite files below ``/android/system``. In order to make use of mount-based overlay files they should be placed below the designated base directory ``/android/system/halium`` as described above. Due to the limitations in Ubuntu 16.04 it is only possible to add new files via overlay or override directories available in Ubuntu 20.04 or later. - -Example -^^^^^^^ - -Typically at least the file ``/lib/udev/rules.d/70-android.rules`` created when bringing up Lomiri (see :ref:`Lomiri`) and the file ``/etc/ubuntu-touch-session.d/android.conf`` for configuring display scaling need to be added via overlay files. The bind mount mechanism of both Ubuntu Touch 16.04 and 20.04 requires that the files are placed below the designated base directory ``/android/system/halium``, that is at ``/android/system/halium/lib/udev/rules.d/70-android.rules`` and ``/android/system/halium/etc/ubuntu-touch-session.d/android.conf`` - -Both ``70-android.rules`` and ``android.conf`` should be placed in the subdirectory ``ubuntu`` of the repository and the following lines need to be added to ``device.mk`` in order to copy them onto the generated image:: - - ### Ubuntu Touch ### - PRODUCT_COPY_FILES += \ - $(LOCAL_PATH)/ubuntu/70-android.rules:$(TARGET_COPY_OUT_SYSTEM)/halium/lib/udev/rules.d/70-android.rules \ - $(LOCAL_PATH)/ubuntu/android.conf:$(TARGET_COPY_OUT_SYSTEM)/halium/etc/ubuntu-touch-session.d/android.conf - ### End Ubuntu Touch ### - -.. _Rebuild-system.img: - -Rebuilding system.img -^^^^^^^^^^^^^^^^^^^^^ - -After any changes the ``system.img`` needs to be rebuilt using ``mka clean`` and ``mka systemimage``. When repeatedly rebuilding the system image after small changes, it is possible to do incremental builds without issuing a ``mka clean`` first. However, changes to PRODUCT_PROPERTY_OVERRIDES might not get detected by the build system. In that case the file ``build.prop`` in the directory ``BUILDDIR/out/target/product/CODENAME/system`` should be removed manually before rebuilding. - -After a successful build, the resulting ``system.img`` must reflashed together with the UBports root filesystem. On boot files and – in case of Ubuntu Touch 20.04 or later – marked directories in ``/android/system/halium`` will be mounted onto their final locations which are derived from their path relative to the designated base directory. - -Overlay files in Gitlab CI script-based builds ----------------------------------------------- - -When using Gitlab CI script-based builds (see :ref:`Gitlab-CI`) overlay files and directories have to be placed in in the repository below ``overlay/system`` in a directory tree mirroring the structure of the root filesystem. - -By default, the build system will cause the file to be overwriten directly in the filesystem. This allows arbitrary files to be added to the rootfs, but can cause problem when the overlaid file gets updated in the base system as part of the delta upgrade. Ubuntu Touch 16.04 supports only this mode. - -While Ubuntu Touch 16.04 only allows overlaying files by overwriting them, in case of Ubuntu Touch 20.04 or later versions the mount-based overlay files should be used instead. This can be done by specifying ``deviceinfo_use_overlaystore="true"`` in the port's ``deviceinfo``. If the port is not using the shared building script, it'll have to transition to the shared build script too (see :ref:`UpdatePortsFor2004`). When the option is being set, the build script ensures that the file ends up inside ``/opt/halium-overlay`` in the system, and gets mounted in the same way as ``system.img`` builds. Thus, the same config and limitations apply. - -Example -^^^^^^^ - -Following the above example, overlaying files ``/lib/udev/rules.d/70-android.rules`` and ``/etc/ubuntu-touch-session.d/android.conf`` requires placing the file at ``overlay/system/lib/udev/rules.d/70-android.rules`` and ``overlay/system/etc/ubuntu-touch-session.d/android.conf`` in the repository. - -For ports with ``deviceinfo_use_overlaystore="true"`` running Ubuntu Touch 20.04, the files will end up in ``/opt/halium-overlay/``, and will be bind-mounted into their respective places. - -In case of Ubuntu Touch 16.04 or port without ``deviceinfo_use_overlaystore="true"``, the files on the root filesystem will be overwritten due to the lack of mount-based overlay files. - -Building on GitLab CI -^^^^^^^^^^^^^^^^^^^^^ - -After adding or modifying overlay files the Gitlab CI scripts need to be run according to `the instructions included `_. On boot files and – in case of Ubuntu Touch 20.04 or later – marked directories in ``/opt/halium-overlay`` will be mounted onto their final locations which are derived from their path relative to the designated base directory. diff --git a/porting/configure_test_fix/Sound.rst b/porting/configure_test_fix/Sound.rst deleted file mode 100644 index 7c2c24548..000000000 --- a/porting/configure_test_fix/Sound.rst +++ /dev/null @@ -1,23 +0,0 @@ -Sound -===== - -Ubuntu Touch uses Pulseaudio as sound server. Documentation can be found at `freedesktop.org `_ and in the `Ubuntu manpages `_ - -The default configuration file used on Ubuntu Touch is ``touch.pa``. This file is located in the ``/etc/pulse`` directory on your device and it will need adjustment in order for sound to function properly. Extract the file and copy it to the ``ubuntu`` directory you created in your device repo (see :ref:`Overlay`). - -Locate the line:: - - load-module module-droid-discover voice_virtual_stream=true - -and replace it with this:: - - load-module module-droid-discover rate=48000 quirks=+unload_call_exit - -At the end of the file, append this:: - - ### Automatically load the audioflinger glue - .ifexists module-droid-glue-24.so - load-module module-droid-glue-24 - .endif - -Your modified ``touch.pa`` file now needs to be included in your build. Follow :ref:`the overlay file method ` corresponding to your Halium version. \ No newline at end of file diff --git a/porting/configure_test_fix/USBModed.rst b/porting/configure_test_fix/USBModed.rst deleted file mode 100644 index eb8bd2a4a..000000000 --- a/porting/configure_test_fix/USBModed.rst +++ /dev/null @@ -1,93 +0,0 @@ -.. _USBModed: - -Configuring usb-moded -===================== - -.. note:: - Information on this page is applicable for ports supporting Ubuntu Touch 20.04. To make your port support Ubuntu Touch 20.04, see :ref:`UpdatePortsFor2004`. - -usb-moded is a new daemon in Ubuntu Touch 20.04 which handles transitions between USB modes e.g. MTP and developer mode. It replaces a number of ad-hoc Upstart jobs on 16.04, and ``setupusb`` script used by recent ports. - -The system can detects most of the important settings. But for usb-moded to work best, we encouraged porters to give some configurations to ensure best experience for porters. - -History of the USB mode handling --------------------------------- - -In Ubuntu Touch 16.04, we used Android properties to store and set the phone's USB configuration. This worked well in the past, but today it doesn't work anymore: - -- From Halium 7.1, the component in the Android side which sends signal to Upstart to drive state transition is not going in. Besides, the signal concept doesn't seem to exist in Systemd. -- From Android 8, USB mode configuration code moved into a vendor-controlled HAL process which talks over HIDL. - -This has led to porters resorting to an ad-hoc script like ``setupusb`` which runs at boot to configure the USB mode once. And when a basic things like this gets pushed to porters, inevitably it leads to fragmentation. - -On Ubuntu Touch 20.04, we transition to usb-moded which is a daemon originating from SailfishOS. The daemon doesn't rely on Android properties, but requires configuration. We've created a "configurator" which auto-detect many of those settings, but it cannot detect everything. So, some configuration from the porters is still required. - -The basic configurations ------------------------- - -The main configuration is at ``/etc/default/usb-moded.d/device-specific-config.conf`` which porters can use the overlay system to place the file. The file is in a simple ``=`` format. An example of it is as below: - -.. code-block:: text - - IDVENDOR=0E8D - IDPRODUCT_MTP=2008 - IDPRODUCT_MTP_ADB=201D - IDPRODUCT_RNDIS=2004 - IDPRODUCT_RNDIS_ADB=2005 - USB_MODED_ARGS= - -The following can be configure: - -USB vendor & product IDs -^^^^^^^^^^^^^^^^^^^^^^^^ - -The following configurations are highly-recommended to be set. Without it, the system will fallback to the test code from `pid.codes project `_. - -- IDVENDOR -- IDPRODUCT_MTP -- IDPRODUCT_MTP_ADB -- IDPRODUCT_RNDIS -- IDPRODUCT_RNDIS_ADB - -It accepts the IDs in hexadecimal without ``0x`` prefix. The IDs could be found in: - -- Your device's ``init..rc`` or ``init..rc``. -- Your device's USB HAL source code, if it happens to ship one. -- Your device's ``setupusb`` script, if available. - -Failing that, you might have to probe how your device shows up when booted on Android. - -.. note:: - We're aware that some device use different vendor IDs for different modes. If your device are one of those, please upvote `this issue on GitLab `_. - -Devices' pretty name -^^^^^^^^^^^^^^^^^^^^ - -This is the name that will show up when plugged into a computer. Most of the time, we can detect this from Android properties, but if the detection is not correct or you would like the device to display differently, it can be configured here. - -- MANUFACTURER -- PRODUCT - -usb-moded's arguments -^^^^^^^^^^^^^^^^^^^^^ - -This config controls the launching flag of the usb-moded daemon itself. Most of the time, usb-moded should work without any flag. However, the rootfs ships a default with ``-r`` which enables the rescue mode upon boot (see below). The behavior of the rescue mode can be confusing for end users, so it's recommended that porters config this value to the blank value to disable the rescue mode. - -- USB_MODED_ARGS - -About usb-moded's rescue mode ------------------------------ - -usb-moded's rescue mode is similar to hybris-usb's usb-tethering mode. It enables the phone's USB to function as a network interface, and starts a DHCP server. The phone will be available at 10.15.19.82, and an emergency SSH server will be available on port 8022. This is intended for porters to debug issues during the development, and thus it will stay in that mode until the cable is re-plugged. - -This behavior is helpful for the porters. However, this can be confusing to end-users when the port is shipped. So I recommended disabling this mode before making the port available to users by overriding ``USB_MODED_ARGS`` as discussed above. - -Another rescue feature available is the ability to force usb-moded to go to "rescue mode" or to enable ADB on every boot. This can be done by placing an empty file at ``/userdata/.force-ssh`` or ``/userdata/.force-adb`` (which translate to ``/data/.force-ssh`` or ``/data/.force-adb`` in the recovery), and the system will make sure the correct mode is enabled. - -.. note:: - If using ADB, you may also have to disable ADB authorization prompt. See :ref:`AdbdAuthz`. - -Configuring usb-moded directly ------------------------------- - -Besides tweaking options for the configurator script, porters can also set usb-moded options directly via ``/etc/usb-moded/90-device-specific-config.ini``. However, this is intended as an escape hatch in case the automatic detection fails, and if you found yourself need to use this file, consider filing issue over usb-moded's packaging repository. See `usb-moded's docs ` for the syntax. diff --git a/porting/configure_test_fix/Wifi.rst b/porting/configure_test_fix/Wifi.rst deleted file mode 100644 index 8ba1270c8..000000000 --- a/porting/configure_test_fix/Wifi.rst +++ /dev/null @@ -1,4 +0,0 @@ -Wifi -==== - -For the time being, refer to `the Halium porting guide. `_ \ No newline at end of file diff --git a/porting/configure_test_fix/device_info/Ayatana-indicator-power.rst b/porting/configure_test_fix/device_info/Ayatana-indicator-power.rst deleted file mode 100644 index 575bc05cb..000000000 --- a/porting/configure_test_fix/device_info/Ayatana-indicator-power.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. _DeviceInfo_Ayatana-indicator-power: - -Ayatana-indicator-power -======================= - -All deviceinfo keys used by ayatana-indicator-power are given below:: - - : - FlashlightSysfsPath: - FlashlightSwitchPath: - -Device quirks -------------- - -==================== ============================================================================================================= ======================================= -Key Description Value(s) -==================== ============================================================================================================= ======================================= -FlashlightSysfsPath Specifies the path to flashlight node for Flashlight toggle in indicator. Path to flashlight node in /sys. -FlashlightSwitchPath Specifies the path to the flashlight switch node needed for the kernel driver to actually turn on flashlight. Path to flashlight switch node in /sys. -==================== ============================================================================================================= ======================================= - -Examples --------- - -Device ``sample`` using: - -- Change flashlight path to "/sys/class/leds/led:torch_0/brightness" to resolve the issue where ayatana-indicator-power will choose the wrong node. -- Change flashlight switch path so flashlight will actually turn on. - -Config file:: - - $ cat /etc/deviceinfo/devices/sample.yaml - sample: - FlashlightSysfsPath: "/sys/class/leds/led:torch_0/brightness" - FlashlightSwitchPath: "/sys/class/leds/led:switch_0/brightness" - diff --git a/porting/configure_test_fix/device_info/HfdService.rst b/porting/configure_test_fix/device_info/HfdService.rst deleted file mode 100644 index 88b263cc0..000000000 --- a/porting/configure_test_fix/device_info/HfdService.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _DeviceInfo_HfdService: - -hfd-service -=========== - -Overview of all hfd-service keys:: - - : - VibrateDurationExtraMs: - -Device quirks -------------- - -====================== ============================================= ================== -Key Description Value(s) -====================== ============================================= ================== -VibrateDurationExtraMs Milliseconds to extend all vibration calls by Any integer number -====================== ============================================= ================== - -Examples --------- - -Device ``sample`` using: - -- Extend vibrations by 50 milliseconds to feel the on-screen keyboard haptics on devices with simpler on/off vibration motors - -Config file:: - - $ cat /etc/deviceinfo/devices/sample.yaml - sample: - VibrateDurationExtraMs: 50 diff --git a/porting/configure_test_fix/device_info/Mir.rst b/porting/configure_test_fix/device_info/Mir.rst deleted file mode 100644 index 1b7a22bec..000000000 --- a/porting/configure_test_fix/device_info/Mir.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. _DeviceInfo_Mir: - -Mir -=== - -Overview of all Mir keys:: - - : - MirAndroidPlatformClientEglFlush: - MirAndroidPlatformClientFenceSync: - MirAndroidPlatformServerBackpressure: - MirAndroidPlatformServerClearFbFence: - MirAndroidPlatformServerEglSync: - MirAndroidPlatformServerPartialUpdates: - -mir-platform-android --------------------- - -====================================== =========== ============================================= =========================== -Key Description Value(s) Default value -====================================== =========== ============================================= =========================== -MirAndroidPlatformClientEglFlush See below Comma-separated list (or special value "all") Empty -MirAndroidPlatformClientFenceSync See below Comma-separated list (or special value "all") Empty -MirAndroidPlatformServerBackpressure See below Boolean False -MirAndroidPlatformServerClearFbFence See below Boolean False -MirAndroidPlatformServerEglSync See below Boolean Launcher argument (``default``) -MirAndroidPlatformServerPartialUpdates See below Boolean False -====================================== =========== ============================================= =========================== - -MirAndroidPlatformClientEglFlush -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Force GL command buffer flush on eglSwapBuffers, in case the driver doesn't follow the spec. - -MirAndroidPlatformClientFenceSync -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Classic fence-only synchronization without GL command buffer flushing. - -MirAndroidPlatformServerBackpressure -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Allows redrawing to be skipped or not after a missed frame, similarly to SurfaceFlinger. - -MirAndroidPlatformServerClearFbFence -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Framebuffer changes only continue after the fence has been successfully waited on. - -MirAndroidPlatformServerEglSync -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Allow or avoid synchronization using EGL fencing primitives when drawing the screen. - -Overrules existing launcher argument. - -MirAndroidPlatformServerPartialUpdates -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Allow partial redraws to HWC-assigned server-side buffers. - -Examples --------- - -Device ``sample`` using: - -- Enabling egl flushing for every client except for ``lomiri`` and ``unity8`` - - Note that you can use ``!`` to invert conditions and turn the `allow` into a `deny` list. -- Disabling egl sync for the server -- Enabling partial updates for the server - -Config file:: - - $ cat /etc/deviceinfo/devices/sample.yaml - sample: - MirAndroidPlatformClientEglFlush: - - "!/usr/bin/unity8,!/usr/bin/lomiri,all" - MirAndroidPlatformServerEglSync: - - false - MirAndroidPlatformServerPartialUpdates: - - true diff --git a/porting/configure_test_fix/device_info/Repowerd.rst b/porting/configure_test_fix/device_info/Repowerd.rst deleted file mode 100644 index f99627e35..000000000 --- a/porting/configure_test_fix/device_info/Repowerd.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _DeviceInfo_Repowerd: - -Repowerd -======== - -Overview of all repowerd keys:: - - : - BacklightSysfsPath: - DoubleTapToWake: - - || - - ... - -Device quirks -------------- - -================== =============================== ======================================================== -Key Description Value(s) -================== =============================== ======================================================== -BacklightSysfsPath File path to backlight device File path -DoubleTapToWake Configuration for toggling DT2W List of formatted strings: ``||`` -================== =============================== ======================================================== - -Examples --------- - -Device ``sample`` using: - -- Custom backlight sysfs path to disable autodetection of the path controlling the backlight -- Double Tap to Wake (DT2W) configuration to allow double tapping to wake the device, specifing two potential paths - - It is allowed to specify multiple entries, invalid or non-existant paths will be removed - -Config file:: - - $ cat /etc/deviceinfo/devices/sample.yaml - sample: - BacklightSysfsPath: /sys/class/backlight/panel0-backlight - DoubleTapToWake: - - /proc/touchpanel/double_tap_enable|1|0 - - /sys/devices/platform/soc/a84000.i2c/i2c-2/2-0020/input/input1/wake_gesture|on|off diff --git a/porting/configure_test_fix/device_info/index.rst b/porting/configure_test_fix/device_info/index.rst deleted file mode 100644 index 2838b6ce8..000000000 --- a/porting/configure_test_fix/device_info/index.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _DeviceInfo: - -DeviceInfo -========== - -DeviceInfo allows to set device specific configuration, which can be accessed in an uniform way using `libdeviceinfo `_. - -Device specific overrides -------------------------- - -Configuration files per device are located at ``/etc/deviceinfo/devices/[device].yaml``. -It will try to autodetect the correct configuration to load based on model of the device, -using android props for halium/android devices and dtb for native linux devices. - -.. note:: - This file needs to be all lowercase, as any autodetected device name will be converted to lowercase. - -For example, the file for the Nexus 7 tablet (flo) would be located at ``/etc/deviceinfo/devices/flo.yaml`` and needs to start with the device's name:: - - $ cat /etc/deviceinfo/devices/flo.yaml - flo: - DeviceType: tablet - GridUnit: 18 - WebkitDpr: 2 - PrimaryOrientation: Landscape - ... - -In case you can not add a new file to the rootfs, you can bind-mount ``/etc/deviceinfo/devices/halium.yaml``. -For a reference, see the `configuration bringup for bonito/sargo `_. - -If no device specific configuration exists or a key is not specified for the device config, DeviceInfo will fallback to ``/etc/deviceinfo/default.yaml``. -Keep your configuration simple and try to not duplicate any entries, which are already defined in ``default.yaml``. - -Any key can be added without needing to modify deviceinfo to use it. -This allows for a lot of flexibility, however keys should be properly documented in order to not duplicate keys. - -Built-in config keys --------------------- - -============================ ========================================================= ======================================================== -Key Description Value(s) -============================ ========================================================= ======================================================== -Name Device name / codename Any string -PrettyName Pretty name of the device Any string -DeviceType Sets device type desktop, tablet, phone -GridUnit Sets scale units Any integer -SupportedOrientations Orientations supported by the device Portrait, InvertedPortrait, Landscape, InvertedLandscape -PrimaryOrientation Primary orientation of the device Portrait, InvertedPortrait, Landscape, InvertedLandscape -PortraitOrientation Orientation of the device when in portrait mode Portrait, InvertedPortrait, Landscape, InvertedLandscape -InvertedPortraitOrientation Orientation of the device when in inverted portrait mode Portrait, InvertedPortrait, Landscape, InvertedLandscape -LandscapeOrientation Orientation of the device when in landscape mode Portrait, InvertedPortrait, Landscape, InvertedLandscape -InvertedLandscapeOrientation Orientation of the device when in inverted landscape mode Portrait, InvertedPortrait, Landscape, InvertedLandscape -============================ ========================================================= ======================================================== - -Other keys are documented in the component specific subpages. - -.. toctree:: - :maxdepth: 1 - :name: device_info - - Mir - Repowerd - HfdService - Ayatana-indicator-power diff --git a/porting/configure_test_fix/index.rst b/porting/configure_test_fix/index.rst deleted file mode 100644 index 2191e339c..000000000 --- a/porting/configure_test_fix/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -Configuring, testing and fixing -=============================== - -Now that you have successfully booted your build, you are ready to bring up the graphical UI, merge AppArmor into your port and see to any remaining functionality that needs configuring. This section explains how to perform these tasks. - -If you are doing a GSI port, much, if not all device features, should already work 'out of the box' once you have brought up Lomiri and added AppArmor. For this reason, Halium-9/GSI porting as well as porting based on standalone kernel builds should normally require only udev rules, AppArmor patches and only limited, if any, configuring using the overlay file method. If, despite performing these tasks, your GSI-based build still does not function properly, you may have to resort to building a device-specific ``system.img`` in order to reach your goal. - -On the other hand, Halium 7.1 porting and Halium-9.0 porting (when building the full device-specific ``system.img``) will require the most work. - -Start by bringing up Lomiri, adjusting the display as required, and adding AppArmor. The remaining steps can be performed in arbitrary order and some may not apply to your particular port. - -As you go along, it can be helpful to have a list of device functions to go by when checking what works and what needs debugging and fixing. This list, along with instructions on how to add your device to the list of devices that can run Ubuntu Touch, can be found in `the informative README.md file linked here. `_ - -.. toctree:: - :maxdepth: 1 - :name: configure_test_fix - - device_info/index.rst - Lomiri - Overlay - Display - Apparmor - Wifi - Sound - Bluetooth - USBModed diff --git a/porting/debugging/configuration/audio.rst b/porting/debugging/configuration/audio.rst new file mode 100644 index 000000000..084b8e527 --- /dev/null +++ b/porting/debugging/configuration/audio.rst @@ -0,0 +1,69 @@ +Audio Configuration +=================== + +Quick Reference +--------------- +Audio in Ubuntu Touch is automatically configured through the Android audio HAL. Direct modification of PulseAudio configuration files is not recommended. + +Understanding Audio Architecture +-------------------------------- + +Audio Stack Components +^^^^^^^^^^^^^^^^^^^^^^ +The Ubuntu Touch audio stack consists of: + +1. **Android Layer** + + * Audio HAL (Hardware Abstraction Layer) + * Hardware drivers and codecs + * Android audio policy + +2. **Integration Layer** + + * PulseAudio droid modules + * Automatic HAL discovery + * Hardware access abstraction + +3. **User Space** + + * PulseAudio sound server + * Media framework + * System audio services + +Audio Configuration +------------------- +Ubuntu Touch automatically configures audio through module-droid-discover, which: + +* Detects available audio hardware +* Loads appropriate droid modules +* Configures necessary parameters +* Handles Android audio integration + +.. note:: + While /etc/pulse/touch.pa contains the audio configuration, it should generally not be modified directly. Future Ubuntu Touch updates will provide proper ways to specify additional parameters if needed. + +Implementation Steps +-------------------- + +1. **Verify Audio Hardware** + + * Check Android audio HAL version + * Verify driver functionality + * Confirm audio policy configuration + +2. **Android Audio Policy** + + The Android audio policy configuration in /vendor/etc/audio_policy_configuration.xml defines: + + * Available audio devices + * Supported formats and rates + * Audio routing paths + * Default configurations + +3. **Test Integration** + + * Verify device detection + * Test basic playback + * Check recording capabilities + +For debugging and troubleshooting guidance, see :doc:`../hardware-debug/audio`. \ No newline at end of file diff --git a/porting/debugging/configuration/display.rst b/porting/debugging/configuration/display.rst new file mode 100644 index 000000000..da1926b95 --- /dev/null +++ b/porting/debugging/configuration/display.rst @@ -0,0 +1,200 @@ +.. _display: + +Display Configuration +===================== + +The display must be properly configured for correct scaling and touch input. This guide covers both quick configuration and detailed understanding. + +Quick Configuration +------------------- +For experienced developers, start with these essential settings:: + + # Edit /etc/ubuntu-touch-session.d/android.conf + GRID_UNIT_PX=18 # Basic scaling unit + QTWEBKIT_DPR=2.0 # Display scaling for web content + NATIVE_ORIENTATION=portrait # Primary device orientation + FORM_FACTOR=phone # Device type + +Apply these settings using the :ref:`overlay method ` for persistence across updates. + +Understanding Display Configuration +----------------------------------- + +Grid Unit (GU) System +^^^^^^^^^^^^^^^^^^^^^ +The Grid Unit (GRID_UNIT_PX) determines interface scaling across all applications. + +Common values based on device type and screen density: + +.. list-table:: + :header-rows: 1 + :widths: 30 15 15 40 + + * - Device Type + - PPI Range + - Grid Unit + - Example Devices + * - Phone (<5") + - 200-300 + - 18 + - Galaxy Nexus + * - Large Phone (>5") + - 400-500 + - 23 + - OnePlus 6 + * - Tablet + - 150-250 + - 12-20 + - Nexus 7 (12) + * - High-DPI Tablet + - 250+ + - 20-24 + - Nexus 10 (20) + +How to determine your Grid Unit: + +1. Calculate device PPI from resolution and screen size +2. Consider typical viewing distance +3. Test with sample value from table above +4. Adjust based on visual comfort + +Display Scaling +^^^^^^^^^^^^^^^ +QTWEBKIT_DPR controls web content scaling: + +.. list-table:: + :header-rows: 1 + :widths: 25 15 60 + + * - Device Type + - DPR Value + - When to Use + * - Standard Density + - 1.0 + - Desktop-like displays (<150 PPI) + * - High Density + - 1.5-2.0 + - Most phones and tablets + * - Very High Density + - 2.5 + - Modern flagship phones (>400 PPI) + +Orientation Settings +-------------------- +Four possible orientations: + +* portrait +* landscape +* inverted-portrait +* inverted-landscape + +NATIVE_ORIENTATION determines: + +* Initial display orientation +* Natural device holding position +* Sensor rotation reference + +Form Factor Configuration +------------------------- +FORM_FACTOR options: + +* phone - Standard phone interface +* tablet - Tablet-optimized layout +* desktop - Desktop-style interface + +This setting affects: + +* Default applications +* Interface layout +* Input method behavior +* Window management + +Implementation Steps +-------------------- + +1. Create Configuration +^^^^^^^^^^^^^^^^^^^^^^^ +Create overlay configuration file:: + + mkdir -p overlay/system/etc/ubuntu-touch-session.d/ + touch overlay/system/etc/ubuntu-touch-session.d/android.conf + +2. Add Settings +^^^^^^^^^^^^^^^ +Edit android.conf with your configuration:: + + GRID_UNIT_PX= + QTWEBKIT_DPR= + NATIVE_ORIENTATION= + FORM_FACTOR= + +3. Apply Configuration +^^^^^^^^^^^^^^^^^^^^^^ +Implement using :ref:`overlay-method` for either: + +* Development testing +* Production implementation + +Testing and Verification +------------------------ + +1. Quick Visual Test +^^^^^^^^^^^^^^^^^^^^ +Check these elements: + +* Text readability +* Button sizes +* Overall scaling +* Web content display + +2. Orientation Testing +^^^^^^^^^^^^^^^^^^^^^^ +Verify: + +* Rotation behavior +* Sensor response +* Initial orientation + +3. Interface Verification +^^^^^^^^^^^^^^^^^^^^^^^^^ +Confirm: + +* Correct form factor layout +* Touch target sizes +* Keyboard scaling +* Application display + +Troubleshooting +--------------- + +Common Issues: + +* **Too Small/Large**: Adjust GRID_UNIT_PX +* **Blurry Web Content**: Modify QTWEBKIT_DPR +* **Wrong Rotation**: Check NATIVE_ORIENTATION +* **Incorrect Layout**: Verify FORM_FACTOR + +Advanced Configuration +---------------------- +For complex display setups: + +* Multiple display support +* Custom scaling factors +* Display-specific overrides + +See the :ref:`hardware-abstraction` guide for detailed display subsystem configuration. + +Next Steps +---------- + +**Display working correctly?** + → :doc:`../configuration/audio` + +**Having issues?** + → :doc:`../troubleshooting/hardware-issues` + +See Also +-------- +* :ref:`overlay-method` - Configuration persistence +* :ref:`hardware-abstraction` - Display subsystem details +* :doc:`../troubleshooting/hardware-issues` - Display troubleshooting \ No newline at end of file diff --git a/porting/debugging/configuration/networking.rst b/porting/debugging/configuration/networking.rst new file mode 100644 index 000000000..43e113fca --- /dev/null +++ b/porting/debugging/configuration/networking.rst @@ -0,0 +1,111 @@ +Network Configuration +===================== + +Quick Reference +--------------- +Essential kernel configurations:: + + # WiFi support + CONFIG_WIRELESS=y # Wireless subsystem support + CONFIG_CFG80211=y # cfg80211 wireless interface + CONFIG_MAC80211=y # IEEE 802.11 support + CONFIG_WLAN=y # Wireless LAN drivers + + # Mobile data + CONFIG_USB_NET_RNDIS_HOST=y # RNDIS host support + CONFIG_USB_CONFIGFS_RNDIS=y # ConfigFS RNDIS gadget + +Understanding Network Architecture +---------------------------------- + +Network Subsystems +^^^^^^^^^^^^^^^^^^ +Ubuntu Touch networking consists of three main subsystems: + +1. **WiFi Stack** + + * Kernel WiFi drivers + * Firmware support + * Hardware interfaces + +2. **Mobile Data** + + * RIL (Radio Interface Layer) + * oFono (telephony framework) + * Modem firmware + +3. **Network Services** + + * Network management + * Interface handling + * Connection control + +The system handles interface configuration and network management automatically once proper kernel support is enabled. + +Configuration Steps +------------------- + +1. WiFi Configuration +^^^^^^^^^^^^^^^^^^^^^ +Enable WiFi support in your kernel configuration:: + + # Required kernel configs + CONFIG_WIRELESS=y # Wireless subsystem support + CONFIG_CFG80211=y # cfg80211 wireless interface + CONFIG_MAC80211=y # IEEE 802.11 support + CONFIG_WLAN=y # Wireless LAN drivers + +Common vendor-specific configs:: + + # Qualcomm WiFi + CONFIG_QCA_CLD_WLAN=y + + # MediaTek WiFi + CONFIG_MTK_COMBO_WIFI=y + + # Broadcom WiFi + CONFIG_BCM4339=y + +2. Mobile Data Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Configure mobile data support: + +Kernel configuration:: + + # USB networking + CONFIG_USB_NET_RNDIS_HOST=y # RNDIS host support + CONFIG_USB_CONFIGFS_RNDIS=y # ConfigFS RNDIS gadget + + # Modem support + CONFIG_USB_SERIAL=y # USB Serial support + CONFIG_USB_SERIAL_WWAN=y # USB Serial WWAN driver + CONFIG_USB_SERIAL_OPTION=y # USB Serial Option driver + +For debugging and troubleshooting of network activation issues, see :doc:`../hardware-debug/connectivity`. + +Common Configurations +--------------------- + +Qualcomm Devices +^^^^^^^^^^^^^^^^ +Common settings for Qualcomm platforms:: + + # WiFi driver + CONFIG_QCA_CLD_WLAN=y + CONFIG_QCACLD_WLAN_LFR3=y + +MediaTek Devices +^^^^^^^^^^^^^^^^ +Typical MediaTek configuration:: + + # WiFi support + CONFIG_MTK_COMBO=y + CONFIG_MTK_COMBO_WIFI=y + +Samsung Devices +^^^^^^^^^^^^^^^ +Samsung-specific settings:: + + # WiFi configuration + CONFIG_BCM4339=y + CONFIG_BCM4354=y \ No newline at end of file diff --git a/porting/debugging/configuration/sensors.rst b/porting/debugging/configuration/sensors.rst new file mode 100644 index 000000000..22608f2fa --- /dev/null +++ b/porting/debugging/configuration/sensors.rst @@ -0,0 +1,186 @@ +Sensor Configuration +==================== + +Quick Reference +--------------- +Essential configurations:: + + # Required kernel configs + CONFIG_INPUT_EVDEV=y # Event interface + CONFIG_INPUT_MISC=y # Misc input drivers + CONFIG_IIO=y # Industrial I/O support + + # Common sensor types + /dev/input/event* # Event-based sensors + /sys/bus/iio/devices/* # IIO-based sensors + /dev/sensors/* # Android sensor HAL + +Service configuration:: + + systemctl status sensorfwd # Sensor daemon status + ls /etc/sensor/*.conf # Sensor configs + +Understanding Sensor Architecture +--------------------------------- + +Sensor Stack Components +^^^^^^^^^^^^^^^^^^^^^^^ +The sensor system consists of multiple layers: + +1. **Hardware Layer** + + * Physical sensors + * Kernel drivers + * Hardware interfaces (I2C/SPI) + +2. **Abstraction Layer** + + * Android sensor HAL + * Input subsystem + * IIO subsystem + +3. **User Space** + + * Sensor service (sensorfwd) + * Android sensor service + * Applications + +Types of Sensors +^^^^^^^^^^^^^^^^ +Common sensor categories: + +1. **Motion Sensors** + * Accelerometer + * Gyroscope + * Magnetometer + +2. **Environmental Sensors** + * Light sensor + * Proximity sensor + * Temperature sensor + +3. **Position Sensors** + * GPS + * Compass + * Step counter + +Configuration Steps +------------------- + +1. Kernel Configuration +^^^^^^^^^^^^^^^^^^^^^^^ +Enable required kernel support:: + + # Basic input support + CONFIG_INPUT=y + CONFIG_INPUT_EVDEV=y + + # IIO framework + CONFIG_IIO=y + CONFIG_IIO_BUFFER=y + CONFIG_IIO_TRIGGERED_BUFFER=y + + # Common sensor drivers + CONFIG_INPUT_LSM6DSM=y # IMU example + CONFIG_INPUT_ALS_IS31FL319X=y # Light sensor example + +2. Sensor Service Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Configure sensor framework:: + + # /etc/sensorfw/primaryuse.conf + [plugins] + accelerometeradaptor = evdevaccelerometer + alsadaptor = evdevals + proximityadaptor = evdevproximity + magnetometeradaptor = evdevmagnetometer + + [features] + orientationenabled = true + alwaysonEnabled = false + +3. HAL Integration +^^^^^^^^^^^^^^^^^^ +Configure sensor HAL mapping:: + + # /vendor/etc/sensors/sensor_def_qcomdev.conf + # Example Qualcomm sensor configuration + :version 0x00010001 + + # Accelerometer configuration + 10001 0x00010001 # SNS_REG_ITEM_SSI_DEVINFO_ACCEL_ID + 1 0x00010001 # SNS_REG_ITEM_SSI_DEVINFO_ACCEL_NUM + 2 0x00010001 # SNS_REG_ITEM_SSI_DEVINFO_ACCEL_TYPE + 3 0x00010001 # SNS_REG_ITEM_SSI_DEVINFO_ACCEL_NAME + +4. Permission Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Set up udev rules for sensor access:: + + # /etc/udev/rules.d/60-sensors.rules + # Give input group access to sensor devices + SUBSYSTEM=="input", KERNEL=="event*", MODE="0660", GROUP="input" + + # IIO devices + SUBSYSTEM=="iio", MODE="0660", GROUP="input" + + # Generic sensor access + KERNEL=="sensors", MODE="0660", GROUP="input" + +Implementation Steps +-------------------- + +1. **Identify Available Sensors** + + * Check kernel driver support + * Verify hardware presence + * Review vendor documentation + +2. **Configure Basic Support** + + * Enable kernel drivers + * Set up sensor service + * Configure permissions + +3. **Setup Sensor Service** + + * Configure sensor adaptors + * Set up calibration + * Enable sensor features + +4. **Verify Integration** + + * Check sensor detection + * Verify permissions + * Test basic functionality + +For debugging and troubleshooting guidance, see :doc:`../hardware-debug/sensors`. + +Common Configurations +--------------------- + +Qualcomm Devices +^^^^^^^^^^^^^^^^ +Common settings for Qualcomm platforms:: + + # Sensor drivers + CONFIG_SENSORS_SSC=y + CONFIG_SENSORS_QTI=y + + # Sensor HAL mapping + [sensors] + accel.sns_reg_config = "qualcomm/accel_reg_config" + gyro.sns_reg_config = "qualcomm/gyro_reg_config" + +MediaTek Devices +^^^^^^^^^^^^^^^^ +Typical MediaTek configuration:: + + # Sensor support + CONFIG_MTK_SENSOR_SUPPORT=y + CONFIG_MTK_SENSORS_1_0=y + + # Sensor configuration + [sensors] + accelerometer = "MTK_ACCEL" + alsps = "MTK_ALSPS" \ No newline at end of file diff --git a/porting/debugging/hardware-debug/audio.rst b/porting/debugging/hardware-debug/audio.rst new file mode 100644 index 000000000..c36a32ea5 --- /dev/null +++ b/porting/debugging/hardware-debug/audio.rst @@ -0,0 +1,55 @@ +Audio Debugging +=============== + +Audio Stack +----------- +Components:: + + ALSA -> PulseAudio -> Android HAL + UCM -> Audio Policy -> Audio HAL + +Debug Commands +-------------- +Hardware detection:: + + aplay -l # List devices + pacmd list-sinks # PulseAudio sinks + tinymix # Mixer controls + +Routing tests:: + + speaker-test -D hw:0,0 # Direct ALSA + paplay test.wav # PulseAudio + arecord -f cd # Recording + +Common Issues +------------- +No audio output:: + + # Check HAL + systemctl status android-audiosystem + logcat -s audio_hw_hal + + # Verify routing + pacmd list-cards + amixer -c 0 contents + +Distorted sound:: + + # Check levels + alsamixer + pacmd list-sink-inputs + + # Test paths + alsaucm -c $CARD test Playback + +UCM Configuration +----------------- +Debug methods:: + + # Test config + alsaucm -c $CARD dump + amixer -c 0 contents + + # Verify paths + cat /usr/share/alsa/ucm2/*/*.conf \ No newline at end of file diff --git a/porting/debugging/hardware-debug/connectivity.rst b/porting/debugging/hardware-debug/connectivity.rst new file mode 100644 index 000000000..4111a6d01 --- /dev/null +++ b/porting/debugging/hardware-debug/connectivity.rst @@ -0,0 +1,47 @@ +Connectivity Debugging +====================== + +WiFi +---- +Debug steps:: + + # Driver status + lsmod | grep wifi + dmesg | grep wifi + iw list + + # Connection + iw dev wlan0 scan + iw event + wpa_cli status + +Cellular/Modem +-------------- +Debug methods:: + + # Check modem status + dmesg | grep -i modem + + # Verify RIL status + journalctl -u ofono + + # Check SIM status + list_modems # ofono tool + dbus-send --system --print-reply --dest=org.ofono /[modem] \ + org.ofono.Modem.GetProperties + +Bluetooth +--------- +Debug commands:: + + # Stack + btmon + bluetoothctl show + hcidump + + # Firmware + dmesg | grep -i blue + hexdump -C /sys/firmware/acpi/tables/SSDT* + + # Audio + pactl list short | grep blue \ No newline at end of file diff --git a/porting/debugging/hardware-debug/display.rst b/porting/debugging/hardware-debug/display.rst new file mode 100644 index 000000000..2ef8b627f --- /dev/null +++ b/porting/debugging/hardware-debug/display.rst @@ -0,0 +1,71 @@ +Display Subsystem Debugging +=========================== + +Display Stack +------------- +Components:: + + Android HAL/hwcomposer -> libhybris -> Mir -> Lomiri + +Debug interfaces:: + + /dev/dri/* # DRM devices + /sys/class/drm/* # Display info + /dev/fb* # Framebuffer + +Common Issues +------------- +1. No Display Output:: + + # Check framebuffer + cat /sys/class/graphics/fb0/name + hexdump -C /dev/fb0 + + # Verify DRM + modetest -D /dev/dri/card0 + + # Monitor errors + dmesg | grep -i drm + journalctl -u lightdm + +2. Display Corruption:: + + # Test modes + cat /sys/class/graphics/fb0/modes + xrandr --verbose + + # Check composition + DISPLAY=:0 glxinfo + mir-performance-test + +3. Resolution/Scaling:: + + # Current mode + cat /sys/class/graphics/fb0/mode + + # Scaling factors + grep GRID_UNIT /etc/ubuntu-touch-session.d/* + grep DPR /etc/ubuntu-touch-session.d/* + +Hardware Tests +-------------- +Basic tests:: + + # Display info + cat /sys/class/backlight/*/brightness + cat /sys/class/graphics/fb0/bits_per_pixel + + # Hardware composer + dumpsys SurfaceFlinger + cat /d/dri/*/state + +Advanced debugging:: + + # DRM debug + echo 0xf > /sys/module/drm/parameters/debug + + # Force modes + echo "U:1920x1080p-60" > /sys/class/graphics/fb0/mode + + # Test patterns + fbtest \ No newline at end of file diff --git a/porting/debugging/hardware-debug/index.rst b/porting/debugging/hardware-debug/index.rst new file mode 100644 index 000000000..3608d6d0c --- /dev/null +++ b/porting/debugging/hardware-debug/index.rst @@ -0,0 +1,16 @@ +.. _hardware-enablement: + +Hardware Debugging +================== + +Detailed guides for debugging hardware subsystems on Ubuntu Touch devices. + +.. toctree:: + :maxdepth: 2 + :name: hardware-debug-toc + + display + audio + sensors + power + connectivity \ No newline at end of file diff --git a/porting/debugging/hardware-debug/power.rst b/porting/debugging/hardware-debug/power.rst new file mode 100644 index 000000000..11b8bc238 --- /dev/null +++ b/porting/debugging/hardware-debug/power.rst @@ -0,0 +1,43 @@ +Power Management Debug +====================== + +Power States +------------ +Components:: + + Battery -> Charging -> Suspend + Thermal -> CPU freq -> GPU freq + +Battery Monitor +--------------- +Debug commands:: + + upower -i /org/freedesktop/UPower/devices/battery_0 + cat /sys/class/power_supply/*/status + dmesg | grep -i battery + +Suspend/Resume +-------------- +Test methods:: + + # Manual suspend + systemctl suspend + pm-suspend + + # Monitor + journalctl -u systemd-sleep + cat /sys/power/state + dmesg | grep -i suspend + +Thermal Control +--------------- +Debug interfaces:: + + # Zones + cat /sys/class/thermal/thermal_zone*/temp + + # Cooling + cat /sys/class/thermal/cooling_device*/cur_state + + # CPU freq + cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_cur_freq \ No newline at end of file diff --git a/porting/debugging/hardware-debug/sensors.rst b/porting/debugging/hardware-debug/sensors.rst new file mode 100644 index 000000000..44c4bd7c7 --- /dev/null +++ b/porting/debugging/hardware-debug/sensors.rst @@ -0,0 +1,41 @@ +Sensor Debugging +================ + +Available Sensors +----------------- +Common types:: + + accelerometer # Motion + proximity # Distance + als # Light + compass # Orientation + +Debug Interface +--------------- +Input system:: + + ls /dev/input/event* # Device nodes + getevent -l # Monitor events + evtest # Test inputs + +Sensor Service +-------------- +Debug steps:: + + # Check service + systemctl status sensorfwd + journalctl -u sensorfwd + + # Test sensors + sensorfw-tests + sensor-test accelerometer + +Calibration +----------- +Methods:: + + # Read values + cat /sys/devices/iio:device0/* + + # Test calibration + /usr/lib/sensord-qt5/testing/testutils/sensordummyclient \ No newline at end of file diff --git a/porting/debugging/hardware-fixes/apparmor.rst b/porting/debugging/hardware-fixes/apparmor.rst new file mode 100644 index 000000000..ebacbbc93 --- /dev/null +++ b/porting/debugging/hardware-fixes/apparmor.rst @@ -0,0 +1,198 @@ +.. _apparmor: + +AppArmor Implementation +======================= + +Quick Reference +--------------- +Essential kernel configurations:: + + CONFIG_SECURITY_APPARMOR=y + CONFIG_SECURITY_APPARMOR_HASH=y + CONFIG_DEFAULT_SECURITY_APPARMOR=y + CONFIG_AUDIT=y # For policy logging + CONFIG_SECURITY=y # General security support + CONFIG_LSM="apparmor" # Set AppArmor as default LSM + +Understanding AppArmor +---------------------- +AppArmor is a Mandatory Access Control (MAC) system that confines programs to a limited set of resources. In Ubuntu Touch, it: + +* Restricts what apps can access +* Protects system resources +* Enforces security policies +* Controls inter-app communication + +Think of AppArmor as a security guard that checks every program's ID card before allowing access to resources. + +Implementation Steps +-------------------- + +1. Kernel Configuration +^^^^^^^^^^^^^^^^^^^^^^^ +Modern Kernels (4.2+) +""""""""""""""""""""" +For kernels version 4.2 and newer, you'll need to cherry-pick specific AppArmor commits. + +First, identify your kernel version:: + + make kernelversion + +Choose the appropriate commit set: + +* 3.18: https://github.com/MotoZ-2016/android_kernel_motorola_msm8996/commits/halium-9.0/security/apparmor +* 4.4: https://github.com/moto-SDM660/android_kernel_motorola_sdm660/commits/halium-9.0/security/apparmor +* 4.9+: https://github.com/erfanoabdi/android_kernel_motorola_sdm632/commits/halium-9.0/security/apparmor + +Example cherry-pick process:: + + cd kernel/[vendor]/[device] + git remote add apparmor https://github.com/[repo]/[kernel] + git fetch apparmor + git cherry-pick [commit-id] + +Legacy Kernels (Pre-4.2) +"""""""""""""""""""""""" +For older kernels, apply the backported patch: + +1. Download appropriate patch:: + + wget https://github.com/ubports/AppArmor-backports-ut/raw/master/3.4/apparmor-3.4.patch + +2. Apply the patch:: + + cd kernel/[vendor]/[device] + patch -p1 < /path/to/apparmor-3.4.patch + +3. Resolve any conflicts:: + + # Check for reject files + find . -name "*.rej" + + # Manually apply rejected hunks + patch -p1 --dry-run < /path/to/apparmor-3.4.patch + +2. Configure AppArmor +^^^^^^^^^^^^^^^^^^^^^ +Edit your kernel defconfig to enable AppArmor:: + + # Enable core AppArmor support + CONFIG_SECURITY_APPARMOR=y + CONFIG_SECURITY_APPARMOR_HASH=y + CONFIG_DEFAULT_SECURITY_APPARMOR=y + + # Required supporting options + CONFIG_AUDIT=y + CONFIG_SECURITY=y + CONFIG_LSM="apparmor" + + # Recommended features + CONFIG_SECURITY_APPARMOR_ENFORCE_DEFAULT=y + CONFIG_SECURITY_APPARMOR_LOOPBACK=y + CONFIG_SECURITY_APPARMOR_UNCONFINED_INIT=y + +3. Build and Test +^^^^^^^^^^^^^^^^^ +1. Rebuild your kernel:: + + mka halium-boot + +2. Flash and boot:: + + fastboot flash boot halium-boot.img + +3. Verify AppArmor status:: + + # Check if AppArmor is enabled + cat /sys/module/apparmor/parameters/enabled + + # View loaded profiles + aa-status + + # Check kernel messages + dmesg | grep -i apparmor + +Verification Steps +------------------ + +1. Basic Functionality +^^^^^^^^^^^^^^^^^^^^^^ +Check AppArmor initialization:: + + # AppArmor should be listed as a security module + cat /sys/kernel/security/lsm + + # Should show "Y" + cat /sys/module/apparmor/parameters/enabled + + # Should show numerous AppArmor messages + dmesg | grep -i apparmor + +2. Profile Loading +^^^^^^^^^^^^^^^^^^ +Verify profile loading:: + + # Check loaded profiles + aa-status + + # Should include entries like: + # - /usr/bin/lomiri + # - /usr/bin/mediaplayer-app + # - click packages + +3. Policy Enforcement +^^^^^^^^^^^^^^^^^^^^^ +Test confinement:: + + # Try to access restricted file + sudo -u phablet touch /etc/passwd + + # Should see denial in logs + dmesg | grep DENIED + + # Check app confinement + ps aux | grep -i "(enforce)" + +Common Issues +------------- + +1. Profile Loading Failures +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If profiles fail to load:: + + # Check syntax + apparmor_parser -QK /etc/apparmor.d/* + + # View detailed errors + aa-status --verbose + + # Check journal for loading errors + journalctl -b | grep apparmor + +2. Missing Features +^^^^^^^^^^^^^^^^^^^ +If kernel features are missing:: + + # Verify config + zcat /proc/config.gz | grep APPARMOR + + # Check required features + aa-features-abi + + # View available features + cat /sys/kernel/security/apparmor/features/* + +3. Policy Violations +^^^^^^^^^^^^^^^^^^^^ +For unexpected denials:: + + # Monitor denials + aa-notify -s 1d + + # Generate policy + aa-logprof + + # View detailed logs + ausearch -m AVC + +For debugging and troubleshooting guidance, see :doc:`../system-debug/apparmor`. \ No newline at end of file diff --git a/porting/debugging/hardware-fixes/bluetooth.rst b/porting/debugging/hardware-fixes/bluetooth.rst new file mode 100644 index 000000000..68453bd95 --- /dev/null +++ b/porting/debugging/hardware-fixes/bluetooth.rst @@ -0,0 +1,176 @@ +Bluetooth Configuration +======================= + +Quick Reference +--------------- +Essential configurations:: + + # Kernel config for modern devices + CONFIG_BT=y + CONFIG_BT_BREDR=y # Classic Bluetooth support + CONFIG_BT_LE=y # Bluetooth Low Energy + CONFIG_BT_HCIUART=y # UART transport layer + + # Service verification + systemctl status bluetooth + hciconfig -a + bluetoothctl show + +Understanding Bluetooth Architecture +------------------------------------ + +Bluetooth Stack Components +^^^^^^^^^^^^^^^^^^^^^^^^^^ +The Bluetooth subsystem consists of multiple layers: + +1. **Hardware Layer** + + * Bluetooth controller + * Firmware + * Host interface (UART/USB) + +2. **Host Stack** + + * BlueZ Linux stack + * Android Bluetooth HAL + * Hardware abstraction + +3. **User Space** + + * Bluetooth service + * Audio routing + * Profile support + +Configuration Steps +------------------- + +1. Kernel Configuration +^^^^^^^^^^^^^^^^^^^^^^^ +Modern devices (kernel 4.2+):: + + # Core Bluetooth support + CONFIG_BT=y + CONFIG_BT_BREDR=y + CONFIG_BT_LE=y + + # Transport layers + CONFIG_BT_HCIUART=y + CONFIG_BT_HCIUART_H4=y # H4 protocol + CONFIG_BT_HCIUART_BCM=y # Broadcom protocol + CONFIG_BT_HCIUART_QCA=y # Qualcomm protocol + +Legacy devices (pre-4.2):: + + # Requires backporting from newer kernel + # See backporting guide in vendor-specific section + CONFIG_BT_BACKPORT=y + +2. Firmware Setup +^^^^^^^^^^^^^^^^^ +Configure firmware loading:: + + # /lib/firmware/ + ├── qca/ # Qualcomm firmware + │ ├── nvm.bin + │ └── rampatch.bin + ├── brcm/ # Broadcom firmware + │ ├── BCM4345C0.hcd + │ └── bcm4339.hcd + └── rtl/ # Realtek firmware + └── rtl8723b_fw.bin + +3. Service Configuration +^^^^^^^^^^^^^^^^^^^^^^^^ +Configure bluetooth service:: + + # /etc/bluetooth/main.conf + [General] + Name = %h + Class = 0x000100 + DiscoverableTimeout = 0 + PairableTimeout = 0 + Privacy = off + + [Policy] + AutoEnable=true + ReconnectAttempts=7 + ReconnectIntervals=1,2,4,8,16,32,64 + +4. Audio Profile Setup +^^^^^^^^^^^^^^^^^^^^^^ +Configure Bluetooth audio:: + + # /etc/pulse/touch.pa + .ifexists module-bluetooth-policy.so + load-module module-bluetooth-policy + .endif + + .ifexists module-bluetooth-discover.so + load-module module-bluetooth-discover + .endif + +Implementation Steps +-------------------- + +1. **Verify Hardware Support** + + * Check controller type + * Identify firmware requirements + * Verify kernel support + +2. **Basic Configuration** + + * Enable kernel support + * Configure firmware + * Set up basic service + +3. **Profile Setup** + + * Configure audio profiles + * Enable BLE support + * Set up pairing handling + +4. **Integration Test** + + * Verify controller detection + * Test basic functionality + * Check audio routing + +Common Configurations +--------------------- + +Qualcomm Devices +^^^^^^^^^^^^^^^^ +Common settings for Qualcomm platforms:: + + # Kernel config + CONFIG_BT_HCIUART_QCA=y + CONFIG_QCA_BT_ROME=y + + # Firmware paths + /lib/firmware/qca/nvm.bin + /lib/firmware/qca/rampatch.bin + +Broadcom Devices +^^^^^^^^^^^^^^^^ +Typical Broadcom configuration:: + + # Kernel config + CONFIG_BT_HCIUART_BCM=y + CONFIG_BT_BCM43XX=y + + # Firmware path + /lib/firmware/brcm/BCM4345C0.hcd + +MediaTek Devices +^^^^^^^^^^^^^^^^ +MediaTek specific settings:: + + # Kernel config + CONFIG_MTK_COMBO_BT=y + CONFIG_MTK_BTIF=y + + # Firmware handling + /lib/firmware/mt76xx/mt7668_patch_e1_hdr.bin + +For debugging and troubleshooting guidance, see :doc:`../hardware-debug/connectivity`. \ No newline at end of file diff --git a/porting/debugging/hardware-fixes/camera.rst b/porting/debugging/hardware-fixes/camera.rst new file mode 100644 index 000000000..add24f94c --- /dev/null +++ b/porting/debugging/hardware-fixes/camera.rst @@ -0,0 +1,31 @@ +Camera Configuration +==================== + +Requirements +------------ + +- Working camera HAL +- Proper media codecs +- GStreamer integration + +HAL Setup +--------- +1. Verify camera service: + + .. code-block:: bash + + systemctl status camera-service + +2. Check camera nodes: + + .. code-block:: bash + + ls /dev/video* + +Troubleshooting +--------------- + +- Permission issues +- Missing codecs +- Format compatibility +- Preview/capture issues \ No newline at end of file diff --git a/porting/debugging/index.rst b/porting/debugging/index.rst new file mode 100644 index 000000000..4873c7cd6 --- /dev/null +++ b/porting/debugging/index.rst @@ -0,0 +1,50 @@ +.. _debugging: + +Configuration and Debugging +=========================== + +After achieving first boot, your device will need configuration and debugging to enable full functionality. + +Quick Reference +--------------- + +Critical fixes: +- Display configuration +- Network enablement +- AppArmor implementation +- Audio enablement + +Core Methods +------------ + +1. **Overlay Method** + Configuration changes stored separately and applied during boot. + +2. **Debugging Strategies** + Systematic approaches to identifying and fixing issues. + +3. **Standard Workflows** + Common debugging paths for specific problems. + +.. toctree:: + :maxdepth: 2 + :name: debugging-toc + + overlay-method + + configuration/display + configuration/audio + configuration/networking + configuration/sensors + + + hardware-fixes/apparmor + hardware-fixes/bluetooth + hardware-fixes/camera + + troubleshooting/index + + strategies/index + workflows/index + hardware-debug/index + system-debug/index \ No newline at end of file diff --git a/porting/debugging/overlay-method.rst b/porting/debugging/overlay-method.rst new file mode 100644 index 000000000..06db9ba0b --- /dev/null +++ b/porting/debugging/overlay-method.rst @@ -0,0 +1,222 @@ +.. _overlay-method: + +The Overlay Method +================== + +Quick Start +----------- +Place configuration files in one of these locations: + +1. Primary overlay location:: + + overlay/ + └── system/ + └── halium/ + └── path/to/config + +2. Alternative structure:: + + system/ + └── opt/ + └── halium-overlay/ + └── path/to/config + +Add deviceinfo_use_overlaystore="true" to your deviceinfo file to enable overlay mounting. + +Understanding Overlays +---------------------- +Think of overlays like transparent sheets placed over a document - they let you modify what's visible without changing the original. In Ubuntu Touch, overlays allow you to: + +* Add or modify system files without changing the base system +* Preserve changes across system updates +* Keep device-specific configurations separate +* Test changes safely before making them permanent + +This approach is similar to how you might use transparent sheets for overhead projectors - each sheet adds or modifies content while the base content remains unchanged. + +Types of Overlays +----------------- + +1. File Overlays +^^^^^^^^^^^^^^^^ +Individual files mounted directly over system files, like placing a new page over an old one. + +Example - Changing display configuration:: + + overlay/ + └── system/ + └── halium/ + └── etc/ + └── ubuntu-touch-session.d/ + └── device.conf + +2. Directory Overlays +^^^^^^^^^^^^^^^^^^^^^ +Combines overlay content with original directory, like merging two sets of files. + +Create a marker file named .halium-overlay-dir:: + + overlay/ + └── system/ + └── halium/ + └── etc/ + └── some-dir/ + ├── .halium-overlay-dir + └── custom.conf + +3. Directory Replacement +^^^^^^^^^^^^^^^^^^^^^^^^ +Completely replaces original directory content, like swapping out an entire folder. + +Create a marker file named .halium-override-dir:: + + overlay/ + └── system/ + └── halium/ + └── etc/ + └── replaced-dir/ + ├── .halium-override-dir + └── new.conf + +Implementation +-------------- + +Basic Setup +^^^^^^^^^^^ +1. Create overlay directory:: + + mkdir -p overlay/system/halium + +2. Mirror target path structure:: + + # For file at /etc/example.conf + mkdir -p overlay/system/halium/etc + + # Add configuration file + cp example.conf overlay/system/halium/etc/ + +This structure tells the system exactly where to apply your changes. + +Directory Operations +^^^^^^^^^^^^^^^^^^^^ + +To merge with existing directory:: + + # Create overlay directory + mkdir -p overlay/system/halium/etc/some-dir + + # Mark for overlay + touch overlay/system/halium/etc/some-dir/.halium-overlay-dir + + # Add files + cp custom.conf overlay/system/halium/etc/some-dir/ + +The .halium-overlay-dir marker tells the system to merge contents. + +To replace entire directory:: + + # Create replacement directory + mkdir -p overlay/system/halium/etc/replaced-dir + + # Mark for replacement + touch overlay/system/halium/etc/replaced-dir/.halium-override-dir + + # Add new files + cp new.conf overlay/system/halium/etc/replaced-dir/ + +The .halium-override-dir marker signals complete directory replacement. + +Common Configurations +--------------------- + +1. Display Settings:: + + overlay/system/halium/etc/ubuntu-touch-session.d/ + ├── .halium-overlay-dir + └── device.conf + +2. Audio Configuration:: + + overlay/system/halium/etc/pulse/ + ├── .halium-override-dir + └── arm_droid_card_custom.pa + +3. System Services:: + + overlay/system/halium/etc/systemd/system/ + ├── .halium-overlay-dir + └── custom.service + +Verification +------------ + +1. Check Overlay Mounting +^^^^^^^^^^^^^^^^^^^^^^^^^ +After boot, verify overlays:: + + # Check mount points + mount | grep overlay + + # Verify file content + cat /etc/example.conf + + # Check permissions + ls -l /path/to/overlaid/file + +2. Common Issues +^^^^^^^^^^^^^^^^ +* Missing parent directories +* Incorrect permissions +* Wrong overlay markers +* Path mapping errors + +Troubleshooting +--------------- + +If overlays aren't working: + +1. Verify directory structure matches exactly +2. Check overlay marker files exist +3. Confirm file permissions +4. Review mount points +5. Check system logs:: + + journalctl -b | grep overlay + +Advanced Usage +-------------- + +1. Multi-level Overlays:: + + overlay/ + └── system/ + └── halium/ + └── etc/ + ├── dir1/ + │ ├── .halium-overlay-dir + │ └── file1.conf + └── dir2/ + ├── .halium-override-dir + └── file2.conf + +2. Conditional Overlays:: + + # Based on device model + overlay/system/halium/etc/model-specific/ + └── $(getprop ro.product.device)/ + └── config.conf + +Next Steps +---------- + +**Ready to configure hardware?** + → :doc:`configuration/display` + +**Need to debug overlay issues?** + → :doc:`troubleshooting/system-issues` + +See Also +-------- +* :ref:`device-config` - Device configuration +* :doc:`configuration/display` - Display setup example +* :doc:`troubleshooting/system-issues` - Overlay debugging \ No newline at end of file diff --git a/porting/debugging/strategies/hardware.rst b/porting/debugging/strategies/hardware.rst new file mode 100644 index 000000000..fc2230bd8 --- /dev/null +++ b/porting/debugging/strategies/hardware.rst @@ -0,0 +1,39 @@ +Hardware Debugging +================== + +Debug Interfaces +---------------- +Serial console:: + + screen /dev/ttyUSB0 115200 + minicom -D /dev/ttyUSB0 + dmesg | grep ttyUSB + +JTAG/SWD:: + + openocd -f interface.cfg + gdb -ex "target remote :3333" + load-firmware.sh + +Testing Tools +------------- +Hardware probes:: + + evtest # Input events + v4l2-ctl # Camera/video + rtcwake # Power management + +Bus analysis:: + + i2cdetect -l # I2C devices + lsusb -v # USB devices + udevadm monitor # Device events + +Debug Hardware +-------------- +Required equipment: + +- USB-serial adapter +- JTAG debugger +- Logic analyzer +- Multimeter \ No newline at end of file diff --git a/porting/debugging/strategies/index.rst b/porting/debugging/strategies/index.rst new file mode 100644 index 000000000..8f9fb1adb --- /dev/null +++ b/porting/debugging/strategies/index.rst @@ -0,0 +1,212 @@ +.. _debugging-strategies: + +Debugging Strategies +==================== + +This guide covers systematic approaches to debugging Ubuntu Touch ports. + +Core Principles +--------------- + +1. **Identify Failure Stage** + + * Pre-boot: No USB detection + * Early boot: USB detected, no shell access + * Late boot: Shell access but system incomplete + * Post-boot: System runs with issues + +2. **Gather Information** + + Critical logs:: + + dmesg # Kernel messages + journalctl -b # System logs + lxc-info -n android # Container status + /var/log/lightdm/lightdm.log # Display server + /proc/last_kmsg # Last kernel log + + Hardware status:: + + ls /dev/input/event* # Input devices + ls /dev/block/platform # Storage + mount # Mounted filesystems + ps aux # Running processes + +3. **Isolate Issues** + + Hardware vs Software:: + + # Hardware checks + cat /proc/interrupts # IRQ assignment + cat /sys/class/power_supply/* # Power subsystem + + # Software checks + systemctl status # Service status + apparmor_status # Security policy + logcat # Android container + +Core Tools +---------- + +Debug Access +^^^^^^^^^^^^ +Methods by failure stage: + +**No Boot** + * Fastboot for partition operations + * Recovery mode logging + * Serial console if available + +**Partial Boot** + * ADB for system access + * SSH over USB network + * Telnet emergency shell + +**System Running** + * SSH/ADB normal access + * System logs + * Performance tools + +Log Analysis +^^^^^^^^^^^^ +Key log locations:: + + /var/log/ # System logs + /proc/last_kmsg # Last kernel messages + /var/log/dmesg # Boot messages + /var/log/syslog # System messages + /var/log/lightdm/ # Display server + /android/system/var/log/ # Android container + +Common Patterns +--------------- + +Boot Issues +^^^^^^^^^^^ +1. **Kernel Panic** + + * Check last_kmsg + * Verify kernel config + * Test without modules + +2. **Init Failure** + + * Check init scripts + * Verify mounts + * Review service deps + +3. **Container Issues** + + * Verify vendor blobs + * Check SELinux status + * Monitor LXC state + +Hardware Detection +^^^^^^^^^^^^^^^^^^ +1. **Input Devices**:: + + # Check detection + ls /dev/input/event* + getevent -l + + # Test functionality + evtest /dev/input/event0 + +2. **Display**:: + + # Check framebuffer + ls /dev/fb* + + # Monitor errors + dmesg | grep -i display + journalctl -u lightdm + +3. **Storage**:: + + # Verify partitions + lsblk + mount | grep mapper + + # Check errors + dmesg | grep -i "I/O error" + +Systematic Approach +------------------- + +1. **Gather Facts** + + * Identify exact failure point + * Collect relevant logs + * Document hardware state + +2. **Form Hypothesis** + + * Review similar issues + * Check common failures + * Consider hardware/software split + +3. **Test Solution** + + * Make single changes + * Document modifications + * Verify fix complete + +4. **Document Findings** + + * Record root cause + * Document solution + * Share with community + +Recovery Options +---------------- + +1. **Safe Mode**:: + + # Disable services + systemctl isolate multi-user.target + + # Minimal graphics + GRID_UNIT_PX=18 ubuntu-touch-session + +2. **Emergency Access**:: + + # Recovery shell + touch /userdata/.force-ssh + + # Debug shell + ubuntu_chroot debug + +3. **Factory Reset**:: + + # Clear user data + rm -rf /userdata/* + + # Reset system + halium-install -p ut rootfs.tar.gz system.img + +.. toctree:: + :maxdepth: 2 + :name: strategies-toc + + logs + hardware + performance + recovery + +Next Steps +---------- + +**Hardware issues?** + → :doc:`../hardware-debug/index` + +**System problems?** + → :doc:`../system-debug/index` + +**Need workflows?** + → :doc:`../workflows/index` + +See Also +-------- +* :ref:`first-boot` - First boot debugging +* :ref:`hardware-abstraction` - Hardware subsystems +* :ref:`overlay-method` - System configuration \ No newline at end of file diff --git a/porting/debugging/strategies/logs.rst b/porting/debugging/strategies/logs.rst new file mode 100644 index 000000000..e3e205c3c --- /dev/null +++ b/porting/debugging/strategies/logs.rst @@ -0,0 +1,40 @@ +Log Analysis Guide +================== + +Key Log Locations +----------------- +System logs:: + + /var/log/syslog # General system logs + /proc/last_kmsg # Last kernel messages + /var/log/lightdm/* # Display server + /var/crash/* # System crash dumps + /android/system/var/log/* # Android container + +Collection Methods +------------------ +Boot logs:: + + dmesg -w # Kernel messages + journalctl -fb # System journal + logcat # Android logs + +Service logs:: + + journalctl -u # Specific service + systemctl status # Service status + lxc-info -n android # Container info + +Analysis Tools +-------------- +Text processing:: + + grep -r "error" /var/log/ # Search logs + tail -f /var/log/syslog # Monitor logs + awk '/pattern/ {print}' # Filter logs + +Visualization:: + + journalctl --output=json # JSON format + journalctl --output=short # Condensed view + logcat -v threadtime # Thread view \ No newline at end of file diff --git a/porting/debugging/strategies/performance.rst b/porting/debugging/strategies/performance.rst new file mode 100644 index 000000000..551cc0f55 --- /dev/null +++ b/porting/debugging/strategies/performance.rst @@ -0,0 +1,31 @@ +Performance Analysis +==================== + +Monitoring Tools +---------------- +System metrics:: + + top -b -n1 # Process stats + iostat -x # I/O stats + free -h # Memory usage + mpstat -P ALL # CPU usage + +Profile tools:: + + perf record # Performance data + strace -c # System calls + valgrind --tool=callgrind # Call profiling + +Benchmarking +------------ +Storage:: + + dd if=/dev/zero # Write speed + hdparm -tT # Read speed + fio # I/O patterns + +Graphics:: + + glmark2 # OpenGL test + vkmark # Vulkan test + lomiri-benchmark # UI performance \ No newline at end of file diff --git a/porting/debugging/strategies/recovery.rst b/porting/debugging/strategies/recovery.rst new file mode 100644 index 000000000..67a9ed8c1 --- /dev/null +++ b/porting/debugging/strategies/recovery.rst @@ -0,0 +1,30 @@ +Recovery Methods +================ + +Emergency Access +---------------- +Debug shells:: + + touch /userdata/.force-ssh # Enable SSH + ubuntu_chroot debug # Debug shell + adbd # ADB access + +Safe mode:: + + systemctl isolate rescue.target + systemctl emergency + init=/bin/bash + +Data Recovery +------------- +Filesystem tools:: + + fsck.ext4 # Check filesystem + e2image # Backup partition + ddrescue # Recovery copy + +Recovery options:: + + halium-install -p ut # Reinstall system + fastboot flash # Flash partitions + adb sideload # Load updates \ No newline at end of file diff --git a/porting/debugging/system-debug/apparmor.rst b/porting/debugging/system-debug/apparmor.rst new file mode 100644 index 000000000..e405ea9c7 --- /dev/null +++ b/porting/debugging/system-debug/apparmor.rst @@ -0,0 +1,33 @@ +AppArmor Debugging +================== + +Profile Status +-------------- +Check status:: + + aa-status + apparmor_parser -p + dmesg | grep apparmor + +Policy Debug +------------ +Debug steps:: + + # Check denials + dmesg | grep DENIED + aa-notify -s 1d + + # Test profiles + aa-complain /etc/apparmor.d/PROFILE + aa-audit /etc/apparmor.d/PROFILE + +Common Issues +------------- +Profile problems:: + + # Reload profile + apparmor_parser -r /etc/apparmor.d/PROFILE + + # Generate policy + aa-logprof + aa-genprof \ No newline at end of file diff --git a/porting/debugging/system-debug/container.rst b/porting/debugging/system-debug/container.rst new file mode 100644 index 000000000..19f35d7c5 --- /dev/null +++ b/porting/debugging/system-debug/container.rst @@ -0,0 +1,66 @@ +.. _debugging-container: + +Android Container Debugging +=========================== + +Container Status +---------------- +Basic checks:: + + lxc-info -n android + lxc-ls --fancy + systemctl status lxc@android + +Log Analysis +------------ +Key logs:: + + journalctl -u lxc@android + logcat + dmesg | grep -i binder + +Mount Points +------------ +Check mounts:: + + mount | grep android + ls -l /android/system + ls -l /vendor + +Security Policies +^^^^^^^^^^^^^^^^^ +Ubuntu Touch uses AppArmor as its primary security framework, while the Android container utilizes SELinux. This dual-policy approach means: + +1. **AppArmor** + * Manages Ubuntu Touch system security + * Controls application confinement + * Handles system service access + +2. **SELinux** + * Active only within Android container + * Controls Android HAL permissions + * Manages hardware access rights + +When debugging permission issues:: + + # Check AppArmor status (Ubuntu Touch) + aa-status + dmesg | grep DENIED + + # Check SELinux (Android container) + getenforce + audit2allow -i /var/log/audit/audit.log + +This separation helps maintain compatibility with Android's security model while integrating with Ubuntu Touch's security framework. + +Common Issues +------------- +Service failures:: + + # Binder + cat /proc/binder/status + cat /proc/binder/failed_transaction_log + + # SELinux + getenforce + audit2allow -i /var/log/audit/audit.log \ No newline at end of file diff --git a/porting/debugging/system-debug/index.rst b/porting/debugging/system-debug/index.rst new file mode 100644 index 000000000..43f9d7224 --- /dev/null +++ b/porting/debugging/system-debug/index.rst @@ -0,0 +1,10 @@ +System Debugging +================ + +.. toctree:: + :maxdepth: 2 + + container + services + apparmor + storage \ No newline at end of file diff --git a/porting/debugging/system-debug/services.rst b/porting/debugging/system-debug/services.rst new file mode 100644 index 000000000..e3c1d790a --- /dev/null +++ b/porting/debugging/system-debug/services.rst @@ -0,0 +1,27 @@ +System Services Debug +===================== + +Service Management +------------------ +Status checks:: + + systemctl list-units + systemctl status NAME + systemd-analyze blame + +Common Services +--------------- +Critical services:: + + lightdm # Display + repowerd # Power + lxc@android # Container + ofono # Telephony + +Debug Methods +------------- +Service logs:: + + journalctl -u SERVICE + systemctl status SERVICE + systemd-analyze critical-chain \ No newline at end of file diff --git a/porting/debugging/system-debug/storage.rst b/porting/debugging/system-debug/storage.rst new file mode 100644 index 000000000..9a90db959 --- /dev/null +++ b/porting/debugging/system-debug/storage.rst @@ -0,0 +1,38 @@ +Storage Debugging +================= + +Filesystem Check +---------------- +Basic checks:: + + df -h + mount + lsblk + +Partition Layout +---------------- +Check layout:: + + fdisk -l + sgdisk --print + blkid + +Common Issues +------------- +I/O errors:: + + dmesg | grep -i "I/O error" + smartctl -a /dev/sda + hdparm -i /dev/sda + +Mount Issues +------------ +Debug steps:: + + # Check fstab + cat /etc/fstab + mount -a + + # Verify paths + ls -l /dev/mapper/ + cryptsetup status \ No newline at end of file diff --git a/porting/debugging/troubleshooting/boot-issues.rst b/porting/debugging/troubleshooting/boot-issues.rst new file mode 100644 index 000000000..bfba6f009 --- /dev/null +++ b/porting/debugging/troubleshooting/boot-issues.rst @@ -0,0 +1,166 @@ +Boot-Related Issues +=================== + +Quick Diagnosis +--------------- +1. Observe symptoms: + + * No boot at all + * Boot loop + * Stuck at logo + * Black screen with power + +2. Check for access: + + * Fastboot availability + * ADB connectivity + * SSH/telnet possible + * Serial console output + +Kernel Panic +------------ +Symptoms: + +* Device reboots immediately +* No USB connection established +* May show brief error message + +Diagnostic Steps: + +1. Check kernel logs:: + + # If you can get adb access + adb pull /proc/last_kmsg + + # From recovery + cat /proc/last_kmsg > /sdcard/last_kmsg + adb pull /sdcard/last_kmsg + +2. Common causes: + + * Missing kernel configs + * Incorrect device tree + * Driver initialization failure + * Memory allocation issues + +Solutions: + +1. **Config Issues**:: + + # Verify essential configs + CONFIG_DEVTMPFS=y + CONFIG_FHANDLE=y + CONFIG_SYSVIPC=y + CONFIG_CGROUPS=y + +2. **Device Tree**: + + * Check compatible string + * Verify pin configurations + * Review clock settings + +3. **Driver Issues**: + + * Disable problematic drivers + * Add debugging prints + * Check initialization order + +Boot Loop +--------- +Symptoms: + +* Device starts booting +* Shows vendor logo +* Restarts repeatedly + +Diagnostic Steps: + +1. Enable kernel messages:: + + # Add to kernel command line + androidboot.console=tty0 console=tty0 + +2. Check system logs: + + * Look for init failures + * Check service crashes + * Monitor resource usage + +Solutions: + +1. **Init Issues**: + + * Verify init scripts + * Check service dependencies + * Review mount points + +2. **Resource Problems**: + + * Monitor memory usage + * Check storage space + * Verify partition layout + +Black Screen +------------ +Symptoms: + +* No display output +* Device may be running +* Possible USB connectivity + +Diagnostic Steps: + +1. Check device state:: + + # Look for network interface + dmesg -w + + # Try SSH connection + ssh phablet@10.15.19.82 + +2. Verify display subsystem: + + * Check driver loading + * Review backlight control + * Monitor display initialization + +Solutions: + +1. **Driver Loading**:: + + # Add to kernel command line + video=HDMI-A-1:1920x1080@60 + +2. **Display Configuration**: + + * Review display device tree + * Check panel initialization + * Verify backlight control + +Recovery Steps +-------------- +When troubleshooting fails: + +1. **Safe Boot** + + * Disable services + * Use minimal configuration + * Enable verbose logging + +2. **Recovery Mode** + + * Access device logs + * Modify configurations + * Restore known-good state + +3. **Emergency Procedures** + + * Force USB mode + * Use emergency shells + * Access recovery console + +See Also +-------- +* :ref:`first-boot` - Initial boot process +* :ref:`display` - Display configuration +* :ref:`debugging` - General debugging \ No newline at end of file diff --git a/porting/debugging/troubleshooting/hardware-issues.rst b/porting/debugging/troubleshooting/hardware-issues.rst new file mode 100644 index 000000000..4afd227b6 --- /dev/null +++ b/porting/debugging/troubleshooting/hardware-issues.rst @@ -0,0 +1,267 @@ +.. _debugging-hardware: + +Hardware-Related Issues +======================= + +This guide covers diagnosing and fixing hardware functionality issues in Ubuntu Touch ports. + +Quick Diagnosis +--------------- +1. Check hardware detection:: + + # List detected devices + ls /dev/input/event* + + # Check USB devices + lsusb + + # View loaded kernel modules + lsmod + +2. Verify permissions:: + + # Check udev rules + ls /etc/udev/rules.d/ + + # View device permissions + ls -l /dev/input/event* + +3. Monitor hardware events:: + + # Watch device events + udevadm monitor + + # Monitor input events + evtest /dev/input/event1 + +WiFi Issues +----------- +Common Symptoms: + +* WiFi device not detected +* Cannot scan networks +* Connection failures +* Poor performance + +Diagnostic Steps: + +1. Check driver status:: + + # View wireless interfaces + iw dev + + # Check driver loading + dmesg | grep wifi + + # Verify firmware loading + dmesg | grep firmware + +2. Common causes: + + * Missing firmware files + * Incorrect driver configuration + * Power management issues + * Regulatory domain problems + +Solutions: + +1. **Driver Setup**:: + + # Required kernel configs + CONFIG_CFG80211=y + CONFIG_MAC80211=y + CONFIG_WLAN=y + +2. **Firmware Files**: + + * Check vendor firmware directory + * Verify file permissions + * Monitor firmware loading + +3. **Debugging Steps**:: + + # Enable verbose logging + echo 1 > /sys/kernel/debug/ieee80211/phy0/netdev:wlan0/pm_disable + + # Monitor connection attempts + iw event + +Audio Problems +-------------- +Symptoms: + +* No audio output +* Distorted sound +* Wrong output device +* Microphone issues + +Diagnostic Steps: + +1. Check audio subsystem:: + + # List audio devices + aplay -l + + # Check ALSA status + alsa-info + +2. Verify UCM configuration:: + + # Check UCM files + ls /usr/share/alsa/ucm2/ + + # Test audio routing + pacmd list-sinks + +Solutions: + +1. **Driver Configuration**:: + + # Essential kernel configs + CONFIG_SND=y + CONFIG_SND_SOC=y + CONFIG_SND_PCM=y + +2. **UCM Setup**: + + * Copy correct UCM files + * Set proper device names + * Configure mixer paths + +3. **PulseAudio Configuration**:: + + # Edit /etc/pulse/touch.pa + load-module module-droid-card rate=48000 + load-module module-droid-hidl + +Sensor Issues +------------- +Symptoms: + +* Screen rotation not working +* Proximity sensor fails +* Ambient light issues +* Accelerometer problems + +Diagnostic Steps: + +1. Check sensor detection:: + + # List input devices + ls /dev/input/ + + # Monitor sensor events + getevent -l + +2. Verify sensor service:: + + # Check service status + systemctl status sensorfwd + + # Monitor sensor data + sensorfw-tests + +Solutions: + +1. **Input Configuration**:: + + # Add udev rules + ACTION=="add", KERNEL=="event*", ATTRS{name}=="accelerometer", \ + MODE="0666", GROUP="input" + +2. **Sensor Service**: + + * Configure sensor plugins + * Set correct orientations + * Enable debugging output + +3. **Common Fixes**:: + + # Reset sensor service + systemctl restart sensorfwd + + # Clear sensor calibration + rm -rf ~/.local/share/sensors + +Camera Problems +--------------- +Symptoms: + +* Camera not detected +* Preview fails +* Capture errors +* Focus issues + +Diagnostic Steps: + +1. Check camera detection:: + + # List video devices + ls /dev/video* + + # Check permissions + ls -l /dev/video* + +2. Verify camera service:: + + # Check service status + systemctl status camera-service + + # Monitor logs + journalctl -u camera-service + +Solutions: + +1. **Driver Setup**:: + + # Required kernel configs + CONFIG_MEDIA_SUPPORT=y + CONFIG_MEDIA_CAMERA_SUPPORT=y + CONFIG_VIDEO_V4L2=y + +2. **HAL Configuration**: + + * Set correct media profiles + * Configure camera parameters + * Verify format support + +3. **Permission Setup**:: + + # Add camera group + usermod -a -G video phablet + +Recovery Steps +-------------- +When hardware troubleshooting fails: + +1. **Driver Reset**:: + + # Reload kernel module + modprobe -r problematic_module + modprobe problematic_module + + # Reset device power + echo 1 > /sys/bus/usb/devices/xxx/authorized + +2. **Service Recovery**:: + + # Restart affected services + systemctl restart affected-service + + # Clear cached data + rm -rf /var/lib/service-cache/* + +3. **System Verification**:: + + # Check system logs + journalctl -b + + # Monitor hardware status + udevadm monitor --property + +See Also +-------- +* :ref:`hardware-abstraction` - HAL configuration +* :ref:`debugging` - General debugging guide +* :doc:`boot-issues` - Boot-related problems +* :doc:`system-issues` - System-level issues \ No newline at end of file diff --git a/porting/debugging/troubleshooting/index.rst b/porting/debugging/troubleshooting/index.rst new file mode 100644 index 000000000..c08764c9c --- /dev/null +++ b/porting/debugging/troubleshooting/index.rst @@ -0,0 +1,42 @@ +.. _troubleshooting: + +Troubleshooting Guide +===================== + +This guide helps diagnose and resolve common issues encountered during Ubuntu Touch porting. + +Quick Reference +--------------- + +Common failure points: + +1. **Boot Issues** + + - Kernel panic + - Boot loop + - Black screen + - Stuck at logo + +2. **Hardware Issues** + + - Display not working + - No touch input + - WiFi/modem failure + - Audio problems + +3. **System Issues** + + - Container fails to start + - Missing hardware support + - App crashes + - Performance problems + +See specific sections below for diagnostic steps and solutions. + +.. toctree:: + :maxdepth: 2 + :name: troubleshooting-toc + + boot-issues + hardware-issues + system-issues \ No newline at end of file diff --git a/porting/debugging/troubleshooting/system-issues.rst b/porting/debugging/troubleshooting/system-issues.rst new file mode 100644 index 000000000..283f9454c --- /dev/null +++ b/porting/debugging/troubleshooting/system-issues.rst @@ -0,0 +1,450 @@ +System-Level Issues +=================== + +This part of the guide covers problems with Ubuntu Touch system components, services, and overall functionality. System issues often manifest after successful boot but prevent normal operation. + +Quick Diagnosis +--------------- +1. Check system status:: + + # View system logs + journalctl -b + + # Check running services + systemctl status + + # Monitor resource usage + top -b -n 1 + +Understanding these commands: + +* journalctl -b: Shows messages from current boot +* systemctl status: Reports service health +* top: Reveals resource usage and running processes + +2. Verify container state:: + + # Check LXC status + lxc-info -n android + + # View container logs + journalctl -u lxc@android + +3. Test system access:: + + # Check system mounts + mount | grep system + + # Verify system services + systemctl status ofono + systemctl status repowerd + + # Check user session services + systemctl --user status lomiri-full-session.service + +.. note:: + Lomiri (formerly Unity8) runs as a user service, not a system service. Always use + ``systemctl --user`` when checking Lomiri-related services. The full service name + is ``lomiri-full-session.service``. + +These checks reveal: + +* System partition mounting +* Core service status +* Hardware initialization + +Container Problems +------------------ + +Android Container Fails +^^^^^^^^^^^^^^^^^^^^^^^ +Symptoms: + +* System boots but no hardware support +* Services fail to start +* Hardware initialization errors + +Understanding the container: + +* Runs minimal Android for hardware support +* Contains vendor-specific code +* Manages hardware abstraction layer + +Diagnostic Steps:: + + # Check container status + systemctl status lxc@android + + # View detailed logs + journalctl -u lxc@android -n 100 + + # Check mount points + ls -l /android/system + ls -l /vendor + +Understanding outputs: + +* Failed status suggests initialization problems +* Log messages reveal specific failures +* Mount points show filesystem issues + +Solutions: + +1. **Mount Issues**:: + + # Verify fstab entries + cat /etc/fstab + + # Check mount points + mountpoint /android/system + mountpoint /vendor + +Common mount problems: + +* Missing mount points +* Wrong filesystem type +* Permission issues +* SELinux contexts + +2. **Permission Problems**:: + + # Fix basic permissions + chmod 755 /android/system + chmod 755 /vendor + + # Verify SELinux status + getenforce + +Understanding permissions: + +* Directories need execute (x) permission +* SELinux can block access +* Wrong ownership prevents operation + +3. **Service Dependencies**:: + + # Restart container + systemctl restart lxc@android + + # Check dependent services + systemctl list-dependencies lxc@android + +Service dependency chain: + +* Container needs working filesystem +* Hardware services depend on container +* System services need hardware access + +System Services +--------------- + +Service Failures +^^^^^^^^^^^^^^^^ +Common problematic services: + +* repowerd (power management) +* ofono (telephony) +* unity8 (display server) +* pulseaudio (audio) + +Understanding service roles: + +* repowerd manages power states +* ofono handles phone functionality +* unity8 provides user interface +* pulseaudio controls audio system + +Diagnostic Steps:: + + # Check specific service + systemctl status servicename + + # View service logs + journalctl -u servicename + + # List failed services + systemctl --failed + +Log interpretation: + +* Failed state indicates startup problems +* Log messages show error details +* Dependencies reveal related issues + +Solutions: + +1. **Service Recovery**:: + + # Restart service + systemctl restart servicename + + # Clear service state + rm -rf /var/lib/servicename/* + + # Reset service configuration + dpkg-reconfigure servicename + +Recovery process: + +* Restart attempts clean start +* Clearing state removes corruption +* Reconfiguration resets settings + +2. **Dependency Issues**:: + + # Check dependencies + systemctl list-dependencies servicename + + # Verify required files + ldd /usr/bin/servicename + +Understanding dependencies: + +* Services need specific libraries +* Missing dependencies block start +* Version mismatches cause failures + +3. **Permission Problems**:: + + # Fix service user + chown -R service:service /var/lib/servicename + + # Check policy kit rules + ls /usr/share/polkit-1/actions/ + +Policy considerations: + +* Services run as specific users +* PolicyKit manages permissions +* Wrong ownership blocks access + +Performance Issues +------------------ + +System Slowdown +^^^^^^^^^^^^^^^ +Symptoms: + +* Slow response time +* App launch delays +* UI lag +* High resource usage + +Understanding performance: + +* Multiple potential causes +* Resource constraints +* System bottlenecks + +Diagnostic Steps:: + + # Monitor CPU usage + top -b -n 1 + + # Check memory + free -h + + # View I/O activity + iotop -b -n 1 + +Interpreting results: + +* High CPU indicates processing bottleneck +* Low memory causes swapping +* I/O bottlenecks slow system + +Solutions: + +1. **Resource Management**:: + + # Clear cache + sync; echo 3 > /proc/sys/vm/drop_caches + + # Check swap usage + swapon -s + +Cache management: + +* Clearing cache frees memory +* Swap usage indicates memory pressure +* Regular cleaning helps performance + +2. **Process Control**:: + + # Find resource-heavy processes + ps aux --sort=-%cpu + ps aux --sort=-%mem + + # Adjust process priority + renice -n 19 -p PID + +Process management: + +* High CPU processes may need limiting +* Memory-heavy processes affect performance +* Priority adjustment helps balance + +3. **Storage Issues**:: + + # Check disk space + df -h + + # Find large files + find / -type f -size +100M + +Storage considerations: + +* Full storage slows system +* Large files impact performance +* Regular cleanup helps + +App Crashes +----------- +Symptoms: + +* Apps fail to launch +* Random crashes +* White screen on launch +* App freezes + +Understanding app issues: + +* Multiple potential causes +* Security constraints +* Resource limitations + +Diagnostic Steps:: + + # Check app logs + journalctl | grep appname + + # View AppArmor denials + dmesg | grep audit + + # Monitor app process + ps aux | grep appname + +Log interpretation: + +* Crashes show in system logs +* AppArmor may block access +* Process state reveals issues + +Solutions: + +1. **AppArmor Issues**:: + + # Check profile status + aa-status + + # Review denials + aa-notify -s 1d + +AppArmor considerations: + +* Profiles restrict app access +* Denials prevent functionality +* Profiles may need updating + +2. **Resource Limitations**:: + + # Clear app cache + rm -rf ~/.cache/appname + + # Reset app data + rm -rf ~/.local/share/appname + +Resource management: + +* Cache buildup affects performance +* Corrupted data causes crashes +* Fresh start often helps + +3. **System Integration**:: + + # Verify app confinement + click list + + # Check frameworks + click framework + +Integration aspects: + +* Apps need correct frameworks +* Confinement affects functionality +* System updates impact apps + +Recovery Procedures +------------------- + +When system issues persist: + +1. **Safe Mode Boot**:: + + # Disable non-essential services + systemctl isolate rescue.target + + # Start minimal system + systemctl isolate multi-user.target + +Safe mode provides: + +* Minimal system functionality +* Debugging opportunity +* Issue isolation + +2. **System Reset**:: + + # Clear system logs + journalctl --vacuum-time=1d + + # Reset failed services + systemctl reset-failed + +Reset benefits: + +* Removes old logs +* Clears error states +* Enables fresh start + +3. **Emergency Recovery**:: + + # Access emergency mode + systemctl emergency + + # Check system integrity + fsck -f / + +Emergency mode offers: + +* Basic system access +* Filesystem checks +* Recovery options + +Best Practices +-------------- + +1. **Regular Maintenance** + + * Monitor system logs + * Check service status + * Review resource usage + * Clear old logs/cache + +2. **Backup Critical Data** + + * Save configuration files + * Back up user data + * Document custom changes + +3. **Update Management** + + * Track system updates + * Test after changes + * Maintain rollback ability + +See Also +-------- +* :ref:`hardware-abstraction` - HAL configuration +* :doc:`boot-issues` - Boot-related problems +* :doc:`hardware-issues` - Hardware-specific issues \ No newline at end of file diff --git a/porting/debugging/workflows/first-boot.rst b/porting/debugging/workflows/first-boot.rst new file mode 100644 index 000000000..4600d9bdd --- /dev/null +++ b/porting/debugging/workflows/first-boot.rst @@ -0,0 +1,280 @@ +.. _initial-boot: + +First Boot Debugging +==================== + +A systematic approach to debugging first boot issues and gaining initial system access. The first boot of a new port often provides no visual feedback, so we need to understand what's happening behind the scenes. + +Boot Stages +----------- + +1. **Bootloader Stage** + + First, verify you can communicate with the device:: + + fastboot devices + fastboot getvar all + + What to look for: + + * Device detected by fastboot + * Correct bootloader variant + * Partition information + * Lock status + + Common issues: + + - No device detection + + * Check USB cable and port + * Verify bootloader mode + * Check udev rules + + - Wrong bootloader variant + + * Verify bootloader compatibility + * Check for specific requirements + * Review vendor documentation + + - Partition errors + + * Verify partition table + * Check partition sizes + * Confirm naming conventions + +2. **Early Boot** + + Monitor kernel startup:: + + # From recovery + cat /proc/last_kmsg + + # From host + dmesg -w + + What to watch for: + + * Kernel initialization messages + * Driver loading status + * Hardware detection + * Error messages + + Common failures: + + - Kernel panic + + * Incorrect configuration + * Missing drivers + * Wrong device tree + + - Init failure + + * Missing required modules + * Wrong ramdisk + * Filesystem issues + + - Missing modules + + * Check kernel config + * Verify module loading + * Review dependencies + +3. **System Init** + + Check system startup:: + + # Via SSH/ADB + systemctl status + journalctl -b + lxc-info -n android + + Important indicators: + + * Systemd initialization + * Service startup sequence + * Android container status + * Hardware initialization + +Gaining Access +-------------- + +USB Network Method +^^^^^^^^^^^^^^^^^^ +1. On host system:: + + # Set up USB network interface + ip link set address 02:11:22:33:44:55 + ip address add 10.15.19.100/24 dev + ip link set up + +Understanding these commands: + +* Sets MAC address for consistent networking +* Configures IP network for communication +* Enables the interface + +2. Connect to device:: + + ssh phablet@10.15.19.82 + +The default password is the one you set during installation. + +Telnet Debug Access +^^^^^^^^^^^^^^^^^^^ +If system partially boots:: + + telnet 192.168.2.15 + +This fallback method indicates: + +* Init system started +* Network partially working +* System not fully booted + +Serial Console +^^^^^^^^^^^^^^ +If available:: + + sudo screen /dev/ttyUSB0 115200 + +Serial access provides: + +* Earliest boot messages +* Kernel debugging output +* Direct system access + +Common Issues +------------- + +Kernel Problems +^^^^^^^^^^^^^^^ +1. **Panic on Boot** + + Check logs for:: + + Unable to mount root fs + VFS: Cannot open root device + Kernel panic - not syncing + + Solutions: + + - Root filesystem issues + + * Verify kernel config + * Check initramfs content + * Review mount options + + - Device tree problems + + * Validate DTB/DTBO + * Check compatibility + * Review pin configurations + +2. **Driver Failures** + + Look for:: + + Unknown symbol + Failed to load module + Device probe failed + + Solutions: + + - Module issues + + * Check dependencies + * Verify build config + * Review loading order + + - Vendor blob problems + + * Verify blob versions + * Check compatibility + * Review initialization + +System Issues +^^^^^^^^^^^^^ +1. **Container Failure** + + Check:: + + # Container status + lxc-info -n android + + # Service logs + journalctl -u lxc@android + + Solutions: + + - Mount problems + + * Check fstab entries + * Verify mount points + * Review permissions + + - SELinux issues + + * Check policies + * Review contexts + * Verify settings + +2. **Init Problems** + + Monitor:: + + systemctl status + journalctl -u systemd-* + dmesg | grep systemd + + Key areas: + + * Service dependencies + * Mount ordering + * Hardware initialization + +Recovery Steps +-------------- + +Safe Mode Boot +^^^^^^^^^^^^^^ +1. Disable services:: + + systemctl isolate rescue.target + +2. Enable debugging:: + + touch /userdata/.force-ssh + +This provides: + +* Minimal system startup +* Basic hardware access +* Debug capabilities + +Recovery Access +^^^^^^^^^^^^^^^ +1. Boot to recovery +2. Pull logs:: + + adb pull /proc/last_kmsg + adb pull /cache/recovery/last_kmsg + +3. Check partitions:: + + adb shell mount + adb shell ls -l /dev/block/platform + +Next Steps +---------- + +**Container issues?** + → :doc:`../system-debug/container` + +**Hardware problems?** + → :doc:`../hardware-debug/index` + +See Also +-------- +* :ref:`debugging-strategies` - General debugging approach +* :ref:`hardware-abstraction` - Hardware subsystems +* :ref:`troubleshooting` - Issue-specific guides \ No newline at end of file diff --git a/porting/debugging/workflows/hardware-bringup.rst b/porting/debugging/workflows/hardware-bringup.rst new file mode 100644 index 000000000..70bbe3269 --- /dev/null +++ b/porting/debugging/workflows/hardware-bringup.rst @@ -0,0 +1,97 @@ +Hardware Bringup Workflow +========================= + +Systematic process for enabling and debugging device hardware components. + +Display +------- +1. Check framebuffer:: + + ls /dev/fb* + cat /sys/class/graphics/fb0/modes + +2. Verify services:: + + systemctl status lightdm + journalctl -u lightdm + +3. Test configuration:: + + # /etc/ubuntu-touch-session.d/android.conf + GRID_UNIT_PX=18 + QTWEBKIT_DPR=2.0 + +Audio +----- +1. Check detection:: + + ls /dev/snd/* + aplay -l + pactl list sinks + +2. Test paths:: + + # UCM configuration + ls /usr/share/alsa/ucm2/ + amixer + alsactl init + +3. Verify service:: + + systemctl status pulseaudio + pactl info + +Sensors +------- +1. Check inputs:: + + ls /dev/input/event* + getevent -l + evtest + +2. Test sensor service:: + + systemctl status sensorfwd + sensorfw-tests + +3. Verify permissions:: + + ls -l /dev/input/event* + groups phablet + +Network +------- +1. WiFi bring-up:: + + iw list + nmcli radio wifi + rfkill list + +2. Cellular setup:: + + mmcli -L + ofono-phonesim + dmesg | grep tty + +3. Bluetooth config:: + + hciconfig -a + bluetoothctl show + btmon + +Power Management +---------------- +1. Battery info:: + + upower -i /org/freedesktop/UPower/devices/battery_0 + cat /sys/class/power_supply/*/capacity + +2. Suspend/resume:: + + systemctl suspend + journalctl -b -u systemd-sleep + +3. Thermal control:: + + cat /sys/class/thermal/thermal_zone*/temp + cat /sys/class/thermal/cooling_device*/cur_state \ No newline at end of file diff --git a/porting/debugging/workflows/index.rst b/porting/debugging/workflows/index.rst new file mode 100644 index 000000000..6e89da7b1 --- /dev/null +++ b/porting/debugging/workflows/index.rst @@ -0,0 +1,10 @@ +Debugging Workflows +=================== + +.. toctree:: + :maxdepth: 2 + + first-boot + hardware-bringup + performance + stability \ No newline at end of file diff --git a/porting/debugging/workflows/performance.rst b/porting/debugging/workflows/performance.rst new file mode 100644 index 000000000..44130411d --- /dev/null +++ b/porting/debugging/workflows/performance.rst @@ -0,0 +1,64 @@ +Performance Optimization +======================== + +Tools and methods for identifying and resolving performance issues. + +System Performance +------------------ +1. CPU monitoring:: + + top -b -n 1 + mpstat -P ALL 1 + cat /proc/cpuinfo + +2. Memory usage:: + + free -h + vmstat 1 + cat /proc/meminfo + +3. I/O activity:: + + iostat -x 1 + iotop -b -n 1 + cat /proc/diskstats + +Android Container +----------------- +1. Process stats:: + + ps aux | grep android + top -b -n 1 | grep android + lxc-info -n android + +2. Resource usage:: + + cat /sys/fs/cgroup/memory/lxc/android/memory.usage_in_bytes + cat /sys/fs/cgroup/cpu/lxc/android/cpu.stat + +Graphics +-------- +1. Compositor:: + + LOMIRI_LOG_LEVEL=debug lomiri 2>&1 | tee lomiri.log + mir-performance-test + +2. Hardware acceleration:: + + glxinfo + vainfo + cat /proc/gpufreq/* + +Storage +------- +1. I/O performance:: + + dd if=/dev/zero of=test bs=64k count=16k conv=fdatasync + hdparm -tT /dev/mmcblk0 + fio --filename=test --direct=1 --rw=randrw + +2. Filesystem check:: + + df -h + du -sh /* + tune2fs -l /dev/mmcblk0p1 \ No newline at end of file diff --git a/porting/debugging/workflows/stability.rst b/porting/debugging/workflows/stability.rst new file mode 100644 index 000000000..487b4f54c --- /dev/null +++ b/porting/debugging/workflows/stability.rst @@ -0,0 +1,64 @@ +System Stability +================ + +Workflow for diagnosing and fixing system crashes and stability issues. + +Crash Analysis +-------------- +1. System logs:: + + journalctl -p err -b + coredumpctl list + cat /proc/sys/kernel/core_pattern + +2. App crashes:: + + ~/.cache/upstart/application-*.log + grep -r "Segmentation fault" ~/.cache/upstart/ + sudo ausearch -i -sv no -m avc + +3. Service failures:: + + systemctl --failed + journalctl -u failed-unit + coredumpctl info + +Memory Issues +------------- +1. OOM events:: + + dmesg | grep -i "out of memory" + cat /proc/sys/vm/oom_kill_allocating_task + journalctl -k | grep -i oom + +2. Memory leaks:: + + valgrind --leak-check=full + ps_mem.py + smem -t -k -p + +3. Memory pressure:: + + cat /proc/pressure/memory + vmstat -s + cat /proc/zoneinfo + +Race Conditions +--------------- +1. Service ordering:: + + systemctl list-dependencies + journalctl --since "5 min ago" + systemd-analyze critical-chain + +2. Resource conflicts:: + + fuser -v /path/to/resource + lsof | grep deleted + strace -f -p PID + +3. Lock issues:: + + lslocks + flock -n /tmp/lockfile + inotifywait -m /path \ No newline at end of file diff --git a/porting/finalize/UBports_installer.rst b/porting/finalize/UBports-installer.rst similarity index 50% rename from porting/finalize/UBports_installer.rst rename to porting/finalize/UBports-installer.rst index 74e9483c7..3738b27ad 100644 --- a/porting/finalize/UBports_installer.rst +++ b/porting/finalize/UBports-installer.rst @@ -1,8 +1,6 @@ -.. _Installer: - -Configuring the UBports installer -================================= +Configuring the UBport installer +================================ For the time being, Halium-7.1 porters should refer to the UBports porting notes on `the UBPorts installer and System image `_. -For Halium-9.0, exact steps are not available at this time. Please :ref:`get in touch with the community for help. ` \ No newline at end of file +For Halium-9.0, exact steps are not available at this time. \ No newline at end of file diff --git a/porting/finalize/UBports-recovery.rst b/porting/finalize/UBports-recovery.rst new file mode 100644 index 000000000..265523a2f --- /dev/null +++ b/porting/finalize/UBports-recovery.rst @@ -0,0 +1,6 @@ +Building UBports recovery +========================= + +Porters working on legacy devices should refer to the UBports porting notes on `the UBPorts installer and System image `_. + +For Halium-9.0, exact steps are not available at this time. \ No newline at end of file diff --git a/porting/finalize/UBports_recovery.rst b/porting/finalize/UBports_recovery.rst deleted file mode 100644 index c9febc82c..000000000 --- a/porting/finalize/UBports_recovery.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _Recovery: - -Building UBports recovery -========================= - -For the time being, Halium 7.1 porters should refer to the UBports porting notes on `the UBPorts installer and System image `_. - -For Halium-9.0, exact steps are not available at this time. Please :ref:`get in touch with the community for help. ` \ No newline at end of file diff --git a/porting/finalize/index.rst b/porting/finalize/index.rst index 235d34c5f..eaf299cbf 100644 --- a/porting/finalize/index.rst +++ b/porting/finalize/index.rst @@ -13,5 +13,5 @@ With the necessary components prepared, these should first be installed in their :maxdepth: 1 :name: finalizing - UBports_recovery - UBports_installer \ No newline at end of file + UBports-recovery + UBports-installer \ No newline at end of file diff --git a/porting/fundamentals/build-systems/index.rst b/porting/fundamentals/build-systems/index.rst new file mode 100644 index 000000000..9001bc785 --- /dev/null +++ b/porting/fundamentals/build-systems/index.rst @@ -0,0 +1,153 @@ +.. _build-systems: + +Build Systems +============= + +Understanding the build system is crucial for creating a successful Ubuntu Touch port. This section explains the available build methods and helps you choose the right approach for your device. + +Quick Reference +--------------- +Essential concepts: + +* Build environment setup +* Device configuration +* System image creation +* Hardware integration +* Testing and verification + +Core Components +--------------- + +The Ubuntu Touch build system integrates several key elements: + +1. **Device Configuration** + + * Hardware definitions + * System properties + * Build parameters + * Feature flags + +2. **Source Management** + + * Kernel sources + * Android components + * System services + * Hardware support + +3. **Image Creation** + + * Boot images + * System images + * Recovery support + * Partition layout + +Build Methods +------------- + +Available build approaches: + +1. **Modern Method** + + Best for current devices: + + * Android 9.0 or newer + * Project Treble support + * Available kernel source + * Standard hardware support + + Benefits: + * Simpler process + * Better maintainability + * Faster iteration + * Standard interfaces + +2. **Legacy Method** + + Required for older devices: + + * Pre-Android 9.0 + * Custom hardware support + * Specific vendor needs + * Legacy compatibility + + Considerations: + * More complex setup + * Deeper customization + * Full system build + * Vendor-specific code + +Choosing Your Method +-------------------- + +Consider these factors: + +1. **Device Characteristics** + + * Android version + * Hardware support + * Vendor cooperation + * Available sources + +2. **Development Resources** + + * Build environment + * Technical expertise + * Time investment + * Testing capabilities + +3. **Long-term Support** + + * Update strategy + * Maintenance needs + * Community support + * Documentation + +Implementation Path +------------------- + +Steps for successful builds: + +1. **Environment Setup** + + * Tool installation + * Dependency management + * Source preparation + * Build configuration + +2. **Device Preparation** + + * Configuration files + * Hardware definitions + * System properties + * Build parameters + +3. **Build Process** + + * Image creation + * System integration + * Testing procedures + * Deployment methods + +Detailed Guides +--------------- + +.. toctree:: + :maxdepth: 2 + + modern + legacy + +Next Steps +---------- + +Choose your build path: + +* :doc:`modern` - Current devices +* :doc:`legacy` - Older devices +* :ref:`debugging` - Build troubleshooting + +See Also +-------- +* :ref:`hardware-abstraction` - Hardware support +* :ref:`android-integration` - System integration +* :ref:`device-config` - Device configuration \ No newline at end of file diff --git a/porting/fundamentals/build-systems/legacy.rst b/porting/fundamentals/build-systems/legacy.rst new file mode 100644 index 000000000..c4caf2ea7 --- /dev/null +++ b/porting/fundamentals/build-systems/legacy.rst @@ -0,0 +1,137 @@ +.. _legacy-build: + +Legacy Build Methods +==================== + +The legacy build method is required for devices running pre-Android 9.0 systems or needing complete system customization. While more complex than modern methods, it provides maximum control for devices that need it. + +Quick Reference +--------------- +Essential requirements: + +* Pre-Android 9.0 device +* Complete device tree available +* Working LineageOS/AOSP base +* Vendor blobs +* Hardware sources + +Implementation Steps +-------------------- + +1. **Environment Setup**:: + + sudo apt install git gcc adb fastboot repo python-is-python2 + # This installs: + # git/repo - Source code management tools + # gcc - Code compiler + # adb/fastboot - Device communication + # python - Required for build scripts + +2. **Source Preparation**:: + + # Initialize repository + mkdir halium && cd halium + repo init -u https://github.com/Halium/android -b halium-7.1 + repo sync -c -j$(nproc) + + # This: + # - Creates build directory + # - Sets up Android build system + # - Downloads required Android sources + # - Prepares build environment + +3. **Configuration**:: + + # Initialize device + breakfast [device] + # This: + # - Sets up device-specific configurations + # - Checks build dependencies + # - Prepares vendor files + # - Configures build targets + + # Configure device settings in: + # device/[vendor]/[device]/BoardConfig.mk # Hardware settings + # device/[vendor]/[device]/device.mk # Features and packages + # device/[vendor]/[device]/system.prop # System properties + +4. **Build Process**:: + + # Build boot image + mka halium-boot + # This: + # - Compiles device kernel + # - Creates initial ramdisk + # - Builds Android boot image + # - Packages for device flashing + + # Build system image + mka systemimage + # This: + # - Builds Android system components + # - Compiles hardware support layer + # - Creates system partition image + # - Prepares for device installation + +Common Issues +------------- + +1. **Source Sync Failures** + + * Check internet connection + * Verify repo installation + * Ensure sufficient storage + * Try with different branch + +2. **Build Environment Problems** + + * Install missing packages + * Check Python version + * Verify $PATH setup + * Update build tools + +3. **Device Tree Issues** + + * Verify device tree exists + * Check vendor blobs + * Validate configurations + * Review dependencies + +Best Practices +-------------- + +1. **Environment Management** + + * Use ccache for faster rebuilds + * Keep build tree clean + * Document configurations + * Backup working builds + +2. **Testing Process** + + * Build incrementally + * Test each component + * Document issues + * Save known-good configs + +3. **Update Strategy** + + * Track upstream changes + * Manage patches carefully + * Document modifications + * Test thoroughly + +Next Steps +---------- + +After successful build: + +* :ref:`initial-boot` - First boot process +* :ref:`debugging` - Problem solving +* :ref:`hardware-enablement` - Feature support + +See Also +-------- +* :doc:`modern` - Modern build methods +* :ref:`migration-guide` - Upgrading builds +* :ref:`debugging` - Troubleshooting guide \ No newline at end of file diff --git a/porting/fundamentals/build-systems/modern.rst b/porting/fundamentals/build-systems/modern.rst new file mode 100644 index 000000000..2f1cf1112 --- /dev/null +++ b/porting/fundamentals/build-systems/modern.rst @@ -0,0 +1,276 @@ +.. _modern-build: + +Modern Build Methods +==================== + +The modern build method is the recommended approach for devices running Android 9.0 or newer. It simplifies the porting process by leveraging Project Treble's standardized hardware interfaces. + +Quick Reference +--------------- +Essential requirements: + +* Android 9.0+ device +* Available kernel source +* Project Treble support +* Working vendor blobs + +Understanding the Build Process +------------------------------- +Think of building Ubuntu Touch like assembling a complex model kit. You need: + +- The right parts (source code and tools) +- Clear instructions (configuration files) +- Proper assembly order (build steps) +- Quality checks (testing) + +Understanding Modern Builds +--------------------------- + +Modern builds take advantage of Android's hardware standardization: + +1. **Project Treble** + + How it helps: + + * Standardized HAL interfaces + * Separated vendor code + * Consistent hardware access + * Simplified updates + + Required components: + + * Vendor partition + * HIDL interfaces + * HAL implementations + * System services + +2. **GSI Compatibility** + + Benefits: + + * Standard system images + * Hardware abstraction + * Easier testing + * Faster development + +Build Components +---------------- + +Key elements of the modern build: + +1. **Kernel Build** + + Essential parts:: + + deviceinfo_kernel_source="https://github.com/..." + deviceinfo_kernel_defconfig="vendor_defconfig" + deviceinfo_kernel_image_name="Image.gz-dtb" + + Purpose: + + * Hardware support + * System initialization + * Device control + * Feature enablement + +2. **System Image** + + Components: + + * Ubuntu Touch rootfs + * Android container + * Hardware support + * System configuration + +3. **Boot Image** + + Required files: + + * Kernel + * Initial ramdisk + * Device tree + * Boot configuration + +Implementation Steps +-------------------- + +1. **Environment Setup**:: + + sudo apt install git gcc adb fastboot + # This installs: + # git - Gets source code (like getting your model kit parts) + # gcc - Compiles code (like the glue for your model) + # adb/fastboot - Talks to device (like the paint brushes and tools) + +2. **Source Preparation** + +Two distinct build methods are available. Choose ONE of these approaches based on your device: + +A) Standalone Kernel Method (Recommended for modern devices):: + + # Clone build tools + git clone https://github.com/ubports/build-tools + + # This: + # - Downloads necessary build scripts (instruction manual) + # - Sets up basic directory structure (organizes workspace) + # - Prepares build environment (sets up workbench) + +B) Full System Build Method (For legacy or special cases):: + + # Initialize repository + repo init -u https://github.com/Halium/android -b halium-10.1 + repo sync -c -j$(nproc) + + # This: + # - Sets up complete Android build environment + # - Downloads all required Android sources + # - Prepares for full system compilation + +WARNING: These methods are mutually exclusive - do not mix commands between them. +Choose the appropriate method based on your device's Android version and hardware support: + +- Use Standalone Kernel Method for Android 9+ devices +- Use Full System Build Method (legacy build method) for pre-Android 9 devices or those requiring deep customization + +3. **Configuration** + +A) For Standalone Kernel Method:: + + # Create deviceinfo configuration + cp deviceinfo.template deviceinfo + + # Edit essential settings like: + # - Device name and manufacturer + # - Kernel source and branch + # - Build parameters + # - Hardware configs + nano deviceinfo + +B) For Full System Build Method:: + + # Initialize device configuration + breakfast [device] + + # Configure device-specific settings in: + # device/[vendor]/[device]/BoardConfig.mk - Hardware configs + # device/[vendor]/[device]/device.mk - Features and packages + # device/[vendor]/[device]/system.prop - System properties + + # Verify vendor files are present in: + # vendor/[vendor]/[device]/proprietary-files.txt + +4. **Build Process** + +A) For Standalone Kernel Method:: + + # Build kernel only + ./build.sh -k + # This command: + # 1. Downloads your device's kernel source + # 2. Applies necessary patches + # 3. Configures for Ubuntu Touch + # 4. Compiles the kernel + # 5. Creates kernel modules + + # Full build + ./build.sh -b + # This command: + # 1. Builds the complete system image + # 2. Creates necessary Android components + # 3. Packages Ubuntu Touch rootfs + # 4. Generates boot and recovery images + # 5. Prepares flashable system files + +B) For Full System Build Method:: + + # Build boot image + mka halium-boot + # This command: + # 1. Compiles the kernel and modules + # 2. Creates initial ramdisk + # 3. Packages boot image with device tree + # 4. Prepares bootloader-compatible format + + # Build system image + mka systemimage + # This command: + # 1. Compiles Android HAL components + # 2. Integrates vendor binaries + # 3. Creates system partition image + # 4. Packages for device installation + +Debugging Builds +---------------- + +Common issues and solutions: + +1. **Compilation Errors** + + Check: + + * Build dependencies + * Compiler version + * Source compatibility + * Configuration flags + +2. **Boot Problems** + + Verify: + + * Kernel configuration + * Device tree + * Boot parameters + * Initial ramdisk + +3. **System Integration** + + Review: + + * HAL compatibility + * Vendor blobs + * Service configuration + * Hardware support + +Best Practices +-------------- + +1. **Source Management** + + * Use version control + * Document changes + * Keep clean trees + * Backup configurations + +2. **Testing Process** + + * Build incrementally + * Test each component + * Document issues + * Maintain logs + +3. **Update Strategy** + + * Track upstream changes + * Manage dependencies + * Document procedures + * Plan maintenance + +Next Steps +---------- + +Further details on modern porting methods: + +* :ref:`modern-methods` - Modern porting methods + +After successful build: + +* :ref:`initial-boot` - First boot process +* :ref:`debugging` - Problem solving +* :ref:`hardware-enablement` - Feature support + +See Also +-------- +* :ref:`build-concepts` - Core build concepts +* :ref:`gki-devices` - GSI compatibility +* :doc:`legacy` - Legacy build support \ No newline at end of file diff --git a/porting/fundamentals/concepts/containers.rst b/porting/fundamentals/concepts/containers.rst new file mode 100644 index 000000000..9b869ee97 --- /dev/null +++ b/porting/fundamentals/concepts/containers.rst @@ -0,0 +1,217 @@ +Container System +================ + +Ubuntu Touch uses containers to isolate Android hardware support from the main GNU/Linux system. This design enables standard Linux software to run while maintaining full hardware compatibility. + +Quick Reference +--------------- +Key container concepts: + +* LXC container hosts Android +* Hardware access through libhybris +* Service isolation +* Resource management + +Understanding Containers +------------------------ + +The Container Model +^^^^^^^^^^^^^^^^^^^ +Ubuntu Touch's container system: + +1. **Main System** + + * GNU/Linux userspace + * Ubuntu Touch interface + * User applications + * System services + +2. **Android Container** + + * Minimal Android system + * Hardware services + * Vendor binaries + * Device drivers + +Think of the container system like a house with two rooms: + +- One room (main system) where you live and work +- Another room (Android container) containing all the building's infrastructure + +Container Implementation +------------------------ + +1. **LXC Configuration** + + Basic structure:: + + /var/lib/lxc/android/ + ├── config # Container configuration + ├── rootfs/ # Android root filesystem + └── system.img # System image + + Key settings:: + + # Container config + lxc.rootfs.path = /var/lib/lxc/android/rootfs + lxc.mount.auto = cgroup:mixed proc:mixed sys:mixed + lxc.arch = arm64 + +2. **Service Integration** + + Essential services: + + * binder - IPC system + * hwcomposer - Display + * media - Audio/Video + * sensors - Device input + +3. **Resource Management** + + Container controls: + + * Memory limits + * CPU allocation + * Storage access + * Device permissions + +Hardware Access +--------------- + +1. **Direct Hardware** + + Through container: + + * Device drivers + * Kernel modules + * Hardware interfaces + * Low-level access + +2. **Abstracted Hardware** + + Via libhybris: + + * Graphics + * Audio + * Sensors + * Networking + +3. **Shared Resources** + + Common access: + + * Storage + * Network interfaces + * Input devices + * System memory + +Security Considerations +----------------------- + +1. **Isolation** + + Container boundaries: + + * Process separation + * Resource limits + * Permission control + * Access restrictions + +2. **AppArmor Profiles** + + Security policies:: + + # Container profile + profile lxc-container-default flags=(attach_disconnected,mediate_deleted) { + # Allow container access + capability, + network, + + # Restrict system access + deny /proc/** wkx, + deny /sys/** wkx, + } + +3. **Resource Controls** + + Management tools: + + * cgroups configuration + * Resource limits + * Process controls + * Network isolation + +Common Issues +------------- + +1. **Container Start Failures** + + Check: + + * LXC configuration + * Mount points + * Service dependencies + * Log files + +2. **Hardware Access** + + Verify: + + * Device permissions + * Driver loading + * Service status + * System logs + +3. **Resource Problems** + + Monitor: + + * Memory usage + * CPU allocation + * Storage space + * Process limits + +Best Practices +-------------- + +1. **Configuration** + + * Document changes + * Test modifications + * Back up working configs + * Monitor performance + +2. **Debugging** + + Essential commands:: + + # Check container status + lxc-info -n android + + # View logs + journalctl -u lxc@android + + # Monitor processes + ps aux | grep android + +3. **Maintenance** + + Regular tasks: + + * Update configurations + * Check logs + * Monitor resources + * Test functionality + +Next Steps +---------- + +* :doc:`system-images` - Image structure +* :doc:`hardware-support` - Hardware integration +* :ref:`debugging` - Problem solving + +See Also +-------- +* :ref:`android-integration` - Android system details +* :ref:`hardware-abstraction` - HAL implementation +* :ref:`implementation-guide` - Practical steps \ No newline at end of file diff --git a/porting/fundamentals/concepts/hardware-support.rst b/porting/fundamentals/concepts/hardware-support.rst new file mode 100644 index 000000000..4c1e936ba --- /dev/null +++ b/porting/fundamentals/concepts/hardware-support.rst @@ -0,0 +1,234 @@ +Hardware Support +================ + +Ubuntu Touch achieves hardware support by combining Android's Hardware Abstraction Layer (HAL) with libhybris to bridge Android drivers and GNU/Linux applications. + +Quick Reference +--------------- +Key components: + +* Android HAL interfaces +* libhybris translation layer +* Device drivers and blobs +* Hardware initialization + +Hardware Architecture +--------------------- + +Component Layers +^^^^^^^^^^^^^^^^ + +1. **Physical Hardware** + + * Device components + * Hardware interfaces + * Platform features + * Vendor silicon + +2. **Driver Layer** + + * Kernel drivers + * Binary blobs + * Firmware files + * Hardware control + +3. **Abstraction Layer** + + * Android HAL + * libhybris bridge + * Service interfaces + * Hardware protocols + +4. **Application Layer** + + * User applications + * System services + * GUI elements + * User interface + +Hardware Components +------------------- + +1. **Display System** + + Graphics stack:: + + Application + ↓ + Mir/Wayland + ↓ + libhybris + ↓ + Android HAL + ↓ + Hardware + + Key interfaces: + + * HWComposer + * Gralloc + * OpenGL ES + * Vulkan + +2. **Audio System** + + Sound path:: + + PulseAudio + ↓ + Audio HAL + ↓ + ALSA/Kernel + ↓ + Hardware + + Components: + + * Audio HAL + * Audio Policy + * Audio Flinger + * Sound drivers + +3. **Input/Sensors** + + Input chain:: + + Ubuntu Touch + ↓ + libhybris + ↓ + Android HAL + ↓ + Hardware + + Supported types: + + * Touchscreen + * Buttons + * Sensors + * GPS + +Hardware Integration +-------------------- + +1. **Driver Setup** + + Essential configurations:: + + # Kernel config + CONFIG_ANDROID_BINDER_IPC=y + CONFIG_ASHMEM=y + CONFIG_INPUT_UINPUT=y + +2. **HAL Implementation** + + Interface requirements:: + + # Hardware interfaces + android.hardware.graphics.composer@2.1 + android.hardware.audio@4.0 + android.hardware.sensors@1.0 + +3. **Service Configuration** + + System services:: + + # Service definitions + /etc/init/ + ├── android-services.conf + ├── media-hub.conf + └── sensors.conf + +Common Issues +------------- + +1. **Driver Problems** + + Check: + + * Kernel config + * Module loading + * Hardware detection + * Driver errors + +2. **HAL Compatibility** + + Verify: + + * Interface versions + * Binary compatibility + * Service status + * Error logs + +3. **Performance Issues** + + Monitor: + + * Hardware usage + * Driver efficiency + * Resource allocation + * System load + +Hardware Debugging +------------------ + +1. **Basic Tools**:: + + # Check hardware + lsusb + lsmod + dmesg + hwinfo + +2. **Advanced Debugging**:: + + # Monitor hardware + strace + ltrace + gdb + valgrind + +3. **Log Analysis**:: + + # System logs + journalctl + logcat + dmesg + syslog + +Best Practices +-------------- + +1. **Hardware Support** + + * Document features + * Test thoroughly + * Monitor performance + * Update drivers + +2. **Compatibility** + + * Check versions + * Test interfaces + * Verify functionality + * Monitor updates + +3. **Maintenance** + + * Regular testing + * Performance checks + * Update tracking + * Documentation + +Next Steps +---------- + +* :ref:`implementation-guide` - Implementation +* :ref:`debugging` - Problem solving +* :ref:`hardware-enablement` - Feature support + +See Also +-------- +* :ref:`hardware-abstraction` - HAL details +* :ref:`android-integration` - Android system +* :doc:`system-images` - Image structure \ No newline at end of file diff --git a/porting/fundamentals/concepts/index.rst b/porting/fundamentals/concepts/index.rst new file mode 100644 index 000000000..2d1feca34 --- /dev/null +++ b/porting/fundamentals/concepts/index.rst @@ -0,0 +1,64 @@ +.. _build-concepts: + +Core Concepts +============= + +This section covers the fundamental concepts that form the foundation of Ubuntu Touch porting. Understanding these concepts is crucial for successful port development. + +Quick Reference +--------------- +Essential concepts: + +* Container system architecture +* System image structure +* Hardware support model +* Service integration + +Core Areas +---------- + +1. **Container System** + + * LXC container usage + * Process isolation + * Resource management + * Security boundaries + +2. **System Images** + + * Image structure + * Partition layout + * Update system + * Recovery process + +3. **Hardware Support** + + * Driver integration + * Hardware abstraction + * Feature support + * Vendor integration + +Detailed Guides +--------------- + +.. toctree:: + :maxdepth: 2 + + containers + system-images + hardware-support + +Next Steps +---------- + +After understanding these concepts: + +* :ref:`build-systems` - Build methods +* :ref:`implementation-guide` - Implementation +* :ref:`debugging` - Problem solving + +See Also +-------- +* :ref:`hardware-abstraction` - HAL details +* :ref:`android-integration` - Android system +* :ref:`build-systems` - Building images \ No newline at end of file diff --git a/porting/fundamentals/concepts/system-images.rst b/porting/fundamentals/concepts/system-images.rst new file mode 100644 index 000000000..b5556fdfe --- /dev/null +++ b/porting/fundamentals/concepts/system-images.rst @@ -0,0 +1,217 @@ +System Images +============= + +Ubuntu Touch uses a unique system image structure that combines GNU/Linux and Android components. Understanding this structure is essential for successful porting and debugging. + +Quick Reference +--------------- +Key components: + +* Boot images (boot.img, recovery.img) +* System image (system.img) +* Ubuntu rootfs +* Android container image + +Image Structure +--------------- + +Basic Layout +^^^^^^^^^^^^ +System image components: + +1. **Boot Images** + + Essential files:: + + boot.img # Kernel and init + recovery.img # Recovery system + vendor_boot.img # Vendor init (A12+) + + Contains: + + * Linux kernel + * Device tree + * Initial ramdisk + * Boot configuration + +2. **System Image** + + Main components:: + + system.img/ + ├── bin/ # System binaries + ├── etc/ # Configuration + ├── lib/ # Libraries + ├── usr/ # User space + └── var/ # Variable data + +3. **Ubuntu Root** + + Core system:: + + / + ├── boot/ # Boot files + ├── etc/ # System config + ├── usr/ # Programs + ├── var/ # Data + └── opt/ # Add-ons + +4. **Android Container** + + Hardware support:: + + android/ + ├── system/ # Android system + ├── vendor/ # Vendor files + └── data/ # Runtime data + +Partition Layout +---------------- + +Standard Configuration +^^^^^^^^^^^^^^^^^^^^^^ +Common partition scheme:: + + /dev/ + ├── mmcblk0p1 # Boot + ├── mmcblk0p2 # Recovery + ├── mmcblk0p3 # System + ├── mmcblk0p4 # Vendor + └── mmcblk0p5 # Data + +Dynamic Partitions +^^^^^^^^^^^^^^^^^^ +Modern devices:: + + /dev/mapper/ + ├── system # System partition + ├── vendor # Vendor files + └── userdata # User data + +Image Creation +-------------- + +1. **Boot Image** + + Build process:: + + # Create boot image + mkbootimg \ + --kernel $KERNEL \ + --ramdisk $RAMDISK \ + --cmdline "$CMDLINE" \ + --base $BASE \ + -o boot.img + +2. **System Image** + + Assembly steps:: + + # Create empty image + truncate -s 2G system.img + + # Format image + mkfs.ext4 system.img + + # Mount and populate + mount system.img /mnt + cp -a rootfs/* /mnt/ + +3. **Recovery Image** + + Building recovery:: + + # Create recovery + mkbootimg \ + --kernel $KERNEL \ + --ramdisk $RECOVERY \ + --cmdline "$CMDLINE" \ + -o recovery.img + +Update System +------------- + +Image Updates +^^^^^^^^^^^^^ +Update process: + +1. **Delta Updates** + + * Download changes + * Verify signatures + * Apply updates + * Update bootloader + +2. **Full Updates** + + * Download image + * Verify checksums + * Flash system + * Preserve data + +Common Issues +------------- + +1. **Space Problems** + + Check: + + * Partition sizes + * Available space + * Image sizes + * File systems + +2. **Boot Issues** + + Verify: + + * Boot parameters + * Initial ramdisk + * Kernel config + * Device tree + +3. **Update Failures** + + Review: + + * Signatures + * Space usage + * File permissions + * System state + +Best Practices +-------------- + +1. **Image Management** + + * Regular backups + * Version control + * Documentation + * Testing process + +2. **Partition Layout** + + * Proper sizing + * Alignment + * Backup space + * Update room + +3. **Recovery Options** + + * Working recovery + * Backup methods + * Restore process + * Emergency tools + +Next Steps +---------- + +* :doc:`hardware-support` - Hardware integration +* :ref:`debugging` - Problem solving +* :ref:`implementation-guide` - Implementation + +See Also +-------- +* :ref:`build-systems` - Building images +* :ref:`android-integration` - Android system +* :doc:`containers` - Container system \ No newline at end of file diff --git a/porting/fundamentals/index.rst b/porting/fundamentals/index.rst new file mode 100644 index 000000000..5db651b6e --- /dev/null +++ b/porting/fundamentals/index.rst @@ -0,0 +1,83 @@ +# fundamentals/index.rst + +Fundamentals of Ubuntu Touch Porting +==================================== + +This section provides a comprehensive overview of the core concepts and technical foundations needed to successfully port Ubuntu Touch to new devices. + +Why This Matters +---------------- +Understanding these fundamentals is like learning the basic rules of a new language before trying to speak it. Each concept plays a vital role in your porting journey: + +* **System Architecture** is like understanding how a car's engine, transmission, and wheels work together. Just as you can't fix a car without knowing how the parts interact, you can't port Ubuntu Touch without understanding how its components work together. + +* **Build Systems** are like having the right tools and knowing how to use them. Just as you wouldn't try to build furniture without understanding the instructions and tools, you shouldn't start porting without understanding how to build the system. + +* **Core Concepts** are like knowing the principles of driving before getting behind the wheel. These give you the foundation to make good decisions during the porting process. + +Key Terms +--------- +Here are some essential terms you'll encounter, explained simply: + +* **HAL (Hardware Abstraction Layer)**: Think of this as a translator between your device's hardware and the operating system. Just like a human translator converts between languages, HAL converts between hardware commands and software instructions. + +* **Container**: Imagine this as a box that keeps certain programs separate from others, like keeping work files in a different folder from personal files. In Ubuntu Touch, we use containers to keep Android hardware support separate from the main system. + +* **Bootloader**: This is like your device's starter motor. It's the first thing that runs when you turn on your device, and it helps load the rest of the operating system. + +* **Device Tree**: Think of this as a map of your device's hardware. Just like a city map shows where everything is located, a device tree tells the system where to find and how to talk to different hardware components. + +Core Areas +---------- + +1. **System Architecture** + + * How Ubuntu Touch works with Android hardware + * Integration between system components + * Hardware abstraction and support + * Implementation approaches + +2. **Build Systems** + + * Different build methods + * Tool requirements + * Build process workflows + * System integration + +3. **Core Concepts** + + * Container system + * System images + * Hardware support + * Security model + +Prerequisites +------------- +* Basic understanding of Linux systems +* Familiarity with Android concepts +* Command line experience +* Basic programming knowledge + +Each section builds upon these fundamentals to provide a complete understanding of Ubuntu Touch porting. + +Before proceeding with porting, ensure you understand: + +- How Ubuntu Touch integrates with Android hardware +- Which build method is appropriate for your device +- Core concepts of system integration + +.. toctree:: + :maxdepth: 2 + :name: fundamentals-toc + + system-architecture/index + build-systems/index + concepts/index + +Next Steps +---------- +After understanding these fundamentals, proceed to: + +* :doc:`../preparation/index` - Environment and device setup +* :doc:`../modern-porting/index` - Porting process +* :doc:`../resources/index` - Additional reference materials \ No newline at end of file diff --git a/porting/fundamentals/system-architecture/android-integration.rst b/porting/fundamentals/system-architecture/android-integration.rst new file mode 100644 index 000000000..c349ff95a --- /dev/null +++ b/porting/fundamentals/system-architecture/android-integration.rst @@ -0,0 +1,106 @@ +.. _android-integration: + +Android Integration +=================== + +Quick Reference +--------------- +Essential concepts: + +* Android container runs minimal system +* Hardware access through HAL +* libhybris bridges Android/Linux +* Kernel provides Android features + +Understanding Android Integration +--------------------------------- + +Android Components +^^^^^^^^^^^^^^^^^^ +The minimal Android system provides: + +1. **Hardware Support** + + * Hardware Abstraction Layer (HAL) + * Vendor-specific drivers + * Binary blobs + * Power management + +2. **Core Services** + + * Camera service + * Audio HAL + * Sensor hub + * RIL daemon + +3. **System Integration** + + * Binder IPC + * Shared memory + * Property system + * Hardware permissions + +Container Architecture +---------------------- + +LXC Container +^^^^^^^^^^^^^ +The Android system runs in a container that: + +* Isolates Android from Ubuntu Touch +* Manages hardware access +* Controls resource usage +* Handles service lifecycle + +Example container configuration: + +.. code-block:: text + + lxc.rootfs.path = /var/lib/lxc/android/rootfs + lxc.init.cmd = /init + lxc.mount.auto = cgroup:mixed proc:mixed sys:mixed + lxc.apparmor.profile = unconfined + lxc.aa_allow_incomplete = 1 + +Hardware Access +^^^^^^^^^^^^^^^ +Hardware access flows through: + +1. Android HAL interfaces +2. libhybris translation layer +3. Linux system calls +4. Device drivers + +Implementation Requirements +--------------------------- + +Kernel Features +^^^^^^^^^^^^^^^ +Required kernel configurations: + +* Android binder +* Ashmem +* Cgroup support +* SELinux/AppArmor + +.. code-block:: text + + CONFIG_ANDROID=y + CONFIG_ANDROID_BINDER_IPC=y + CONFIG_ASHMEM=y + CONFIG_CGROUPS=y + +Service Management +^^^^^^^^^^^^^^^^^^ +Critical Android services: + +* media.audio_flinger +* media.camera +* sensorservice +* rild + +See Also +-------- +* :ref:`hardware-abstraction` - HAL details +* :ref:`debugging-container` - Container debugging +* :doc:`../../vendor-specific/index` - Vendor specifics \ No newline at end of file diff --git a/porting/fundamentals/system-architecture/hardware-abstraction/implementation.rst b/porting/fundamentals/system-architecture/hardware-abstraction/implementation.rst new file mode 100644 index 000000000..9cc76b97c --- /dev/null +++ b/porting/fundamentals/system-architecture/hardware-abstraction/implementation.rst @@ -0,0 +1,107 @@ +# fundamentals/system-architecture/hardware-abstraction/implementation.rst + +.. _implementation-guide: + +HAL Implementation +================== + +Quick Reference +--------------- +Essential steps: + +* Identify required interfaces +* Configure HAL versions +* Set up vendor implementation +* Test hardware access + +Implementation Process +---------------------- + +1. **Interface Setup** + + Determine required interfaces:: + + /vendor/lib64/hw/ + ├── audio.primary.default.so + ├── camera.default.so + ├── gralloc.default.so + └── sensors.default.so + +2. **Version Configuration** + + Configure HAL versions:: + + # Example manifest.xml + + android.hardware.audio + hwbinder + 4.0 + + IDevicesFactory + default + + + +3. **Vendor Integration** + + Essential components: + + * Vendor libraries + * Binary blobs + * Configuration files + * Hardware mappings + +Integration Requirements +------------------------ + +1. **Hardware Access** + + * Device nodes + * Permissions + * SELinux context + * udev rules + +2. **Service Management** + + * Init scripts + * Service dependencies + * Resource control + * Error handling + +3. **Testing/Verification** + + * Interface testing + * Hardware access + * Performance metrics + * Stability checks + +Best Practices +-------------- + +1. **Version Control** + + * Match HAL to Android version + * Track binary compatibility + * Document dependencies + * Maintain patches + +2. **Error Handling** + + * Graceful degradation + * Error reporting + * Recovery procedures + * Logging + +3. **Security** + + * Access control + * SELinux policies + * Secure boot + * Key management + +See Also +-------- +* :ref:`hardware-enablement` - Hardware debugging guide +* :ref:`vendor-specific` - Vendor implementations +* :doc:`../implementation-guide` - General implementation + diff --git a/porting/fundamentals/system-architecture/hardware-abstraction/index.rst b/porting/fundamentals/system-architecture/hardware-abstraction/index.rst new file mode 100644 index 000000000..6ee3840e3 --- /dev/null +++ b/porting/fundamentals/system-architecture/hardware-abstraction/index.rst @@ -0,0 +1,58 @@ +.. _hardware-abstraction: + +Hardware Abstraction Layer +========================== + +Quick Reference +--------------- +* HAL provides standardized hardware interfaces +* libhybris bridges Android and Linux userspace +* Vendor implementations provide actual hardware support +* Version compatibility is critical + +Understanding HAL +----------------- + +The Hardware Abstraction Layer (HAL) is the interface between: + +* Hardware drivers and vendor implementations +* System services and applications +* Android and Linux userspace + +Core Components +^^^^^^^^^^^^^^^ +1. **Interface Definitions** + + * Standard hardware APIs + * Version specifications + * Binary interfaces + * Protocol definitions + +2. **Implementation Layer** + + * Vendor-specific code + * Hardware drivers + * Binary blobs + * Service interfaces + +3. **Bridge Components** + + * libhybris translation + * Service management + * Resource handling + +Detailed Documentation +---------------------- + +.. toctree:: + :maxdepth: 2 + :name: hal-docs + + version-matrix + implementation + +See Also +-------- +* :ref:`debugging-hardware` - Hardware debugging +* :ref:`vendor-specific` - Vendor implementations +* :doc:`../implementation-guide` - Implementation details \ No newline at end of file diff --git a/porting/fundamentals/system-architecture/hardware-abstraction/version-matrix.rst b/porting/fundamentals/system-architecture/hardware-abstraction/version-matrix.rst new file mode 100644 index 000000000..474066f18 --- /dev/null +++ b/porting/fundamentals/system-architecture/hardware-abstraction/version-matrix.rst @@ -0,0 +1,84 @@ +HAL Version Matrix +================== + +Version Compatibility +--------------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 20 30 30 + + * - Android Version + - HAL Version + - Features + - Requirements + * - Android 7.1 + - HAL1 + - Base hardware support + - Legacy compatibility + * - Android 9 + - HAL2/Treble + - Project Treble, HIDL + - Vendor partition + * - Android 10+ + - HAL3/AIDL + - Modern interfaces + - GKI support + +Interface Requirements +---------------------- + +1. **Graphics Stack** + + * HWC version requirements + * Gralloc interface + * EGL/OpenGL support + * Vulkan compatibility + +2. **Audio System** + + * Audio HAL version + * Policy configuration + * ALSA requirements + * UCM support + +3. **Camera System** + + * Camera HAL version + * Buffer management + * Format support + * Feature levels + +4. **Sensor Hub** + + * Sensor HAL version + * Input device support + * Event handling + * Calibration + +Implementation Guidelines +------------------------- + +Version Selection +^^^^^^^^^^^^^^^^^ +Choose HAL version based on: + +* Device Android version +* Available vendor blobs +* Hardware capabilities +* System requirements + +Compatibility Notes +^^^^^^^^^^^^^^^^^^^ +Critical considerations: + +* Binary compatibility +* ABI requirements +* SELinux policies +* Init requirements + +See Also +-------- +* :doc:`implementation` - Implementation details +* :ref:`vendor-specific` - Vendor requirements +* :ref:`debugging` - HAL debugging \ No newline at end of file diff --git a/porting/fundamentals/system-architecture/implementation-guide.rst b/porting/fundamentals/system-architecture/implementation-guide.rst new file mode 100644 index 000000000..3948ad269 --- /dev/null +++ b/porting/fundamentals/system-architecture/implementation-guide.rst @@ -0,0 +1,104 @@ +From Concepts to Implementation +=============================== + +This guide bridges the gap between understanding Ubuntu Touch's architecture and implementing a port for your device. It provides a practical roadmap for translating system concepts into working code. + +Implementation Overview +----------------------- + +The porting process involves several key steps: + +1. **Hardware Layer** + + * Device kernel configuration + * Android HAL integration + * Binary driver support + * Hardware feature enablement + +2. **System Integration** + + * Container setup + * Service configuration + * Boot process management + * System image creation + +3. **User Space** + + * Display server setup + * Interface configuration + * Application support + * System services + +Making Implementation Choices +----------------------------- + +Your implementation path depends on: + +1. **Device Age and Support** + + * Modern devices (Android 9+) + * Legacy devices (pre-Android 9) + * Vendor support level + * Available documentation + +2. **Hardware Complexity** + + * SoC features + * Proprietary components + * Driver availability + * Hardware interfaces + +3. **Build Requirements** + + * Kernel source availability + * Vendor blob compatibility + * Build system needs + * Testing capabilities + +Implementation Methods +---------------------- + +Available approaches: + +1. **Standalone Kernel Method** + + Best for: + + * Modern devices + * Good vendor support + * Standard hardware + * Available documentation + +2. **Full System Build** + + Required for: + + * Legacy devices + * Complex hardware + * Custom requirements + * Specific vendor needs + +3. **GSI-Based Method** + + Suitable for: + + * Treble-compliant devices + * Standard implementations + * Modern hardware + * Reference designs + +Next Steps +---------- + +Based on your device and requirements: + +* :ref:`modern-build` - Modern build methods +* :ref:`legacy-build` - Legacy build support +* :ref:`hardware-enablement` - Hardware support +* :ref:`debugging` - Testing and verification + +See Also +-------- +* :ref:`hardware-abstraction` - HAL details +* :ref:`android-integration` - Android system +* :ref:`build-systems` - Build methods \ No newline at end of file diff --git a/porting/fundamentals/system-architecture/index.rst b/porting/fundamentals/system-architecture/index.rst new file mode 100644 index 000000000..1afecd1ea --- /dev/null +++ b/porting/fundamentals/system-architecture/index.rst @@ -0,0 +1,56 @@ +# fundamentals/system-architecture/index.rst + +System Architecture +=================== + +Quick Reference +--------------- +Essential components: + +* Ubuntu Touch userspace with systemd +* Halium hardware adaptation layer +* Android container for drivers +* libhybris hardware bridging + +Understanding the Architecture +------------------------------ + +Ubuntu Touch combines a full GNU/Linux system with Android hardware support to create a complete mobile operating system. Think of it as having three main layers: + +1. **User Space** + + * Ubuntu Touch interface and apps + * System services + * User data management + +2. **Hardware Adaptation** + + * Halium integration layer + * Hardware abstraction + * Android compatibility + +3. **Hardware Support** + + * Android kernel and drivers + * Hardware initialization + * Power management + +These layers work together to provide a seamless mobile Linux experience while maintaining compatibility with Android hardware. + +Detailed Coverage +----------------- + +.. toctree:: + :maxdepth: 2 + :name: architecture-toc + + ubuntu-touch + android-integration + hardware-abstraction/index + implementation-guide + +See Also +-------- +* :ref:`build-systems` - Building system components +* :ref:`debugging` - Architecture debugging +* :ref:`vendor-specific` - Vendor implementations \ No newline at end of file diff --git a/porting/fundamentals/system-architecture/ubuntu-touch.rst b/porting/fundamentals/system-architecture/ubuntu-touch.rst new file mode 100644 index 000000000..23756c5cd --- /dev/null +++ b/porting/fundamentals/system-architecture/ubuntu-touch.rst @@ -0,0 +1,126 @@ +Ubuntu Touch System Architecture +================================ + +Understanding the Architecture +------------------------------ +Think of Ubuntu Touch's architecture like a modern building. Just as a building has different systems working together (electrical, plumbing, heating), Ubuntu Touch has different layers that work together to create a complete mobile operating system. + +Core System Components +---------------------- +Let's break down each major component and understand its role: + +1. **User Interface Layer** + + This is like the rooms and furniture in our building - the parts you actually see and interact with: + + * Lomiri (Unity8) interface - The main "floor plan" of your phone + * Mir display server - The "lighting system" that makes everything visible + * Qt/QML applications - The "furniture" - apps you use daily + * System indicators - Like light switches and thermostats - show battery, WiFi, etc. + + Why it matters: This layer determines how you interact with your device. If it's not working, you won't be able to use your phone, even if everything else works perfectly. + +2. **System Services** + + These are like the building's utilities - you don't see them, but they're essential: + + * systemd init system - The "main power switch" that starts everything + * Network management - Like the building's internet and phone lines + * Power management - Similar to the electrical system + * Audio routing - Think of it as the building's intercom system + + Common issues: + + * Services failing to start (like a tripped circuit breaker) + * Services starting in wrong order (like turning on the AC before power) + * Resource conflicts (like too many appliances on one circuit) + +3. **Core Infrastructure** + + This is the building's foundation and structural supports: + + * Click package system - Like the building's elevator system for delivering apps + * AppArmor security - The building's security system and access controls + * Wayland protocols - The communication system between components + * DBus services - Like the building's internal mail system + + Troubleshooting tips: + + * Always check system logs when something fails + * Verify permissions when apps can't access features + * Monitor resource usage when system seems slow + +How These Work Together +----------------------- +Just as a building's systems must work together (water heater needs both water and electricity), Ubuntu Touch's components are interconnected: + +1. When you tap an app icon: + + * Lomiri receives your touch input + * Mir creates a window for the app + * systemd ensures necessary services are running + * AppArmor checks if the app has required permissions + +2. When you take a photo: + + * Camera app requests hardware access + * HAL translates this request for the camera hardware + * System services manage memory and storage + * UI layer shows you the viewfinder and controls + +Common Integration Points +------------------------- +These are critical areas where components must work together properly: + +Hardware Access +^^^^^^^^^^^^^^^ +* libhybris bridging +* Android hardware services +* Sensor systems +* Camera interfaces + +System Management +^^^^^^^^^^^^^^^^^ +* Boot process +* Service supervision +* Resource control +* Update system + +Security Model +-------------- +* AppArmor confinement +* Permission system +* Encrypted data +* Secure boot support + +Implementation Details +---------------------- + +Service Architecture +^^^^^^^^^^^^^^^^^^^^ +Essential system services: + +.. code-block:: text + + ├── lomiri-session + ├── system-services + │ ├── network + │ ├── audio + │ └── sensors + └── android-services + └── hardware + +Configuration Systems +^^^^^^^^^^^^^^^^^^^^^ +Key configuration areas: + +* Device settings +* Hardware configs +* System policies +* User preferences + +See Also +-------- +* :ref:`hardware-abstraction` - HAL details +* :ref:`debugging` - System debugging +* :doc:`implementation-guide` - Implementation \ No newline at end of file diff --git a/porting/index.rst b/porting/index.rst new file mode 100644 index 000000000..e1b1612ad --- /dev/null +++ b/porting/index.rst @@ -0,0 +1,58 @@ +Porting +======= + +This guide documents the process of porting Ubuntu Touch to new devices. A successful port enables standard Linux software to run on hardware designed for Android, making your device a true Linux phone or tablet. + +Getting Started +--------------- + +1. **Understand the Basics** + + * Core concepts and architecture + * Hardware requirements + * Build systems and methods + * Required tools and resources + +2. **Choose Your Method** + + Different approaches are available depending on your device: + + * Standalone Kernel Method - Modern devices with Android 9+ + * Full System Build - Complex or legacy devices + * GSI-Based Method - Treble-compliant devices + +3. **Follow the Process** + + * Prepare your environment + * Configure your device + * Build necessary components + * Test and debug + * Enable hardware features + * Finalize the port + +Guide Structure +--------------- + +* **Fundamentals**: Core concepts and architecture +* **Quick Start**: Quick start steps +* **Preparation**: Environment setup and device requirements +* **Modern Porting**: Step-by-step porting process +* **Debugging**: Troubleshooting and configuration +* **Finalizing**: Completing the port +* **Vendor-Specific**: Hardware-specific considerations +* **Legacy Devices**: Pre Project Treble porting +* **Resources**: Reference materials and documentation + +Getting Help +------------ + +If you get stuck: + +1. Check the troubleshooting sections +2. Review vendor-specific documentation +3. Search the resources section +4. Join the UBports porting community: + + * Telegram: @ubports_porting + * Matrix: #ubports_porting:matrix.org + * Forum: forums.ubports.com \ No newline at end of file diff --git a/porting/introduction/Intro.rst b/porting/introduction/Intro.rst deleted file mode 100644 index b871ead13..000000000 --- a/porting/introduction/Intro.rst +++ /dev/null @@ -1,134 +0,0 @@ -Introduction to porting -======================= - -This first section will introduce you to the specifics of porting Ubuntu Touch to an Android device. Note that it is written with the general public in mind, not primarily the experienced porting developer. In subsequent sections we have made an effort to differentiate by keeping the main text more concise in order to meet the needs of the more experienced reader, while providing links to supplementary reading for the less experienced. - -The guide as a whole is written as a sequence of steps describing how an ideal port might proceed. However, porting is unpredictable and messy. Every device is different and in reality you will likely iterate and revisit some steps, skip over other steps and uncover new and undocumented challenges. - -.. _What-is-Ubuntu-Touch: - -What is Ubuntu Touch? ---------------------- - -Ubuntu Touch is an open source operating system for mobile devices. It can be ported to devices that originally shipped with Android OS. Alas, the majority of these devices are dependent to some degree on proprietary software. - -.. _Vendor_blobs: - -To be specific, device vendors tend to keep the code that speaks directly to the device hardware (the low level device drivers) proprietary. These components are commonly called the `vendor 'blobs' (Binary Large OBjects) `_. The vendor blobs need to be incorporated into an Ubuntu Touch port. Note that these components are specific not only to each device, but also to each Android version. It is therefore necessary to secure the correct version of these components when building a port. - -This is why Ubuntu Touch cannot be built completely from source code for most commercial devices. Instead, porting the system to these devices involves integrating the previously mentioned vendor blobs into the rest of the system, which can be built from source. - -The next component of Ubuntu Touch is a pre-compiled root filesystem which needs to be installed on the device. This component does not communicate directly with the device hardware. Instead, this communication is mediated by a Hardware Abstraction Layer (HAL) which needs to be built for each specific device, because each device has its specific hardware architecture. This component is called Halium and is available in different versions (5.1 which is largely obsolete, 7.1, 9, 10 and 11 as of writing) corresponding to different Android versions. - -The `Halium project `_ enables Linux systems to run on Android hardware. It is a joint effort by multiple mobile operating systems, notably Lune OS and UBports. - -UBports porting builds on top of Halium porting. Consequently, you will be using both the Halium porting guide and the UBports porting guide. At times it may also be helpful to test with one of the other operating systems to debug a problem from different angles. - -Halium is an indispensible part of an Ubuntu Touch port and is available in the form of open source software. Developing a new version of Halium is a very considerable task which is why only a few versions of Halium are available. Each port of Ubuntu Touch has to be based on one of the available Halium versions and vendor blobs from the corresponding Android version. See the first two columns of the table below for details. - -Thus an Ubuntu Touch port is composed of the these components: - * The Ubuntu Touch (UT) root filesystem (rootfs) - * `Halium `_ (contained in the boot and system images) - * The vendor blobs - -You, the porter, need to build Halium (in part or in whole, depending on :ref:`porting method `) and install this together with the Ubuntu Touch rootfs in order to create a functioning Ubuntu Touch port. - -.. _Android-and-Halium-versions: - -Android and Halium versions ---------------------------- - -Halium is built using source code for a modified version of the Android operating system called LineageOS (see `the LineageOS website `_ and `wiki `_). The required source code is available online and needs to be downloaded and configured to build the correct Halium version for each individual device port. The table below shows which versions are required for the different Halium versions. - -=============== ============== ================ -Android version Halium version Lineage OS (LOS) -=============== ============== ================ -7.1 7.1 14.1 -9.0 9.0 16.0 -10.0 10.0 17.1 -11.0 11.0 18.1 -=============== ============== ================ - -.. _What-is-a-GSI: - -Generic System Image --------------------- - -Starting with Android version 9.0, a significant change of architecture was introduced. -The device-specific vendor blobs now reside on a separate partition instead of sharing a partition with the rest of the system image. This separation of device-specific code from generic code made possible what is known as the **Generic System Image (GSI)**. - -A GSI is a system image that is built to be able to function with a wide range of devices. Android devices, as of version 9.0, use a GSI. For more information, see the `Android Developer pages `_ - -The development of the Android GSI architecture also cleared the way for the now available generic Halium 9.0 arm64 system image (hereafter referred to as *the Halium GSI*, or simply *the GSI*) which is used for Ubuntu Touch. This, however, is somewhat different from the Android GSI. For a more detailed explanation of the Halium GSI, please refer to `the wiki page on Gitlab CI builds of the generic Halium system image `_. - -What does this mean for the porting process? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Since the GSI is a prebuilt, device-independent component, it effectively simplifies the task of building a viable port by removing much of the meticulous and time consuming task of getting the hardware-specific vendor blobs compiled into the system image and configured to function properly. - -.. _Porting-methods: - -Porting methods ---------------- - -This guide documents three different porting methods, which we call: **Full system image method**, **Halium-boot method**, and **Standalone kernel method**. -When porting based on Halium 7.1 the Full system image method is the only available method to follow. For Halium 9.0 all three methods are possible. - -Full system image method -^^^^^^^^^^^^^^^^^^^^^^^^ - -This porting method requires building both the boot image (halium-boot.img) and the full device specific system image (system.img) from source and installing these together with the UBports root file system (rootfs). For Halium 7.1 ports this is the only possible method (Consequently, this method is sometimes referred to as *the Halium 7.1 method*). -For Halium 9.0 it is also possible to use this method, however for Halium 9.0 the other two methods below are probably easier. - -Halium-boot method -^^^^^^^^^^^^^^^^^^ - -For this porting method it is sufficent to build the halium-boot.img and install this together with the Halium GSI and the UBports rootfs. This method can be used for Halium 9.0 ports. - -Standalone kernel method -^^^^^^^^^^^^^^^^^^^^^^^^ - -This porting method only requires building the kernel and installing this together with the Halium ramdisk, the Halium GSI and the UBports rootfs. This method can be used for Halium 9.0 ports. - -All methods share some common steps. However, there are also significant differences that must not be missed. Therefore, the methods will be treated separately in the subsequent sections where needed. - -The remainder of this section gives some words of advice to new porters. If you already have porting experience or ROM building experience, you can likely skip straight to :ref:`Preparations `. - -.. _The-challenges-of-the-porting-process: - -The challenges of the porting process -------------------------------------- - -Building the necessary components and getting them to work together properly always involves an amount of code modifications, configuring and testing, but considerably moreso when doing full system image builds, compared to builds using the GSI (see :ref:`porting methods `). - -Luckily, there is a community of porters out there who are eager to see Ubuntu Touch ported to new devices. When you run into trouble, you should search the sources below (:ref:`Getting-community-help`) to see if others before you have solved the issue. There are online Telegram chat groups you can join to ask for help, but please bear in mind that those participating are doing so in their spare time. - -.. _Prior-knowledge-and-skills: - -Prior knowledge and skills --------------------------- - -Porters come in all sizes and shapes, so to speak. Therefore, this guide does not presuppose extensive knowledge or skills in any particular field. You should, however, as a bare minimum be familiar with some common shell commands and be comfortable working from the terminal on you host PC. Furthermore, the guide is based on a host PC running Linux. If you have some knowledge of programming, this will come in handy at some point, especially if you are familiar with C / C++. Also, you should familiarize yourself with git and set up a Github or Gitlab account to keep track of your code changes. It is wise to start documenting your steps from the very beginning. - -We have attempted to give a certain amount of explanation along the way. However, this guide is not an in-depth reference into the architecture and inner workings of Ubuntu Touch, and gaining a deeper understanding will consequently require an amount of research on your part. - -.. _Getting-community-help: - -Getting community help ----------------------- - -When you run into trouble, and you will, refer to one or more of the sources below: - -* `Telegram: @ubports_porting `_ -* `The UBports Forum `_ - -.. _General-advice: - -General advice --------------- - -The more rigorous you are at making notes and documenting your steps, the less time you will spend backtracking your steps and guessing your way along. When dealing with issues that arise along the way, it is wise to work on them one at a time. If you try to correct several things at once, you risk ending up trying to guess which changes solved a given issue, which easily leads to breaking the functionality in question once more at some later stage. - -If you are not discouraged after reading this, we welcome your efforts and wish you the best of luck! - -The next section presents a key to the rest of this guide. diff --git a/porting/introduction/Preparations.rst b/porting/introduction/Preparations.rst deleted file mode 100644 index af7d33f24..000000000 --- a/porting/introduction/Preparations.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _Preparations: - -Preparations -============ - -Not all devices can be made to run Ubuntu Touch. Research your target device before you start. - -To determine your device's specifications, search for it on `GSM Arena `_ and/or `Device Specification `_. -Refer to `Pick an Android target device in the Halium Porting Guide `_ for further information on requirements and how to check if your device qualifies. - -.. _Locate-relevant-guides-and-other-information: - -Locate relevant guides and other information --------------------------------------------- - -If your desired target device complies to the above, the next thing to do is locate the available guides and other documentation. This step will help you later on when you run into issues developing your port. For now, the main thing to look for is how to unlock your bootloader. (See below). - -Head over to the `LineageOS Wiki `_. Look up your device and read and bookmark the guides that are listed there. Try a web search for additional information, specifying both its retail name and the code name you found on the LineageOS site. Be careful to check that the information you gather applies to your specific device, keeping in mind that many devices are sold in a number of different variants with different hardware specifications. - -Another rich source of information is the `XDA Developers Forum `_. - -.. _Unlock-the-bootloader: - -Unlock the bootloader ---------------------- - -Vendors usually provide their devices in a locked bootloader state. This is a kind of software "seal" intended to prevent modifications directly to the operating system and system software. If you unlock the bootloader, you will be able to make such modifications, but in this state your device's warranty might be void. The choice is yours, but this step is mandatory if you wish to install Ubuntu Touch on the device. - -Devices differ and there is no general method that covers all makes and models. Therefore, you need to check the aforementioned guides for instructions on how to unlock the bootloader of your particular device. - -.. _Install-TWRP-recovery: - -Install TWRP recovery ---------------------- - -You need to install a custom recovery image on your device in order to handle formatting and flashing image files onto it. Head over to the `Team Win Recovery Project `_ and locate the image file for your device. Follow the installation instructions provided on the website. - -.. _Recommendations-for-the-build-PC: - -Recommendations for the host/build PC -------------------------------------- - -The remainder of this guide presumes you are using a build PC running Linux. Although high performance always is nice, stability and sufficient RAM and harddisk space are the main concerns here. You do not need the latest and the best hardware, nor do you need the latest distribution release. In fact, it is not uncommon to run into issues when choosing the very newest release, as some of the software needed may not yet have been built for it. For example, as of writing the latest release of Ubuntu Linux is 20.04, but many still recommend using the previous long term support release, 18.04. - -Having completed the steps above, you are now ready to set up your build environment and start the porting process per se (next section). \ No newline at end of file diff --git a/porting/introduction/Setting_up.rst b/porting/introduction/Setting_up.rst deleted file mode 100644 index 0efde8b7e..000000000 --- a/porting/introduction/Setting_up.rst +++ /dev/null @@ -1,84 +0,0 @@ -.. _Setting-up: - -Setting up the build environment -================================ - -Your host PC needs a number of tools installed before you can begin to port. This section describes the necessary preparations. - -Prerequisites -------------- - -When setting up the build environment you need to have Python 3.6 or newer installed on your system. This can be installed via your system's package management system. Significant changes in syntax were introduced from Python 2 to Python 3, and some stages of the porting process may require Python 2 instead of Python 3. To check which version is active on your system, type:: - - python -V - -.. Note:: - Any Linux distribution can easily be set up to switch between Python versions. Consult the documentation for your distribution to find out how this can be done. - -Debian (Stretch or newer) / Ubuntu (16.04 or 18.04) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If your host PC has a 64-bit architecture (amd64), enable the usage of the i386 architecture:: - - sudo dpkg --add-architecture i386 - -Update your package lists to take advantage of the new architecture:: - - sudo apt update - -Install the required dependencies:: - - sudo apt install git gnupg flex bison gperf build-essential \ - zip bzr curl libc6-dev libncurses5-dev:i386 x11proto-core-dev \ - libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-glx:i386 \ - libgl1-mesa-dev g++-multilib mingw-w64-i686-dev tofrodos \ - python-markdown libxml2-utils xsltproc zlib1g-dev:i386 schedtool \ - repo liblz4-tool bc lzop imagemagick libncurses5 rsync - -Ubuntu (20.04 or newer) -^^^^^^^^^^^^^^^^^^^^^^^ - -If your host PC has a 64-bit architecture (amd64), enable the usage of the i386 architecture:: - - sudo dpkg --add-architecture i386 - -Update your package lists to take advantage of the new architecture:: - - sudo apt update - -Install the required dependencies:: - - sudo apt install git gnupg flex bison gperf build-essential \ - zip bzr curl libc6-dev libncurses5-dev:i386 x11proto-core-dev \ - libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-glx:i386 \ - libgl1-mesa-dev g++-multilib mingw-w64-i686-dev tofrodos \ - python3-markdown libxml2-utils xsltproc zlib1g-dev:i386 schedtool \ - liblz4-tool bc lzop imagemagick libncurses5 rsync \ - python-is-python3 python2 - -Create a directory named 'bin' in your home directory, and include it in your path:: - - mkdir -p ~/bin - echo export PATH=\$PATH:\$HOME/bin >> ~/.bashrc - source ~/.bashrc - -Download the repo script and make it executable:: - - curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo - chmod a+rx ~/bin/repo - -Arch -^^^^ - -If your host PC has a 64-bit architecture, you need to add the [multilib] repository to your /etc/pacman.conf . This will allow you to install and run i686 packages. Please refer to `‘Official Repositories/multilib’ on the Arch Wiki `_. - -Make sure you have the base-devel package installed. - -Install the required dependencies from AUR:: - - git clone https://aur.archlinux.org/halium-devel.git && cd halium-devel && makepkg -i - - Please note: as of Autumn 2021 this package is no longer maintained. You will be unable to clone and build Halium on Arch as all dependencies are not met. - - - diff --git a/porting/introduction/index.rst b/porting/introduction/index.rst deleted file mode 100644 index 7cfe38db2..000000000 --- a/porting/introduction/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -Introduction -============ - -Porting is the process of making Ubuntu Touch run on new hardware, i.e. on devices that have not previously been able to run Ubuntu Touch. - -On the vast majority of commercially available devices crucial parts of their systems are not open source. Furthermore, these proprietary parts are specific, not only to the manufacturer, but usually also to the individual model. - -Porting Ubuntu Touch involves building it in such a way as to integrate it with these proprietary components on a device so as to enable it to "talk to" the device hardware. - -Before attempting to port Ubuntu Touch to a new device, there are a few things to understand and consider, some research to be done, and a suitable build environment needs to be set up. This section addresses these points. - -.. toctree:: - :maxdepth: 1 - :name: introduction - - Intro - Preparations - Setting_up diff --git a/porting/legacy-porting/full-system/build-system.rst b/porting/legacy-porting/full-system/build-system.rst new file mode 100644 index 000000000..c05cba82a --- /dev/null +++ b/porting/legacy-porting/full-system/build-system.rst @@ -0,0 +1,168 @@ +Building System Images +====================== + +This guide walks you through building the necessary system images for your legacy device port. We'll build two main components: a boot image (halium-boot.img) and a system image (system.img). + +Quick Reference +--------------- +Steps in brief:: + + source build/envsetup.sh + breakfast [device] + mka halium-boot + mka systemimage + +Understanding the Build Process +------------------------------- +Before diving in, let's understand what we're building: + +1. **Boot Image (halium-boot.img)** + + - Contains the kernel + - Includes initial ramdisk + - Handles hardware initialization + - Starts core system + +2. **System Image (system.img)** + + - Main system files + - Hardware abstraction layer + - Android services + - Vendor files + +Think of the boot image as the starter and the system image as the engine of your device. + +Detailed Steps +-------------- + +1. Prepare Build Environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +First, set up your shell environment:: + + source build/envsetup.sh + +This command: + +- Sets up necessary environment variables +- Adds build commands to your shell +- Configures build tools + +2. Configure Device +^^^^^^^^^^^^^^^^^^^ +Initialize device configuration:: + + breakfast [device] + +Replace [device] with your device's codename (like i9300). + +What breakfast does: + +- Checks device configuration +- Downloads additional dependencies +- Sets up build targets + +3. Configure Kernel +^^^^^^^^^^^^^^^^^^^ +The kernel needs specific settings for Ubuntu Touch. + +Find your kernel config:: + + grep "TARGET_KERNEL_CONFIG" device/[vendor]/[device]/BoardConfig.mk + +This shows which kernel configuration file to modify. + +Apply Halium patches:: + + ./halium/halium-boot/check-kernel-config path/to/defconfig -w + +Important kernel settings:: + + CONFIG_NAMESPACES=y # Container support + CONFIG_ANDROID_BINDER_IPC=y # Android IPC + CONFIG_DUMMY_CONSOLE=y # Display support + CONFIG_DEVTMPFS=y # Device filesystem + +4. Build Boot Image +^^^^^^^^^^^^^^^^^^^ +First, build boot image tools:: + + mka mkbootimg + +Then build the boot image:: + + mka halium-boot + +This creates halium-boot.img, which contains: + +- Your compiled kernel +- Initial ramdisk +- Device tree (if required) + +5. Build System Image +^^^^^^^^^^^^^^^^^^^^^ +Build the complete system:: + + mka systemimage + +This step: + +- Compiles Android HAL +- Integrates vendor blobs +- Creates filesystem image +- Packages everything together + +Build Output +------------ +Find your build results in:: + + out/target/product/[device]/ + ├── halium-boot.img # Boot image + ├── system.img # System image + └── recovery.img # Recovery (if built) + +Common Issues +------------- +1. **Build Errors** + + - Missing dependencies: Check build-essential, etc. + - Space issues: Need at least 100GB free + - RAM limitations: Need 16GB+ RAM + +2. **Kernel Problems** + + - Config errors: Verify kernel configuration + - Missing modules: Check kernel defconfig + - Build fails: Look for compiler errors + +3. **System Image Issues** + + - Vendor blob problems: Check vendor files + - HAL errors: Verify HAL versions + - Space errors: Check partition sizes + +Monitoring Progress +------------------- +Watch build progress:: + + # Check CPU usage + htop + + # Monitor storage + df -h + + # Watch memory + free -h + +Next Steps +---------- +After successful build: + +- :doc:`installation` - Installing your build +- :doc:`../../debugging/workflows/first-boot` - First boot process +- :doc:`../../debugging/index` - Debugging tools + +See Also +-------- +* :ref:`build-systems` - Understanding build systems +* :ref:`hardware-abstraction` - HAL details +* :ref:`android-integration` - Android build process \ No newline at end of file diff --git a/porting/legacy-porting/full-system/device-configs.rst b/porting/legacy-porting/full-system/device-configs.rst new file mode 100644 index 000000000..a66578dd2 --- /dev/null +++ b/porting/legacy-porting/full-system/device-configs.rst @@ -0,0 +1,201 @@ +Device Configuration +==================== + +This guide explains how to configure your device-specific settings. These configurations tell the build system about your device's hardware and features. + +Quick Reference +--------------- +Key configuration files: + +* BoardConfig.mk - Core hardware settings +* device.mk - Features and packages +* system.prop - System properties + +Understanding Configuration Files +--------------------------------- +Your device needs three main configuration files: + +1. **BoardConfig.mk** + + - Basic hardware setup + - Partition information + - Kernel configuration + - CPU/GPU settings + +2. **device.mk** + + - Hardware features + - Included packages + - System properties + - File permissions + +3. **system.prop** + + - Runtime properties + - Hardware settings + - Feature flags + - System behaviors + +Think of these files as your device's instruction manual - they tell Ubuntu Touch how your hardware works. + +Detailed Configuration +---------------------- + +BoardConfig.mk Settings +^^^^^^^^^^^^^^^^^^^^^^^ +Basic device architecture:: + + # CPU Architecture + TARGET_ARCH := arm64 # or 'arm' for 32-bit + TARGET_ARCH_VARIANT := armv8-a # CPU version + TARGET_CPU_VARIANT := generic # CPU type + + # Bootloader + TARGET_NO_BOOTLOADER := true # Skip bootloader build + TARGET_NO_RECOVERY := false # Include recovery + +Kernel configuration:: + + # Kernel location + TARGET_KERNEL_SOURCE := kernel/[vendor]/[device] + TARGET_KERNEL_CONFIG := [device]_defconfig + + # Kernel options + BOARD_KERNEL_BASE := 0x80000000 # Kernel load address + BOARD_KERNEL_PAGESIZE := 2048 # Memory page size + BOARD_KERNEL_CMDLINE += console=tty0 # Required for Ubuntu Touch + +Partition layout:: + + # System image + BOARD_SYSTEMIMAGE_PARTITION_SIZE := 2147483648 # 2GB + BOARD_SYSTEMIMAGE_FILE_SYSTEM_TYPE := ext4 + + # Data partition + BOARD_USERDATAIMAGE_PARTITION_SIZE := 576716800 + BOARD_USERDATAIMAGE_FILE_SYSTEM_TYPE := ext4 + +device.mk Configuration +^^^^^^^^^^^^^^^^^^^^^^^ +Basic device setup:: + + # Inherit base configuration + $(call inherit-product, $(SRC_TARGET_DIR)/product/full_base_telephony.mk) + + # Device identifier + PRODUCT_DEVICE := [device] + PRODUCT_NAME := halium_[device] + PRODUCT_BRAND := [vendor] + PRODUCT_MODEL := [model] + PRODUCT_MANUFACTURER := [vendor] + +Hardware permissions:: + + # Copy permission files + PRODUCT_COPY_FILES += \ + frameworks/native/data/etc/android.hardware.wifi.xml:system/etc/permissions/android.hardware.wifi.xml \ + frameworks/native/data/etc/android.hardware.telephony.gsm.xml:system/etc/permissions/android.hardware.telephony.gsm.xml \ + frameworks/native/data/etc/android.hardware.sensor.accelerometer.xml:system/etc/permissions/android.hardware.sensor.accelerometer.xml + +Include packages:: + + # Basic packages + PRODUCT_PACKAGES += \ + libion \ + lights.$(TARGET_BOARD_PLATFORM) \ + audio.primary.$(TARGET_BOARD_PLATFORM) + +System Properties +^^^^^^^^^^^^^^^^^ +Create system.prop:: + + # Hardware + ro.hardware=halium + + # Radio + ro.telephony.default_network=9 + ro.radio.noril=false + + # Display + ro.sf.lcd_density=320 + +Common Configurations +--------------------- + +1. **Display Settings**:: + + # In BoardConfig.mk + TARGET_USES_HWC2 := true + TARGET_USES_GRALLOC1 := true + + # In system.prop + debug.sf.hw=1 + debug.egl.hw=1 + +2. **Audio Configuration**:: + + # In device.mk + PRODUCT_PACKAGES += \ + audio.primary.$(TARGET_BOARD_PLATFORM) \ + audio.a2dp.default \ + audio.usb.default + +3. **WiFi Setup**:: + + # In BoardConfig.mk + BOARD_HOSTAPD_DRIVER := NL80211 + BOARD_WPA_SUPPLICANT_DRIVER := NL80211 + + # In device.mk + PRODUCT_PACKAGES += \ + hostapd \ + wpa_supplicant + +Common Issues +------------- + +1. **Missing Hardware Support** + + - Check permission files + - Verify hardware features + - Review vendor blobs + +2. **System Property Errors** + + - Validate property names + - Check value formats + - Verify property locations + +3. **Package Problems** + + - Check package names + - Verify dependencies + - Review build errors + +Testing Configuration +--------------------- +Verify your configuration:: + + # Check properties + getprop | grep + + # Test hardware + ls -l /dev/ + ls -l /sys/class/ + + # Review permissions + ls -l /system/etc/permissions/ + +Next Steps +---------- +After configuration: + +- :doc:`build-system` - Build your port +- :doc:`../../debugging/hardware-debug/index` - Hardware debugging +- :doc:`../../debugging/system-debug/index` - System debugging + +See Also +-------- +* :ref:`hardware-abstraction` - Hardware layer details +* :ref:`android-integration` - Android system structure +* :doc:`../../debugging/overlay-method` - Configuration overlays \ No newline at end of file diff --git a/porting/legacy-porting/full-system/index.rst b/porting/legacy-porting/full-system/index.rst new file mode 100644 index 000000000..af64067ed --- /dev/null +++ b/porting/legacy-porting/full-system/index.rst @@ -0,0 +1,13 @@ +Full System Build Method +======================== + +For pre-Android 9 devices, a complete system image must be built from source. + +.. toctree:: + :maxdepth: 2 + :name: legacy-fullsystem + + setup-sources + build-system + device-configs + installation \ No newline at end of file diff --git a/porting/legacy-porting/full-system/installation.rst b/porting/legacy-porting/full-system/installation.rst new file mode 100644 index 000000000..c42aee5cf --- /dev/null +++ b/porting/legacy-porting/full-system/installation.rst @@ -0,0 +1,187 @@ +Installation Guide +================== + +This guide walks you through installing Ubuntu Touch on your legacy device. The process involves installing a boot image, system image, and the Ubuntu Touch rootfs. + +Quick Reference +--------------- +Steps in brief:: + + # Get installer + git clone https://gitlab.com/JBBgameich/halium-install.git + + # Install system + sudo ./halium-install -p ut rootfs.tar.gz system.img + + # Flash boot + fastboot flash boot halium-boot.img + +Understanding the Components +---------------------------- +Before installing, let's understand what we're working with: + +1. **Boot Image (halium-boot.img)** + + - Boots your device + - Contains the kernel + - Initializes hardware + +2. **System Image (system.img)** + + - Contains Android HAL + - Provides hardware support + - Includes vendor files + +3. **Ubuntu Touch Rootfs** + + - Main Ubuntu Touch system + - User interface + - Applications + - System services + +Think of these as layers: boot image starts the device, system image provides hardware support, and rootfs gives you the actual Ubuntu Touch experience. + +Prerequisites +------------- +Before starting, ensure you have: + +1. **Working Recovery** + + - TWRP recommended + - Must support ext4 + - Must have adb enabled + +2. **Required Tools** + + - ADB and Fastboot + - Root access on your PC + - Sufficient storage space + +3. **Device Access** + + - Unlocked bootloader + - USB debugging enabled + - Working USB connection + +Detailed Installation Steps +--------------------------- + +1. Download Ubuntu Touch Rootfs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Choose the correct rootfs for your device architecture:: + + # For 32-bit devices (armhf) + wget https://ci.ubports.com/job/xenial-rootfs-armhf/lastSuccessfulBuild/artifact/out/ubuntu-touch-xenial-armhf-rootfs.tar.gz + + # For 64-bit devices (arm64) + wget https://ci.ubports.com/job/xenial-rootfs-arm64/lastSuccessfulBuild/artifact/out/ubuntu-touch-xenial-arm64-rootfs.tar.gz + +2. Prepare Installation Tools +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Get the installation script:: + + git clone https://gitlab.com/JBBgameich/halium-install.git + cd halium-install + +3. Install System Image and Rootfs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Install Ubuntu Touch:: + + sudo ./halium-install -p ut path/to/rootfs.tar.gz path/to/system.img + +This command: + +- Unpacks the rootfs +- Installs system image +- Sets up configuration +- Creates user account + +4. Flash Boot Image +^^^^^^^^^^^^^^^^^^^ +Boot to fastboot mode and flash:: + + fastboot flash boot path/to/halium-boot.img + +First Boot Process +------------------ + +1. **Initial Boot** + + - Device may appear unresponsive + - This is normal - wait a few minutes + - Watch for USB network interface + +2. **Gaining Access** + When device boots:: + + # Setup USB networking + sudo ip address add 10.15.19.100/24 dev + sudo ip link set up + + # Connect via SSH + ssh phablet@10.15.19.82 + +3. **Verify Installation** + Check system status:: + + # System status + systemctl status + + # Android container + lxc-info -n android + + # Hardware status + dmesg | grep -i hardware + +Common Issues +------------- + +1. **Installation Fails** + + - Check storage space + - Verify file permissions + - Review error messages + +2. **Boot Problems** + + - Check boot image compatibility + - Verify partition layout + - Review kernel logs + +3. **No USB Network** + + - Check USB configuration + - Review kernel config + - Verify network setup + +Recovery Options +---------------- + +1. **Failed Installation**:: + + # Clean up + fastboot erase system + fastboot erase userdata + + # Start over + fastboot reboot recovery + +2. **Boot Problems**:: + + # Boot to recovery + adb pull /proc/last_kmsg + adb pull /cache/recovery/last_kmsg + +Next Steps +---------- +After successful installation: + +- :doc:`../../debugging/workflows/first-boot` - First boot debugging +- :doc:`../../debugging/index` - Basic configuration +- :doc:`../../debugging/hardware-debug/index` - Hardware enablement + +See Also +-------- +* :ref:`debugging-strategies` - Debugging approach +* :ref:`overlay-method` - System configuration +* :doc:`../../debugging/troubleshooting/boot-issues` - Boot problems \ No newline at end of file diff --git a/porting/legacy-porting/full-system/setup-sources.rst b/porting/legacy-porting/full-system/setup-sources.rst new file mode 100644 index 000000000..cc0745eea --- /dev/null +++ b/porting/legacy-porting/full-system/setup-sources.rst @@ -0,0 +1,149 @@ +Setting Up Sources +================== + +This guide helps you prepare the necessary source code for your legacy device port. Legacy devices (pre-Android 9) require building a complete system from source, which means we need to gather several components. + +Quick Reference +--------------- +Steps in brief:: + + mkdir halium && cd halium + repo init -u https://github.com/Halium/android -b halium-7.1 --depth=1 + repo sync -c -j$(nproc) + +Understanding the Components +---------------------------- +Before we begin, let's understand what we need: + +1. **Halium Sources** + + - Base Android system modified for Ubuntu Touch + - Hardware support layer + - Build system + +2. **Device-Specific Sources** + + - Device tree: Hardware configurations + - Kernel source: Core device code + - Vendor blobs: Proprietary hardware drivers + - Common platform files: Shared device family code + +Think of these components as building blocks - each one is necessary for your device to function properly. + +Detailed Steps +-------------- + +1. Create Build Environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +First, create a directory for your build:: + + mkdir halium + cd halium + +This will be your main working directory, often called BUILDDIR in documentation. + +2. Initialize Repository +^^^^^^^^^^^^^^^^^^^^^^^^ +The 'repo' tool helps manage multiple Git repositories:: + + repo init -u https://github.com/Halium/android -b halium-7.1 --depth=1 + +What this does: + +- Initializes repo tool +- Points to Halium's Android fork +- Selects halium-7.1 branch +- --depth=1 saves space by getting only recent history + +3. Download Source Code +^^^^^^^^^^^^^^^^^^^^^^^ +Sync all repositories:: + + repo sync -c -j$(nproc) + +This will take time and needs good internet. The -j flag uses multiple threads to speed up the download. + +4. Adding Device Sources +^^^^^^^^^^^^^^^^^^^^^^^^ +Now comes the crucial part - adding your device-specific code. + +Create Device Manifest +"""""""""""""""""""""" +Create a file: ``halium/devices/manifests/[vendor]_[device].xml`` + +Example for "Samsung Galaxy S3" (i9300):: + + + + + + + + + + + + + +Understanding the manifest: + +- path: Where files will be placed in your build tree +- name: Repository to download +- remote: Where to download from +- revision: Which branch to use + +Finding Repositories +"""""""""""""""""""" +1. Check LineageOS's GitHub organization +2. Search for your device's codename +3. Look for repositories matching: + + - android_device_[vendor]_[codename] + - android_kernel_[vendor]_[platform] + - proprietary_vendor_[vendor] + +5. Setup Device +^^^^^^^^^^^^^^^ +Initialize your device-specific code:: + + ./halium/devices/setup [device] + +Replace [device] with your device's codename (like i9300). + +6. Apply Patches +^^^^^^^^^^^^^^^^ +Apply Halium-specific patches:: + + hybris-patches/apply-patches.sh --mb + +These patches modify Android code to work with Ubuntu Touch. + +Common Issues +------------- +- **repo sync fails**: Check internet connection, free space +- **Repository not found**: Verify repository names and availability +- **Wrong branches**: Make sure branches match Android version +- **Missing repositories**: Check device dependencies + +Next Steps +---------- +After setting up sources: + +- :doc:`build-system` - Building system images +- :doc:`device-configs` - Configure your device +- :doc:`../../debugging/index` - Basic Configuration + +See Also +-------- +* :ref:`build-systems` - Understanding build systems +* :ref:`android-integration` - Android system structure +* :ref:`hardware-abstraction` - Hardware support layer \ No newline at end of file diff --git a/porting/legacy-porting/index.rst b/porting/legacy-porting/index.rst new file mode 100644 index 000000000..4ec2e027d --- /dev/null +++ b/porting/legacy-porting/index.rst @@ -0,0 +1,22 @@ +Legacy Device Porting +===================== + +This section covers porting Ubuntu Touch to pre-Android 9 devices using Halium 7.1. + +.. warning:: + Legacy porting is more complex and less supported than modern methods. Only use this approach if your device cannot support newer Android versions. + +Requirements +------------ +* Device running Android 7.x +* Available kernel source code +* Complete device tree +* Vendor blobs +* Working LineageOS 14.1 or similar ROM + +.. toctree:: + :maxdepth: 2 + :name: legacy-porting + + full-system/index + migration/index \ No newline at end of file diff --git a/porting/legacy-porting/migration/index.rst b/porting/legacy-porting/migration/index.rst new file mode 100644 index 000000000..17b4166e0 --- /dev/null +++ b/porting/legacy-porting/migration/index.rst @@ -0,0 +1,204 @@ +.. _migration-guide: + +Migration to Modern Methods +=========================== + +This guide helps you evaluate whether your legacy device can be upgraded to use modern porting methods. While legacy ports work, moving to newer methods can provide better maintainability and features. + +Quick Reference +--------------- +Key requirements for migration: + +* Android 9.0 support potential +* Available updated vendor blobs +* Hardware compatibility +* Working Android 9 ROMs (official or unofficial) + +Understanding Migration +----------------------- +Before considering migration, let's understand what's involved: + +1. **Why Migrate?** + + Benefits: + + - Better hardware support + - Simplified maintenance + - Improved security + - New features + - GSI compatibility + + Challenges: + + - Complex upgrade process + - Potential hardware issues + - Time investment + - Testing requirements + +2. **What Changes?** + + Technical differences: + + - Project Treble support + - Vendor partition separation + - HAL interface changes + - Security enhancements + - System architecture + +Assessment Process +------------------ + +1. Check Android 9 Support +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Research ROM availability:: + + # Places to check + - LineageOS device list + - XDA Developers forum + - GitHub repositories + - Community forums + +Key indicators: + +* Working LineageOS 16 +* Other Android 9 custom ROMs +* Developer community activity +* Hardware driver availability + +2. Verify Hardware Compatibility +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Check critical components:: + + # Essential hardware + - WiFi drivers + - Mobile data + - Camera HAL + - Audio system + - Sensors + +Common issues: + +* Proprietary blob availability +* Driver compatibility +* HAL version mismatches +* Firmware requirements + +3. Review Vendor Support +^^^^^^^^^^^^^^^^^^^^^^^^ +Assess vendor files:: + + # Check availability + - Android 9 vendor blobs + - Updated proprietary files + - Firmware versions + - HAL implementations + +Sources to check: + +* Device manufacturer +* Community repositories +* Existing Android 9 ROMs +* Firmware dumps + +Planning Migration +------------------ + +1. **Preparation Steps** + + Document current state:: + + # Gather information + - Current hardware status + - Working features + - Known issues + - Custom patches + +2. **Test Environment** + + Set up testing:: + + # Create test setup + - Backup current port + - Set up build environment + - Prepare test device + - Document procedures + +3. **Migration Path** + + Plan the process:: + + # Step by step + 1. Backup existing work + 2. Set up new environment + 3. Port to Android 9 + 4. Test and verify + 5. Document changes + +Common Challenges +----------------- + +1. **Hardware Support** + + - Driver compatibility + - Blob availability + - Feature regression + - Performance issues + +2. **Build Issues** + + - Build system changes + - Dependency updates + - Configuration updates + - Tool chain requirements + +3. **Testing Requirements** + + - Feature verification + - Performance testing + - Stability checks + - User testing + +Decision Making +--------------- + +Consider these factors: + +1. **Resources Required** + + - Development time + - Testing effort + - Documentation needs + - Maintenance impact + +2. **Community Support** + + - Available expertise + - Testing assistance + - Documentation help + - Long-term maintenance + +3. **Risk Assessment** + + - Feature regression + - Stability impact + - User disruption + - Recovery options + +Next Steps +---------- + +If migration is possible: +- :doc:`../../modern-porting/index` - Modern porting guide +- :doc:`../../modern-porting/standalone-kernel/index` - Kernel-based method +- :doc:`../../debugging/index` - Updated debugging guide + +If staying on legacy: +- :doc:`../full-system/index` - Continue legacy port +- :doc:`../../debugging/index` - Debugging current port + +See Also +-------- +* :ref:`android-integration` - Halium architecture +* :ref:`hardware-abstraction` - HAL details +* :doc:`../../vendor-specific/index` - Vendor-specific guides \ No newline at end of file diff --git a/porting/modern-porting/full-system/build.rst b/porting/modern-porting/full-system/build.rst new file mode 100644 index 000000000..1c22e2ef0 --- /dev/null +++ b/porting/modern-porting/full-system/build.rst @@ -0,0 +1,64 @@ +Building System Images +====================== + +Initialize Build Environment +---------------------------- +:: + + source build/envsetup.sh + breakfast [device] + +Kernel Configuration +-------------------- + +1. **Locate Config**:: + + grep "TARGET_KERNEL_CONFIG" device/[vendor]/[device]/BoardConfig.mk + +2. **Verify Settings** + + * CONFIG_ANDROID_BINDER_IPC + * CONFIG_NAMESPACES + * CONFIG_FHANDLE + * CONFIG_STAGING + * CONFIG_ASHMEM + +3. **Apply Halium Patches**:: + + ./halium/halium-boot/check-kernel-config path/to/defconfig -w + +Build Process +------------- + +1. **Build Boot Image**:: + + mka mkbootimg + mka halium-boot + +2. **Build System Image**:: + + mka systemimage + +3. **Build Recovery** (if needed):: + + mka recoveryimage + +Output Files +------------ +Check out/target/product/[device]/ for: + +* halium-boot.img +* system.img +* recovery.img (if built) + +Common Issues +------------- +* Missing kernel configs +* Vendor blob incompatibility +* Build system errors +* Resource limitations + +Next Steps +---------- +* :doc:`installation` - Installing images +* :doc:`../../debugging/index` - Debugging and configuration \ No newline at end of file diff --git a/porting/modern-porting/full-system/index.rst b/porting/modern-porting/full-system/index.rst new file mode 100644 index 000000000..78ad32a5a --- /dev/null +++ b/porting/modern-porting/full-system/index.rst @@ -0,0 +1,26 @@ +Full System Build Method +======================== + +This method builds a complete system image from source, providing maximum control over the build process. + +Process Overview: +----------------- +1. Set up build environment +2. Configure device sources +3. Build system images +4. Install and configure + +Prerequisites: +-------------- +* Linux build environment +* 32GB RAM recommended +* 200GB+ storage +* Android build experience + +.. toctree:: + :maxdepth: 1 + :name: full-system-build + + setup + build + installation \ No newline at end of file diff --git a/porting/modern-porting/full-system/installation.rst b/porting/modern-porting/full-system/installation.rst new file mode 100644 index 000000000..7858cf99e --- /dev/null +++ b/porting/modern-porting/full-system/installation.rst @@ -0,0 +1,52 @@ +Installing Full System Build +============================ + +Prerequisites +------------- +* Working recovery (TWRP recommended) +* Unlocked bootloader +* ADB access +* Required images built + +Installation Steps +------------------ + +1. **Download Rootfs** + + * Get appropriate rootfs version + * Match architecture (arm64/armhf) + * Verify checksum + +2. **Flash Images** + +Standard Method:: + + fastboot flash boot halium-boot.img + fastboot flash system system.img + +Dynamic Partitions:: + + fastboot reboot fastboot + fastboot flash boot boot.img + fastboot flash system system.img + +3. **Install Rootfs**:: + + # Get halium-install + git clone https://gitlab.com/JBBgameich/halium-install.git + + # Install Ubuntu Touch + sudo ./halium-install -p ut [rootfs.tar.gz] [system.img] + +First Boot +---------- +* Device may appear unresponsive +* Check for network interface +* Try SSH access +* See :doc:`../standalone-kernel/first-boot` + +Next Steps +---------- +* :doc:`../../debugging/configuration/display` +* :doc:`../../debugging/hardware-fixes/apparmor` +* :doc:`../../debugging/configuration/audio` \ No newline at end of file diff --git a/porting/modern-porting/full-system/setup.rst b/porting/modern-porting/full-system/setup.rst new file mode 100644 index 000000000..aec1a0440 --- /dev/null +++ b/porting/modern-porting/full-system/setup.rst @@ -0,0 +1,82 @@ +Setting Up Full System Build +============================ + +Environment Setup +----------------- + +1. **System Requirements** + + * Ubuntu 22.04 LTS recommended + * 32GB RAM (16GB minimum) + * 200GB storage + * High-speed internet + +2. **Install Dependencies**:: + + sudo apt update + sudo apt install git gnupg flex bison gperf build-essential \ + zip bzr curl libc6-dev libncurses5-dev:i386 x11proto-core-dev \ + libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-glx:i386 \ + libgl1-mesa-dev g++-multilib tofrodos python3-markdown \ + libxml2-utils xsltproc zlib1g-dev:i386 schedtool \ + repo liblz4-tool bc lzop + +3. **Configure Git**:: + + git config --global user.name "Your Name" + git config --global user.email "you@example.com" + +Source Setup +------------ + +1. **Create Build Directory**:: + + mkdir halium && cd halium + +2. **Initialize Repository**:: + + repo init -u https://github.com/Halium/android -b halium-9.0 --depth=1 + repo sync -c -j$(nproc --all) + +3. **Device Sources** + + * Create manifest in halium/devices/manifests/[vendor]_[device].xml + * Include device tree + * Add vendor blobs + * Include kernel source + +Example Manifest +---------------- +.. code-block:: xml + + + + + + + + +4. **Sync Sources**:: + + ./halium/devices/setup [device] + +Verification +------------ +* Verify sources downloaded correctly +* Check all repositories synced +* Ensure vendor blobs present +* Validate device tree structure + +Next Steps +---------- +* :doc:`build` - Building system images +* :doc:`../standalone-kernel/device-config` - Device configuration \ No newline at end of file diff --git a/porting/modern-porting/index.rst b/porting/modern-porting/index.rst new file mode 100644 index 000000000..bd475ca67 --- /dev/null +++ b/porting/modern-porting/index.rst @@ -0,0 +1,163 @@ +.. _modern-methods: + +Modern Porting Methods +====================== + +This section covers the available methods for porting Ubuntu Touch to modern devices. The choice of method depends on your device's characteristics and hardware support. + +Method Selection +---------------- + +.. mermaid:: + + flowchart TD + A[Start Method Selection] -->B{Android Version?} + B -->|Android 9+| C{Project Treble?} + B -->|Pre-Android 9| D[Full System Method] + C -->|Yes| E{GKI Device?} + C -->|No| D + E -->|Yes| F[Standalone Kernel + GSI] + E -->|No| G{Hardware Compatible?} + G -->|Works with GSI| F + G -->|Needs Customization| D + + style F fill:#90EE90 + style D fill:#FFB6C1 + +Available Methods +----------------- + +Standalone Kernel Method +^^^^^^^^^^^^^^^^^^^^^^^^ +Best suited for: + +* Android 9+ devices +* Treble-compliant hardware +* GKI compatibility +* Available kernel source + +This method: + +* Uses pre-built system components +* Focuses on kernel and configuration +* Reduces build complexity +* Provides faster iteration + +Full System Build Method +^^^^^^^^^^^^^^^^^^^^^^^^ +Required for: + +* Pre-Android 9 devices +* Non-Treble hardware +* Custom Android modifications +* Specific hardware requirements + +This method: + +* Builds complete system image +* Provides maximum customization +* Requires more resources +* Takes longer to implement + +GSI-Based Method +^^^^^^^^^^^^^^^^ +Suitable for: + +* Treble-compliant devices +* Standard HAL implementations +* Modern hardware support +* Project Treble compatibility + +This method: + +* Uses generic system image +* Simplifies system integration +* Reduces maintenance +* Enables faster updates + +Method Comparison +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + + * - Method + - Advantages + - Requirements + * - Standalone Kernel + - | - Simpler process + | - Faster builds + | - Easier updates + - | - Android 9+ + | - Kernel source + | - Treble support + * - Full System + - | - Maximum control + | - Custom modifications + | - Legacy support + - | - Complete device tree + | - All source code + | - Build environment + * - GSI-Based + - | - Standard base + | - Quick deployment + | - Easy maintenance + - | - Treble compliance + | - Vendor partition + | - HAL compatibility + +Selection Criteria +------------------ + +1. **Device Assessment** + + * Android version + * Hardware architecture + * Available source code + * Vendor support + +2. **Technical Requirements** + + * Build environment needs + * Development time + * Maintenance considerations + * Update requirements + +3. **Hardware Support** + + * HAL compatibility + * Driver availability + * Vendor blob support + * Hardware features + +Implementation Paths +-------------------- + +.. toctree:: + :maxdepth: 2 + :name: modern-porting + + standalone-kernel/index + full-system/index + special-cases/index + system-updates/index + +Prerequisites +------------- +Before starting: + +* Complete environment setup +* Gather device information +* Check hardware compatibility +* Verify source availability + +Next Steps +---------- +Choose your implementation path based on your device's characteristics and proceed to the corresponding section. + +See Also +-------- +* :doc:`../resources/deviceinfo-reference` +* :doc:`../debugging/index` +* :doc:`../vendor-specific/index` \ No newline at end of file diff --git a/porting/modern-porting/special-cases/gki-devices.rst b/porting/modern-porting/special-cases/gki-devices.rst new file mode 100644 index 000000000..6d8663747 --- /dev/null +++ b/porting/modern-porting/special-cases/gki-devices.rst @@ -0,0 +1,217 @@ +.. _gki-devices: + +GKI Device Support +================== + +Quick Reference +--------------- +:: + + # Essential GKI configuration + deviceinfo_bootimg_header_version="4" + deviceinfo_kernel_llvm_compile="true" + deviceinfo_vendor_bootconfig_path="bootconfig" + deviceinfo_ramdisk_compression="lz4" + deviceinfo_bootimg_has_init_boot="true" + +Understanding GKI +----------------- +Generic Kernel Image (GKI) represents a significant change in how Android handles device kernels. Instead of each device having a completely customized kernel, GKI provides: + +* A standardized core kernel +* Vendor-specific modules +* Strict hardware abstraction +* Unified update path + +Think of GKI like a standard engine (core kernel) that can be customized with different parts (modules) for different vehicles (devices). + +Key Components +-------------- + +1. **Core Kernel** + + The standard GKI kernel provides: + * Basic system functionality + * Common driver frameworks + * Standard interfaces + * Security features + +2. **Vendor Modules** + + Device-specific code exists as modules:: + + # Common module locations + /vendor/lib/modules/ + /vendor/lib64/modules/ + + # Module configuration + /vendor/etc/modules.load + +3. **Boot Components** + + GKI devices use a split boot configuration: + * boot.img - Core kernel + * vendor_boot.img - Device-specific code + * init_boot.img - Early initialization + +Build Requirements +------------------ + +1. **Compiler Setup**:: + + deviceinfo_kernel_llvm_compile="true" # Use LLVM toolchain + deviceinfo_bootimg_header_version="4" # Modern header version + +2. **Boot Configuration**:: + + deviceinfo_vendor_bootconfig_path="bootconfig" # Vendor boot config + deviceinfo_bootimg_has_init_boot="true" # Enable init_boot + deviceinfo_ramdisk_compression="lz4" # Modern compression + +3. **Module Handling**:: + + # Modules in vendor_ramdisk-overlay + vendor-ramdisk-overlay/lib/modules/ + ├── modules.load # Load sequence + ├── modules.dep # Dependencies + └── kernel-modules/ # Actual modules + +Common Challenges +----------------- + +1. **Module Integration** + + Issues: + + * Missing dependencies + * Load order problems + * Version mismatches + + Solutions: + + * Check module dependencies + * Verify load sequence + * Match kernel versions + +2. **Boot Process** + + Challenges: + + * Split boot image handling + * Vendor boot configuration + * Init sequence timing + + Approach: + + * Verify bootloader support + * Check partition layout + * Monitor boot sequence + +3. **Hardware Support** + + Common problems: + + * Driver compatibility + * Module initialization + * Hardware detection + + Solutions: + + * Use vendor modules when possible + * Check hardware initialization + * Monitor driver loading + +Debugging Tips +-------------- + +1. **Boot Issues**:: + + # Check kernel logs + dmesg | grep -i "module" + + # Monitor module loading + journalctl -b | grep modprobe + + # View vendor boot status + cat /proc/cmdline + +2. **Module Problems**:: + + # List loaded modules + lsmod + + # Check module details + modinfo module_name + + # View loading errors + dmesg | grep -i "module" + +3. **Hardware Detection**:: + + # Check device nodes + ls /dev + + # View hardware status + lspci -v + + # Monitor udev events + udevadm monitor + +Best Practices +-------------- + +1. **Build Process** + + * Use LLVM/Clang toolchain + * Keep modules separate + * Maintain clean configuration + +2. **Module Management** + + * Document dependencies + * Test load sequences + * Monitor performance + +3. **Testing** + + * Verify boot sequence + * Check hardware support + * Monitor resource usage + +Example Configuration +--------------------- + +Full GKI device setup:: + + # Basic device info + deviceinfo_name="Pixel 6" + deviceinfo_manufacturer="Google" + deviceinfo_codename="raven" + deviceinfo_arch="aarch64" + + # GKI configuration + deviceinfo_bootimg_header_version="4" + deviceinfo_kernel_llvm_compile="true" + deviceinfo_vendor_bootconfig_path="bootconfig" + deviceinfo_bootimg_has_init_boot="true" + deviceinfo_ramdisk_compression="lz4" + + # Kernel specifics + deviceinfo_kernel_source="https://github.com/kernel/common" + deviceinfo_kernel_source_branch="android13-5.10" + deviceinfo_kernel_defconfig="gki_defconfig" + +Next Steps +---------- + +**Need hardware debugging?** + → :doc:`../../debugging/hardware-debug/index` + +**Build issues?** + → :doc:`../../debugging/troubleshooting/system-issues` + +See Also +-------- +* :ref:`build-systems` - Build system details +* :ref:`hardware-abstraction` - HAL integration +* :doc:`../../debugging/index` - Debugging guide \ No newline at end of file diff --git a/porting/modern-porting/special-cases/index.rst b/porting/modern-porting/special-cases/index.rst new file mode 100644 index 000000000..d886ff282 --- /dev/null +++ b/porting/modern-porting/special-cases/index.rst @@ -0,0 +1,14 @@ +Special Device Cases +==================== + +This section will cover special device categories requiring additional handling: + +- GKI (Generic Kernel Image) devices +- Devices with dynamic partitions +- A/B partition scheme devices +- Other special hardware configurations + +.. toctree:: + :maxdepth: 2 + + gki-devices \ No newline at end of file diff --git a/porting/modern-porting/standalone-kernel/device-config.rst b/porting/modern-porting/standalone-kernel/device-config.rst new file mode 100644 index 000000000..cddd59f83 --- /dev/null +++ b/porting/modern-porting/standalone-kernel/device-config.rst @@ -0,0 +1,170 @@ +.. _device-config: + +Device Configuration +==================== + +[Previous Quick Reference and Understanding deviceinfo sections remain unchanged] + +Essential Configuration +----------------------- +[Previous Basic port initialization section remains unchanged through boot configuration] + +Kernel Configuration +-------------------- +The kernel is the core of your device's operating system. It needs specific configuration to work with Ubuntu Touch. + +Basic Build Options +^^^^^^^^^^^^^^^^^^^ +Configure how your kernel should be built:: + + # Standard compilation + deviceinfo_kernel_clang_compile="true" # Use modern Clang compiler + deviceinfo_kernel_llvm_compile="true" # Use complete LLVM toolchain + +Toolchain Selection +^^^^^^^^^^^^^^^^^^^ +The build system selects toolchains in this priority order: + +1. Custom GCC toolchain (if specified) +2. LLVM/Clang (if enabled) +3. Default Android GCC toolchain + +Basic Selection:: + + deviceinfo_kernel_clang_compile="true" # Use Clang instead of GCC + deviceinfo_kernel_llvm_compile="true" # Use complete LLVM toolchain + +Custom GCC Toolchain:: + + deviceinfo_kernel_gcc_toolchain_source="https://releases.linaro.org/path/to/toolchain.tar.xz" + deviceinfo_kernel_gcc_toolchain_dir="gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu" + +.. note:: + Modern Android devices typically require Clang compilation. Only use custom GCC + toolchains when specifically required by your device. + +For GKI devices, additional settings are needed:: + + deviceinfo_bootimg_header_version="4" # Modern GKI header + deviceinfo_kernel_llvm_compile="true" # Required for GKI + deviceinfo_vendor_bootconfig_path="bootconfig" # Vendor boot config + deviceinfo_ramdisk_compression="lz4" # Modern compression + +Flash Layout Configuration +-------------------------- +[Previous Flash Layout section remains unchanged] + +Advanced Configuration +---------------------- + +Device Tree Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^ +[Previous Device Tree Configuration section remains unchanged] + +Vendor Ramdisk Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +For GKI devices, kernel modules are handled through vendor_ramdisk-overlay:: + + # Directory structure + vendor-ramdisk-overlay/ + ├── lib/ + │ └── modules/ + │ ├── modules.load # Module load sequence + │ ├── modules.dep # Module dependencies + │ └── kernel-modules/ # Actual module files + +The modules.load file specifies the loading sequence:: + + # modules.load example + kernel/drivers/misc/foo.ko + kernel/net/bar.ko + kernel/drivers/baz.ko + +Dependencies are automatically calculated and included in modules.dep. + +Boot Image Configuration +^^^^^^^^^^^^^^^^^^^^^^^^ +Advanced boot image settings for modern devices:: + + # Basic boot image settings + deviceinfo_bootimg_header_version="2" # See version table + deviceinfo_bootimg_os_version="11.0.0" # OS version in header + deviceinfo_bootimg_os_patch_level="2024-01" # Security patch level + + # Verified Boot settings + deviceinfo_bootimg_append_vbmeta="true" # Include vbmeta in boot image + deviceinfo_bootimg_partition_size="67108864" # Boot partition size + + # Special device requirements + deviceinfo_bootimg_board="SRPUK23A007" # Device-specific board name + deviceinfo_bootimg_tailtype="SEAndroid" # Custom tail format + +For devices using Verified Boot: + +1. vbmeta.img will be automatically downloaded and appended if needed +2. Partition size must match device specifications exactly +3. Board name must match device expectations + +Storage Configuration +^^^^^^^^^^^^^^^^^^^^^ +[Previous Storage Configuration section remains unchanged] + +Example Configurations +---------------------- +[Previous example configurations section remains unchanged, +but add these examples for GKI and Verified Boot devices:] + +GKI Device with Verified Boot:: + + deviceinfo_bootimg_header_version="4" + deviceinfo_kernel_llvm_compile="true" + deviceinfo_use_overlaystore="true" + deviceinfo_vendor_bootconfig_path="bootconfig" + deviceinfo_ramdisk_compression="lz4" + deviceinfo_bootimg_has_init_boot="true" + deviceinfo_bootimg_append_vbmeta="true" + deviceinfo_bootimg_partition_size="67108864" + +Troubleshooting +--------------- + +Common Issues: + +1. **Boot loops**: + + * Check header version matches Android version + * Verify cmdline includes console=tty0 + * Confirm flash offsets are correct + +2. **Flash fails**: + + * Verify flash offsets and pagesize + * Check partition sizes match device + * Confirm bootloader accepts images + +3. **No display**: + + * Ensure console=tty0 in cmdline + * Check DTB configuration + * Verify display driver enabled in kernel + +4. **Init fails**: + + * Check systempart parameter + * Verify ramdisk compression + * Confirm init_boot configuration (if GKI) + +Next Steps +---------- + +**Configuration complete?** + → :doc:`kernel-build` + +**Need hardware details?** + → :ref:`hardware-abstraction` + +See Also +-------- +* :ref:`build-systems` - Build process details +* :doc:`../../vendor-specific/index` - Vendor-specific requirements +* :doc:`../../resources/deviceinfo-reference` - Complete parameter reference \ No newline at end of file diff --git a/porting/modern-porting/standalone-kernel/first-boot.rst b/porting/modern-porting/standalone-kernel/first-boot.rst new file mode 100644 index 000000000..c3e11e2fe --- /dev/null +++ b/porting/modern-porting/standalone-kernel/first-boot.rst @@ -0,0 +1,193 @@ +.. _first-boot: + +Installation and First Boot Process +=================================== + +Installation +------------ + +Flash Images +^^^^^^^^^^^^ + +Standard devices: + +.. code-block:: bash + + fastboot flash boot boot.img + fastboot flash system system.img + +Dynamic partition devices: + +.. code-block:: bash + + fastboot reboot fastboot + fastboot flash boot boot.img + fastboot flash system system.img + +.. note:: + GKI devices may require flashing additional partitions: + + * init_boot.img (if deviceinfo_bootimg_has_init_boot="true") + * vendor_boot.img (for devices using separate vendor boot) + * dtbo.img (if device uses overlays) + +Initial Boot Behavior +--------------------- + +Common Scenarios +^^^^^^^^^^^^^^^^ + +1. **Successful Boot** + + * Device appears unresponsive but has booted + * No display output + * Network interface available + * SSH/telnet possible + +2. **Boot Loop** + + * Device repeatedly restarts + * May show vendor logo + * No network interface + * Debug through fastboot/recovery + +3. **Stuck at Logo** + + * Frozen at bootloader/vendor logo + * May indicate kernel panic + * Check kernel logs via recovery + +4. **Black Screen** + + * Display not initialized + * System may be running + * Try SSH/telnet connection + +Verifying Boot Status +--------------------- + +1. **Check Network Interface** + + * Connect device via USB + * On host:: + + dmesg -w + # Look for "GNU/Linux device" or "rndis" interface + +.. note:: + After flashing, wait at least 2-3 minutes before checking network interfaces. + Initial boot may take longer than subsequent boots. + +2. **SSH Access** + + * If network interface appears:: + + # Setup host network + ip link set address 02:11:22:33:44:55 + ip address add 10.15.19.100/24 dev + ip link set up + + # Connect to device + ssh phablet@10.15.19.82 + # Password is same as set during installation + +3. **Telnet Access** + + * If SSH fails but device boots:: + + telnet 192.168.2.15 + +Boot Debugging +-------------- + +1. **Initial Checks**:: + + # Check system status + systemctl status + + # View kernel logs + dmesg + + # Check Android container + lxc-info -n android + + # View system logs + journalctl -b + + # For GKI devices, also check + dmesg | grep -i vendor # Vendor boot issues + dmesg | grep -i init_boot # Init boot issues + dmesg | grep -i modload # Module loading + +2. **Common Issues** + + * Missing kernel configs + * Incorrect Android container setup + * Device tree mismatches + * Missing firmware/drivers + +3. **Recovery Access** + + * Boot to recovery if available + * Pull logs and kernel messages + * Check partition status + + # Common log locations + /proc/last_kmsg # Last kernel log + /cache/recovery/log # Recovery log + /data/android-logs/* # Android container logs + +Configuring udev Rules +---------------------- + +After verifying basic boot and establishing connection, udev rules must be configured for hardware access. + +1. **Make Root Writable**:: + + sudo mount -o remount,rw / + +2. **Generate Rules** + + Different devices store ueventd rules in various locations. Try these commands in order until one succeeds:: + + # For most devices + sudo cat /var/lib/lxc/android/rootfs/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//' > /usr/lib/lxc-android-config/70-$DEVICE.rules + + # If above fails, try vendor location + sudo cat /var/lib/lxc/android/rootfs/vendor/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//' > /usr/lib/lxc-android-config/70-$DEVICE.rules + + # For some devices, try both locations + sudo cat /var/lib/lxc/android/rootfs/ueventd*.rc /vendor/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//' > /usr/lib/lxc-android-config/70-$DEVICE.rules + +3. **Verify Rules**:: + + cat /usr/lib/lxc-android-config/70-$DEVICE.rules + # Should contain multiple lines of udev rules + + # Example of expected udev rules + ACTION=="add", KERNEL=="graphics*", OWNER="system", GROUP="graphics", MODE="0660" + ACTION=="add", KERNEL=="input*", OWNER="system", GROUP="input", MODE="0660" + +4. **Reboot**:: + + sudo reboot + +After reboot, you should see the Ubuntu Touch spinner. If not, proceed to display configuration. + +Next Steps +---------- + +* :ref:`display` - Display setup +* :ref:`apparmor` - Security configuration + +.. note:: + A seemingly unresponsive device may have booted successfully. Always check for SSH/telnet access before assuming boot failure. \ No newline at end of file diff --git a/porting/modern-porting/standalone-kernel/index.rst b/porting/modern-porting/standalone-kernel/index.rst new file mode 100644 index 000000000..dff5c8758 --- /dev/null +++ b/porting/modern-porting/standalone-kernel/index.rst @@ -0,0 +1,30 @@ +Standalone Kernel Method +======================== + +The standalone kernel method is the primary approach for modern Ubuntu Touch ports. This method focuses on building just the device kernel, while using pre-built system images and rootfs from UBports. + +Quick Reference +--------------- + +1. Configure deviceinfo +2. Build kernel only (-k flag) +3. Full build after kernel success +4. First boot verification + +Detailed Steps +-------------- + +.. toctree:: + :maxdepth: 2 + + device-config + kernel-build + first-boot + +Prerequisites +------------- + +- Device kernel source code +- Build environment (Python 3.6+, build tools) +- Unlocked bootloader +- ARM64 architecture (preferred) \ No newline at end of file diff --git a/porting/modern-porting/standalone-kernel/kernel-build.rst b/porting/modern-porting/standalone-kernel/kernel-build.rst new file mode 100644 index 000000000..da7c8e6dc --- /dev/null +++ b/porting/modern-porting/standalone-kernel/kernel-build.rst @@ -0,0 +1,160 @@ +Building the Kernel +=================== + +Initial Kernel Build +-------------------- + +Start with a kernel-only build to identify and resolve issues early. The build command varies based on your device type: + +Standard Devices:: + + ./build.sh -k -b workdir + +GKI Devices:: + + export LLVM=1 LLVM_IAS=1 + ./build.sh -k -b workdir + +This builds just the kernel without generating boot or system images. + +Understanding the Build Process +------------------------------- + +The build system follows this sequence: + +1. Sets up build environment and tools +2. Configures compiler toolchain based on device type +3. Builds kernel and modules +4. Processes device tree files +5. Prepares boot image components + +Kernel Configuration +-------------------- + +Required Options +^^^^^^^^^^^^^^^^ +Add to halium.config in arch//configs/: + +.. code-block:: none + + CONFIG_DEVTMPFS=y + CONFIG_FHANDLE=y + CONFIG_SYSVIPC=y + CONFIG_IPC_NS=y + CONFIG_NET_NS=y + CONFIG_PID_NS=y + CONFIG_USER_NS=y + CONFIG_UTS_NS=y + CONFIG_VT=y + +Build Environment Variables +--------------------------- + +Modern devices may require specific compiler settings: + +Standard Devices:: + + export ARCH=arm64 # For ARM64 devices + export CROSS_COMPILE=aarch64-linux-android- + +GKI Devices:: + + export LLVM=1 # Use LLVM compiler + export LLVM_IAS=1 # Use LLVM integrated assembler + export CROSS_COMPILE=aarch64-linux-gnu- # For ARM64 devices + +.. note:: + These variables are automatically set based on your deviceinfo configuration. Manual setting is only needed if you encounter toolchain-related issues. + +Module Handling +--------------- + +Standard Module Installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Modules are installed to the system image unless disabled:: + + deviceinfo_kernel_disable_modules="true" # Skip module installation + +For GKI devices, modules go into vendor_ramdisk-overlay:: + + vendor-ramdisk-overlay/ + ├── lib/modules/ + │ ├── modules.load # Load sequence + │ ├── modules.dep # Dependencies + │ └── *.ko # Module files + +Build Flash Artifacts +--------------------- + +After successful kernel build: + +.. code-block:: bash + + # Build kernel and create artifacts + ./build.sh -b workdir + + # Prepare system image + ./build/prepare-fake-ota.sh out/device_${DEVICE}.tar.xz ota + + # Create final images + ./build/system-image-from-ota.sh ota/ubuntu_command images + +This creates: + +- boot.img +- system.img +- rootfs.img +- vendor_boot.img (if needed) +- dtbo.img (if specified in deviceinfo) + +Common Issues +------------- + +1. **Build Environment** + + - Missing toolchain (automatically downloaded) + - Config option conflicts + - Architecture mismatch + +2. **Module Problems** + + - Missing kernel configs + - Wrong module path + - Dependency issues + - Strip errors + +3. **Output Issues** + + - Incorrect kernel image name + - Build directory permissions + - Insufficient resources + +Debugging Tips +-------------- + +Monitor Build Progress:: + + # Watch compilation + make O="$OUT" V=1 + + # Check for errors + make O="$OUT" 2>&1 | tee build.log + + # Verify toolchain + ${CROSS_COMPILE}gcc --version # For standard devices + clang --version # For GKI devices + +Next Steps +---------- + +**Kernel built successfully?** + → :doc:`first-boot` + +**Build problems?** + → :doc:`../../debugging/troubleshooting/system-issues` + +See Also +-------- +* :ref:`build-systems` - Build process details +* :doc:`device-config` - Device configuration +* :doc:`../../debugging/index` - Debugging guide \ No newline at end of file diff --git a/porting/modern-porting/system-updates/index.rst b/porting/modern-porting/system-updates/index.rst new file mode 100644 index 000000000..f7f36159e --- /dev/null +++ b/porting/modern-porting/system-updates/index.rst @@ -0,0 +1,412 @@ +System Base Transitions +======================= + +This guide helps you adapt your Ubuntu Touch port when moving to a newer Ubuntu base system. While most examples reference the transition from Ubuntu 16.04 (xenial) to Ubuntu 20.04 (focal), the concepts and methods described here will help you understand and handle future system updates as well. + +Understanding System Transitions +-------------------------------- + +What is a System Base Transition? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Think of Ubuntu Touch as a house built on a foundation. The foundation is the Ubuntu base system - the core operating system components that everything else relies on. When we update this foundation (for example, moving from Ubuntu 16.04 to 20.04), we need to make sure everything above it still works correctly. + +These transitions happen because: + +* Security updates are needed +* New features become available +* Old software becomes unsupported +* Performance improvements are possible + +Core Changes During Transitions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +When the base system changes, several key areas typically need attention: + +1. **Init System Management** + The init system is like the conductor of an orchestra - it starts and manages all system services in the right order. Different Ubuntu versions might use different init systems or configurations. + + Example: + + .. code-block:: bash + + # Old way (Ubuntu 16.04): + start on started lightdm + + # New way (Ubuntu 20.04): + [Unit] + After=graphical.target + +2. **Hardware Support** + Hardware support involves multiple layers: + + * Kernel drivers - Talk directly to hardware + * HAL (Hardware Abstraction Layer) - Provides standard interfaces + * System services - Manage hardware features + + These layers might change between versions: + + .. code-block:: bash + + # Old way (16.04): + /etc/init/mount-android.conf + + # New way (20.04): + /etc/systemd/system/mount-android.service + +3. **System Services** + Services handle specific tasks like: + + * USB connections + * Power management + * Network connectivity + * Display handling + + Each might need updates for the new system. + +Common Transition Patterns +^^^^^^^^^^^^^^^^^^^^^^^^^^ +Most system transitions follow similar patterns. Understanding these helps you prepare for future updates: + +1. **Configuration Changes** + + * Files move to new locations + * Formats change + * New options become available + * Old options become deprecated + + Example from USB management: + + .. code-block:: bash + + # Old way (16.04): + # Custom script in /usr/sbin/mount-android.sh + + # New way (20.04): + # Configuration in /etc/default/usb-moded.d/ + IDVENDOR=0E8D + IDPRODUCT_MTP=2008 + +Practical Example: 16.04 to 20.04 +--------------------------------- + +Let's look at the 16.04 to 20.04 transition as a real-world example. This helps understand what actually changes during a system transition and how to handle it. + +Service Changes +^^^^^^^^^^^^^^^ +Services are programs that run in the background, handling tasks like USB connections, power management, and hardware control. The 16.04 to 20.04 transition brought several major service changes: + +1. **USB Management** + + Old System (16.04): + + .. code-block:: bash + + # Custom script approach + if [ -f /usr/sbin/setupusb ]; then + /usr/sbin/setupusb + fi + + New System (20.04): + + .. code-block:: bash + + # Managed by usb-moded daemon + # /etc/default/usb-moded.d/device-specific-config.conf + IDVENDOR=0E8D + IDPRODUCT_MTP=2008 + IDPRODUCT_RNDIS=2004 + + Why the change? + + * More reliable USB state management + * Standard way to handle USB modes + * Better support for different devices + * Easier updates and maintenance + + How to adapt: + + 1. Remove old USB setup scripts + 2. Create usb-moded configuration + 3. Test each USB mode (MTP, adb, rndis) + 4. Verify USB behavior after sleep/resume + +2. **Device Configuration** + + Old System (16.04): + + .. code-block:: bash + + # Scattered configuration files + /etc/ubuntu-touch-session.d/android.conf + /etc/init/mount-android.conf + /etc/udev/rules.d/70-android.rules + + New System (20.04): + + .. code-block:: bash + + # /etc/deviceinfo/devices/[device].yaml + codename: + GridUnit: 18 + DeviceType: phone + BacklightSysfsPath: /sys/class/backlight/panel0-backlight + + Why the change? + + * All device settings in one place + * Easier to maintain and update + * Better organization + * Cleaner system structure + + How to adapt: + + 1. List all your current device configurations + 2. Create new deviceinfo YAML file + 3. Move settings to new format + 4. Test each configured feature + +Hardware Adaptation +^^^^^^^^^^^^^^^^^^^ +Hardware support requires special attention during transitions because it affects basic device functionality. + +1. **Overlay System** + + The overlay system lets you modify system files without changing the base system. + + Old System (16.04): + + .. code-block:: bash + + # Direct file replacement + /system/etc/file.conf replaced directly + + New System (20.04): + + .. code-block:: bash + + # Overlay store + /opt/halium-overlay/etc/file.conf + deviceinfo_use_overlaystore="true" + + Why the change? + + * Safer system updates + * Cleaner organization + * Better maintainability + * Easier troubleshooting + + How to adapt: + + 1. Move overlay files to new location + 2. Enable overlay store in deviceinfo + 3. Test file overlays + 4. Verify after system updates + +2. **Media Stack** + + Media handling affects camera, video, and audio functionality. + + Old System (16.04): + + .. code-block:: bash + + + video/x-raw-yuv + + New System (20.04):: + + video/x-raw + + Why the change? + + * Modern media formats + * Better performance + * New features + * Hardware acceleration + + How to adapt: + + 1. Update media profiles + 2. Check codec support + 3. Test camera functionality + 4. Verify video playback + +Practical Transition Steps +-------------------------- + +Before You Start +^^^^^^^^^^^^^^^^ +Good preparation makes transitions much easier: + +1. **Document Current State** + Create a detailed record of your current port: + + .. code-block:: bash + + # List custom files + find /etc -type f -mtime -30 + + # Save configurations + cp -r /etc/ubuntu-touch-session.d/ backup/ + cp -r /etc/init/ backup/ + + # Note hardware status + lsmod > modules.txt + dmesg > dmesg.txt + +2. **Test Environment** + Set up a safe testing environment: + + * Use a spare device if possible + * Back up all custom files + * Document current working state + * Prepare recovery options + +Step-by-Step Process +^^^^^^^^^^^^^^^^^^^^ +Follow these steps to transition your port: + +1. **Update Core Services** + Start with basic system functionality: + + .. code-block:: bash + + # Check current services + systemctl list-unit-files + + # Convert init scripts + # Old (16.04): + start on started lightdm + exec /usr/bin/myservice + + # New (20.04): + [Unit] + After=graphical.target + + [Service] + ExecStart=/usr/bin/myservice + +2. **Update Hardware Support** + + Ensure hardware features work: + + .. code-block:: bash + + # Check hardware status + udevadm monitor + + # Test basic features + echo 100 > /sys/class/backlight/*/brightness + + # Verify sensors + systemctl status sensorfwd + +3. **Configure System Integration** + Connect all components:: + # Update device settings + vim /etc/deviceinfo/devices/mydevice.yaml + + # Test integration + systemctl status android-mount + systemctl status lxc@android + +Common Problems and Solutions +----------------------------- + +1. **Service Failures** + + Problem: Services don't start properly: + + .. code-block:: bash + + systemctl status myservice + ● myservice.service - My Important Service + Loaded: loaded + Active: failed + + Solutions: + + * Check service dependencies + * Verify file permissions + * Look for missing files + * Review service logs + +2. **Hardware Issues** + + Problem: Hardware feature stops working: + + .. code-block:: bash + + dmesg | grep -i error + [ 3.245] Hardware XYZ: initialization failed + + Solutions: + + * Check kernel configuration + * Verify device permissions + * Update udev rules + * Test with previous version + +Testing Your Changes +-------------------- + +1. **Systematic Testing** + + Create a checklist: + + - [ ] Basic boot + - [ ] Display/touch + - [ ] Network (WiFi/Mobile) + - [ ] Sound + - [ ] Camera + - [ ] Sensors + - [ ] USB modes + +2. **Performance Testing** + + Monitor system health: + + .. code-block:: bash + + # Check boot time + systemd-analyze + + # Monitor resources + top -b -n 1 + + # Test storage + iostat -x 1 + +Future-Proofing Your Port +------------------------- + +Make future transitions easier: + +1. **Clean Organization** + + * Keep all custom files in one place + * Document all changes + * Use standard methods where possible + * Follow system conventions + +2. **Good Documentation** + + * Write clear notes + * Explain why changes were made + * Keep a changelog + * Share knowledge with others + +Getting Help +------------ + +Don't hesitate to ask for help: + +* UBports Forum: forums.ubports.com +* Telegram: @ubports_porting +* Documentation: docs.ubports.com +* Issue tracker: gitlab.com/ubports + +Next Steps +---------- +* :doc:`../../debugging/index` - Detailed debugging guide +* :doc:`../../finalize/index` - Finalizing your port +* :doc:`../../vendor-specific/index` - Vendor-specific details \ No newline at end of file diff --git a/porting/preparation/device-selection/index.rst b/porting/preparation/device-selection/index.rst new file mode 100644 index 000000000..cf41c93fe --- /dev/null +++ b/porting/preparation/device-selection/index.rst @@ -0,0 +1,114 @@ +Device Selection +================ + +This guide helps you evaluate and select a suitable device for porting Halium. Proper device selection is crucial for a successful port. + +Quick Reference +--------------- + +* Check kernel source availability +* Verify bootloader can be unlocked +* Confirm device has >= 2GB RAM, 16GB storage +* Check for existing LineageOS support +* Verify vendor blob availability + +Detailed Requirements +--------------------- + +Hardware Requirements +^^^^^^^^^^^^^^^^^^^^^ +* **RAM**: Minimum 2GB, 3GB+ recommended +* **Storage**: Minimum 16GB internal storage +* **CPU**: ARM64 (aarch64) or ARM (armhf) architecture +* **Bootloader**: Must be unlockable +* **Hardware Features**: Working basic functions (display, touch, storage) + +Software/Source Availability +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Essential requirements: + +* **Kernel Source**: Must be available, preferably through: + + - Device manufacturer's repository + - LineageOS repositories + - Independent developer releases +* **Vendor Blobs**: Required for hardware functionality +* **Device Tree**: Android device configuration +* **Proprietary Files**: Hardware-specific binary blobs + +Recommended sources: + +* Official LineageOS support +* Active XDA-Developers forum presence +* Manufacturer kernel release compliance + +Compatibility Assessment +^^^^^^^^^^^^^^^^^^^^^^^^ +Check device compatibility with: + +1. **Android Version** + + * Android 9.0+ recommended for new ports + * Legacy support for 7.1 available but not recommended + +2. **Project Treble Support** + + * Treble compliance simplifies porting + * GSI compatibility indicates good hardware abstraction + * Check for vendor partition presence + +3. **Hardware Abstraction** + + * HIDL interface support + * Vendor HAL versions + * Binderized HAL availability + +Selection Criteria +------------------ + +Development Considerations +^^^^^^^^^^^^^^^^^^^^^^^^^^ +Evaluate these factors: + +1. **Community Support** + + * Active development community + * Available documentation + * Existing ports (LineageOS, postmarketOS, etc.) + +2. **Development Difficulty** + + * Manufacturer cooperation level + * Hardware complexity + * Known issues and workarounds + +3. **Testing Requirements** + + * Physical device access + * Debug capabilities + * Recovery options + +Risk Assessment +^^^^^^^^^^^^^^^ +Consider these risks: + +1. **Hardware Risks** + + * Bootloader unlocking warranty impact + * Brick recovery options + * Hardware replacement availability + +2. **Development Risks** + + * Source code quality + * Blob compatibility + * Maintenance requirements + +.. note:: + Device selection impacts the entire porting process. Taking time to properly evaluate device suitability can save significant effort later. + +See Also +-------- +* :ref:`Quick Start Guide ` - For experienced porters +* :ref:`Hardware Abstraction ` - Understanding hardware requirements +* :ref:`Build Systems ` - Build system compatibility \ No newline at end of file diff --git a/porting/preparation/environment/development-tools.rst b/porting/preparation/environment/development-tools.rst new file mode 100644 index 000000000..52dae8db2 --- /dev/null +++ b/porting/preparation/environment/development-tools.rst @@ -0,0 +1,116 @@ +.. _development-tools: + +Development Tools +================= + +Essential tools for managing and debugging the build environment and development process. + +Quick Reference +--------------- +Key tools are:: + + # Build monitoring + watch -n1 "free -h; df -h" # Monitor RAM/storage + ccache -s # Check compile cache stats + time make -j$(nproc) # Track build duration + + # Source management + repo status # Check repo tree status + git status -uno # Check local changes + + # Environment verification + printenv | grep ANDROID # Check Android env vars + which adb fastboot repo # Verify basic tools + +Build Environment Tools +----------------------- + +System Monitoring +^^^^^^^^^^^^^^^^^ +Essential tools for tracking system resources:: + + htop # Process/CPU monitoring + iotop # I/O usage monitoring + df -h # Storage usage + free -h # RAM usage + +Compilation Tools +^^^^^^^^^^^^^^^^^ +Tools for managing and debugging builds:: + + # ccache configuration + export USE_CCACHE=1 + export CCACHE_DIR=~/.ccache + ccache -M 50G + + # Build logging + make showcommands # Show compile commands + make -j$(nproc) 2>&1 | tee build.log # Log build output + +Source Management +^^^^^^^^^^^^^^^^^ +Tools for source code management:: + + # Repo tools + repo sync --force-sync # Force clean sync + repo status # Tree status + repo forall -c git clean -xfd # Clean all repos + + # Git tools + git status -uno # Local changes + git diff --cached # Staged changes + gitk # Visual history browser + +Environment Validation +---------------------- + +Dependency Checking +^^^^^^^^^^^^^^^^^^^ +Tools to verify build dependencies:: + + # Check Android build tools + python3 --version # Python version + + # Check development tools + which make gcc g++ # Basic toolchain + which adb fastboot # Android tools + which repo git # Source control + +Environment Variables +^^^^^^^^^^^^^^^^^^^^^ +Essential environment checks:: + + # Android build environment + echo $ANDROID_HOME + echo $JAVA_HOME + echo $PATH + + # Build configuration + echo $USE_CCACHE + echo $CCACHE_DIR + echo $OUT + +Storage Management +------------------ +Tools for managing build storage:: + + # Clean build files + make clean # Clean current build + make clobber # Full clean + + # Storage analysis + du -sh * # Directory sizes + ncdu # Interactive disk usage + + # Cache management + ccache -C # Clear ccache + rm -rf ~/.ccache # Remove ccache completely + +.. note:: + Regular monitoring of system resources and build progress helps identify issues early. + +See Also +-------- +* :ref:`environment-setup` - Initial environment configuration +* :ref:`build-systems` - Understanding build systems +* :ref:`android-integration` - Android build system details \ No newline at end of file diff --git a/porting/preparation/environment/index.rst b/porting/preparation/environment/index.rst new file mode 100644 index 000000000..a8c14afac --- /dev/null +++ b/porting/preparation/environment/index.rst @@ -0,0 +1,194 @@ +.. _environment-setup: + +Environment Setup +================= + +Quick Setup +----------- +The main steps for setting up the environment are as follows (with detailed explanations below):: + + # Essential packages for Ubuntu/Debian + sudo apt update && sudo apt install git gcc adb fastboot repo + python2 python3 python-is-python3 android-tools-adb android-tools-fastboot + htop iotop ccache + + # Configure git and repo + git config --global user.name "Your Name" + git config --global user.email "your@email.com" + mkdir -p ~/bin + curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo + chmod a+x ~/bin/repo + echo 'export PATH=~/bin:$PATH' >> ~/.bashrc + + # Verify installation + repo --version + adb version + fastboot --version + +System Requirements +------------------- + +Hardware Requirements +^^^^^^^^^^^^^^^^^^^^^ +Minimum specifications: + +* CPU: 4+ cores recommended +* RAM: 16GB minimum, 32GB recommended +* Storage: 100GB free space +* Internet: High-speed connection + +Recommended specifications for faster builds: + +* CPU: 8+ cores +* RAM: 32GB +* Storage: 200GB+ SSD +* Internet: 100Mbps+ + +Operating System +^^^^^^^^^^^^^^^^ +Ubuntu 22.04 LTS is recommended and best supported. While other Linux distributions can work, this guide assumes Ubuntu/Debian-based systems. + +Detailed Setup Guide +-------------------- + +1. Base Development Environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Essential build tools and libraries:: + + sudo apt install bc bison build-essential ccache curl flex g++-multilib \ + gcc-multilib git gnupg gperf imagemagick lib32ncurses5-dev \ + lib32readline-dev lib32z1-dev liblz4-tool libncurses5 libncurses5-dev \ + libsdl1.2-dev libssl-dev libxml2 libxml2-utils lzop pngcrush rsync \ + schedtool squashfs-tools xsltproc zip zlib1g-dev + +Why these packages? + +* build-essential: Basic compilation tools +* ccache: Speeds up rebuilds +* Others: Required by various build stages + +2. Python Configuration +^^^^^^^^^^^^^^^^^^^^^^^ +Both Python 2 and 3 are required for building: + +* Python 2: Required for legacy Android build tools +* Python 3: Used by newer build components + +Set up Python environment:: + + # Ensure both versions are installed + sudo apt install python2 python3 + + # Create Python 2 symlink for build scripts + sudo ln -sf /usr/bin/python2 /usr/bin/python + +.. note:: + Some build scripts explicitly require Python 2 and will fail if it's not + the default 'python' command. The symlink ensures compatibility while + maintaining Python 3 as the system default through python-is-python3. + +3. Android Development Tools +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Set up tools for device communication and source management. + +ADB and Fastboot:: + + sudo apt install android-tools-adb android-tools-fastboot + +Configure udev rules for device access:: + + sudo curl -o /etc/udev/rules.d/51-android.rules \ + https://raw.githubusercontent.com/NicolasBernaerts/ubuntu-scripts/master/android/51-android.rules + sudo chmod 644 /etc/udev/rules.d/51-android.rules + sudo udevadm control --reload-rules + +4. Source Control Setup +^^^^^^^^^^^^^^^^^^^^^^^ +Configure git with your credentials:: + + git config --global user.name "Your Name" + git config --global user.email "your.email@example.com" + +Install and configure repo tool:: + + mkdir -p ~/bin + curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo + chmod a+x ~/bin/repo + echo 'export PATH=~/bin:$PATH' >> ~/.bashrc + source ~/.bashrc + +5. Build Environment Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Set up ccache for faster rebuilds:: + + export USE_CCACHE=1 + export CCACHE_DIR=~/.ccache + export CCACHE_SIZE=50G + ccache -M 50G + +Add to ~/.bashrc for persistence:: + + echo 'export USE_CCACHE=1' >> ~/.bashrc + echo 'export CCACHE_DIR=~/.ccache' >> ~/.bashrc + +6. Storage Setup +^^^^^^^^^^^^^^^^ +Prepare build directory:: + + mkdir ~/ubports-builds + cd ~/ubports-builds + +Check available space:: + + df -h . + +Environment Verification +------------------------ +Run these checks to verify your setup:: + + # Check essential tools + git --version + repo --version + adb version + fastboot --version + gcc --version + python2 --version + python3 --version + python --version # This line verifies symlink + + # Verify build environment + echo $PATH + echo $USE_CCACHE + df -h + +Common Issues +------------- +* **Python version errors**: Build scripts may fail with syntax errors. Verify Python 2 is installed and symlinked correctly. +* **Missing dependencies**: Install additional packages as needed. +* **Storage space**: Ensure enough free space is available. +* **RAM limitations**: Build may fail on systems with less than 16GB RAM. + +Next Steps +---------- +Environment ready? Choose your path: + +**Ready to start building?** + → :doc:`../../modern-porting/standalone-kernel/index` + +**Need to understand the build system?** + → :doc:`../../fundamentals/build-systems/index` + +**Want to check device compatibility?** + → :doc:`../device-selection/index` + +See Also +-------- +* :doc:`development-tools` - Additional development tools and monitoring +* :ref:`build-systems` - Understanding build requirements +* :ref:`android-integration` - Android build system context + +.. toctree:: + :maxdepth: 1 + :hidden: + + development-tools \ No newline at end of file diff --git a/porting/preparation/index.rst b/porting/preparation/index.rst new file mode 100644 index 000000000..525158f93 --- /dev/null +++ b/porting/preparation/index.rst @@ -0,0 +1,18 @@ +.. _preparation: + +Preparation +=========== + +Before starting the porting process, adequate preparation is essential. This section covers two key areas: + +* Device selection - Evaluating and choosing a suitable device +* Environment setup - Setting up your development environment + +It is adviseable to read through this section carefully before proceeding. If you have previous experience and wish to get started quickly, see the :ref:`Quick Start Guide `. + +.. toctree:: + :maxdepth: 2 + :name: preparation-toc + + device-selection/index + environment/index \ No newline at end of file diff --git a/porting/quick-start/index.rst b/porting/quick-start/index.rst new file mode 100644 index 000000000..1336a04ca --- /dev/null +++ b/porting/quick-start/index.rst @@ -0,0 +1,125 @@ +.. _quick-start: + +Quick Start Guide +================= + +This section provides a condensed overview of the Ubuntu Touch porting process, following the standalone kernel method, and focusing on essential commands and key configuration steps. + +Essential Steps +--------------- + +1. Environment Setup +^^^^^^^^^^^^^^^^^^^^ +Basic tools and configuration: + +.. code-block:: bash + + sudo apt install git gcc adb fastboot repo python3 python-is-python3 \ + android-tools-adb android-tools-fastboot + + # Configure git and repo + git config --global user.name "Your Name" + git config --global user.email "your.email@example.com" + mkdir ~/bin + curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo + chmod a+x ~/bin/repo + +2. Device Configuration +^^^^^^^^^^^^^^^^^^^^^^^ +Create deviceinfo file with essential settings: + +.. code-block:: bash + + deviceinfo_name="Device Name" + deviceinfo_manufacturer="Brand" + deviceinfo_codename="codename" + deviceinfo_arch="aarch64" + deviceinfo_kernel_source="" + deviceinfo_kernel_source_branch="" + deviceinfo_kernel_defconfig="_defconfig" + +3. Build Process +^^^^^^^^^^^^^^^^ +Basic build commands: + +.. code-block:: bash + + # Build kernel + ./build.sh -k -b workdir + + # Full build with system image + ./build.sh -b workdir + ./build/prepare-fake-ota.sh out/device_$DEVICE.tar.xz ota + ./build/system-image-from-ota.sh ota/ubuntu_command images + +4. Installation +^^^^^^^^^^^^^^^ +Flash images to device: + +.. code-block:: bash + + # Standard method + fastboot flash boot boot.img + fastboot flash system system.img + + # Dynamic partition devices + fastboot reboot fastboot + fastboot flash boot boot.img + fastboot flash system system.img + +Key Verification Points +----------------------- + +1. **Build Verification** + + * Check image creation + * Verify file sizes + * Validate configurations + +2. **Boot Process** + + * Watch for USB network interface + * Monitor kernel messages + * Check service initialization + +3. **Hardware Detection** + + * Verify basic functionality + * Check hardware interfaces + * Monitor system logs + +Common Issues +------------- + +1. **Build Problems** + + * Missing dependencies + * Wrong configuration + * Space limitations + +2. **Boot Issues** + + * Kernel panic + * Init failures + * Service problems + +3. **Hardware Support** + + * Driver initialization + * HAL compatibility + * Vendor blob issues + +Next Steps +---------- + +For detailed information on specific topics: + +* :doc:`../debugging/index` - Troubleshooting guide +* :doc:`../debugging/hardware-debug/index` - Hardware enablement +* :doc:`../vendor-specific/index` - Vendor-specific details + +See Also +-------- +* :ref:`build-systems` - Complete build system documentation +* :ref:`hardware-abstraction` - Hardware support details +* :doc:`../resources/deviceinfo-reference` - Configuration reference \ No newline at end of file diff --git a/porting/redirects.txt b/porting/redirects.txt new file mode 100644 index 000000000..e69de29bb diff --git a/porting/resources/bibliography/android.rst b/porting/resources/bibliography/android.rst new file mode 100644 index 000000000..9de5154aa --- /dev/null +++ b/porting/resources/bibliography/android.rst @@ -0,0 +1,29 @@ +Android System Resources +======================== + +AOSP Documentation +------------------ +* `Platform Architecture Guide `_ +* `Build System Overview `_ + +Android Security +---------------- +* `Security Architecture `_ +* `Verified Boot Documentation `_ +* `SELinux for Android `_ +* `Security Patch Levels `_ +* `Android Kernel Security `_ + +Android Development +------------------- +* `Platform Development `_ +* `Android Testing Documentation `_ +* `Android Debug Tools `_ +* `Android Kernel Building `_ + +Project Treble +-------------- +* `Treble Architecture `_ +* `VINTF (Vendor Interface) `_ +* `HAL Types and Process `_ +* `Vendor Native Development Kit `_ \ No newline at end of file diff --git a/porting/resources/bibliography/community.rst b/porting/resources/bibliography/community.rst new file mode 100644 index 000000000..efb7fe4ed --- /dev/null +++ b/porting/resources/bibliography/community.rst @@ -0,0 +1,28 @@ +Community Resources +=================== + +Development Communities +----------------------- +* `UBports Forum `_ +* `LineageOS Wiki `_ +* `PostmarketOS Wiki `_ + +Support Channels +---------------- +* `UBports Porting Telegram Group `_ +* `LineageOS Device Development `_ +* `XDA Developers Forums `_ +* `UBports GitLab Issues `_ +* `Matrix Channel - UBports Porting `_ + +Development Processes +--------------------- +* `Halium Project Documentation `_ +* `Android Platform Development `_ + +Knowledge Bases +--------------- +* `Android Open Source Project `_ +* `ARM Developer Documentation `_ +* `Ubuntu Wiki `_ +* `UBports Device Documentation `_ \ No newline at end of file diff --git a/porting/resources/bibliography/debugging.rst b/porting/resources/bibliography/debugging.rst new file mode 100644 index 000000000..699330cb6 --- /dev/null +++ b/porting/resources/bibliography/debugging.rst @@ -0,0 +1,25 @@ +Debugging Resources +=================== + +Hardware Debugging +------------------ +* `Android Debug Bridge documentation `_ +* `Linux Serial Console Guide `_ + +System Analysis +--------------- +* `Linux perf documentation `_ +* `Systemd Journal Documentation `_ +* `Linux ftrace guide `_ +* `Memory Debugging with valgrind `_ + +Development Tools +----------------- +* `Git Version Control `_ +* `GitLab CI Documentation `_ +* `Linux Kernel Building Guide `_ + +Common Issues +------------- +* `Linux Driver Debugging `_ +* `SELinux Troubleshooting `_ \ No newline at end of file diff --git a/porting/resources/bibliography/hardware.rst b/porting/resources/bibliography/hardware.rst new file mode 100644 index 000000000..5ae6e5704 --- /dev/null +++ b/porting/resources/bibliography/hardware.rst @@ -0,0 +1,39 @@ +Hardware Resources +================== + +System on Chip (SoC) Documentation +---------------------------------- +* `Qualcomm Developer Network `_ +* `ARM Developer Documentation `_ +* `Samsung Developer Information `_ +* `Intel Open Source Documentation `_ + +Device Tree Resources +--------------------- +* `Device Tree Specification `_ +* `Device Tree Bindings `_ +* `Device Tree Usage `_ +* `Device Tree For Dummies `_ +* `Device Tree Overlays `_ + +Hardware Abstraction Layer +-------------------------- +* `Android HAL Documentation `_ +* `Android HIDL Guide `_ +* `Android AIDL Documentation `_ +* `Libhybris Documentation `_ +* `Graphics HAL Documentation `_ + +Bootloader Documentation +------------------------ +* `U-Boot Documentation `_ +* `Little Kernel Documentation `_ +* `Android Bootloader Guide `_ +* `UEFI Specification `_ + +Driver Development +------------------ +* `Linux Driver Development Guide `_ +* `USB Driver Development `_ +* `Input Device Documentation `_ +* `Display Driver Guide `_ \ No newline at end of file diff --git a/porting/resources/bibliography/linux.rst b/porting/resources/bibliography/linux.rst new file mode 100644 index 000000000..1d2106be2 --- /dev/null +++ b/porting/resources/bibliography/linux.rst @@ -0,0 +1,32 @@ +Linux System Resources +====================== + +Kernel Development +------------------ +* `Linux Kernel Documentation `_ +* `Linux Device Drivers Guide `_ +* `Kernel Build System Documentation `_ +* `Linux Kernel Newbies `_ +* `Linux Cross Reference `_ + +System Integration +------------------ +* `Systemd Documentation `_ +* `Linux Standard Base `_ +* `Freedesktop Specifications `_ +* `Linux Hardware Database `_ +* `Linux Foundation Training `_ + +Ubuntu Touch Specifics +---------------------- +* `Ubuntu Core Documentation `_ +* `Ubuntu Wiki Phone Development (deprecated) `_ +* `Mir Display Server Documentation `_ + +Container Systems +----------------- +* `LXC Documentation `_ +* `Linux Namespaces `_ +* `Cgroups Documentation `_ +* `Docker Documentation `_ +* `Container Security Guide `_ \ No newline at end of file diff --git a/porting/resources/deviceinfo-reference.rst b/porting/resources/deviceinfo-reference.rst new file mode 100644 index 000000000..e068304cc --- /dev/null +++ b/porting/resources/deviceinfo-reference.rst @@ -0,0 +1,116 @@ +Deviceinfo Configuration Quick Reference +======================================== + +This reference documents all currently available deviceinfo parameters used in the UBports build system. This list was last updated in December 2024. + +Basic Device Information +------------------------ +.. code-block:: bash + + deviceinfo_name # Human-readable device name + deviceinfo_manufacturer # Device manufacturer + deviceinfo_codename # Device codename (used in paths and filenames) + deviceinfo_arch # Architecture (aarch64, arm, x86_64) + +Kernel Configuration +-------------------- + +Source Settings +^^^^^^^^^^^^^^^ +.. code-block:: bash + + deviceinfo_kernel_source # Git repository URL + deviceinfo_kernel_source_branch # Branch to use + deviceinfo_kernel_defconfig # Kernel defconfig name and optional configs + deviceinfo_kernel_image_name # Optional custom kernel image name + deviceinfo_kernel_apply_overlay # Boolean: apply DTB overlays + deviceinfo_kernel_disable_modules # Boolean: skip module compilation + deviceinfo_dtb # List of DTB files to include + deviceinfo_dtbo # List of DTBO files to compile + +Compiler Settings +^^^^^^^^^^^^^^^^^ +.. code-block:: bash + + deviceinfo_kernel_clang_compile # Boolean: use Clang compiler + deviceinfo_kernel_llvm_compile # Boolean: use complete LLVM toolchain + deviceinfo_kernel_use_lld # Boolean: use LLD linker + deviceinfo_kernel_use_dtc_ext # Boolean: use external DTC + +Boot Configuration +------------------ + +Image Settings +^^^^^^^^^^^^^^ +.. code-block:: bash + + deviceinfo_bootimg_header_version # Boot image header version + deviceinfo_bootimg_os_version # OS version in boot image + deviceinfo_bootimg_os_patch_level # Security patch level + deviceinfo_bootimg_partition_size # Boot partition size in bytes + deviceinfo_bootimg_board # Board name in boot image + deviceinfo_bootimg_hash_footer # Boolean: append hash footer + deviceinfo_bootimg_append_vbmeta # Boolean: append vbmeta + deviceinfo_bootimg_has_init_boot # Boolean: uses separate init_boot + +Flash Layout +^^^^^^^^^^^^ +.. code-block:: bash + + deviceinfo_flash_offset_base # Base address for flash + deviceinfo_flash_offset_kernel # Kernel offset + deviceinfo_flash_offset_ramdisk # Ramdisk offset + deviceinfo_flash_offset_second # Second bootloader offset + deviceinfo_flash_offset_tags # Tags offset + deviceinfo_flash_offset_dtb # DTB offset + deviceinfo_flash_pagesize # Flash page size + +Advanced Features +----------------- + +Dynamic Partitions +^^^^^^^^^^^^^^^^^^ +.. code-block:: bash + + deviceinfo_use_overlaystore # Boolean: use overlay storage + deviceinfo_rootfs_image_sector_size # Sector size for rootfs + deviceinfo_system_partition_size # System partition size + +Recovery & Special Cases +^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: bash + + deviceinfo_has_recovery_partition # Boolean: device has recovery + deviceinfo_recovery_partition_size # Recovery partition size + deviceinfo_bootimg_tailtype # Special boot image tail type + deviceinfo_vendor_bootconfig_path # Path to vendor bootconfig + +Usage Examples +-------------- + +Standard Configuration +^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: bash + + deviceinfo_name="Google Pixel 4a" + deviceinfo_manufacturer="Google" + deviceinfo_codename="sunfish" + deviceinfo_arch="aarch64" + deviceinfo_kernel_source="https://github.com/vendor/kernel" + deviceinfo_kernel_source_branch="android12-5.4" + deviceinfo_kernel_defconfig="sunfish_defconfig halium.config" + +GKI Device Configuration +^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: bash + + deviceinfo_bootimg_header_version="4" + deviceinfo_kernel_llvm_compile="true" + deviceinfo_use_overlaystore="true" + deviceinfo_vendor_bootconfig_path="bootconfig" + +See Also +-------- +- :doc:`../modern-porting/standalone-kernel/device-config` +- :doc:`../modern-porting/special-cases/gki-devices` +- :doc:`../resources/understanding-deviceinfo` \ No newline at end of file diff --git a/porting/resources/index.rst b/porting/resources/index.rst new file mode 100644 index 000000000..ac286ba8f --- /dev/null +++ b/porting/resources/index.rst @@ -0,0 +1,17 @@ +.. _additional-resources: + +Additional Resources +==================== + +This section provides reference materials, external resources, and supplementary documentation to support your porting efforts. + +.. toctree:: + :maxdepth: 2 + + deviceinfo-reference + understanding-deviceinfo + bibliography/hardware + bibliography/android + bibliography/linux + bibliography/debugging + bibliography/community diff --git a/porting/resources/understanding-deviceinfo.rst b/porting/resources/understanding-deviceinfo.rst new file mode 100644 index 000000000..66287102f --- /dev/null +++ b/porting/resources/understanding-deviceinfo.rst @@ -0,0 +1,735 @@ +Understanding Deviceinfo Parameters +=================================== + +Introduction +------------ +The deviceinfo file is the central configuration point for your Ubuntu Touch port. It tells the build system everything it needs to know about your device and how to build for it. This guide explains each parameter in detail, helping you understand not just what to set, but why and how. + +Basic Device Information +------------------------ + +Understanding Device Identity +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Every device needs to be uniquely identified in the system. This identification serves multiple purposes: +- Ensuring correct hardware detection +- Setting up proper file paths +- Displaying device information to users +- Matching system components to your device + +These first parameters establish your device's basic identity: + +deviceinfo_name +""""""""""""""" + +.. container:: parameter-details + + **Purpose**: The full commercial name of your device as it should appear to users. + + **Format**: String in quotes + + **Example**: ``deviceinfo_name="Google Pixel 4a"`` + + **How to determine**: Use the official marketing name of your device. For variants, include relevant identifiers: + - Storage variants: "Google Pixel 4a 128GB" + - Regional variants: "OnePlus 9 (European)" + + **Common mistakes to avoid**: + - Using codenames here instead of full names + - Including unnecessary information like OS version + +deviceinfo_manufacturer +""""""""""""""""""""""" + **Purpose**: The company that manufactured your device. + + **Format**: String in quotes + + **Example**: ``deviceinfo_manufacturer="Google"`` + + **How to determine**: Use the brand name shown on: + - Device packaging + - Official website + - Regulatory labels + + **Common mistakes to avoid**: + - Using parent company names (e.g., "BBK" instead of "OnePlus") + - Including suffixes like "Inc." or "Ltd." + +deviceinfo_codename +""""""""""""""""""" + **Purpose**: The internal development name for your device. + + **Format**: String in quotes, lowercase, no spaces + + **Example**: ``deviceinfo_codename="sunfish"`` + + **How to determine**: + 1. Check your device's build.prop file + 2. Look up the device on LineageOS wiki + 3. Search kernel source repository names + + **Common mistakes to avoid**: + - Using marketing names + - Including uppercase letters + - Using variant names (e.g., "sunfish_verizon") + +Understanding Architecture +^^^^^^^^^^^^^^^^^^^^^^^^^^ +The CPU architecture determines which code can run on your device. Modern Android devices typically use either 32-bit (arm) or 64-bit (aarch64) ARM processors. + +deviceinfo_arch +""""""""""""""" + **Purpose**: Defines the CPU architecture for building system components. + + **Format**: One of: ``aarch64``, ``arm``, ``x86_64`` + + **Example**: ``deviceinfo_arch="aarch64"`` + + **How to determine**: + 1. Check your device specifications + 2. Look at the kernel architecture: + + .. code-block:: bash + + # For ARM64 devices + ls arch/arm64/boot/ + + # For 32-bit ARM devices + ls arch/arm/boot/ + + 3. Check Android build configuration + + **Common mistakes to avoid**: + - Confusing build architecture with CPU capability + - Not matching kernel architecture + - Using incorrect format (e.g., "arm64" instead of "aarch64") + +Kernel Configuration +-------------------- + +Understanding Kernel Sources +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The kernel is the core component that enables Ubuntu Touch to interact with your device's hardware. The build system needs to know where to find the kernel source code and how to compile it. + +deviceinfo_kernel_source +"""""""""""""""""""""""" + **Purpose**: Specifies the Git repository containing your device's kernel source code. + + **Format**: URL to Git repository + + **Example**: ``deviceinfo_kernel_source="https://github.com/LineageOS/android_kernel_google_sunfish"`` + + **How to determine**: + + 1. Check device manufacturer's GitHub + 2. Look for LineageOS kernel repository + 3. Search for community-maintained sources + + **Common mistakes to avoid**: + + - Using Android ROM repositories instead of kernel sources + - Using incorrect branches + - Linking to archived/outdated repositories + +deviceinfo_kernel_source_branch +""""""""""""""""""""""""""""""" + **Purpose**: Specifies which branch of the kernel source to use. + + **Format**: String matching branch name in repository + + **Example**: ``deviceinfo_kernel_source_branch="lineage-18.1"`` + + **How to determine**: + + 1. Check device's Android version: + + - Android 11 → lineage-18.1 + - Android 12 → lineage-19.1 + - Android 13 → lineage-20.0 + + 2. Look for android-[version] branches + 3. Check for specific Halium branches + + **Common mistakes to avoid**: + + - Using feature branches instead of stable branches + - Not matching Android/Halium version + - Using tags instead of branches + +Understanding Kernel Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The kernel needs specific configuration options for Ubuntu Touch compatibility. + +deviceinfo_kernel_defconfig +""""""""""""""""""""""""""" + **Purpose**: Specifies base kernel configuration and additional config files. + + **Format**: String with config names, space-separated + + **Example**: ``deviceinfo_kernel_defconfig="sunfish_defconfig halium.config"`` + + **How to determine**: + + 1. Find device defconfig in kernel source: + + .. code-block:: bash + + ls arch/arm64/configs/ # or arch/arm/configs/ + + 2. Always add halium.config for Ubuntu Touch compatibility + + **Special configurations**: + + - halium.config: Adds required Ubuntu Touch options + - Custom configs: Can be added for specific features + + **Common mistakes to avoid**: + + - Using wrong architecture path + - Forgetting halium.config + - Using invalid config names + +Understanding Compiler Options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Modern Android kernels often require specific compiler configurations. + +deviceinfo_kernel_clang_compile +""""""""""""""""""""""""""""""" + **Purpose**: Enables Clang compiler for kernel build. + + **Format**: Boolean ("true" or "false") + + **Example**: ``deviceinfo_kernel_clang_compile="true"`` + + **When to use**: + + - Required for Android 10+ kernels + - When kernel makefile specifies Clang + - For GKI kernels + +deviceinfo_kernel_llvm_compile +"""""""""""""""""""""""""""""" + **Purpose**: Enables full LLVM toolchain (includes linker). + + **Format**: Boolean ("true" or "false") + + **Example**: ``deviceinfo_kernel_llvm_compile="true"`` + + **When to use**: + - For newer GKI kernels + - When specified in kernel documentation + - Android 12+ devices typically + + **Note**: Supersedes deviceinfo_kernel_use_lld when enabled + +deviceinfo_kernel_use_lld +""""""""""""""""""""""""" + **Purpose**: Uses LLVM's LLD linker. + + **Format**: Boolean ("true" or "false") + + **Example**: ``deviceinfo_kernel_use_lld="true"`` + + **When to use**: + - When needing LLD without full LLVM + - For specific kernel optimizations + - If specified in kernel build + +Device Tree Configuration +------------------------- + +Understanding Device Trees +^^^^^^^^^^^^^^^^^^^^^^^^^^ +Device Tree Blobs (DTB) and Device Tree Overlays (DTBO) describe your device's hardware to the kernel. Getting these right is crucial for hardware support. + +deviceinfo_dtb +"""""""""""""" + **Purpose**: Specifies which Device Tree Blob(s) to include in the boot image. + + **Format**: Space-separated list of DTB files relative to kernel source + + **Example**: ``deviceinfo_dtb="mediatek/mt6765.dtb mediatek/mt6765-motorola-ginna.dtb"`` + + **How to determine**: + + 1. Check kernel source: + + .. code-block:: bash + + ls arch/arm64/boot/dts/ # or arch/arm/boot/dts/ + + 2. Look for your device's manufacturer directory + 3. Find DTB matching your device codename + + **Common mistakes to avoid**: + + - Using incorrect paths + - Wrong manufacturer directory + - Missing vendor-specific DTBs + +deviceinfo_dtbo +""""""""""""""" + **Purpose**: Specifies Device Tree Overlay files to compile. + + **Format**: Space-separated list of DTBO files + + **Example**: ``deviceinfo_dtbo="mediatek/ginna-dvt1.dtbo mediatek/ginna-evt1.dtbo"`` + + **When to use**: + + - Modern devices (Android 9+) + - When device has dynamic hardware variants + - If kernel uses overlays + +deviceinfo_kernel_apply_overlay +""""""""""""""""""""""""""""""" + **Purpose**: Enables merging of DTB and DTBO during build. + + **Format**: Boolean ("true" or "false") + + **Example**: ``deviceinfo_kernel_apply_overlay="true"`` + + **When to use**: + + - Qualcomm devices often need this + - When DTB needs runtime modifications + - If boot fails without overlay + +Boot Image Configuration +------------------------ + +Understanding Boot Images +^^^^^^^^^^^^^^^^^^^^^^^^^ +The boot image contains the kernel and initial ramdisk. Its format has evolved through Android versions. + +deviceinfo_bootimg_header_version +""""""""""""""""""""""""""""""""" + **Purpose**: Specifies the Android boot image header format. + + **Format**: Integer (0-4) + + **Example**: ``deviceinfo_bootimg_header_version="2"`` + + **How to determine**: + + - Android version correlation: + + * Version 0: Pre-Android 9 + * Version 1: Android 9 + * Version 2: Android 10 + * Version 3: Android 11 GKI + * Version 4: Android 12+ GKI + + **Common issues**: + + - Boot fails to flash + - Kernel panic during boot + - Recovery mode issues + +deviceinfo_bootimg_os_version +""""""""""""""""""""""""""""" + **Purpose**: Sets OS version in boot image header. + + **Format**: Android version (e.g., "11.0.0") + + **Example**: ``deviceinfo_bootimg_os_version="11.0.0"`` + + **When needed**: + + - Bootloader checks OS version + - Secure boot is enabled + - Version-specific features + +deviceinfo_bootimg_os_patch_level +""""""""""""""""""""""""""""""""" + **Purpose**: Sets security patch level in boot image. + + **Format**: "YYYY-MM" date string + + **Example**: ``deviceinfo_bootimg_os_patch_level="2024-01"`` + + **How to determine**: + + 1. Check your device's current Android build + 2. Use latest available patch level + 3. Match vendor image level if using stock vendor + +deviceinfo_bootimg_has_init_boot +"""""""""""""""""""""""""""""""" + **Purpose**: Indicates separate init_boot partition usage. + + **Format**: Boolean ("true" or "false") + + **Example**: ``deviceinfo_bootimg_has_init_boot="true"`` + + **When to use**: + + - GKI devices (typically) + - Android 13+ devices + - When device has init_boot partition + +Flash Layout Configuration +-------------------------- + +Understanding Flash Layouts +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Flash layout parameters define where different components are stored in the device's memory. Incorrect values can prevent booting or cause data corruption. + +deviceinfo_flash_offset_base +"""""""""""""""""""""""""""" + **Purpose**: Base address for loading kernel into memory. + + **Format**: Hexadecimal address (e.g., "0x00000000") + + **Example**: ``deviceinfo_flash_offset_base="0x00000000"`` + + **How to determine**: + + 1. Extract from stock boot.img + 2. Check kernel documentation + 3. Look in device tree files + + **Common mistakes to avoid**: + + - Using decimal instead of hex + - Omitting "0x" prefix + - Using incorrect alignment + +deviceinfo_flash_offset_kernel +"""""""""""""""""""""""""""""" + **Purpose**: Offset where kernel is loaded relative to base. + + **Format**: Hexadecimal address + + **Example**: ``deviceinfo_flash_offset_kernel="0x00008000"`` + +**Typical values**: + + - 0x00008000 (common) + - 0x00080000 (some newer devices) + - Check device trees for unusual values + +deviceinfo_flash_offset_ramdisk +""""""""""""""""""""""""""""""" + **Purpose**: Offset where initial ramdisk is loaded. + + **Format**: Hexadecimal address + + **Example**: ``deviceinfo_flash_offset_ramdisk="0x01000000"`` + + **Important considerations**: + + - Must not overlap with kernel + - Needs sufficient space for ramdisk + - Platform-specific alignment requirements + +deviceinfo_flash_offset_second +"""""""""""""""""""""""""""""" + **Purpose**: Offset for second bootloader if present. + + **Format**: Hexadecimal address + + **Example**: ``deviceinfo_flash_offset_second="0x00f00000"`` + + **When needed**: + + - Samsung devices often use this + - Some legacy devices + - Special bootloader configurations + +deviceinfo_flash_offset_tags +"""""""""""""""""""""""""""" + **Purpose**: Offset for kernel tags. + + **Format**: Hexadecimal address + + **Example**: ``deviceinfo_flash_offset_tags="0x00000100"`` + + **Common issues**: + + - Boot failures if misaligned + - Kernel panic during boot + - Device not responding to commands + +deviceinfo_flash_pagesize +""""""""""""""""""""""""" + **Purpose**: Flash memory page size of device. + + **Format**: Integer (typically power of 2) + + **Example**: ``deviceinfo_flash_pagesize="4096"`` + + **Common values**: + + - 2048 (2K pages) + - 4096 (4K pages) + - Must match device hardware + +Advanced Features +----------------- + +Understanding System Storage +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +These parameters control how Ubuntu Touch uses device storage. + +deviceinfo_use_overlaystore +""""""""""""""""""""""""""" + **Purpose**: Enables overlay-based system modifications. + + **Format**: Boolean ("true" or "false") + + **Example**: ``deviceinfo_use_overlaystore="true"`` + + **When to use**: + + - Modern ports (recommended) + - When using GSI + - For easier system updates + +deviceinfo_rootfs_image_sector_size +""""""""""""""""""""""""""""""""""" + **Purpose**: Specifies sector size for rootfs creation. + + **Format**: Integer (typically power of 2) + + **Example**: ``deviceinfo_rootfs_image_sector_size="4096"`` + + **When to set**: + + - UFS storage devices + - Newer flagship devices + - When default size causes issues + +deviceinfo_system_partition_size +"""""""""""""""""""""""""""""""" + **Purpose**: Sets the size of system partition image. + + **Format**: Size with suffix (M or G) + + **Example**: ``deviceinfo_system_partition_size="4000M"`` + + **How to determine**: + + 1. Check partition table + 2. Use adb/fastboot to query + 3. Consider system requirements: + + - Base system: ~2.5GB + - Apps and updates: ~500MB + - Safe margin: ~500MB + +Special Boot Configurations +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +deviceinfo_bootimg_board +"""""""""""""""""""""""" + **Purpose**: Sets board name in boot image header. + + **Format**: String + + **Example**: ``deviceinfo_bootimg_board="EXYNOS4412"`` + + **When needed**: + + - Samsung devices often require this + - Some MediaTek devices + - When bootloader checks board name + +Recovery Configuration +---------------------- + +Understanding Recovery Options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Recovery mode provides a way to perform system maintenance and updates. Ubuntu Touch uses a custom recovery for system updates and troubleshooting. + +deviceinfo_has_recovery_partition +""""""""""""""""""""""""""""""""" + **Purpose**: Indicates if device uses separate recovery partition. + + **Format**: Boolean ("true" or "false") + + **Example**: ``deviceinfo_has_recovery_partition="true"`` + + **When to use**: + + - Most devices need this + - Required for system updates + - When not using A/B partition scheme + + **Common configurations**: + + - Standard devices: "true" + - A/B devices: "false" + - GSI devices: varies by device + +deviceinfo_recovery_partition_size +"""""""""""""""""""""""""""""""""" + **Purpose**: Sets recovery image size limit. + + **Format**: Integer (bytes) + + **Example**: ``deviceinfo_recovery_partition_size="67108864"`` + + **How to determine**: + + 1. Check existing partition size: + + .. code-block:: bash + + fastboot getvar partition-size:recovery + + 2. Use alignment guidelines: + + - Must be multiple of flash page size + - Leave margin for headers + - Consider firmware requirements + +Vendor Integration +------------------ + +Understanding Vendor Requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Modern devices often require specific vendor configurations and bootloader interactions. + +deviceinfo_vendor_bootconfig_path +""""""""""""""""""""""""""""""""" + **Purpose**: Path to vendor bootconfig file for GKI devices. + + **Format**: Path relative to device tree root + + **Example**: ``deviceinfo_vendor_bootconfig_path="bootconfig"`` + + **When needed**: + + - GKI devices (Android 12+) + - Custom boot configurations + - Vendor-specific requirements + +deviceinfo_bootimg_tailtype +""""""""""""""""""""""""""" + **Purpose**: Specifies custom boot image tail format. + + **Format**: String identifier + + **Example**: ``deviceinfo_bootimg_tailtype="SEAndroid"`` + + **Common values**: + + - "SEAndroid": Samsung devices + - Empty: Most devices + - Vendor-specific values + +Boot Ramdisk Options +-------------------- + +Understanding Boot Ramdisk Options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The build needs to receive an instruction if a specific ramdisk compression method is to be used. + +deviceinfo_ramdisk_compression +"""""""""""""""""""""""""""""" + **Purpose**: Sets compression method for ramdisk. + + **Format**: String ("gzip" or "lz4") + + **Example**: ``deviceinfo_ramdisk_compression="lz4"`` + + **When to use**: + + - "lz4": Modern GKI devices + - "gzip": Traditional devices + - Check kernel config support + +Special Hardware Support +------------------------ + +Understanding Special Hardware Support +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The build system can make use of an external device tree compiler if required. + +deviceinfo_kernel_use_dtc_ext +""""""""""""""""""""""""""""" + **Purpose**: Uses external Device Tree Compiler. + + **Format**: Boolean ("true" or "false") + + **Example**: ``deviceinfo_kernel_use_dtc_ext="true"`` + + **When needed**: + + - Complex DTB requirements + - Vendor-specific DTB formats + - Build compatibility issues + +Practical Examples +------------------ + +Standard Android Device +^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: bash + + deviceinfo_name="OnePlus 8" + deviceinfo_manufacturer="OnePlus" + deviceinfo_codename="instantnoodle" + deviceinfo_arch="aarch64" + deviceinfo_kernel_source="https://github.com/OnePlus-SM8250-Development/android_kernel_oneplus_sm8250" + deviceinfo_kernel_source_branch="lineage-20" + deviceinfo_kernel_defconfig="vendor/instantnoodle_defconfig" + deviceinfo_has_recovery_partition="true" + deviceinfo_flash_pagesize="4096" + +GKI Device Configuration +^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: bash + + deviceinfo_bootimg_header_version="4" + deviceinfo_kernel_llvm_compile="true" + deviceinfo_use_overlaystore="true" + deviceinfo_vendor_bootconfig_path="bootconfig" + deviceinfo_ramdisk_compression="lz4" + deviceinfo_bootimg_has_init_boot="true" + +Samsung Device Example +^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: bash + + deviceinfo_bootimg_board="SRPUK23A007" + deviceinfo_bootimg_tailtype="SEAndroid" + deviceinfo_flash_pagesize="2048" + deviceinfo_has_recovery_partition="true" + +Troubleshooting Common Issues +----------------------------- + +Boot Problems +^^^^^^^^^^^^^ +1. Device won't boot: + - Check flash offsets + - Verify header version + - Confirm compression method + +2. Recovery issues: + - Verify partition sizes + - Check recovery configuration + - Confirm ramdisk settings + +3. Vendor compatibility: + - Match bootconfig settings + - Verify tail requirements + - Check board name setting + +Build Failures +^^^^^^^^^^^^^^ +1. Compilation errors: + - Verify compiler settings + - Check LLVM/Clang configuration + - Confirm kernel branch + +2. Image creation fails: + - Check partition sizes + - Verify compression settings + - Confirm DTB/DTBO paths + +See Also +-------- +- :doc:`../modern-porting/standalone-kernel/device-config` +- :doc:`../modern-porting/special-cases/gki-devices` \ No newline at end of file diff --git a/porting/vendor-specific/index.rst b/porting/vendor-specific/index.rst new file mode 100644 index 000000000..9d2bc4699 --- /dev/null +++ b/porting/vendor-specific/index.rst @@ -0,0 +1,66 @@ +.. _vendor-specific: + +Vendor-Specific Considerations +============================== + +This section covers vendor-specific challenges and solutions you may encounter when porting Ubuntu Touch. While basic porting steps are similar across devices, each vendor's hardware and software implementations introduce unique considerations. + +Quick Reference +--------------- + +Common vendor-specific issues: + +- Qualcomm: Modem initialization, graphics drivers +- MediaTek: WiFi drivers, device tree overlays +- Samsung: Bootloader constraints, kernel patches + +For detailed solutions, see the vendor-specific sections below. + +Understanding Vendor Differences +-------------------------------- + +Hardware Implementation +^^^^^^^^^^^^^^^^^^^^^^^ +Each vendor approaches hardware integration differently: + +* Qualcomm: Highly integrated SoCs with proprietary blobs +* MediaTek: More open documentation but complex initialization +* Samsung: Mixed SoC sources with custom security features + +Software Considerations +^^^^^^^^^^^^^^^^^^^^^^^ +Vendor-specific software layers: + +* Bootloader implementations +* Hardware abstraction approaches +* Security mechanisms +* Firmware requirements + +Key Challenges +-------------- + +1. **Proprietary Components** + + * Vendor-specific blobs + * Firmware requirements + * Driver dependencies + +2. **Hardware Access** + + * Custom initialization + * Unique protocols + * Vendor-specific APIs + +3. **Security Features** + + * Bootloader locks + * Secure boot + * Hardware encryption + +.. toctree:: + :maxdepth: 2 + :name: vendor-specific-toc + + qualcomm/index + mediatek/index + samsung/index \ No newline at end of file diff --git a/porting/vendor-specific/mediatek/index.rst b/porting/vendor-specific/mediatek/index.rst new file mode 100644 index 000000000..058b6ede7 --- /dev/null +++ b/porting/vendor-specific/mediatek/index.rst @@ -0,0 +1,267 @@ +.. _mediatek: + +MediaTek Devices +================ + +Quick Reference +--------------- +Essential configurations for MediaTek devices: + +* WiFi driver setup (MTK-WLAN) +* Power management (PMIC) +* Display configuration (DISP) +* Touchscreen handling + +Platform Characteristics +------------------------ + +Platform Types +^^^^^^^^^^^^^^ +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + + * - Series + - Characteristics + - Common Issues + * - Dimensity + - * Modern ARM platforms + * GKI compatibility + * Dynamic partitions + * Advanced ISP + - * Device tree overlays + * Camera integration + * Thermal management + * - Helio + - * Mid-range platforms + * Mixed HAL versions + * Legacy components + - * Mixed blob versions + * Firmware compatibility + * Power management + * - MT67xx + - * Legacy platforms + * Basic feature set + * Simpler architecture + - * Driver backporting + * Kernel patches + * Limited documentation + +Common Challenges +----------------- + +WiFi Configuration +^^^^^^^^^^^^^^^^^^^ +MediaTek WiFi requires specific setup: + +1. **Driver Setup**:: + + # Required kernel configs + CONFIG_MTK_WIFI=y + CONFIG_MTK_WIFI_DRIVER=y + CONFIG_MTK_COMBO=y + CONFIG_MTK_COMBO_WIFI=y + +Understanding these options: + +* MTK_WIFI: Core WiFi support +* COMBO: Connectivity combo driver +* WIFI_DRIVER: Main WiFi driver + +2. **Firmware Integration** + + Required files and locations:: + + /vendor/firmware/WIFI_RAM_CODE_soc.bin + /vendor/firmware/WIFI_ROM_CODE_soc.bin + /vendor/firmware/wifi.cfg + + Purpose of each file: + + * RAM_CODE: Runtime firmware + * ROM_CODE: Base firmware + * wifi.cfg: Configuration parameters + +Display Configuration +^^^^^^^^^^^^^^^^^^^^^ +1. **Panel Setup** + + Configure display in device tree:: + + &pio { + lcd_bias_pins_default: lcd_bias_pins_default { + pins_cmd_dat { + pinmux = ; + slew-rate = <1>; + output-high; + }; + }; + }; + + Key components: + + * pio: GPIO controller + * pinmux: Pin multiplexing + * slew-rate: Signal timing + * output-high: Default state + +2. **Display Driver** + + Enable required configs:: + + CONFIG_DRM_MEDIATEK=y + CONFIG_DRM_PANEL_SIMPLE=y + CONFIG_DRM_MEDIATEK_HDMI=y + + Understanding settings: + + * DRM_MEDIATEK: Display driver framework + * PANEL_SIMPLE: Basic panel support + * HDMI: External display support + +Hardware Access +--------------- + +1. **Power Management** + + PMIC Configuration:: + + &mt6359p { + regulators { + mt6359p_vcore_reg: buck_vcore { + regulator-name = "vcore"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <1200000>; + regulator-always-on; + }; + }; + }; + + Key concepts: + + * Regulators control power domains + * Voltage ranges must match hardware + * Some regulators must stay enabled + +2. **Memory Controller** + + EMI Configuration:: + + &emi { + compatible = "mediatek,emi"; + reg = <0 0x10219000 0 0x1000>; + mediatek,dram-rank-num = <2>; + mediatek,dram-freq = <3200>; + }; + + Important settings: + + * rank-num: Memory configuration + * dram-freq: Memory speed + * timing parameters + +Best Practices +-------------- + +1. **Power Management** + + * Configure PMIC settings + * Handle sleep states + * Manage CPU clusters + + Implementation:: + + # CPU frequency scaling + CONFIG_MTK_CPUFREQ_PLATFORM=y + CONFIG_MTK_PTPOD=y + + # Power domains + CONFIG_MTK_POWER_DOMAIN=y + CONFIG_PM_DOMAIN=y + +2. **Storage Setup** + + * Configure UFS/eMMC + * Handle partition layout + * Manage flash parameters + + Example configuration:: + + &mmc0 { + status = "okay"; + pinctrl-names = "default", "state_uhs"; + pinctrl-0 = <&mmc0_pins_default>; + pinctrl-1 = <&mmc0_pins_uhs>; + bus-width = <8>; + max-frequency = <200000000>; + }; + +3. **Performance Tuning** + + * CPU frequency scaling + * Thermal management + * Memory configuration + + Tuning parameters:: + + # CPU governors + CONFIG_CPU_FREQ_GOV_MTK=y + + # Thermal + CONFIG_MTK_THERMAL=y + CONFIG_MTK_THERMAL_PA_VIA_ATCMD=y + +Debugging Tips +-------------- + +1. **Common Issues** + + WiFi initialization failures:: + + # Check driver status + dmesg | grep -i wifi + + # Verify firmware + ls -l /vendor/firmware/WIFI* + + # Monitor initialization + logcat -b radio + + Display driver crashes:: + + # Check panel status + dmesg | grep -i disp + + # Monitor DSI + cat /sys/kernel/debug/dri/0/state + + Power management issues:: + + # Check regulators + cat /sys/class/regulator/regulator.*/name + + # Monitor voltages + cat /sys/class/regulator/regulator.*/voltage + +2. **Debug Tools** + + MTK debug tools:: + + # Memory interface + cat /sys/kernel/debug/emi_mbw/dump_buf + + # Clock status + cat /sys/kernel/debug/clk/clk_dump + + Hardware monitoring:: + + # Thermal zones + cat /sys/class/thermal/thermal_zone*/temp + + # CPU frequency + cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_cur_freq + +See Also +-------- +* :ref:`hardware-abstraction` - HAL configuration +* :ref:`debugging` - Debugging guide \ No newline at end of file diff --git a/porting/vendor-specific/qualcomm/index.rst b/porting/vendor-specific/qualcomm/index.rst new file mode 100644 index 000000000..265979def --- /dev/null +++ b/porting/vendor-specific/qualcomm/index.rst @@ -0,0 +1,251 @@ +.. _qualcomm: + +Qualcomm Devices +================ + +Quick Reference +--------------- +Common requirements for Qualcomm devices: + +* QCACLD WiFi driver configuration +* Audio codec setup (WCD) +* Modem initialization +* Graphics initialization sequence + +Platform Characteristics +------------------------ + +Platform Types +^^^^^^^^^^^^^^ +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + + * - Series + - Characteristics + - Common Issues + * - SM8xxx + - * Modern flagship SoCs + * GKI support + * Dynamic partitions + * Advanced security + - * Complex initialization + * Firmware dependencies + * Security constraints + * - SM7xxx + - * Mid-range SoCs + * Mixed HAL versions + * Balanced features + - * HAL compatibility + * Vendor blob matching + * Power management + * - SM6xxx + - * Budget SoCs + * Basic features + * Simpler architecture + - * Driver availability + * Performance limitations + * Memory constraints + +Common Challenges +----------------- + +Graphics Configuration +^^^^^^^^^^^^^^^^^^^^^^ +Qualcomm devices often require specific configuration for the Adreno GPU: + +1. **Driver Integration**:: + + # Required kernel configs + CONFIG_DRM_MSM=y + CONFIG_DRM_MSM_DSI=y + CONFIG_DRM_MSM_DP=y + +Why these settings? + +* DRM_MSM: Core graphics driver +* MSM_DSI: Display interface support +* MSM_DP: DisplayPort support + +2. **Display Configuration** + + Edit display config in device tree:: + + &mdss_dsi0 { + compatible = "qcom,mdss-dsi-ctrl"; + qcom,dsi-host-index = <0>; + ... + }; + +Understanding the components: + +* mdss_dsi: Mobile Display SubSystem +* dsi-host-index: Display controller ID +* Compatible string: Links to driver + +Modem Setup +^^^^^^^^^^^ +Steps for modem initialization: + +1. Check required firmware files:: + + # Common firmware locations + /vendor/firmware/modem.mbn + /vendor/firmware/mba.mbn + +Required files: + +* modem.mbn: Main modem firmware +* mba.mbn: Modem bootloader +* Additional QMI modules + +2. Configure rild service in init scripts +3. Add udev rules for modem devices + +Special Cases +------------- + +Devices with Secure Boot +^^^^^^^^^^^^^^^^^^^^^^^^ +For devices with secure boot: + +1. Verify AVB configuration +2. Check vbmeta requirements +3. Configure device-specific keys + +Why this matters: + +* Secure boot validates boot components +* Wrong configuration prevents booting +* Keys must match expectations + +A/B Devices +^^^^^^^^^^^ +Additional configuration for A/B partition schemes: + +1. Update boot configuration +2. Configure system-as-root +3. Handle vendor_boot partition + +Understanding A/B: + +* Dual partition sets +* Seamless updates +* Fallback capability + +Best Practices +-------------- + +1. **Audio Configuration** + + * Use QCOM audio HAL + * Configure UCM files + * Handle mixer paths + +Configuration steps: + +1. Identify codec type +2. Set up mixer paths +3. Configure UCM rules + +2. **Power Management** + + * Configure CPUFreq governors + * Handle thermal zones + * Set up battery charging + +Key components: + +* Frequency scaling +* Temperature control +* Battery management + +3. **Debugging Tools** + + * Use Qualcomm debug tools + * Configure serial console + * Enable relevant logging + +Common tools: + +* qpst: Qualcomm testing tool +* qmuxd: QMI debugging +* diag: Modem diagnostics + +Implementation Examples +----------------------- + +Audio Setup +^^^^^^^^^^^ +Example UCM configuration:: + + SectionDevice."Headphones" { + Comment "Headphones playback" + + EnableSequence [ + cset "name='RX1 MIX1 INP1' RX1" + cset "name='RX2 MIX1 INP1' RX2" + cset "name='HPHL DAC Switch' 1" + cset "name='HPHR DAC Switch' 1" + ] + } + +Graphics Configuration +^^^^^^^^^^^^^^^^^^^^^^ +Device tree example for Adreno GPU:: + + &soc { + gpu@5000000 { + compatible = "qcom,adreno-gpu-vkxxxxxxx"; + reg = <0x5000000 0x40000>; + interrupts = ; + clock-names = "core", "rbbmtimer", "iface"; + }; + }; + +Debugging Tips +-------------- + +1. **Graphics Issues** + + Common problems: + + * Initialization failures + * Performance issues + * Display corruption + + Debug steps:: + + # Check GPU status + cat /sys/class/kgsl/kgsl-3d0/status + + # Monitor GPU frequency + cat /sys/class/kgsl/kgsl-3d0/gpuclk + + # Check GPU load + cat /sys/class/kgsl/kgsl-3d0/gpu_busy_percentage + +2. **Modem Problems** + + Watch for: + + * Initialization failures + * QMI errors + * Firmware issues + + Debug process:: + + # Check modem status + dmesg | grep -i modem + + # Monitor QMI + qmicli -d /dev/cdc-wdm0 --dms-get-operating-mode + + # Verify firmware + ls -l /vendor/firmware/ + +See Also +-------- +* :ref:`display` - Display configuration details +* :ref:`debugging` - General debugging guidance +* `Qualcomm Developer Network `_ \ No newline at end of file diff --git a/porting/vendor-specific/samsung/index.rst b/porting/vendor-specific/samsung/index.rst new file mode 100644 index 000000000..64e695cf7 --- /dev/null +++ b/porting/vendor-specific/samsung/index.rst @@ -0,0 +1,311 @@ +.. _samsung: + +Samsung Devices +=============== + +Quick Reference +--------------- +Essential requirements for Samsung devices: + +* Custom boot image configuration (SEAndroid) +* Specialized flashing tools (Heimdall/Odin) +* Knox configuration handling +* Samsung-specific kernel patches + +Understanding Samsung Architecture +---------------------------------- + +Platform Types +^^^^^^^^^^^^^^ +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + + * - Series + - Characteristics + - Common Issues + * - Exynos 9xxx/2xxx + - * Modern flagship SoCs + * In-house design + * Advanced security + * Custom mali drivers + - * SELinux policies + * Vendor partitions + * Knox integration + * Proprietary blobs + * - Exynos 8xxx/1xxx + - * Mid-range SoCs + * Mixed hardware + * Legacy features + - * Mixed HAL versions + * RIL handling + * Power management + * Graphics drivers + * - Exynos 7xxx + - * Budget SoCs + * Basic features + * Simpler security + - * Legacy driver support + * WiFi integration + * Limited documentation + * Memory management + +Boot Image Requirements +----------------------- + +SEAndroid Configuration +^^^^^^^^^^^^^^^^^^^^^^^ +Samsung devices require specific boot image modifications: + +1. **Boot Image Footer** + + Add to deviceinfo:: + + deviceinfo_bootimg_tailtype="SEAndroid" + + Why needed: + + * Samsung bootloader checks for footer + * Prevents red Knox warning + * Required for secure boot + +2. **Header Version** + + Modern Samsung devices use header version 2 or higher:: + + deviceinfo_bootimg_header_version="2" + deviceinfo_bootimg_os_version="11.0.0" + deviceinfo_bootimg_os_patch_level="2024-01" + + Understanding parameters: + + * Header version matches Android release + * OS version affects bootloader checks + * Patch level must be recent + +3. **Board Name** + + Required for proper device detection:: + + deviceinfo_bootimg_board="SRPUK23A007" + + Purpose: + + * Bootloader verification + * Hardware identification + * Firmware compatibility + +Flashing Tools +-------------- + +Heimdall Setup +^^^^^^^^^^^^^^ +Use Heimdall for flashing from Linux: + +1. **Installation**:: + + # Ubuntu/Debian + sudo apt install heimdall-flash + +2. **Basic Usage**:: + + # Flash boot partition + sudo heimdall flash --BOOT boot.img + + # Flash recovery partition + sudo heimdall flash --RECOVERY recovery.img + +3. **Partition Layout** + + Common Samsung partition mapping:: + + # Check partition layout + sudo heimdall print-pit + + # Common partition names + BOOT = boot.img + RECOVERY = recovery.img + SYSTEM = system.img + VENDOR = vendor.img + + Understanding PIT: + + * Partition Information Table + * Defines partition layout + * Required for flashing + +Hardware Integration +-------------------- + +RIL Configuration +^^^^^^^^^^^^^^^^^ +Samsung devices need specific radio interface setup: + +1. **Required Blobs**:: + + # Key RIL files + /vendor/lib64/libsec-ril.so + /vendor/lib64/libsec-ril-dsds.so + + # Required configurations + /vendor/etc/plmn_delta.bin + /vendor/etc/plmn_se13.bin + +2. **Service Configuration** + + Update rild service in init scripts:: + + service vendor.ril-daemon /vendor/bin/hw/rild + class main + user radio + group radio cache inet misc audio sdcard_r sdcard_rw log + capabilities BLOCK_SUSPEND NET_ADMIN NET_RAW + +Graphics Setup +^^^^^^^^^^^^^^ +Samsung devices often use Mali or Adreno GPUs: + +1. **Mali Configuration**:: + + # Required kernel configs + CONFIG_MALI_MIDGARD=y + CONFIG_MALI_EXPERT=y + CONFIG_MALI_DEBUG=y + + Understanding options: + + * MIDGARD: Modern Mali architecture + * EXPERT: Advanced configuration + * DEBUG: Development support + +2. **Display Panel** + + Configure display in device tree:: + + &dsi_panel { + compatible = "samsung,s6e3fc3"; + reg = <0>; + reset-gpios = <&tlmm 12 0>; + power-gpios = <&tlmm 100 0>; + vddio-supply = <&pm8150_l14>; + }; + +Audio Configuration +^^^^^^^^^^^^^^^^^^^ +Setup for Samsung audio hardware: + +1. **Required UCM Files**:: + + /usr/share/alsa/ucm2/conf.d/samsung-audio.conf + +2. **Mixer Paths**:: + + /vendor/etc/mixer_paths.xml + +Special Considerations +---------------------- + +Knox Handling +^^^^^^^^^^^^^ +For devices with Knox security: + +1. **Warning Indicators** + + Understanding Knox: + + * Warranty void counter + * Security indicators + * Boot verification + +2. **Feature Limitations** + + Impact on functionality: + + * Secure storage access + * DRM capabilities + * Payment services + * Biometric features + +One UI Integration +^^^^^^^^^^^^^^^^^^ +Handling Samsung's Android modifications: + +1. **Vendor Services** + + Required components: + + * Samsung framework services + * Custom HAL implementations + * Security services + +2. **Hardware Features** + + Limitations: + + * Samsung Pay unavailable + * Secure Folder restrictions + * Biometric system changes + +Debugging Tips +-------------- + +1. **Common Issues** + + Boot loop after flashing: + + * Check boot image footer + * Verify partition table + * Monitor boot process + + RIL initialization failures: + + * Check vendor blobs + * Monitor logcat + * Verify permissions + +2. **Debug Tools** + + Samsung-specific tools: + + * Samsung Modem Logger + * SysDump + * SEC Debug Bridge + +3. **Recovery Options** + + Emergency recovery: + + * Download mode access + * PIT restoration + * Factory binary flashing + +Best Practices +-------------- + +1. **Initial Setup** + + * Verify bootloader unlock status + * Back up stock firmware + * Document partition layout + * Save stock PIT file + +2. **Build Configuration** + + * Use correct defconfig + * Handle SELinux policies + * Configure device tree + * Match security settings + +3. **Testing Process** + + * Verify basic functionality + * Test radio features + * Check power management + * Monitor Knox status + +See Also +-------- +* :ref:`first-boot` - Initial boot and configuration +* :ref:`hardware-abstraction` - HAL setup +* :ref:`debugging` - General debugging guide +* :doc:`../qualcomm/index` - For Samsung devices with Qualcomm SoCs \ No newline at end of file diff --git a/redirects.txt b/redirects.txt index ff752c077..d9e1f1415 100644 --- a/redirects.txt +++ b/redirects.txt @@ -1,19 +1,32 @@ -"porting/index.rst" "porting/introduction/index.rst" -"porting/introduction.rst" "porting/introduction/index.rst" -"porting/halium_7-1/index.rst" "porting/introduction/index.rst" -"porting/halium_7-1/Building.rst" "porting/build_and_boot/index.rst" -"porting/halium_7-1/Common_errors.rst" "porting/build_and_boot/index.rst" -"porting/halium_7-1/Installing.rst" "porting/build_and_boot/index.rst" -"porting/halium_7-1/Unity8.rst" "porting/configure_test_fix/index.rst" -"porting/halium_7-1/Configuring.rst" "porting/configure_test_fix/index.rst" -"porting/halium_9/Halium_9_GSI_porting.rst" "porting/build_and_boot/index.rst" -"porting/halium_9/Halium_9_common_errors.rst" "porting/build_and_boot/index.rst" -"porting/halium_9/index.rst" "porting/build_and_boot/index.rst" -"porting/halium_7-1/Reference_material.rst" "porting/configure_test_fix/index.rst" -"porting/build_and_boot/H9_gitlab_build.rst" "porting/build_and_boot/standalone_kernel_build.rst" -"porting/UBports_installer.rst" "porting/finalize/UBports_installer.rst" -"porting/UBports_recovery.rst" "porting/finalize/UBports_recovery.rst" -"porting/Preparations.rst" "porting/introduction/Preparations.rst" +"porting/introduction/index.rst" "porting/index.rst" +"porting/configure_test_fix/device_info/Repowerd.rst" "porting/index.rst" +"porting/configure_test_fix/device_info/HfdService.rst" "porting/index.rst" +"porting/configure_test_fix/device_info/Ayatana-indicator-power.rst" "porting/index.rst" +"porting/configure_test_fix/device_info/index.rst" "porting/index.rst" +"porting/configure_test_fix/device_info/Mir.rst" "porting/index.rst" +"porting/configure_test_fix/Apparmor.rst" "porting/index.rst" +"porting/configure_test_fix/USBModed.rst" "porting/index.rst" +"porting/configure_test_fix/Lomiri.rst" "porting/index.rst" +"porting/configure_test_fix/Wifi.rst" "porting/index.rst" +"porting/configure_test_fix/Display.rst" "porting/index.rst" +"porting/configure_test_fix/index.rst" "porting/index.rst" +"porting/configure_test_fix/Bluetooth.rst" "porting/index.rst" +"porting/configure_test_fix/Sound.rst" "porting/index.rst" +"porting/configure_test_fix/Overlay.rst" "porting/index.rst" +"porting/build_and_boot/H9_build.rst" "porting/index.rst" +"porting/build_and_boot/H9_setup_sources.rst" "porting/index.rst" +"porting/build_and_boot/index.rst" "porting/index.rst" +"porting/build_and_boot/Boot_debug.rst" "porting/index.rst" +"porting/build_and_boot/standalone_kernel_build.rst" "porting/index.rst" +"porting/build_and_boot/H7_setup_sources.rst" "porting/index.rst" +"porting/build_and_boot/Halium_install.rst" "porting/index.rst" +"porting/build_and_boot/H7_build.rst" "porting/index.rst" +"porting/introduction/Intro.rst" "porting/index.rst" +"porting/introduction/Preparations.rst" "porting/index.rst" +"porting/introduction/Setting_up.rst" "porting/index.rst" +"porting/finalize/UBports_installer.rst" "porting/index.rst" +"porting/finalize/UBports_recovery.rst" "porting/index.rst" +"porting/UpdatePortsFor2004.rst" "porting/index.rst" "appdev/getting-started.rst" "appdev/index.rst" "appdev/publishing/index.rst" "appdev/index.rst" "appdev/samples/index.rst" "appdev/index.rst" diff --git a/requirements.txt b/requirements.txt index 0e4cd2a09..69893c07c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,3 +2,4 @@ sphinx==8.0.2 furo==2024.8.6 sphinx-intl sphinxext-rediraffe +sphinxcontrib-mermaid \ No newline at end of file diff --git a/systemdev/kernel-hal.rst b/systemdev/kernel-hal.rst index f5e786cae..bc7318f62 100644 --- a/systemdev/kernel-hal.rst +++ b/systemdev/kernel-hal.rst @@ -72,7 +72,7 @@ However, Halium permits a more generic way of porting to Android devices. This a Some examples of Halium ports are those for Sony Xperia X and Oneplus 3. Basically all devices that are listed on `devices.ubuntu-touch.io `_, expect those explicitly mentioned above as 5.1, or below as Linux based ports. -All new ports of UT to Android devices should follow the Halium process. Further details can be found under :doc:`Halium porting <../porting/introduction/index>` +All new ports of UT to Android devices should follow the Halium process. Further details can be found under :doc:`Halium porting <../porting/index>` Linux based ports ----------------- diff --git a/systemdev/ubp-5.1.rst b/systemdev/ubp-5.1.rst index f60d64f21..3c0653225 100644 --- a/systemdev/ubp-5.1.rst +++ b/systemdev/ubp-5.1.rst @@ -6,7 +6,7 @@ This page documents how to build the Kernel and the Android image for the LG Nex .. note:: - We highly suggest that you follow the :doc:`Halium porting guide <../porting/introduction/index>` if you want to bring up a new device. The steps in here are only relevant for hammerhead, bacon and FP2. + We highly suggest that you follow the :doc:`Halium porting guide <../porting/index>` if you want to bring up a new device. The steps in here are only relevant for hammerhead, bacon and FP2. This document assumes you already have knowledge of building Android or Halium. It also assumes that your device has Ubuntu Touch installed. diff --git a/userguide/install.rst b/userguide/install.rst index 25529041e..65d682bec 100644 --- a/userguide/install.rst +++ b/userguide/install.rst @@ -16,7 +16,7 @@ You can `Download the UBports Installer from GitHub `. +If you're an experienced android developer and want to help us bring Ubuntu Touch to more devices, visit the :doc:`porting section `. .. note:: Please do **not** start the installer with ``sudo``. It is meant to be run as a normal user, not as root. Using the installer with sudo will mess up permissions in the installer's cached files and lead to problems down the road. If the installer does not recognize your device, check the troubleshooting information below.