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
- 2 Preparing the kernel
- 3 Initializing adeb
- 4 Installing Adeb
- 5 Installing BCC tools
- 6 BCC trace tool
- 7 Backing up adeb
- 8 Limitation
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:
PC $> 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:
PC $> source build/envsetup.sh PC $> lunch aosp-<BoardId>-userdebug
You must have administrator rights on your machine to be able to execute commands.
|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:
PC $> load_kernel PC $> 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:
PC $> cd device/stm/<STM32Series>-kernel/linux-<STM32Series> PC $> git am ../source/patch/4.19/0999-add-SELinux-denial-tracepoint.patch
Rebuild the kernel and regenerate the boot image:
PC $> cd $ANDROID_BUILD_TOP PC $> build_kernel -i PC $> 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:
PC $> cd external
Then clone the git:
PC $> git clone https://android.googlesource.com/platform/external/adeb PC $> 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:
PC $> sudo ln -s $(pwd)/adeb /usr/bin/adeb
4 Installing Adeb
|You need a device powered on with Android connected to the computer and accessible via ADB.|
PC $> adeb prepare --build --arch armhf --kernelsrc out-bsp/<STM32Series>/KERNEL_OBJ/
|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:
PC $> 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:
PC $> adeb push device/stm/<STM32Series>/patch/bcc/0001-arm-make-bcc-32-bits-compatible.patch PC $> 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:
PC $> adeb push out-bsp/<STM32Series>/KERNEL_OBJ/usr/include/* /data/androdeb/debian/kernel-headers/include/ PC $> 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:
PC $> adeb push device/stm/<STM32Series>/patch/bcc/0001-trace-update-headers-to-make-trace-work-with-BCC-32-.patch PC $> 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:
PC $> 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:
PC $> tar -xphf androdeb.tar.bz2
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 - NEW
Android debug bridge (Android specific)