1.. _usercrash_doc:
2
3Usercrash
4#########
5
6Description
7***********
8
9The ``usercrash`` tool gets the crash information for the crashing process in
10user space. The collected information is saved as usercrash_xx under
11``/var/log/usercrashes/``.
12
13Design
14******
15
16``usercrash`` is designed using a  client/server model. The server is
17autostarted at boot. The client is configured in ``core_pattern``, which
18will be triggered when a crash occurs in user space. The client then
19sends the crash event to the server. The server checks the files under
20``/var/log/usercrashes/`` and creates a file usercrash_xx (xx means
21the index of the crash file).  Then it sends the file descriptor (fd) to
22the client. The client collects the crash information
23and saves it in the crash file. After the saving work is done, the
24client notifies the server. The server cleans up.
25
26The workflow diagram:
27
28::
29
30   +--------------------------------------------------+
31   |                                                  |
32   |        Server                    Client          |
33   |           +                         +            |
34   |           |  Send crash event       |            |
35   |           | <-----------------------+            |
36   |           |                         |            |
37   |    Create usercrash_xx              |            |
38   |           |                         |            |
39   |           | Send usercrash_xx fd    |            |
40   |           +-----------------------> |            |
41   |           |                         |            |
42   |           |                   Fill usercrash_xx  |
43   |           |                         |            |
44   |           |  Notify completion      |            |
45   |           | <-----------------------+            |
46   |           |                         |            |
47   |       Clean up                      |            |
48   |           |                         |            |
49   |           v                         v            |
50   |                                                  |
51   +--------------------------------------------------+
52
53Usage
54*****
55
56- The server is launched automatically at boot after this tool is enabled with
57  instruction ``sudo crashlogctl enable``, and the client is configured in
58  ``usercrash-wrapper``, which is set as the app of ``core_pattern``. In
59  ``usercrash-wrapper``, it will collect and reorder the parameters of the
60  client and default app. Once a crash occurs in user space, the client and
61  default app will be invoked separately.
62
63- The ``debugger`` is an independent tool to dump the debugging information of the
64  specific process, including backtrace, stack, opened files, register values,
65  and memory content around registers.
66
67.. code-block:: none
68
69   $ debugger <pid>
70
71.. note::
72
73   You need to be ``root`` to use the ``debugger``.
74
75Source Code
76***********
77
78- client.c : This file is the implementation for the client of ``usercrash``.
79  The client is responsible for delivering the ``usercrash`` event to the
80  server, and collecting crash information and saving it to the crash file.
81- crash_dump.c : This file is the implementation for dumping the crash
82  information, including backtrace stack, opened files, register values, and
83  memory content around registers.
84- debugger.c : This file implements a tool, which runs in command line to
85  dump the process information listed above.
86- protocol.c : This file is the socket protocol implementation file.
87- server.c : This file is the implementation file for the server of
88  ``usercrash``. The server is responsible for creating the crash file and
89  handling the events from the client.
90