X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fdebug.texi;h=7e372ca0a248d7483aa7e6b5de5142b14161fbee;hb=b09f5e5075c6840d6f7601857840b3de3d5de521;hp=68318fdc855f03638206a1150089fbd59bf045c8;hpb=01679e7fec5244d137cc9b2cfc2d72e946c4d9d2;p=pintos-anon diff --git a/doc/debug.texi b/doc/debug.texi index 68318fd..7e372ca 100644 --- a/doc/debug.texi +++ b/doc/debug.texi @@ -8,14 +8,16 @@ introduces you to a few of them. * printf:: * ASSERT:: * DEBUG:: +* UNUSED NO_RETURN NO_INLINE PRINTF_FORMAT:: * Backtraces:: * i386-elf-gdb:: +* Debugging by Infinite Loop:: * Modifying Bochs:: * Debugging Tips:: @end menu @node printf -@section @func{printf} +@section @code{@code{printf()}} Don't underestimate the value of @func{printf}. The way @func{printf} is implemented in Pintos, you can call it from @@ -39,7 +41,7 @@ Eventually you can narrow the problem down to a single statement. Assertions are useful because they can catch problems early, before they'd otherwise be notices. Pintos provides a macro for assertions -named @code{ASSERT}, defined in @code{}, that you can use for +named @code{ASSERT}, defined in @file{}, that you can use for this purpose. Ideally, each function should begin with a set of assertions that check its arguments for validity. (Initializers for functions' local variables are evaluated before assertions are @@ -54,7 +56,7 @@ backtraces below for more information. @node DEBUG @section @code{DEBUG} -The @code{DEBUG} macro, also defined in @code{}, is a sort of +The @code{DEBUG} macro, also defined in @file{}, is a sort of conditional @func{printf}. It takes as its arguments the name of a ``message class'' and a @func{printf}-like format string and arguments. The message class is used to filter the messages that are @@ -76,6 +78,39 @@ a command line like this: pintos run -d thread @end example +@node UNUSED NO_RETURN NO_INLINE PRINTF_FORMAT +@section UNUSED, NO_RETURN, NO_INLINE, and PRINTF_FORMAT + +These macros defined in @file{} tell the compiler special +attributes of a function or function parameter. Their expansions are +GCC-specific. + +@defmac UNUSED +Appended to a function parameter to tell the compiler that the +parameter might not be used within the function. It suppresses the +warning that would otherwise appear. +@end defmac + +@defmac NO_RETURN +Appended to a function prototype to tell the compiler that the +function never returns. It allows the compiler to fine-tune its +warnings and its code generation. +@end defmac + +@defmac NO_INLINE +Appended to a function prototype to tell the compiler to never emit +the function in-line. Occasionally useful to improve the quality of +backtraces (see below). +@end defmac + +@defmac PRINTF_FORMAT (@var{format}, @var{first}) +Appended to a function prototype to tell the compiler that the +function takes a @func{printf}-like format string as its +@var{format}th argument and that the corresponding value arguments +start at the @var{first}th argument. This lets the compiler tell you +if you pass the wrong argument types. +@end defmac + @node Backtraces @section Backtraces @@ -167,7 +202,15 @@ address. (Use a @samp{0x} prefix to specify an address in hex.) @end table -If you notice unexplainable behavior while using @command{gdb}, there +You might notice that @command{gdb} tends to show code being executed +in an order different from the order in the source. That is, the +current statement jumps around seemingly randomly. This is due to +GCC's optimizer, which does tend to reorder code. If it bothers you, +you can turn off optimization by editing +@file{pintos/src/Make.config}, removing @option{-O3} from the +@code{CFLAGS} definition. + +If you notice other strange behavior while using @command{gdb}, there are three possibilities. The first is that there is a bug in your modified Pintos. The second is that there is a bug in Bochs's interface to @command{gdb} or in @command{gdb} itself. The third is @@ -175,6 +218,38 @@ that there is a bug in the original Pintos code. The first and second are quite likely, and you should seriously consider both. We hope that the third is less likely, but it is also possible. +@node Debugging by Infinite Loop +@section Debugging by Infinite Loop + +If you get yourself into a situation where the machine reboots in a +loop, you've probably hit a ``triple fault.'' In such a situation you +might not be able to use @func{printf} for debugging, because the +reboots might be happening even before everything needed for +@func{printf} is initialized. In such a situation, you might want to +try what I call ``debugging by infinite loop.'' + +What you do is pick a place in the Pintos code, insert the statement +@code{for (;;);} there, and recompile and run. There are two likely +possibilities: + +@itemize @bullet +@item +The machine hangs without rebooting. If this happens, you know that +the infinite loop is running. That means that whatever caused the +problem must be @emph{after} the place you inserted the infinite loop. +Now move the infinite loop later in the code sequence. + +@item +The machine reboots in a loop. If this happens, you know that the +machine didn't make it to the infinite loop. Thus, whatever caused the +reboot must be @emph{before} the place you inserted the infinite loop. +Now move the infinite loop earlier in the code sequence. +@end itemize + +If you move around the infinite loop in a ``binary search'' fashion, you +can use this technique to pin down the exact spot that everything goes +wrong. It should only take a few minutes at most. + @node Modifying Bochs @section Modifying Bochs