ADEB

adeb (also known as androdeb) provides a powerful Linux^® shell environment where one can run popular and mainstream Linux tracing, compiling, editing and other development tools on an existing Android device. All the commands typically available on a modern Linux system are supported in adeb.

The adeb project installs a chroot environment on your Android device to help debugging.

This article shows how to install and use adeb with an 32-bit ARM device to help debugging SELinux denial.

For that purpose, the BCC (BPF compiler collection) tool trace is used (see GitHub for the list of available BCC tools).

This article is intended for Distribution Package users (see Which Package better suits your needs for more information).

1. Prerequisites

The environment must be installed using the Distribution Package adapted to the selected microprocessor device (see STM32MP1 Distribution Package for Android).

Download the kernel sources as explained in How to build kernel for Android.

Install the following packages to generate adeb:

 sudo apt-get install debootstrap qemu-user-static schroot

Execute the following instructions from the distribution root directory STM32MP1 Distribution Package for Android, initialize your environment, and then launch the following commands:

 source build/envsetup.sh
 lunch aosp_<BoardId>-userdebug

You must have administrator rights on your machine to be able to execute commands.

Warning

An 8 Gbit SD card is required to be able to use adeb.

2. Preparing the kernel

First get the kernel source and compile it as explain in How to build kernel for Android:

 load_kernel
 build_kernel -i

The compilation output is available under out-bsp/<STM32Series>/KERNEL_OBJ.

2.1. Customizing the kernel for BCC

First add a tracepoint at the point where an SELinux denial is logged in the kernel.

For that purpose, apply the 0999-add-SELinux-denial-tracepoint.patch patch on the kernel source:

 cd device/stm/<STM32Series>-kernel/linux-<STM32Series>
 git am ../source/patch/4.19/0999-add-SELinux-denial-tracepoint.patch

Rebuild the kernel and regenerate the boot image:

 cd $ANDROID_BUILD_TOP
 build_kernel -i
 make -j

Then flash the boot partition (see Flashing the built image).

3. Initializing adeb

If the adeb repository is not already available, retrieve it and store it in the external folder from the distribution:

 cd external

Then clone the git:

 git clone https://android.googlesource.com/platform/external/adeb
 cd adeb

For troubleshooting tips, read the adeb README.md.

To make adeb executable everywhere, add adeb location in $PATH or create a sym link to the adeb executable:

 sudo ln -s $(pwd)/adeb /usr/bin/adeb

4. Installing Adeb

Warning

You need a device powered on with Android connected to the computer and accessible via ADB.

 adeb prepare --build --arch armhf --kernelsrc out-bsp/<STM32Series>/KERNEL_OBJ/

Information

A sudo password might be requested.

A chroot debian environment will be pushed on the board.

Once adeb installed, we can use it by running the following command:

 adeb shell

5. Installing BCC tools

Prior to installing the BCC tools, some dependencies must be installed in the debian.

Your board must have access to internet to be able to retrieve packages:

Adeb $> apt update
Adeb $> apt install git cmake clang-6.0 libclang-6.0-dev libelf-dev bison flex build-essential

Once all dependencies are installed, clone the BCC repository using the following command:

Adeb $> git clone https://github.com/iovisor/bcc

5.1. Adapting BCC

By default, BCC works only on 64-bit architectures and does not support 32-bit ARM^® devices:

Adeb $> cd bcc
Adeb $> git checkout 1a47a9a
Adeb $> exit

Push the 0001-arm-make-bcc-32-bits-compatible.patch file:

 adeb push device/stm/<STM32Series>/patch/bcc/0001-arm-make-bcc-32-bits-compatible.patch
 adeb shell

Adeb $> cd bcc
Adeb $> git apply ../0001-arm-make-bcc-32-bits-compatible.patch

5.2. Compiling BCC

It is recommended to create a swap to be able to compile BCC:

Adeb $> dd if=/dev/zero of=/data/swapfile bs=1M count=400
Adeb $> mkswap /data/swapfile
Adeb $> swapon /data/swapfile

Install the BCC trace tool with CMake by using the following command in the bcc repo root directory:

Adeb $> mkdir build && cd build && CXX=/usr/bin/clang++-6.0 cmake .. -DCMAKE_INSTALL_PREFIX=/usr
Adeb $> make && make install

The BCC tools use some kernel headers that need to be provided in the androdeb environment. To do so, push the kernel headers from the kernel source to the kernel-header folder of the debian environment:

 adeb push out-bsp/<STM32Series>/KERNEL_OBJ/usr/include/* /data/androdeb/debian/kernel-headers/include/
 adeb push device/stm/<STM32Series>-kernel/linux-<STM32Series>/include/* /data/androdeb/debian/kernel-headers/include/

6. BCC trace tool

6.1. Installing the BCC trace tool

The BCC trace tool auto-generates the code that is compiled into eBPF.

The generated code uses kernel headers that are now incompatible with our patched BCC. Update the trace tool to use the headers rewritten with our own types.

Push the file 0001-trace-update-headers-to-make-trace-work-with-BCC-32-.patch:

 adeb push device/stm/<STM32Series>/patch/bcc/0001-trace-update-headers-to-make-trace-work-with-BCC-32-.patch
 adeb shell

Adeb $> cd bcc
Adeb $> git apply ../0001-trace-update-headers-to-make-trace-work-with-BCC-32-.patch

This patch simply replaces the kernel header used in the generated eBPF code by our own rewritten headers with the define statements and structures required by the generated code.

Then reinstall the trace tool by launching the following commands:

Adeb $> cd build
Adeb $> make && make install

6.2. Using the BCC trace tool

To launch the BCC trace tool, simply run the following command:

Adeb $> trace -K -U 't:selinux:selinux_denied'

The BCC trace tool now prints the user and kernel callstack every time an SELinux denied is raised.

7. Backing up adeb

The adeb folder can be backed up in order to deploy it faster next times.

7.1. Saving adeb

First mount the userdata partition on your computer. Create the androdeb archive wherever you want:

 tar -cpf androdeb.tar.bz2 <mount point>/data/androdeb

7.2. Setting up adeb

Extract the archive previously created into the <mount point>/data/androdeb folder:

 tar -xphf androdeb.tar.bz2

8. Limitation

Since the pointer size has to be redefined, some modifications are required to be able to use the BCC tools that use kernel headers. Apply the same kind of modifications as described in BCC trace tool.

BPF compiler collection

eval,disco (Generic term used, to complete configuration modules paths depending on used board)

SD memory card (https://www.sdcard.org)

stm32mp1

Android debug bridge (Android specific)

BPF compiler collection

eval,disco (Generic term used, to complete configuration modules paths depending on used board)

SD memory card (https://www.sdcard.org)

stm32mp1

Android debug bridge (Android specific)

Secure digital