[rfa] libgdb updates to doco

[rfa] libgdb updates to doco

[Andrew Cagney]

Hello,

Per recent post to gdb@, the attached adds a libgdb chapter to the GDB 
internals document.

Eli, in your original comments you mentioned more @node's.  I'm not sure 
that I follow - gdbint is very @node sparse only having them for @chapters.

	Andrew
From msnyder@redhat.com Wed Jul 25 21:29:00 2001
From: Michael Snyder <msnyder@redhat.com>
To: Andrew Cagney <ac131313@cygnus.com>
Cc: Fernando Nasser <fnasser@redhat.com>, Michael Snyder <msnyder@cygnus.com>, Fernando Nasser <fnasser@cygnus.com>, Daniel Jacobowitz <dmj+@andrew.cmu.edu>, gdb-patches@sourceware.cygnus.com
Subject: Re: [RFA] Testsuite addition for x86 linux GDB and SIGALRM fix
Date: Wed, 25 Jul 2001 21:29:00 -0000
Message-id: <3B5F9CBE.4A9@redhat.com>
References: <200005192321.e4JNLEv13368@delius.kettenis.local> <3B3ABD6E.1040304@cygnus.com> <3B4A2056.4D58E307@cygnus.com> <20010709143406.A17003@nevyn.them.org> <3B4A2C7C.85C688C4@cygnus.com> <3B5F5218.5D55130E@cygnus.com> <3B5F595F.821DA2A5@redhat.com> <3B5F7700.6030407@cygnus.com>
X-SW-Source: 2001-07/msg00639.html
Content-length: 1208

Andrew Cagney wrote:
> 
> > Michael Snyder wrote:
> >
> >>
> >> I must disagree.  Often, when you reach this line and you
> >> want to step into foo, you will not notice the call to bar
> >> until it is too late and you have stepped into bar.
> >>
> >> When that happens, the only way to reach foo is to "finish" from
> >> bar, and then step again.
> >>
> >
> >
> > As I have explained in this thread (one month ago), the single stepping
> > caused by finish would stop as soon as foo is entered -- exactly the
> > behavior you want.
> 
> I think that would be very counter intuitive.  The primatives are:
> 
>         o       step executes instructions until you
>                 leave the current line
>                 (be it enter a function or reach a new
>                 line)
> 
>         o       finish leaves the current function
>                 (reducing the stack depth by one)

I agree; I do not like the idea of this proposed 
enhancement of finish.  I think that if the source
looked like

	foo (bar ());

and I stepped into bar, then said "finish", and 
found myself in foo, I would find that confusing.
It would seem as if bar had been called from foo, 
which is not the case.

Michael

Re: [rfa] libgdb updates to doco

[Eli Zaretskii]

On Wed, 25 Jul 2001, Andrew Cagney wrote:

> Per recent post to gdb@, the attached adds a libgdb chapter to the GDB 
> internals document.

Approved.

> Eli, in your original comments you mentioned more @node's.  I'm not sure 
> that I follow - gdbint is very @node sparse only having them for @chapters.

That is IMHO a mistake, and we should gradually correct it.  The
Texinfo cross-references (and thus index entries) refer to the
enclosing node in the Info version, so having smaller nodes makes sure
you will land close to the stuff you are looking for.  (There's the
new @anchor directive which is free from this limitation, but older
Info readers don't support it, so we should not yet use it too much;
and index entries don't produce @anchor's anyway.)

Re: [rfa] libgdb updates to doco

[Andrew Cagney]

>> Eli, in your original comments you mentioned more @node's.  I'm not sure 
>> that I follow - gdbint is very @node sparse only having them for @chapters.
> 
> 
> That is IMHO a mistake, and we should gradually correct it.  The


Yes true.

> Texinfo cross-references (and thus index entries) refer to the
> enclosing node in the Info version, so having smaller nodes makes sure
> you will land close to the stuff you are looking for.  (There's the
> new @anchor directive which is free from this limitation, but older
> Info readers don't support it, so we should not yet use it too much;
> and index entries don't produce @anchor's anyway.)


For my part, I was looking for an existing example but couldn't find one 
:-(.

I've checked in the libgdb stuff.  Hmm, whats next?

	Andrew

Re: [rfa] libgdb updates to doco

[Eli Zaretskii]

> Date: Thu, 26 Jul 2001 14:42:01 -0400
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> > Texinfo cross-references (and thus index entries) refer to the
> > enclosing node in the Info version, so having smaller nodes makes sure
> > you will land close to the stuff you are looking for.  (There's the
> > new @anchor directive which is free from this limitation, but older
> > Info readers don't support it, so we should not yet use it too much;
> > and index entries don't produce @anchor's anyway.)
> 
> For my part, I was looking for an existing example but couldn't find one 

Just put a @node before each @section and @subsection.  While at that,
consider converting @heading and @subheading into @section and
@subsection, and then apply the first rule again ;-).

> I've checked in the libgdb stuff.  Hmm, whats next?

How about documenting multi-arch so that I could understand how to
multi-arch a target without reading the code? ;-)

Re: [rfa] libgdb updates to doco

[Andrew Cagney]

>> I've checked in the libgdb stuff.  Hmm, whats next?
> 
> 
> How about documenting multi-arch so that I could understand how to
> multi-arch a target without reading the code? ;-)


Something based on:

http://sources.redhat.com/gdb/papers/multi-arch/howto.html

still for the moment I'm just trying to fix bits of the documentation 
that are out-of-date or wrong :-)

	Andrew

Re: [rfa] libgdb updates to doco

[Andrew Cagney]

> That's just a cookbook.  It's important to have that, but it is no
> less important to understand how multi-arch works internally, to be
> able to do something beyond blindly following the cookbook.


Hmm, not sure if you want the doco to explain how it currently works - 
the swap stuff is a really nasty paramatic hack.  How it _should_ work 
might be useful.  I think its like libgdb - in theory it works like ..., 
when working on the reality, try to keep the theory in mind and try to 
make the code more like the theory :-)

	Andrew

Re: [rfa] libgdb updates to doco

[Eli Zaretskii]

> Date: Sat, 28 Jul 2001 10:50:51 -0400
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> > That's just a cookbook.  It's important to have that, but it is no
> > less important to understand how multi-arch works internally, to be
> > able to do something beyond blindly following the cookbook.
> 
> Hmm, not sure if you want the doco to explain how it currently works - 
> the swap stuff is a really nasty paramatic hack.  How it _should_ work 
> might be useful.

I'm not talking about swapping the arch, but about a list of the
methods covered by the arch, and how things like registers, addresses,
and chunks of memory get from the debuggee via gdbarch to GDB.  This
path includes many translation layers which, at least for me, are the
biggest stumbling block when I'm trying to understand how things work
in a certain port, and where to look for possible reasons of some
snafu.

> I think its like libgdb - in theory it works like ..., when working
> on the reality, try to keep the theory in mind and try to make the
> code more like the theory :-)

I agree; but in this case even the theory is not documented.