From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 22194 invoked by alias); 25 Jul 2008 13:34:35 -0000 Received: (qmail 22183 invoked by uid 22791); 25 Jul 2008 13:34:33 -0000 X-Spam-Check-By: sourceware.org Received: from mtaout5.012.net.il (HELO mtaout5.012.net.il) (84.95.2.13) by sourceware.org (qpsmtpd/0.31) with ESMTP; Fri, 25 Jul 2008 13:34:13 +0000 Received: from HOME-C4E4A596F7 ([84.229.112.15]) by i_mtaout5.012.net.il (HyperSendmail v2004.12) with ESMTPA id <0K4K00FBPDNRQE81@i_mtaout5.012.net.il> for gdb-patches@sourceware.org; Fri, 25 Jul 2008 16:33:28 +0300 (IDT) Date: Fri, 25 Jul 2008 13:34:00 -0000 From: Eli Zaretskii Subject: Re: Internals manual fixups In-reply-to: <4866823C.5090002@earthlink.net> X-012-Sender: halo1@inter.net.il To: Stan Shebs Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: References: <4866823C.5090002@earthlink.net> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2008-07/txt/msg00435.txt.bz2 > Date: Sat, 28 Jun 2008 11:26:04 -0700 > From: Stan Shebs > > As threatened, here is my first round of bashing on the internals > manual. Eli, how does it look to you? As threatened, I returned from my traveling and are slowly catching up on the backlog. > -host and target are not the same, doing a fork to start the target > +host and target are not the same, doing a fork() to start the target GNU coding standards frown on using "fork()" with the purpose of saying that `fork' is a function. The rationale is that "fork()" looks like a call to `fork' with no arguments, which is not what you want. Please use @code{fork} instead. > -@code{gdbarch_get_longjmp_target}, which will examine the @code{jmp_buf} > -structure and extract the longjmp target address. Since @code{jmp_buf} > -is target specific, you will need to define it in the appropriate > -@file{tm-@var{target}.h} file. Look in @file{tm-sun4os4.h} and > -@file{sparc-tdep.c} for examples of how to do this. > +@code{gdbarch_get_longjmp_target}, which will examine the > +@code{jmp_buf} structure and extract the longjmp target address. > +Since @code{jmp_buf} is target specific and typically defined in a > +target header not available to @value{GDBN}, you will need to > +determine the offset of the PC manually and return that; many targets Please in the future don't re-fill paragraphs together with real changes. It makes it harder for me to review changes, because I need to find the _real_ changes among whitespace changes. If you want to change whitespace, feel free to commit without an RFA. Also, `longjmp' is a function, so it should be in @code, like the rest of the symbols here. > +define a @code{jb_pc_offset} field in the tdep structure to save the > +value once calculated. See @file{i386-tdep.c} for an example. First, please make sure you have 2 spaces after a period that ends a sentence. Second, please remember that @file{foo} will become just `foo' in the makeinfo/TeX output, so the word "file" that this text begs should be added explicitly, to explain more clearly where to look. > -watchpoints before stepping the inferior. > +watchpoints before stepping the inferior. Currently this is only > +defined for Solaris x86. I generally find text that mentions specific hosts a maintenance nightmare: we will have to remember from now on to modify it whenever some other platform defines this. I prefer saying something vague, like "on some platforms". > +all. Studies have shown that nearly all the time spent is ^^ Two spaces, please, here and elsewhere. > +Returns a @code{(register, offset)} pair representing the virtual I think it would be better here to give "register" and "offset" the @var markup. > +frame pointer in use at the code address @var{pc}. Btw, saying that this pair "represents the virtual frame pointer" seems to be not enough, as the reader is left to wonder what is the role of each one of the 2 members of this pair. Please consider adding some more details. > +(@pxref{Support Libraries, ,Opcodes}). @var{info} is a structure (of > +type @code{disassemble_info}) defined in @file{include/dis-asm.h} used Again, please use an explicit "file" word in the text, @file alone is not enough. > +(Target header files such as > +@file{gdb/config/@var{arch}/tm-@var{ttt}.h}, > +@file{gdb/config/@var{arch}/tm-@var{arch}.h}, and > +@file{config/tm-@var{os}.h} are no longer used.) Then why mention them at all? > that runs in the target system. @value{GDBN} provides several sample > @dfn{stubs} that can be integrated into target programs or operating > -systems for this purpose; they are named @file{*-stub.c}. > +systems for this purpose; they are named @file{*-stub.c}. Many I think @var{cpu}-stub.c is better than *-stub.c here. Otherwise, this is okay. Note that I didn't verify that everything you removed is indeed not used. Thanks.