MSM8916 Mainlining

MSM8916/APQ8016 (or Snapdragon 410/412) is Qualcomm SoC released in 2014. Support in mainline was originally added for the Dragonboard 410c, but most of it also works well on other MSM8916-based devices.

Status
The following features provided by the MSM8916 SoC are supported in mainline and should work on most MSM8916-based devices after the device tree has been set up:
 * UART
 * USB
 * Internal/External Storage (eMMC/SD card)
 * WiFi/Bluetooth
 * GPU, Display (Note: There are many different display panels and each needs a custom panel driver...)
 * Audio
 * Buttons
 * Vibration
 * Modem (SMS, voice calls with audio, mobile data)

Certain components (e.g. touchscreen, sensors, ...) are device-specific. With a bit of luck, some will be already supported by mainline, others won't.

Overview
The first MSM8916 devices using mainline were added in. The following components are involved when running mainline on MSM8916 devices.

msm8916-mainline/linux
The close-to-mainline Linux kernel fork with patches that have not been accepted/submitted upstream yet. Patches in the  branch are generally in good shape unless marked otherwise. Submit a PR to add new patches there.

msm8916-mainline/lk2nd
The reference bootloader provided by Qualcomm for MSM8916 is open-source and based on Little Kernel (LK). Most devices will use this bootloader in a more or less modified form. On Samsung devices for example, the standard Fastboot interface was replaced by their proprietary download mode.

lk2nd is a fork of the reference bootloader with the goal to provide a unified boot interface on all MSM8916 devices. It provides a standard Fastboot interface (even on Samsung devices!). It also used for a number of mainline quirks (e.g. to set a WiFi/BT MAC address in the device tree; without lk2nd, WiFi/BT does not work out of the box). Eventually, more quirks may be added in the future. It is therefore recommended for all mainline MSM8916 devices. Porting it is generally much easier than porting mainline.

The shared device package in postmarketOS. It contains shared dependencies and configuration files.

Requirements

 * MSM8916-based device
 * UART if possible (with a bit of luck you may get USB working without UART)
 * (Downstream) Linux kernel source for your device (explaining ways to mainline without kernel source is out of scope for this article)
 * Basic knowledge about Linux, Git, C, Device Trees, ...
 * Willingness to learn about "mainlining" and to figure out things on your own

Before you start
Mainlining is not easy. MSM8916 is a platform where a lot components can be easily enabled by only setting up a device tree, which can be largely copied from other devices with minor changes. However, at some point you will reach the point where you would like to enable a particular component that is device-specific (e.g. the touchscreen, sensors, ...). In this case you will be largely on your own, and need to figure out how to enable it yourself. (Do you just need to add something to the device tree or even write a new kernel driver?) That requires some familiarity with the way the Linux kernel is working for MSM8916.

The best way to make yourself familiar with the process is to attempt to figure out some simple things on your own. Therefore, this guide will only describe everything until (eventually) USB network is working. For everything else, this article provides only some information that might be helpful to figure it out yourself.

If you have any questions, ask in the mainline channel on Matrix or IRC. Make sure to mention "msm8916" if your question is specific to this article.

Preparations
First, let's take a short look at the downstream kernel. The device trees on downstream are usually in  (in Samsung kernels:  ). You need to find the  file that describes the device tree for your device. One way to check this is to look at  on downstream, and search for the same string in that directory.

Now, let's check how it looks on mainline. Clone msm8916-mainline/linux and take a look at. This is the directory where you will add your device tree later.

lk2nd
msm8916-mainline/lk2nd does not require any device-specific code. Normally, it should just run out of the box on your device. However, most stock bootloaders require a valid device tree to be present in the Android boot image. To avoid problems, a dummy device tree with the  from the downstream kernel needs to be added to lk2nd.

Before you make any changes, try building it. Then, add a new file for your device to  that looks like:

Note the  lines in the example above. This is where you still need to make changes for your device. For example, replace the  with a display name for your device, and the placeholders in the   string.

The  property allows the bootloader to select the correct device tree. MSM8916 devices usually use QCDT (multiple device tree blobs (dtb) are packaged in one Android boot image). You should be able to find the  in the downstream   file for your device.

Make sure to add the new file to, and re-compile lk2nd.

With a bit of luck, flashing the boot image on your device should make it boot into a lk2nd specific Fastboot screen (example), and the device should show up via USB. If either of that is not the case, we need to investigate further. Sometimes, there is some kind of Micro-USB Interface Controller that sits between USB and the SoC, which may require manual setup to work correctly. Setting that up would require device-specific code. If you need help, ask in the mainline channel on Matrix or IRC.

Device Package
Before you can build the mainline kernel for your device, you need to setup the postmarketOS device packages. Avoid creating the device/kernel package directly through pmbootstrap. There is no need to analyze a boot image. (The boot image offsets are not actually used on MSM8916; plus, all MSM8916 devices should use Fastboot through lk2nd...) You can start with the following examples:





Follow the postmarketOS porting guide until the device package builds successfully.

Build Kernel
Go back to your msm8916-mainline/linux clone. Try to build it with envkernel.sh:

This is how you can build and test local changes for the kernel from now on. Now we will continue setting up an initial device tree for your device.

Later on, if you want to change the config, for example to build a new display driver as a module, you can run.

Initial Device Tree
The available hardware components of a device are described in the device tree. Components provided by the SoC (MSM8916) are described in the common include. Components provided by the PMIC (PM8916) are described in. Finally, the combination of both is described in.

You need to create a new device tree with the device-specific configuration, plus additional components used in your device (e.g. touchscreen).

The device tree for your device should be placed in a new file at. A very simple device tree that only enables UART output could look like this:

We see two different kind of device tree nodes here. There is the root device tree node, which we use to set up some configuration in the  node. Then there is the  node. This is a reference to a device tree node that was defined somewhere under the root node by one of the includes. In this case,  sets up lots of pre-defined devices (e.g. for UART, eMMC, SD card, ...). We don't care exactly where or how they are defined. We just want to enable them and (if necessary) add device-specific configuration to them.

We can reference existing device tree nodes using labels. The original device tree node for  in   looks like this:

The part before the colon is the label we can use to reference the node. We can use that to add additional properties or to change one of the existing ones. In particular, we can see that  declares   (one of the UART ports) as disabled by default. We want to enable the UART port so we override  with.

Finally, the combination of the  and   node selects   as default console output.

Before you build, don't forget to add an entry to. This device tree should be already enough to boot with working serial console if you are able to access UART. If you don't have UART you will need to skip testing this step and hope that USB works out of the box in the next step.

Regulators
As next steps we would like to enable internal/external storage (eMMC/SD card) and make USB gadget mode work. This will allow you to attach your device to a PC and get a debugging console.

However, a requirement of both of these hardware components is that you have some voltage regulators set up properly. Hardware components have different power supply requirements, so usually the PMIC(s) used together with a SoC provide several different regulators that can be configured to produce a voltage level within a specified range.

Let's take a quick look at. As a reminder: This include contains common definitions that apply to most devices that pair MSM8916 (the SoC) with PM8916 (the PMIC). Most interesting for us are the references to  (the SD Host Controller) and   (a part of the USB controller):

,  etc are some of the regulators that are provided by PM8916. As you can see they are configured as supplies for both eMMC/SD card and USB.

All these regulators can be configured to a large voltage range, so it is very important that we set up voltage constraints carefully! The voltage constraints specify the allowed voltage range that can be set for a particular regulator. Once we have set them up properly, we can be reasonably sure that accidental mistakes cannot easily destroy one of the hardware components in a device.

Let's get back to the device tree for your device. We extend the initial UART example from the previous section with new device tree nodes to set up the voltage constraints. A typical set of voltage constraints for PM8916 looks like this:

You should paste this at the end of your device tree and then go through all the voltages and compare them what you see in your downstream reference kernel. Here are some tips and tricks:


 * Downstream regulators look a bit different, but they are usually defined in . Note that some device trees may override the regulator voltages in a device-specific.
 * ( and    are missing in the voltage constraints because they are managed separately as power domains. Simply put, these two regulators are used by many components in the SoC. Instead of picking an exact voltage, we vote for a particular performance state. On downstream this is called voltage corner. There is a special Resource Power Manager (RPM) co-processor that collects all the votes and then decides for a particular voltage to use.
 * There is no need to set up voltage constraints for these because there is no way to set an dangerous voltage through the corner interface.
 * is special (used to control the voltage for the CPU cores) and is not touched by mainline at the moment. Just ignore it.
 * Also ignore the  and   regulators (usually just on  )
 * on  in the snippet above is for stability of the SD card . This is declared in a different place on downstream, but most likely you can just keep it as-is.
 * etc does not exist on downstream, but you can also keep it as-is. It is extremely unlikely that this is different for a particular device. Most important is validating the voltages.

USB
Theoretically, enabling USB would be as simple as adding:

However, due to an implementation detail USB only works if the USB controller is notified when you actually insert an USB cable. On mainline, these notifications come from the extcon (external connector) subsystem. Unfortunately, how we can detect that an USB cable was inserted differs quite significantly between devices. Sometimes (mainly on Samsung devices), there is some kind of Micro-USB Interface Controller that sits between USB and the SoC, which can detect various different cable types (connected to PC, connected to charger adapter, USB-OTG, ...). In most other cases, this notification comes from the charger driver, which is usually quite hard to get working (see ).

How to handle some of the common variants is described here. Feel free to ask in the chat for further help.

ID pin
This is the easiest solution if you have some kind of USB ID GPIO defined downstream. Usually it's called  under the   node but the name varies a bit sometimes. The USB ID pin is used to differentiate between:


 * Gadget mode (where you connect the device to a PC)
 * Host mode (where you use a special USB-OTG adapter to connect other USB devices, e.g. an USB keyboard)

It can only detect these two cases, so it does not allow us to detect that an USB cable is actually inserted. However, as a start we can pretend that an USB cable is inserted whenever we are not in host mode (i.e. whenever there is no USB-OTG adapter inserted). This means that the USB controller will stay active all the time. This is not much of a problem for getting started, right? :)

For this example, there was  defined downstream, so the USB ID pin is connected to GPIO 110. Now we declare a new device tree node, which sets up an extcon device using the USB ID GPIO. We put this under the root node because it is an entirely new node (previously we were mainly re-configuring existing device nodes):

Something we have not seen before in this guide is pinctrl (or Pin Control): As mentioned earlier, MSM8916 has 122 GPIO pins that can be configured with different functions. The idea is that there are only so many physical pins you can afford to have on an SoC, but you want to expose a lot of features. Thankfully, most of the time you won't need to use all of the features in the same device, which is why SoC manufatcturers get away with multiplexing multiple functions behind one physical pin. The most common use of a pin is as a GPIO (basically a digital input/output line that can be either set high or low, respectively can be sensed to determine the level it was set to by something outside the SoC). But it's also possible to configure other functions (e.g. UART or I²C) for some of the pins. Additionally, pins can be configured with pull-up/pull-down resistors or with a particular drive strength. In the Linux kernel, the Pin Control Subsystem (pinctrl) handles that configuration.

In most cases you don't need to figure out yourself if you need pull-down/pull-up or a particular drive strength. We can check on downstream how the pins were configured and translate that to a similar configuration on mainline. While downstream may contain errors (like enabling an internal pull-up on a line with external one), it's proven to work reliably. When in doubt, a datasheet is of immense help. In our example here we find the following line downstream:. We can then search for  in the related device tree files (if it exists multiple times, check which includes are actually used for your device). In this case, we find it in  and it looks like:

The pin is configured as GPIO with pull-up and a drive-strength of 8mA.

We can easily define a similar configuration on mainline: To do that, we define a new pin configuration as part of the  node, and then reference it with  /  as seen above. The above example translates to the following:

Finally, we assign our new extcon device to both  and , and then USB should be working. :)

MUIC
Especially Samsung devices do not have the USB ID pin connected to a GPIO like explained in the previous section. Instead, there is an additional chip that sits between the USB connector and the USB controller: a Micro-USB Interface Controller (or: MUIC). The MUIC handles all USB cable related detection and therefore pretty much represents an extcon device as we have set up manually using the USB ID GPIO in the last section.

The disadvantage is that we now need a special driver for the MUIC. Many different chips exist so often a driver is not available immediately, since you usually don't want to write an entire new driver before you know if mainline is booting on your device at all. Anyway, if there is a driver for it already, the approach to make it work would be the following:


 * 1) Identify the MUIC chip. Usually you can find it by searching for   in the downstream device tree. In this example we will use SM5502, which has the   driver in mainline.
 * 2) Identify the I²C bus it is connected to. (it will probably be an I²C bus, but in theory it might be e.g SPI.) Samsung tends to use i2c-gpio, which emulates the I²C protocol on GPIO pins using bit banging. Note that sometimes they use i2c-gpio even when there is a hardware I²C bus available on the same pins. Not sure why they do that. They also sometimes add i2c-gpio-specific dts properties to hw I²C nodes. You can compare the SDA/SCL GPIO with the pins of the hardware I²C controllers and if it matches it is probably better to use the hardware I²C controller instead of i2c-gpio.
 * 3) Declare a new device tree node for the MUIC device (and eventually the i2c-gpio bus) and reference it as extcon for  /  like in the   example above.

If the MUIC chip is not supported by a mainline driver (yet), check out the next section for now.

Let's get to the example. The downstream device tree contains:

As mentioned earlier, there is actually a hardware I²C bus available on these pins so we have two options. We can use the hardware I²C bus (preferred if possible):

... or we can use i2c-gpio like Samsung:

How to define the pinctrl for these nodes is left as an exercise for the reader (see for explanations). Ask if you need any help!

Otherwise
If you have neither USB ID GPIO nor MUIC, none of the options above will work for you. However, you should be able to use the USB detection of the PM8916 PMIC in this case:

Typically  should be replaced later with a reference to the charging hardware. It is usually the most reliable source of detecting if an USB cable is plugged in.

Testing
If you do not have (easy) access to UART, you now have the chance to boot your kernel for the first time!


 * 1) Make sure to build the kernel (see ).
 * 2) Create a postmarketOS installation:
 * 3) Enable the   hook. This will provide a telnet console via USB without having to flash the root file system to the internal storage.
 * 4) Boot the kernel using  . (Alternatively you could flash it using   and reboot, but that's not nearly as convenient during development...)
 * 5) With a bit of luck, the device should show up on telnet via USB after booting. Take a look at   to see the kernel log of mainline booting on your device!

Note that you need to remove the  hook explicitly using   before attempting to boot with the rootfs in the next section.

eMMC
If you have USB working, it's time to get the eMMC (internal storage) working next. This will allow you to flash the postmarketOS rootfs to get access to SSH instead of the minimal telnet session you had so far.

In most cases, enabling the eMMC should be as simple as adding:

In this case, you don't need to write the pinctrl nodes yourself. Almost all of the devices use the same configuration here so these are shared for all devices in.

That's it! Now you can build the kernel again, flash the rootfs using  and reboot the device. Make sure to remove the  hook first using. If you used  previously, you may want to erase the boot partition to avoid confusion as lk2nd will prefer to use the file from ext2 part of the rootfs instead of that. With a bit of luck, you might boot straight into postmarketOS with working SSH! :)

SD card
Your device probably has a (micro) SD card slot. If you would like to keep your Android installation, you can flash the postmarketOS rootfs there alternatively. Or you can use it as extra/removable storage for some special files. It should be almost as simple as getting the eMMC working, so grab a micro SD card for testing and try to get it working:

Please take a close look at the comments here. The implementation of SD card detection varies depending on the device. The following two types are common:


 * Hotplug detection using  (card detect): This allows detecting if the SD card is removed at runtime, so this is often used if the SD card is removable without turning off the device.
 * Scanning for a SD card once during bootup: The assumption is that the device is  at runtime, e.g. because it is not accessible without removing the battery. In that case, they were able to omit the card-detect GPIO.

Check your downstream device tree for  (usually on the   node). If it exists, uncomment it here and also add  to the pinctrl lines. Otherwise, uncomment.

Note: Use  for   if downstream contains   Otherwise, use.

That's it! Try to boot it and see if the SD card shows up in  or. If you want, you can also try to mount it and read/write some files.

Buttons
As a last part of this guide, let's try to get the hardware buttons working. Your device probably has at least a (mechanical), and  button.

The Power and Volume Down buttons are usually connected to the PMIC (PM8916). The Power button is - obviously - used to power on the device. Volume Down is used in combination with the Power button to force a reboot (technically, this behavior is somewhat configurable, but thankfully it is usually set up like this), essentially simulating removing the battery and putting it back in. On devices without removable battery holding these two buttons allows rebooting ("resetting") the device.

On mainline, the  driver implements support for these two buttons. The power button is set up by default in the common  include. As mentioned, the Volume Down button is typically connected to the "reset input" (resin). Theoretically, a device could have any button (or even some test points on the mainboard) connected there so we need to enable it explicitly and assign :

Volume Up and other additional keys (e.g. Home on Samsung devices) are usually connected to a GPIO pin on the SoC. Therefore, setting them up is trivial using gpio-keys. Try to find the GPIOs in the downstream device tree and set up something like:

Make sure to set up pinctrl properly: typically these buttons need to be configured with.

To test the buttons,. Then you can select the input devices in  and see if an input event show up when you press them.

Finishing up
If the features enabled during the guide are working, then it is a good time to do some cleanup and propose your changes "upstream" on msm8916-mainline/linux. This repository is intended as a temporary place for patches that are already in good quality, but either pending or not quite finished to submit them on the Linux mainline mailing lists.

Device Tree Structure
So far you have assembled your device tree from various examples shown in this guide. For consistency with the other MSM8916 device trees, please make sure to put your device tree in the following order:

Patch Requirements
To maintain the quality, all patches are required to:
 * Compile without warnings
 * Have no critical checkpatch failures (also see Style-check your changes in the mainline "Submitting patches" guide)
 * Sometimes it makes sense to ignore notes and warnings from checkpatch if the code is more readable without fixing them.
 * Have a properly formatted one-line summary in the commit message (there is no need to write a detailed commit message, yet)
 * Look at similar commits in the commit history for examples.
 * Comply with the repository's contributing guidelines that also inherit some requirements of upstream Linux.

The first two will be automatically checked for you when you open a PR - the CI build will fail otherwise - so you don't have to check it locally. Eventually, you should expect a few additional review comments to improve your code. This will help you to speed up submission of the patches upstream later! ;)

Hints
Please check these to reduce the time required to review your patch:
 * Add pinctrl for all GPIOs you are using. This is good practice in case they were incorrectly configured by the previous bootloader or operating system (consider kexec booting another Linux kernel).

Reference
The general approach for mainlining is: and compare it with what you can find on downstream (e.g. device tree, kernel code, ...). Do not take the downstream device tree as a base or even copy it as-is. That is the wrong approach. Downstream code tends to be full of mistakes and unnecessarily verbose. It's easier to start from scratch and rather take something in mainline as a base.
 * Look at all resources you can find, e.g.:
 * Commits in msm8916-mainline/linux
 * Existing device trees in mainline and/or commits with relevant changes (sometimes there is helpful information in the commit message)
 * The kernel documentation, especially the device tree binding documentation (all available device tree properties should be documented there)

Additional tips and tricks:
 * When making changes to kernel code compiled as modules, you need to update the kernel modules on the rootfs (they are not part of the boot image that is loaded via Fastboot). There are different options to do this:
 * Re-flash rootfs
 * Upgrade  on your device: see Installing packages on a running phone
 * Other hacky solutions like copying kernel modules manually via SSH

Firmware
Unfortunately, some components in the SoC rely on proprietary firmware to work properly:


 * WiFi/Bluetooth (wcnss)
 * Modem (modem)
 * Hardware-accelerated video codecs (venus)

Perhaps more unfortunately, typically the firmware is signed with a device-specific key, which means you are forced to continue using the potentially outdated/buggy firmware provided by the stock firmware of your device manufacturer. This means that the firmware must be either loaded from the special partition or packaged separately for each device. The following files are needed:


 * plus all related segments (, ...) (usually installed on a separate firmware partition)
 * (usually installed on the system partition, e.g. )
 * ,,  , ... (usually installed on a separate firmware (  or  ) partition)
 * ,, ... (usually installed on a separate firmware  partition, or in  )

First, check if adding  package places any blobs to. If some files from the above list are missing, create a new firmware. Look at  as an example.

Then, add a new  subpackage to your device package:

Generate the checksum for your firmware package with  and build it with. Then continue to build and install as you have been doing above.

WiFi/Bluetooth
WiFi/Bluetooth are usually provided by the Qualcomm Wireless Connectivity Subsystem (WCNSS), which is partially built into the SoC but paired with an external RF module ("iris"). Therefore, enabling it is usually as simple as enabling the  node in the device tree:

By default mainline expects WCN3620 as external RF module. However, MSM8916 can be also paired with other RF modules - another common chip is WCN3660B which has dual-band (5 GHz) support additionally. The chip identifier can be obtained from a downstream kernel log (dmesg): There should be a message like. Take the first 4 hex chars (i.e. ) and compare it with the chip IDs listed in downstream.

If you do not have WCN3620, you need to override the  property of the iris node:

A few more notes:


 * WiFi and Bluetooth share the same antenna, and they tend to conflict with each other when they are used at the same time ("WiFi/BT coexistence"). In case of problems, try disabling one of them.
 * Dual-band support on WCN3660B seems to be broken at the moment: only 2.4 GHz networks show up in the WiFi network list.
 * (aka 0x5112) does not exist, use the default  instead

Display/GPU
The display tends to be one of the most difficult things to get working. This is because manufacturers have many different options how to implement the display in the hardware. Generally, all devices will have a display panel connected to the SoC via MIPI Display Serial Interface (DSI). The panel can vary even for one device model; it is common to support multiple panels to be more flexible when assembling the device. As if this wasn't enough, panels are usually paired with additional controllers (e.g. for the backlight) or regulators (to provide special power supplies). Those may, or may not need to be controlled from the kernel.

The easy part is usually the panel itself. To make it work we likely only need to send some special DSI commands to initialize it. DSI Panel Driver Porting on the Freedreno wiki has an introduction how to port panels. For MSM8916 mainlining, we have created linux-mdss-dsi-panel-driver-generator which attempts to automatically parse the downstream device tree and generates panel drivers for all the supported panels.

How can you figure out which panel is being used by the device you have? The panel is usually listed in a  kernel parameter provided by the (primary) bootloader. You can check it from the lk2nd log, or using. The parameter lists the name of the panel node in the device tree.

You also need to add the display panel to your device tree. The panel driver generator also generates a device tree fragment in the  file that you can use as a base. Typically you just need to fill in the, which can be found downstream. You should also add pinctrl to the  node. See commits for other devices for examples.

Note: If you have  defined downstream you should add (do not add it if you do not have this property downstream!):

In some cases, you may need to turn on a GPIO to enable the power supply of the panel. On mainline, this is implemented using a fixed regulator, which represents the hw component that creates the required voltage. You can then use the  option in the panel driver generator to add code to automatically turn on that GPIO.

Some devices have an extra backlight IC that needs to be controlled separately in the kernel. The easy case is where it is simply enabled using a GPIO: in this case one can simply treat it like a fixed regulator. (It may, in fact, actually be one.) But some backlight ICs have an I²C interface and then need an extra driver in the kernel.

Brightness
There are different approaches used to dim the brightness of the screen. The approach used in downstream is usually defined by the  property in the panel node of the downstream device tree:


 * Pulse-width modulation (PWM) : In this case there is an external PWM generator that generates a PWM signal for the display. PM8916 (the PMIC of MSM8916) contains one PWM generator that can be configured for the display.  is an example of how to set it up.
 * MIPI DCS commands : In this case the panel controller handles the brightness automatically. The generated panel driver should implement brightness without further changes.
 * Custom: Some devices (e.g. Samsung AMOLED panels) have  or something else listed, but actually use an entirely custom way to control display brightness. This needs to be implemented manually in the panel driver (or using an extra backlight driver).

Touchscreen
The touchscreen is usually connected to an I²C bus, e.g. . Often it is either supplied by some PM8916 regulators or a set of fixed regulators. (This is often visible when the touchscreen has some "enable" GPIOs listed downstream; those usually represent a chip that can be enabled through a GPIO and then supplies a fixed voltage to the touchscreen...) This is where similarities end. There can be all sorts of touchscreens connected to the I²C bus and manufacturers like to use many different ones. Look through the supported touchscreen in mainline to see if a driver exists already, or can be modified eventually to support another version of a similar chip. Otherwise, you may need to write a simple driver yourself.

Sensors
Like the touchscreen, sensors are usually connected to an I²C bus, e.g.  and usually supplied by L17. This is where similarities end. There can be all sorts of sensors connected to the I²C bus and manufacturers like to use many different ones. Look through the supported sensors in mainline to see if a driver exists already, or can be modified eventually to support another version of a similar chip. Otherwise, you may need to write a simple driver yourself.

Some devices have a Hall effect sensor that is used to detect if the screen is covered by some kind of flip cover. It is usually a simple GPIO like the buttons, and can be set up easily using gpio-keys.

Testing

 * The sensor should show up in sysfs . Usually there are some  files you can read for initial testing.
 * Accelerometer: The accelerometer is used for automatic screen rotation, so let's make sure that works correctly.
 * Install  (note: need to restart after installing it), start it  and use.
 * Check if the orientations are reported correctly. See File:PhoneRotation.png for a visualization of the different orientations.
 * If the orientations are not correct you need a  in your device tree. See e.g. [this explanation https://michael-srba.cz/mainline4life/mount-matrix.html].
 * Interrupts: If your sensor has interrupts listed downstream you should also add them on mainline and check if they work correctly.
 * Install, then use   where   is the number of the IIO device in sysfs (e.g..
 * It should continuously print weird values.
 * Check  if some interrupts were triggered for the sensor.

Audio
Audio functionality is split up in 3 main blocks (4 when using the modem):


 * LPASS (Low Power Audio Subsystem): The "sound card". Reads/writes digital audio data from/to memory and transmits it via I²S.
 * Digital Codec : Accepts digital audio via I²S, post-processes it (e.g. to change volume). Transmits it via PDM to analog codec. (A proprietary Qualcomm protocol but perhaps there are similiarities to Pulse-density modulation...)
 * Analog Codec : Integrated into PMIC (PM8916). Contains DACs (playback) and ADCs (capture) and amplifiers for Speaker, Earpiece and Headphones.
 * Audio DSP : Can optionally sit between CPU and LPASS to offload audio decoding (e.g. MP3, AC, ...). Also handles voice call audio.

Here is diagram how the blocks relate to each other:

+-+                                    +-+    +---+
 * MSM8916              GPIO|              Some devices use
 * |             a custom speaker
 * ++                    |Quaternary        amplifier!
 * +---+   | Modem  |    +---+        | MI²S +-+
 * |      |<-->| (ADSP) |<-->|       |<--> 112|<>| Digital     |
 * | Linux |   ++    | LPASS |<--> 117|<>| Audio Codec |--> Speaker
 * | (CPU) |     Memory      |       |<--> 118|<>| + Amplifier |
 * |      |<>|       |<--> 119|<>+-+
 * Primary |  ^ Tertiary |    +---+
 * MI²S |   |   MI²S   |    |    PM8916     |
 * v  |          |PDM |               |
 * +---+<---> 63|<-->|CLK ++|
 * |      |<---> 64|<-->|SYNC |        ||<-- Microphone 1
 * |Digital|<---> 65|<---|TX  | Analog ||<-- Microphone 2
 * | Codec |<---> 66|--->|RX0 | Codec  ||--> Earpiece
 * |      |<---> 67|--->|RX1  |        ||--> Headphones
 * +---+<---> 68|--->|RX2 ++|--> Speaker
 * +---+<---> 68|--->|RX2 ++|--> Speaker

Note: MI²S (multichannel I²S) is basically I²S with multiple data lines. This allows using more audio channels, although this is typically not used on MSM8916.

No Custom Speaker Amplifier
Example with no custom amplifier:

Custom Speaker Amplifier
The analog codec in PM8916 contains a mono Class-D (audio) amplifier. However, there are several devices that do not make use of it. Perhaps because the manufacturer thought it's not powerful enough, or because they wanted to include stereo speakers. In that case they have likely included a custom speaker amplifier. There are two types of this:


 * Digital codec + speaker amplifier: This can be seen in the diagram above. It's connected via the Quaternary MI²S interface and contains it's own digital-to-analog converter (DAC).
 * Sometimes they are just enabled with a GPIO, sometimes (especially TFA* amplifiers from NXP/Goodix) they are controlled via I²S and may even include their own audio DSP.
 * A typical property of these is that it's difficult to control the audio volume in hardware. Instead, the digital audio data needs to be adjusted in software (typically handled by PulseAudio.)
 * You need to add the amplifier to the device tree and then set up a DAI link for Quaternary MI²S.
 * Example with enable GPIO:
 * Example with I²C:  (Note: You typically need a driver specific to your amplifier in this case...)


 * Analog speaker amplifier: This one sits behind the analog codec in PM8916 and just further amplifies the (analog) output signal. The speaker output is not suitable for this so most devices have the speaker amplifier connected additionally to one of the headphones output, i.e.  (left channel) or   (right channel). Typically they are activated using a GPIO. Sometimes there is an extra switch for the headphones as well, to make sure they don't activate when we just want to activate the speaker.
 * You need to add the amplifier to the device tree (and eventually fixed regulators required for it). Then add it as  to the sound card and set up.
 * Example with amplifier connected to HPH_R and extra headphones switch:
 * Example with special amplifier connected to HPH_R without headphones switch:

Testing
Please try to test as many of the features below as possible. If you don't have headphones or a headset you can obviously not test that.


 * Speaker/Earpiece/Headphones audio playback
 * Mic1/Mic2/Headset audio recording
 * Note: Some devices only have one integrated microphone.
 * Enable microphone via ALSA UCM / PulseAudio, then use (for example):, then   and check if you hear something.
 * Audio jack detection
 * Plug in/out headphones and check for  in  . It should be 1 when inserted, 0 otherwise. (Make sure it's not inverted!)
 * Plug in/out headset and check for  additionally.
 * If the headset has buttons, try pressing them and see if they show up in.

Camera
There is the qcom-camss subsystem(1), but per device camera drivers are needed too. For use with Megapixels, support for pipelines aren't implemented yet.

Battery/Charging
Although PM8916 provides a linear charger for batteries only few devices actually make use of it. This might be because it is comparatively inefficient compared to a switching mode battery charger. Therefore most devices actually have custom chips that manage the battery and charging. Usually it is separated in:
 * Fuel gauge: Measures the remaining charge of the battery.
 * Charger: Handles charging the battery.

Similar to the sensors, battery/charger are usually connected to an I²C bus. Look through the supported drivers in mainline to see if a driver exists already, or can be modified eventually to support another version of a similar chip. Compare with the downstream driver just to be sure.

SMB1360
SMB1360 is a combined fuel gauge/charger chip from Qualcomm that was used in some MSM8916 devices. The msm8916-mainline/linux fork has an experimental driver for it that allows checking the battery status and basic charging.


 * There are lots of configuration parameters that should be set correctly to ensure correct battery status reporting and in particular correct and safe charging. Most parameters can be taken over from the downstream device tree, but please check the DT schema to be sure. Also check the existing devices for real examples.
 * Battery detection is often device-specific and is implemented in lk2nd to keep the Linux kernel simple. lk2nd updates the  entry in the device tree with the detected values and enables the smb1360 device node.
 * The following properties are currently intentionally not supported by the mainline driver:
 * : This is implemented in lk2nd. The battery profile related properties should be added to the lk2nd device tree instead.
 * : Please remove the property and use  instead.
 * : Use  instead.
 * : Use  instead.

Manufacturers like to make random changes directly to the C code of the charging driver. Therefore it is possible that even the same device tree configuration can lead to different (and possibly incorrect) behavior when using the mainline driver. To verify that all registers are set as intended it is helpful to compare a register dump of the downstream and the mainline driver (after configuration changes have been applied):


 * Mainline: Enable : During startup the whole register content will be dumped twice to dmesg, once before the driver makes any changes and once after.
 * Downstream:
 * Modified downstream kernel: The smb1360-dump code can be integrated in the downstream kernel, which will produce a register dump identical to the one produced by the mainline driver. See e.g. for an example.
 * DebugFS: This avoids having to recompile the downstream kernel (just need root, e.g. in TWRP), but is less complete. Also it needs post processing to allow for easier comparison with the mainline register dump.

NOTE: SMB1360 remembers configuration changes across reboots as long as the battery is still sufficiently charged. This means that some registers may appear to be set correctly when booting into mainline after downstream, while they would be set incorrectly if mainline was directly booted after a battery removal. To ensure clean results you should reset the SMB1360 immediately before taking each register dump:


 * Temporarily remove/disconnect the battery for a few seconds (PREFERRED if possible). This will reset the SMB1360 completely (both charger and fuel gauge registers).
 * Using  in lk2nd. This will only reset the charger related registers.

Take a clean register once using downstream and once using mainline. Using some post processing you can compare the register dumps with a simple diff tool (TBD: Maybe document the post processing a bit more). For most registers, the downstream register dump should be identical to the second register dump printed in dmesg when using the mainline driver. However, there are some expected differences:


 * Differences in IRQ/status related registers can generally be ignored. They are most likely caused by taking the register dumps in slightly different situations (e.g. USB cable inserted vs not inserted, currently fast charging vs slow charging, ...).
 * The  and   registers change depending on the battery status (remaining percentage, temperature etc). However, look closely at registers in full caps (e.g. FG_THERM_C1_COEFF_REG). Most of these are written by the driver.
 * The  register contents may differ because the mainline driver writes them in a different order. The values in   should be identical, however.
 * bits 0-3 contain the input current limit (more current may be taken from a wall charger compared to an USB port on a PC). Unfortunately, the mainline driver does not implement this functionality at the moment and keeps the input current limit as-is.
 * is used by the  code, it may be different if downstream had both   and   (in which case the temperature monitoring was implemented in software rather than programming the hardware registers).
 * may have additional bits for more interrupt types enabled by the mainline driver.
 * may be off-by-one because the mainline driver rounds differently.

Vibrator
To enable the vibrator simply add

To find out which input device the vibrator is, run  and look for something like. Run   with the event number from the command before (i.e. "Handlers=event3" so /dev/input/event3).

Useful page when messing with haptics: https://www.kernel.org/doc/html/v4.15/input/ff.html

Glossary

 * PM8916
 * The PMIC used together with MSM8916 (and MSM8939).


 * BAM
 * Bus Access Manager, some kind of DMA (Direct Memory Access) engine. Basically it can copy data from memory to devices (e.g. UART, USB, ...) more quickly.


 * BAM DMUX
 * BAM Data Mux, a network protocol built using BAM that is used as a network interface to the modem.


 * BLSP
 * "BAM-enabled low-speed peripheral". Controllers for UART, I²C and SPI.


 * LPASS
 * Low-power audio subsystem


 * MDSS
 * Mobile Display Subsystem - the hardware that manages the display.


 * MDP
 * Mobile Display Processor - Part of MDSS that manages display panels.


 * DSI
 * MIPI Display Serial Interface (DSI) - used for communication with display panel.


 * CAMSS
 * Camera Subsystem


 * SPMI
 * System Power Management Interface - used for communication between MSM8916 and PM8916.

Remote Processors

 * WCNSS
 * Wireless Connectivity Subsystem (WCNSS). Provides WiFi and Bluetooth.


 * Venus
 * Provides hardware-accelerated video encoding/decoding.


 * Modem
 * Provides mobile connectivity and Audio DSP (ADSP). Note: On MSM8916, modem and ADSP are one remote processor, but the ADSP is usually separate on Qualcomm SoCs.


 * Hexagon
 * Microarchitecture for DSPs, used for ADSP/Modem/Sensor Hub/...

Documentation

 * Specifications
 * Snapdragon 410E (APQ8016E) Processor Device Specification
 * PM8916/PM8916-1 Power Management IC Device Specification
 * WCN3620 Wireless Connectivity IC Device Specification
 * WCN3680B/WCN3660B Device Specification
 * Register Descriptions
 * Qualcomm Snapdragon 410E Processor (APQ 8016E) Hardware Register Description
 * PM8916 Hardware Register Description
 * Snapdragon 410E Technical Reference Manual (provides explanations for many hardware blocks)
 * More documentation: APQ8016E Tools & Resources