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│ └── systemtest # System function test 73└── tools # Tools 74 ├── crasher_c # Crash constructor (C) 75 ├── crasher_cpp # Crash constructor (C++) 76 └── process_dump # Process information capture tool 77``` 78 79## How to Use 80 81### DumpCatcher 82 83DumpCatcher allows an application to capture call stack information. It provides the API for printing stack information of the specified process and thread. 84 85Interface class: `DfxDumpCatcher` 86 87Interface method: `bool DumpCatch(const int pid, const int tid, std::string& msg);` 88 89Parameters: 90 91* Return value: 92 * `true`: Dumping of stack information is successful. Related information is stored in the `msg` string object. 93 * `false`: Dumping of stack information has failed. 94* Input parameters: 95 * `pid`: ID of the process for dumping stack information. If all threads in the process need to be back traced, set `tid` to **0**. 96 * `tid`: ID of the thread for dumping stack information. 97* Output parameters: 98 * `msg`: dumping result. 99 100> 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. 101 102Sample Code 103 104* dump_catcher_demo.h 105 106```c++ 107#ifndef DUMP_CATCHER_DEMO_H 108#define DUMP_CATCHER_DEMO_H 109 110#include <inttypes.h> 111 112#define NOINLINE __attribute__((noinline)) 113 114#define GEN_TEST_FUNCTION(FuncNumA, FuncNumB) \ 115 __attribute__((noinline)) int TestFunc##FuncNumA() \ 116 { \ 117 return TestFunc##FuncNumB(); \ 118 } 119 120// Test functions for callstack depth test 121int TestFunc0(void); 122int TestFunc1(void); 123int TestFunc2(void); 124int TestFunc3(void); 125int TestFunc4(void); 126int TestFunc5(void); 127int TestFunc6(void); 128int TestFunc7(void); 129int TestFunc8(void); 130int TestFunc9(void); 131int TestFunc10(void); 132 133#endif // DUMP_CATCHER_DEMO_H 134``` 135 136 * dump_catcher_demo.cpp 137 138```c++ 139#include "dump_catcher_dump.h" 140 141#include <iostream> 142#include <string> 143#include <unistd.h> 144#include "dfx_dump_catcher.h" 145using namespace std; 146 147NOINLINE int TestFunc10(void) 148{ 149 OHOS::HiviewDFX::DfxDumpCatcher dumplog; 150 string msg = ""; 151 bool ret = dumplog.DumpCatch(getpid(), gettid(), msg); 152 if (ret) { 153 cout << msg << endl; 154 } 155 return 0; 156} 157 158// auto gen function 159GEN_TEST_FUNCTION(0, 1) 160GEN_TEST_FUNCTION(1, 2) 161GEN_TEST_FUNCTION(2, 3) 162GEN_TEST_FUNCTION(3, 4) 163GEN_TEST_FUNCTION(4, 5) 164GEN_TEST_FUNCTION(5, 6) 165GEN_TEST_FUNCTION(6, 7) 166GEN_TEST_FUNCTION(7, 8) 167GEN_TEST_FUNCTION(8, 9) 168GEN_TEST_FUNCTION(9, 10) 169 170int main(int argc, char *argv[]) 171{ 172 TestFunc0(); 173 return 0; 174} 175``` 176 177* Sample **BUILD.gn** file: 178 179```gn 180import("//base/hiviewdfx/faultloggerd/faultloggerd.gni") 181import("//build/ohos.gni") 182 183config("dumpcatcherdemo_config") { 184 visibility = [ ":*" ] 185 186 include_dirs = [ 187 ".", 188 "//utils/native/base/include", 189 "//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher/include/", 190 ] 191} 192 193ohos_executable("dumpcatcherdemo") { 194 sources = [ "dump_catcher_demo.cpp" ] 195 196 configs = [ ":dumpcatcherdemo_config" ] 197 198 deps = [ 199 "//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher:libdfx_dumpcatcher", 200 "//utils/native/base:utils", 201 ] 202 203 external_deps = [ "hilog:libhilog" ] 204 205 install_enable = true 206 part_name = "faultloggerd" 207 subsystem_name = "hiviewdfx" 208} 209``` 210 211* Execution result: 212 213```txt 214# ./dumpcatcherdemo 215#00 pc 0000000000000981(00000000004a8981) /data/test/dumpcatcherdemo 216#01 pc 0000000000000a6d(00000000004a8a6d) /data/test/dumpcatcherdemo 217#02 pc 0000000000000a63(00000000004a8a63) /data/test/dumpcatcherdemo 218#03 pc 0000000000000a59(00000000004a8a59) /data/test/dumpcatcherdemo 219#04 pc 0000000000000a4f(00000000004a8a4f) /data/test/dumpcatcherdemo 220#05 pc 0000000000000a45(00000000004a8a45) /data/test/dumpcatcherdemo 221#06 pc 0000000000000a3b(00000000004a8a3b) /data/test/dumpcatcherdemo 222#07 pc 0000000000000a31(00000000004a8a31) /data/test/dumpcatcherdemo 223#08 pc 0000000000000a27(00000000004a8a27) /data/test/dumpcatcherdemo 224#09 pc 0000000000000a1d(00000000004a8a1d) /data/test/dumpcatcherdemo 225#10 pc 0000000000000a13(00000000004a8a13) /data/test/dumpcatcherdemo 226#11 pc 0000000000000a77(00000000004a8a77) /data/test/dumpcatcherdemo 227#12 pc 00000000000c2b08(00000000b6fafb08) /system/lib/ld-musl-arm.so.1(__libc_start_main+116) 228#13 pc 0000000000000938(00000000004a8938) /data/test/dumpcatcherdemo 229#14 pc 00000000000008c4(00000000004a88c4) /data/test/dumpcatcherdemo 230``` 231 232### ProcessDump 233 234ProcessDump 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. 235 236Tool name: `processdump` 237 238Location: `/system/bin` 239 240Parameters: 241 242* `-p [pid]`: prints all thread stack information of the specified process. 243* `-p [pid] -t [tid]`: prints information about the specified thread of a process. 244 245Return result: Stack information parsed. 246 247> Note: Only the administrator (**system** or **root**) is allowed to use this API. 248 249Example: querying call stack information of the Hiview main thread 250 251```txt 252# ps -A | grep hiview 253 114 ? 00:00:00 hiview 254# processdump -p 114 -t 114 255Tid:114, Name:hiview 256#00 pc 0000000000089824(00000000b6f44824) /system/lib/ld-musl-arm.so.1(ioctl+68) 257#01 pc 000000000002a709(00000000b6c56709) /system/lib/libipc_core.z.so(_ZN4OHOS15BinderConnector11WriteBinderEmPv+16) 258#02 pc 000000000002ba75(00000000b6c57a75) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker18TransactWithDriverEb+224) 259#03 pc 000000000002bb37(00000000b6c57b37) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker13StartWorkLoopEv+22) 260#04 pc 000000000002c211(00000000b6c58211) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker10JoinThreadEb+36) 261#05 pc 0000000000038d07(00000000004bcd07) /system/bin/hiview(_ZNSt3__h6vectorINS_9sub_matchINS_11__wrap_iterIPKcEEEENS_9allocatorIS6_EEE8__appendEj+596) 262#06 pc 0000000000028655(00000000004ac655) /system/bin/hiview 263#07 pc 00000000000c2b08(00000000b6f7db08) /system/lib/ld-musl-arm.so.1(__libc_start_main+116) 264#08 pc 00000000000285f4(00000000004ac5f4) /system/bin/hiview 265#09 pc 0000000000028580(00000000004ac580) /system/bin/hiview 266``` 267 268## Service Process 269 270### DumpCatcher SDK Service Process 271 272 273 2741. Process A invokes the `DumpCatch()` API provided by `DumpCatcher` to request for dumping stack information of the specified process and thread. 2752. After receiving the dumping request from process A, `DumpCatcher` runs `ProcessDump` to obtain the stack information. 2763. `ProcessDump` requests permission verification from `Faultloggerd`. 2774. If the permission verification is successful, `Faultloggerd` returns a file descriptor to `ProcessDump`. `ProcessDump` then sends the dumping result to `DumpCatcher`. 278 279### ProcessDump Service Process 280 281 282 2831. `Shell` runs the `processdump -p [pid] -t [tid]` command to request for dumping stack information of the specified process and thread. 2842. `ProcessDump` requests permission verification from `Faultloggerd`. 2853. If the permission verification is successful, `Faultloggerd` returns a file descriptor to `ProcessDump`. `ProcessDump` then writes the dumping result to the standard output. 286 287### Faultloggerd Service Process 288 289 290 2911. Process B calls the `DFX_SignalHandler` function to detect crash exception signals from `SignalHandler`. 2922. 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. 2933. After reading the stack information, `ProcessDump` writes logs to the temporary storage directory in `Faultloggerd`. 2944. `Faultloggerd` calls `AddFaultLog()` to report the fault to `Hiview` for subsequent processing. 295 296 297## Repositories Involved 298 299[DFX Subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/dfx.md) 300 301[hiviewdfx\_hiview](https://gitee.com/openharmony/hiviewdfx_hiview/blob/master/README.md) 302 303[hiviewdfx\_hilog](https://gitee.com/openharmony/hiviewdfx_hilog/blob/master/README.md) 304 305[hiviewdfx\_hiappevent](https://gitee.com/openharmony/hiviewdfx_hiappevent/blob/master/README.md) 306 307[hiviewdfx\_hisysevent](https://gitee.com/openharmony/hiviewdfx_hisysevent/blob/master/README.md) 308 309**hiviewdfx\_faultloggerd** 310 311[hiviewdfx\_hilog\_lite](https://gitee.com/openharmony/hiviewdfx_hilog_lite/blob/master/README.md) 312 313[hiviewdfx\_hievent\_lite](https://gitee.com/openharmony/hiviewdfx_hievent_lite/blob/master/README.md) 314 315[hiviewdfx\_hiview\_lite](https://gitee.com/openharmony/hiviewdfx_hiview_lite/blob/master/README.md) 316
