Re: [rfc/rft] [3/3] Remove stabs target macros: SOFUN_ADDRESS_MAYBE_MISSING

["Ulrich Weigand" <uweigand at de dot ibm dot com>]

Eli Zaretskii wrote:

> > Well, the sofun_address_maybe_missing gdbarch entry is of type "v",
> > i.e. it is a simple variable of type "int", not a function.
> 
> Okay, that means my example was chosen wrongly (but please do state
> somewhere that this is a variable).  However, IIRC you have other
> changes where a macro is replaced with a function, but arguments of
> that function are not shown, and that's what I'd like you to fix.  A
> reader of the manual should not need to consult sources to understand
> how to define such a function.

SOFUN_ADDRESS_MAYBE_MISSING is the only doc change in this patch.
(In another patch there was a function, but as far as I can see I've
left the argument in there ...).

> > I guess the question is, what is the entity that the documentation
> > should specify for gdbarch entries:
> > 
> > - the gdbarch_... accessor function
> > or
> > - the argument passed to the set_gdbarch_... routine
> 
> Whatever replaced the old macro should be documented in its stead.  I
> thought you replaced macros with functions, but maybe I misunderstood.

This is not quite how the gdbarch mechanism works.  In the old style,
you have a macro (function-like or not) that is defined in a header file,
and used -under the same name- in GDB source code.

The new gdbarch mechanism replaces those global macros with entries
in a data structure; and provides accessor functions to set and query
those values.  These also come in different variants for function-like
and variable-like entities.

For a function-like gdbarch parameter, there is a set_gdbarch_... routine
that the architecture-specific part calls, passing in a funtion pointer to
the actual implementation of that routine.  There is also an gdbarch_...
accessor routine that calls the appropriate implementation.  (Both of these
are automatically generated by the gdbarch script.)

For a variable-like gdbarch parameter, the set_gdbarch_... routine is called
simply with the value of the parameter for this platform.  The gdbarch_...
accessor routine just returns that value.


That means for the writer of the target-dependent code, instead of defining
a macro in a tm-*.h header file, they need to call the appropriate 
set_gdbarch_... routine in their target's gdbarch_init routine.  If they
want to *use* the architecture-specific setting, instead of just refering
to the macro, they'll have to call the appropriate gdbarch_... accessor.

In the current example, instead of placing
#define SOFUN_ADDRESS_MAYBE_MISSING
in a tm-*.h header file, you'd have to call
set_gdbarch_sofun_address_maybe_missing (gdbarch, 1);
in your gdbarch_init routine.

Instead of checking for
#ifdef SOFUN_ADDRESS_MAYBE_MISSING
you'd have to use something along the lines of
  if (gdbarch_sofun_address_maybe_missing (gdbarch))


For a typical case of a function-like gdbarch parameter, e.g. register_name,
you used to have a target macro
#define REGISTER_NAME(regnr) ...

This was replaced by defining a local function, e.g.

 static const char *
 my_register_name (int regnr) { ... }

and registering it in the gdbarch_init routine:

 set_gdbarch_register_name (gdbarch, my_register_name);

To *use* that gdbarch parameter, you'd have to call the accessor routine

 const char *gdbarch_register_name (struct gdbarch *gdbarch, int regnr);


Overall, the one entity (macro) has been replaced by really *three*
entities: the gdbarch parameter as stored in the gdbarch structure
(which may be either a variable or a function, but is never directly
visible to the programmer), and the set_gdbarch_... and gdbarch_...
accessor functions (which themselves are always functions, but may
take different arguments depending on the type of the underlying
gdbarch parameter).

Now, all of this isn't really anything new, that's how gdbarch has
been working for many years now.  But the associated documentation
looks like it doesn't quite reflect that change in a really consistent
manner, that's why I was asking how it *should* be ...


>From looking at other the documentation of other entries, most appear
to refer to the accessor function.  The analogous doc for the
sofun_address_maybe_missing case could read something like:

--- gdb-orig/gdb/doc/gdbint.texinfo	2007-10-05 18:19:25.000000000 +0200
+++ gdb-head/gdb/doc/gdbint.texinfo	2007-10-09 21:45:12.795269867 +0200
@@ -3847,21 +3847,22 @@
 the next instruction. See @file{sparc-tdep.c} and @file{rs6000-tdep.c}
 for examples.
 
-@item SOFUN_ADDRESS_MAYBE_MISSING
-@findex SOFUN_ADDRESS_MAYBE_MISSING
+@item int gdbarch_sofun_address_maybe_missing (@var{gdbarch})
+@findex gdbarch_sofun_address_maybe_missing
 Somebody clever observed that, the more actual addresses you have in the
 debug information, the more time the linker has to spend relocating
 them.  So whenever there's some other way the debugger could find the
 address it needs, you should omit it from the debug info, to make
 linking faster.
 
-@code{SOFUN_ADDRESS_MAYBE_MISSING} indicates that a particular set of
-hacks of this sort are in use, affecting @code{N_SO} and @code{N_FUN}
-entries in stabs-format debugging information.  @code{N_SO} stabs mark
-the beginning and ending addresses of compilation units in the text
-segment.  @code{N_FUN} stabs mark the starts and ends of functions.
+@code{gdbarch_sofun_address_maybe_missing} returns a non-zero value
+to indicate that a particular set of hacks of this sort are in use,
+affecting @code{N_SO} and @code{N_FUN} entries in stabs-format
+debugging information.  @code{N_SO} stabs mark the beginning and
+ending addresses of compilation units in the text segment.
+@code{N_FUN} stabs mark the starts and ends of functions.
 
-@code{SOFUN_ADDRESS_MAYBE_MISSING} means two things:
+If @code{gdbarch_sofun_address_maybe_missing} returns non-zero:
 
 @itemize @bullet
 @item


What I find a litte bit odd about documenting gdbarch routines this
way is that the typical writer of platform-specific GDB code will
never actually use this accessor function.  For them, the important
question is whether or not to *set* that parameter in their gdbarch
init function ...

Bye,
Ulrich

-- 
  Dr. Ulrich Weigand
  GNU Toolchain for Linux on System z and Cell BE
  Ulrich.Weigand@de.ibm.com