目录

LLDB Debugger

Overview

Low Level Debugger (LLDB) is a next-generation, high-performance debugger. It can be used to set breakpoints, view and modify variables, perform memory operations, control threads, calculate expressions, backtrack stacks, and support cross-platform and plugin extension.

Developed based on llvm15.0.4, LLDB is the default debugger in DevEco Studio and supports debugging of C and C++ applications.

For details, visit the LLDB official website.

Features

LLDB has the following features:

How to Obtain

Signature verification mechanism:

At runtime, lldb-server verifies its digital signature. Only lldb-servers signed by Huawei can be used to debug applications.

lldb-server is a special version processed by the closed-source signature.

This design is used to protect HarmonyOS debugging permissions and prevent unauthorized debugging.

Functionalities

The following lists some functionalities supported by LLDB. For more commands, see Introduction to LLDB and GDB to LLDB command map. LLDB differs slightly on Windows, Linux x86_64, and macOS.

Environment Setup

root image: Run the hdc shell id command and uid=0(root) is displayed. Alternatively, run the hdc shell command to enter the interactive command environment and the prompt is #.

user image: Run the hdc shell id command and uid=2000(shell) is displayed. Alternatively, run the hdc shell command to enter the interactive command environment and the prompt is $.

SELinux enabled: Run the hdc shell getenforce command and Enforcing is displayed.

SELinux disabled: Run the hdc shell getenforce command and Permissive is displayed.

CAUTION

You are advised to create a native project in DevEco Studio and click the Debug button to automatically push the lldb-server. This avoids version compatibility and permission issues.

Local Debugging

[h2]Using LLDB to Start and Debug Applications

The following walks you through on how to debug an executable file named a.out in HarmonyOS. The file contains debugging information and is generated by the Clang compiler, which is of the same version as LLDB.

Source file: hello.cpp

#include <iostream>
using namespace std;
int main() {
    cout << "hello world!" <<endl;
    return 0;
}

Compilation:

<clang distribution>/bin/clang++ --target=aarch64-linux-ohos --sysroot=<sysroot distribution> -g hello.cpp -o a.out

  1. Obtain the executable file a.out.

  2. Run the hdc shell command to enter the interactive command environment of the mobile phone and access the lldb path.

  3. Run LLDB and specify the file to debug as a.out.

    ./lldb a.out

  4. Set breakpoints at the main function in the code.

    (lldb) b main

  5. Run the application, and it stops at the first breakpoint.

    (lldb) run

  6. Continue to run the application.

    (lldb) continue

  7. List all the breakpoints.

    (lldb) breakpoint list

  8. Show the arguments and local variables of the current frame.

    (lldb) frame variable

  9. Run debugging commands as required to continue debugging.

  10. Exit debugging.

    (lldb) quit

[h2]Using LLDB to Debug Running Applications

The following walks you through on how to debug an executable file named a.out in the mobile phone. The file contains user input and debugging information and is generated by the Clang compiler.

Source file: hello.cpp

#include <iostream>
using namespace std;

int main() {
    int i = 0, j = 5, sum = 0;
    cout << "Please input a number of type int" <<endl;
    cin >> i;
    cout << i;
    sum = i + j;
    cout << sum <<endl;
    return 0;
}

Compilation:

<clang distribution>/bin/clang++ --target=aarch64-linux-ohos --sysroot=<sysroot distribution> -g hello.cpp -o a.out

  1. Run the hdc shell command to enter the interactive command environment of the mobile phone and access the lldb path.

  2. Start the application on CLI 1. (The message "Please input a number of type int" is displayed.)

    ./a.out

  3. Run LLDB on CLI 2.

    ./lldb

  4. Attach to the application.

    (lldb) process attach --name a.out

  5. Set a breakpoint in line 10 of hello.cpp.

    (lldb) breakpoint set --file hello.cpp --line 10

  6. Enter an integer on CLI 1.

    88

  7. Continue to run the application on CLI 2. The application stops at the breakpoint.

    (lldb) continue

  8. Run debugging commands as required to continue debugging.

  9. Detach from the application.

    (lldb) detach

  10. Exit debugging.

    (lldb) quit

You can attach to the application and set breakpoints in whichever order you like.

Remote Debugging

  • Remote debugging refers to cross-device debugging using LLDB. The following describes how to debug applications on HarmonyOS devices across devices.

  • For details about remote debugging based on DevEco Studio, see Starting Debugging.

  • During remote debugging, lldb-server and lldb must be used together.

  • The remote debugging procedures for Windows, Linux x86_64, and macOS are the same.

[h2]Remote Debugging on Root Image

  • The application or binary file to be debugged must be a native C++ project of the aarch64-linux-ohos architecture.

  • You are advised to disable SELinux during debugging.

Source file: hello.cpp

#include <iostream>
using namespace std;
int main() {
    cout << "hello world!" <<endl;
    return 0;
}

Compilation:

<clang distribution>/bin/clang++ --target=aarch64-linux-ohos --sysroot=<sysroot distribution> -g hello.cpp -o a.out

  1. Open CLI 1 and disable SELinux.

    hdc shell setenforce 0

  2. Open CLI 1 and push lldb-server and a.out to the device.

    hdc file send lldb-server hdc file send a.out /data/local/tmp/debugserver/debugserver
hdc shell chmod 755
/data/local/tmp/debugserver/lldb-server /data/local/tmp/debugserver/a.out

  3. Run lldb-server. (8080 is a valid port number that is not in use. You can customize it.)

    hdc shell /data/local/tmp/debugserver/lldb-server p --server --listen "*:8080"

  4. Open CLI 2 and run the binary file lldb.

    ./lldb

  5. Select and connect to the remote device on the LLDB CLI.

    (lldb) platform select remote-ohos
(lldb) platform connect connect://localhost:8080

  6. Specify the binary file a.out on the device to be debugged.

    (lldb) target create /data/local/tmp/debugserver/a.out

  7. Set breakpoints at the main function in the code.

    (lldb) b main

  8. Launch

    (lldb) run

  9. Display source code for the current target process.

    (lldb) source list

  10. Run debugging commands as required to continue debugging.

  11. Exit debugging.

    (lldb) quit

[h2]Remote Debugging on User Image

  • SELinux is enabled by default for the user image and cannot be disabled.

  • You are advised to use HUAWEI DevEco Studio to debug the HAP file of the HarmonyOS device running a user image.

  • lldb-server must be pushed to the specified directory /data/local/tmp/debugserver, for example, /data/local/tmp/debugserver/lldb-server or /data/local/tmp/debugserver/com.example.myapplication/lldb-server.

  • lldb-server is obtained from the aarch64-linux-ohos architecture directory. For details, see Table 1 Directories of the lldb-server tool.

  • In this example, the HAP file is compiled from the native C++ default project created based on DevEco Studio, which contains the debug information.

  • During debugging, ensure that the device is unlocked. The debugger cannot start when the screen is locked.

  1. Open CLI window 1 and push lldb-server and the HAP file to the device.

    hdc shell mkdir data/local/tmp/debugserver/com.example.myapplication
hdc file send lldb-server data/local/tmp/debugserver/com.example.myapplication
hdc shell chmod 755 data/local/tmp/debugserver/com.example.myapplication/lldb-server
hdc shell mkdir data/local/tmp/d333e74fe3ab488aad622a7055fbf396
hdc file send C:\Users\xxx\DevEcoStudioProjects\MyApplication\entry\build\default\outputs\default\entry-default-signed.hap data/local/tmp/d333e74fe3ab488aad622a7055fbf396

  2. Install and run the HAP file, and disable appfreeze.

    hdc shell bm install -p data/local/tmp/d333e74fe3ab488aad622a7055fbf396
hdc shell aa start -a EntryAbility -b com.example.myapplication
hdc shell aa attach -b com.example.myapplication

  3. Run lldb-server.

    hdc shell aa process -a EntryAbility -b com.example.myapplication -D "/data/local/tmp/debugserver/com.example.myapplication/lldb-server platform --listen unix-abstract:///lldb-server/platform.sock"

  4. Open CLI 2 and run the binary file lldb.

    ./lldb

  5. Select and connect to the remote device on the LLDB CLI.

    (lldb) platform select remote-ohos
(lldb) platform connect unix-abstract-connect:///lldb-server/platform.sock

  6. Add the search path of the target executable file.

    (lldb) settings append target.exec-search-paths "C:\Users\xxx\DevEcoStudioProjects\MyApplication\entry\build\default\intermediates\cmake\default\obj\arm64-v8a"

  7. Set a breakpoint at line 6 in the source code.

    (lldb) breakpoint set --file "C:/Users/xxx/DevEcoStudioProjects/MyApplication/entry/src/main/cpp/napi_init.cpp" --line 6

  8. Specify the PID of the application corresponding to the HAP file on the device to be debugged.

    (lldb) attach <pid>

  9. Tap the device application to continue the response. The application stops at the breakpoint.

  10. Continue the debugging.

    (lldb) continue

  11. Show the stack backtrace for the current thread.

    (lldb) bt

  12. Run debugging commands as required to continue debugging.

  13. Exit debugging.

    (lldb) quit

FAQ