Difference between revisions of "ADEB"

[unchecked revision] [quality revision]
(Limitation)
(Limitation)
 

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[1].

For that purpose, the BCC (BPF compiler collection) tool trace is used (see GitHub[2] 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[edit]

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.

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

2 Preparing the kernel[edit]

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[edit]

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[edit]

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[3].

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[edit]

Warning.png 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/
Info.png 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[edit]

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[edit]

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[edit]

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[edit]

6.1 Installing the BCC trace tool[edit]

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[edit]

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[edit]

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

7.1 Saving adeb[edit]

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[edit]

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

PC $> tar -xphf androdeb.tar.bz2

8 Limitation[edit]

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 #BCC trace tool.

9 References[edit]


adeb (also known as androdeb) provides a powerful Linux<sup>&reg;</sup> 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''<ref>https://source.android.com/devices/tech/debug/native_stack_dump</ref>.

For that purpose, the BCC (BPF compiler collection) tool ''trace'' is used (see GitHub<ref>https://github.com/iovisor/bcc</ref> for the list of available BCC tools).

This article is intended for Distribution Package users (see [[Which STM32MPU Embedded Software Package for Android better suits your needs|Which Package better suits your needs]] for more information).

== 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:

 {{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_{{HighlightParam|''<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.}}

== 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/{{HighlightParam|''<STM32Series>''}}/KERNEL_OBJ'''.

=== 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/{{HighlightParam|''<STM32Series>''}}-kernel/linux-{{HighlightParam|''<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 [[STM32MP1_Distribution_Package_for_Android#Flashing_the_built_image|Flashing the built image]]).

== 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<ref>https://android.googlesource.com/platform/external/adeb/+/master/README.md</ref>.

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

== Installing Adeb ==
{{InternalInfo|
Manage the proxy settings if required (ST internal network).
Apply the following patch on adeb module. The user will have to enter '''''<login>:<password>''''':<pre>

From 1690567809940f6c3b8d089cd4d8952412ee936e Mon Sep 17 00:00:00 2001
From: frq09432 <nicolas.louboutin@st.com>

Date: Tue, 20 Aug 2019 11:48:04 +0200
Subject: [PATCH] add proxy management

diff --git a/androdeb b/androdeb
index 3600a5b..212235f 100755
--- a/androdeb
+++ b/androdeb
@@ -330,11 +330,11 @@ fi
 PACKAGES+="$DEFAULT_PACKAGES"
 c_info "Using temporary directory: $TDIR"

-if [[ $EUID -ne 0 ]]; then c_info "The next stage runs as sudo, please enter password if asked."; fi
+if [[ $EUID -ne 0 ]]; then c_info "The next stage runs as sudo -i, please enter password if asked."; fi

 ex_files=$(mktemp); echo $EXTRA_FILES > $ex_files

-sudo $spath/buildstrap $ARCH $DISTRO $TDIR $OUT_TMP \
+sudo -i $spath/buildstrap $ARCH $DISTRO $TDIR $OUT_TMP \
 		"$(make_csv "$PACKAGES")"\
 		$ex_files $INSTALL_BCC $SKIP_DEVICE
 rm $ex_files
diff --git a/buildstrap b/buildstrap
index b33b71e..0b117a7 100755
--- a/buildstrap
+++ b/buildstrap
@@ -14,6 +14,10 @@ INSTALL_BCC=$7
 SKIP_DEVICE=$8		# Skip any device-specific stages
 VARIANT="--variant=minbase"

+export http_proxy=http://<login>:<password>@appgw.gnb.st.com:8080
+export https_proxy=http://<login>:<password>@appgw.gnb.st.com:8080
+export ftp_proxy=http://<login>:<password>@appgw.gnb.st.com:8080
+
 time qemu-debootstrap --arch $ARCH --include=$PACKAGES $VARIANT \
 	$DISTRO $OUT_TMP http://deb.debian.org/debian/

-- 
2.7.4</pre>

}}
{{Warning | 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/{{HighlightParam|''<STM32Series>''}}/KERNEL_OBJ/

{{Info | 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

== Installing BCC tools ==

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

{{Highlight|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

=== Adapting BCC ===

By default, BCC works only on 64-bit architectures and does not support 32-bit ARM<sup>&reg;</sup> 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/{{HighlightParam|''<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

=== 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/{{HighlightParam|''<STM32Series>''}}/KERNEL_OBJ/usr/include/* /data/androdeb/debian/kernel-headers/include/
 {{PC$}} adeb push device/stm/{{HighlightParam|''<STM32Series>''}}-kernel/linux-{{HighlightParam|''<STM32Series>''}}/include/* /data/androdeb/debian/kernel-headers/include/

== BCC trace tool ==

=== 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/{{HighlightParam|''<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

=== 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.

== Backing up adeb ==

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

=== 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

=== Setting up adeb ===
Extract the archive previously created into the '''<mount point>/data/androdeb''' folder:

 {{PC$}} tar -xphf androdeb.tar.bz2

== 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 | BCC trace tool]].

== References ==
<references />

<noinclude>

[[Category:Android tracing tools]]
[[Category:Android]]
{{PublicationRequestId | 13253 | 2019-09-12}}</noinclude>
Line 225: Line 225:
   
 
Since the pointer size has to be redefined, some modifications are required to be able to use the BCC tools that use kernel headers.
 
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]].
+
Apply the same kind of modifications as described in [[#BCC trace tool | BCC trace tool]].
   
 
== References ==
 
== References ==

Attachments

Discussions