1# FaultLoggerd 2 3- Introduction 4- Architecture 5- Directory Structure 6- How to Use 7 - DumpCatcher 8 - ProcessDump 9- Service Process 10 - DumpCatcher SDK Service Process 11 - ProcessDump Service Process 12 - Process Crash Service Process 13- Repositories Involved 14 15## Introduction 16 17Faultloggerd is a component that generates and manages temporary C/C++ runtime crash logs in OpenHarmony. You can find crash logs in the preset directory to locate faults. 18 19## Architecture 20 21 22 23* SignalHandler: signal handler, which receives system exception signals and triggers the capture of process exception information. 24* DumpCatcher: stack information capture tool, which provides the function of capturing stack information of the specified process and thread. 25* FaultloggerdClient: temporary crash log management client, which receives requests for file descriptors and stack exporting. 26* ProcessDump: binary tool for capturing process information, which provides the function of capturing stack information of the specified process and thread in command line mode. 27* Crasher: crash constructor, which constructs and simulates crashes. 28* FaultloggerdServer: core service processing module, which receives and processes requests from FaultloggerdClient. 29* FaultloggerdSecure: permission verification module, which provides permission management and verification for runtime crash log generation and capture. 30* FaultloggerdConfig: temporary crash log management module. 31 32The following table describes the exception signals that can be processed. 33 34| Signal Value| Signal | Description | Cause | 35| ------ | --------- | --------------- | ------------------------------------------------------------ | 36| 4 | SIGILL | Invalid instruction | The executable file incurs an error or attempts to execute a data segment. This signal may also be generated in the case of stack overflow.| 37| 5 | SIGTRAP | Breakpoint or trap | A breakpoint instruction or any other trap instruction is executed. | 38| 6 | SIGABRT | Abort signal| The abort function is called. | 39| 7 | SIGBUS | Illegal memory access | Invalid address, including memory address alignment error, is identified. For example, accessing an integer of four digits at an address not divisible by four. The difference between SIGBUS and SIGSEGV is that SIGSEGV is triggered by unauthorized access to valid storage addresses (for example, access to storage space that is read only or does not belong to the process).| 40| 8 | SIGFPE | Floating-point exception | A fatal arithmetic error, for example, floating-point arithmetic error, division overflow, or division by 0, has occurred.| 41| 11 | SIGSEGV | Invalid memory access | The process attempts to access memory that is not allocated to itself, or write data to a memory address that does not have the write permission.| 42| 16 | SIGSTKFLT | Stack overflow | The stack overflows. | 43| 31 | SIGSYS | System call exception | An invalid system call is initiated. | 44 45## Directory Structure 46 47```txt 48faultloggerd/ 49├── OAT.xml 50├── common # Common definitions 51├── faultloggerd.gni 52├── interfaces # APIs 53│ └── innerkits 54│ ├── dump_catcher # Stack information capture tool 55│ ├── faultloggerd_client # Temporary crash log management client 56│ └── signal_handler # Signal handler 57├── ohos.build 58├── services # FaultLoggerd services 59│ ├── BUILD.gn 60│ ├── config # Startup configuration 61│ ├── fault_logger_config.cpp # Log file management 62│ ├── fault_logger_config.h # Log file management 63│ ├── fault_logger_daemon.cpp # Faultloggerd service implementation 64│ ├── fault_logger_daemon.h # Faultloggerd service implementation 65│ ├── fault_logger_secure.cpp # Permission management and verification 66│ ├── fault_logger_secure.h # Permission management and verification 67│ ├── main.cpp 68│ └── test 69├── test # Test resources 70│ ├── BUILD.gn 71│ ├── fuzztest # Fuzz test 72│ ├── performancetest # Performance test 73│ └── systemtest # System function test 74└── tools # Tools 75 ├── crasher_c # Crash constructor (C) 76 ├── crasher_cpp # Crash constructor (C++) 77 └── process_dump # Process information capture tool 78``` 79 80## How to Use 81 82### DumpCatcher 83 84DumpCatcher allows an application to capture call stack information. It provides the API for printing stack information of the specified process and thread. 85 86Interface class: `DfxDumpCatcher` 87 88Interface method: `bool DumpCatch(const int pid, const int tid, std::string& msg);` 89 90Parameters: 91 92* Return value: 93 * `true`: Dumping of stack information is successful. Related information is stored in the `msg` string object. 94 * `false`: Dumping of stack information has failed. 95* Input parameters: 96 * `pid`: ID of the process for dumping stack information. If all threads in the process need to be back traced, set `tid` to **0**. 97 * `tid`: ID of the thread for dumping stack information. 98* Output parameters: 99 * `msg`: dumping result. 100 101> Note: Only the administrator (**system** or **root**) is allowed to capture all process information. Common users can only capture information on their own processes. To capture call stack information of a process that does not belong to the current user group, ensure that you have permissions to read **/proc/pid/maps** and implement **ptrace** on the target process. 102 103Sample Code 104 105* dump_catcher_demo.h 106 107```c++ 108#ifndef DUMP_CATCHER_DEMO_H 109#define DUMP_CATCHER_DEMO_H 110 111#include <inttypes.h> 112 113#define NOINLINE __attribute__((noinline)) 114 115#define GEN_TEST_FUNCTION(FuncNumA, FuncNumB) \ 116 __attribute__((noinline)) int TestFunc##FuncNumA() \ 117 { \ 118 return TestFunc##FuncNumB(); \ 119 } 120 121// Test functions for callstack depth test 122int TestFunc0(void); 123int TestFunc1(void); 124int TestFunc2(void); 125int TestFunc3(void); 126int TestFunc4(void); 127int TestFunc5(void); 128int TestFunc6(void); 129int TestFunc7(void); 130int TestFunc8(void); 131int TestFunc9(void); 132int TestFunc10(void); 133 134#endif // DUMP_CATCHER_DEMO_H 135``` 136 137 * dump_catcher_demo.cpp 138 139```c++ 140#include "dump_catcher_dump.h" 141 142#include <iostream> 143#include <string> 144#include <unistd.h> 145#include "dfx_dump_catcher.h" 146using namespace std; 147 148NOINLINE int TestFunc10(void) 149{ 150 OHOS::HiviewDFX::DfxDumpCatcher dumplog; 151 string msg = ""; 152 bool ret = dumplog.DumpCatch(getpid(), gettid(), msg); 153 if (ret) { 154 cout << msg << endl; 155 } 156 return 0; 157} 158 159// auto gen function 160GEN_TEST_FUNCTION(0, 1) 161GEN_TEST_FUNCTION(1, 2) 162GEN_TEST_FUNCTION(2, 3) 163GEN_TEST_FUNCTION(3, 4) 164GEN_TEST_FUNCTION(4, 5) 165GEN_TEST_FUNCTION(5, 6) 166GEN_TEST_FUNCTION(6, 7) 167GEN_TEST_FUNCTION(7, 8) 168GEN_TEST_FUNCTION(8, 9) 169GEN_TEST_FUNCTION(9, 10) 170 171int main(int argc, char *argv[]) 172{ 173 TestFunc0(); 174 return 0; 175} 176``` 177 178* Sample **BUILD.gn** file: 179 180```gn 181import("//base/hiviewdfx/faultloggerd/faultloggerd.gni") 182import("//build/ohos.gni") 183 184config("dumpcatcherdemo_config") { 185 visibility = [ ":*" ] 186 187 include_dirs = [ 188 ".", 189 "//utils/native/base/include", 190 "//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher/include/", 191 ] 192} 193 194ohos_executable("dumpcatcherdemo") { 195 sources = [ "dump_catcher_demo.cpp" ] 196 197 configs = [ ":dumpcatcherdemo_config" ] 198 199 deps = [ 200 "//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher:libdfx_dumpcatcher", 201 "//utils/native/base:utils", 202 ] 203 204 external_deps = [ "hilog:libhilog" ] 205 206 install_enable = true 207 part_name = "faultloggerd" 208 subsystem_name = "hiviewdfx" 209} 210``` 211 212* Execution result: 213 214```txt 215# ./dumpcatcherdemo 216#00 pc 0000000000000981(00000000004a8981) /data/test/dumpcatcherdemo 217#01 pc 0000000000000a6d(00000000004a8a6d) /data/test/dumpcatcherdemo 218#02 pc 0000000000000a63(00000000004a8a63) /data/test/dumpcatcherdemo 219#03 pc 0000000000000a59(00000000004a8a59) /data/test/dumpcatcherdemo 220#04 pc 0000000000000a4f(00000000004a8a4f) /data/test/dumpcatcherdemo 221#05 pc 0000000000000a45(00000000004a8a45) /data/test/dumpcatcherdemo 222#06 pc 0000000000000a3b(00000000004a8a3b) /data/test/dumpcatcherdemo 223#07 pc 0000000000000a31(00000000004a8a31) /data/test/dumpcatcherdemo 224#08 pc 0000000000000a27(00000000004a8a27) /data/test/dumpcatcherdemo 225#09 pc 0000000000000a1d(00000000004a8a1d) /data/test/dumpcatcherdemo 226#10 pc 0000000000000a13(00000000004a8a13) /data/test/dumpcatcherdemo 227#11 pc 0000000000000a77(00000000004a8a77) /data/test/dumpcatcherdemo 228#12 pc 00000000000c2b08(00000000b6fafb08) /system/lib/ld-musl-arm.so.1(__libc_start_main+116) 229#13 pc 0000000000000938(00000000004a8938) /data/test/dumpcatcherdemo 230#14 pc 00000000000008c4(00000000004a88c4) /data/test/dumpcatcherdemo 231``` 232 233### ProcessDump 234 235ProcessDump is a command line tool provided for users to capture call stack information. This tool uses the `-p` and `-t` parameters to specify the target process and thread. After command execution is complete, it displays the thread stack information of the specified process in the command line window. 236 237Tool name: `processdump` 238 239Location: `/system/bin` 240 241Parameters: 242 243* `-p [pid]`: prints all thread stack information of the specified process. 244* `-p [pid] -t [tid]`: prints information about the specified thread of a process. 245 246Return result: Stack information parsed. 247 248> Note: Only the administrator (**system** or **root**) is allowed to use this API. 249 250Example: querying call stack information of the Hiview main thread 251 252```txt 253# ps -A | grep hiview 254 114 ? 00:00:00 hiview 255# processdump -p 114 -t 114 256Tid:114, Name:hiview 257#00 pc 0000000000089824(00000000b6f44824) /system/lib/ld-musl-arm.so.1(ioctl+68) 258#01 pc 000000000002a709(00000000b6c56709) /system/lib/libipc_core.z.so(_ZN4OHOS15BinderConnector11WriteBinderEmPv+16) 259#02 pc 000000000002ba75(00000000b6c57a75) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker18TransactWithDriverEb+224) 260#03 pc 000000000002bb37(00000000b6c57b37) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker13StartWorkLoopEv+22) 261#04 pc 000000000002c211(00000000b6c58211) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker10JoinThreadEb+36) 262#05 pc 0000000000038d07(00000000004bcd07) /system/bin/hiview(_ZNSt3__h6vectorINS_9sub_matchINS_11__wrap_iterIPKcEEEENS_9allocatorIS6_EEE8__appendEj+596) 263#06 pc 0000000000028655(00000000004ac655) /system/bin/hiview 264#07 pc 00000000000c2b08(00000000b6f7db08) /system/lib/ld-musl-arm.so.1(__libc_start_main+116) 265#08 pc 00000000000285f4(00000000004ac5f4) /system/bin/hiview 266#09 pc 0000000000028580(00000000004ac580) /system/bin/hiview 267``` 268 269## Service Process 270 271### DumpCatcher SDK Service Process 272 273 274 2751. Process A invokes the `DumpCatch()` API provided by `DumpCatcher` to request for dumping stack information of the specified process and thread. 2762. After receiving the dumping request from process A, `DumpCatcher` runs `ProcessDump` to obtain the stack information. 2773. `ProcessDump` requests permission verification from `Faultloggerd`. 2784. If the permission verification is successful, `Faultloggerd` returns a file descriptor to `ProcessDump`. `ProcessDump` then sends the dumping result to `DumpCatcher`. 279 280### ProcessDump Service Process 281 282 283 2841. `Shell` runs the `processdump -p [pid] -t [tid]` command to request for dumping stack information of the specified process and thread. 2852. `ProcessDump` requests permission verification from `Faultloggerd`. 2863. If the permission verification is successful, `Faultloggerd` returns a file descriptor to `ProcessDump`. `ProcessDump` then writes the dumping result to the standard output. 287 288### Faultloggerd Service Process 289 290 291 2921. Process B calls the `DFX_SignalHandler` function to detect crash exception signals from `SignalHandler`. 2932. When detecting a crash exception signal, `SignalHandler` forks a child process and runs `ProcessDump` to dump the stack information of the crashed process and thread. 2943. After reading the stack information, `ProcessDump` writes logs to the temporary storage directory in `Faultloggerd`. 2954. `Faultloggerd` calls `AddFaultLog()` to report the fault to `Hiview` for subsequent processing. 296 297 298## Repositories Involved 299 300[DFX Subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/dfx.md) 301 302[hiviewdfx\_hiview](https://gitee.com/openharmony/hiviewdfx_hiview/blob/master/README.md) 303 304[hiviewdfx\_hilog](https://gitee.com/openharmony/hiviewdfx_hilog/blob/master/README.md) 305 306[hiviewdfx\_hiappevent](https://gitee.com/openharmony/hiviewdfx_hiappevent/blob/master/README.md) 307 308[hiviewdfx\_hisysevent](https://gitee.com/openharmony/hiviewdfx_hisysevent/blob/master/README.md) 309 310**hiviewdfx\_faultloggerd** 311 312[hiviewdfx\_hilog\_lite](https://gitee.com/openharmony/hiviewdfx_hilog_lite/blob/master/README.md) 313 314[hiviewdfx\_hievent\_lite](https://gitee.com/openharmony/hiviewdfx_hievent_lite/blob/master/README.md) 315 316[hiviewdfx\_hiview\_lite](https://gitee.com/openharmony/hiviewdfx_hiview_lite/blob/master/README.md) 317
