Skip to content

Commit 440969f

Browse files
committed
Update documentation
Add "Debugging Facilities" section to README.md
1 parent 5be37ab commit 440969f

File tree

2 files changed

+45
-0
lines changed

2 files changed

+45
-0
lines changed

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@ qtest
44
*.dSYM
55
.vscode
66
.devcontainer
7+
core*

README.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ Tools for evaluating your queue code
8383
* Makefile : Builds the evaluation program `qtest`
8484
* README.md : This file
8585
* scripts/driver.py : The driver program, runs `qtest` on a standard set of traces
86+
* scripts/debug.py : The helper program for GDB, executes qtest without SIGALRM and/or analyzes generated core dump file.
8687

8788
Helper files
8889
* console.{c,h} : Implements command-line interpreter for qtest
@@ -97,6 +98,49 @@ Trace files
9798
* XX is the trace number (1-15). CAT describes the general nature of the test.
9899
* traces/trace-eg.cmd : A simple, documented trace file to demonstrate the operation of `qtest`
99100

101+
## Debugging Facilities
102+
103+
Before using GDB debug `qtest`, there are some routine instructions need to do. The script `scripts/debug.py` covers these instructions and provides basic debug function.
104+
```
105+
$ scripts/debug.py -h
106+
usage: debug.py [-h] [-d | -a]
107+
108+
optional arguments:
109+
-h, --help show this help message and exit
110+
-d, --debug Enter gdb shell
111+
-a, --analyze Analyze the core dump file
112+
```
113+
* Enter GDB without interruption by **SIGALRM**.
114+
```
115+
$ scripts/debug.py -d
116+
Reading symbols from lab0-c/qtest...done.
117+
Signal Stop Print Pass to program Description
118+
SIGALRM No No No Alarm clock
119+
Starting program: lab0-c/qtest
120+
cmd>
121+
```
122+
* When `qtest` encountered **Segmentation fault** while it ran outside GDB, we could invoke GDB in the post-mortem debugging mode to figure out the bug.
123+
124+
The core dump file was created in the working directory of the `qtest`.
125+
* Allow the core dumps by using shell built-in command **ulimit** to set core file size.
126+
```
127+
$ ulimit -c unlimited
128+
$ ulimit -c
129+
unlimited
130+
```
131+
* Enter GDB and analyze
132+
```
133+
$ scripts/debug.py -a
134+
Reading symbols from lab0-c/qtest...done.
135+
[New LWP 9424]
136+
Core was generated by `lab0-c/qtest'.
137+
Program terminated with signal SIGSEGV, Segmentation fault.
138+
#0 ...
139+
#1 ... (backtrace information)
140+
#2 ...
141+
(gdb)
142+
```
143+
100144
## License
101145

102146
`lab0-c`is released under the BSD 2 clause license. Use of this source code is governed by

0 commit comments

Comments
 (0)