Re: [PATCH/RFA] Generic OS ABI handling

["Eli Zaretskii" <eliz@is.elta.co.il>]

> Date: Thu, 16 May 2002 19:52:55 -0700
> From: Jason R Thorpe <thorpej@wasabisystems.com>
> 
>         * doc/gdbint.texinfo: Document new generic OS ABI framework.

This is approved, but see some minor comments below.

> +/* This table matches the indices assigned to enum gdb_osabi.  Keep
> +   them in sync.  */

Wouldn't it be nice to have those in sync automatically, or at least
have a compiler error if they aren't?

> +static const char * const gdb_osabi_names[] =
> +{
> +  "<unknown>",
> +
> +  "SVR4",
> +  "GNU Hurd",
> +  "Solaris",
> +  "OSF/1",
> +  "GNU/Linux",
> +  "FreeBSD a.out",
> +  "FreeBSD ELF",
> +  "NetBSD a.out",
> +  "NetBSD ELF",
> +  "Windows CE",
> +
> +  "ARM EABI v1",
> +  "ARM EABI v2",
> +  "ARM APCS",
> +
> +  "<invalid>"

Do I understand correctly that any target whose ABI is not in this
list will cause the warning below to be issued at run time?

> +  if (osabi == GDB_OSABI_UNKNOWN)
> +    {
> +      /* Don't complain about not knowing the OS ABI if we don't
> +	 have an inferior.  */
> +      if (info.abfd)
> +	fprintf_filtered
> +	  (gdb_stderr, "GDB doesn't recognize the OS ABI of the inferior.  "
> +	   "Attempting to continue with the default %s settings",
> +	   bfd_printable_arch_mach (arch_info->arch, arch_info->mach));
> +      return;

If this warning is to be printed in a normal session, it could get
annoying, I think.

Or maybe I just couldn't figure out when is that function called, and
what is the precise meaning of having the `unknown' OS ABI.  Could you
please tell that in a few words?

Here are some comments about the documentation patch:

> +@section Operating System ABI Variant Handling
> +
> +@value{GDBN} provides a mechanism for handling variations in OS
> +ABIs.  An OS ABI variant may have influence over any number of
> +variables in the target architecture definition.  There are two major
> +components in the OS ABI mechanism: sniffers and handlers.

Please add an index entry here for some relevant subject.  For
example:

  @cindex OS ABI variants

> +A sniffer examines a file matching a BFD architecture/flavour pair
> +(the architecture may be wildcarded) in an attempt to determine the
> +OS ABI of that file.

It is usually a good idea to say @dfn{sniffer} when you are
introducing a new concept or term.  @dfn makes the word stand out in
the produced documents.

> +A handler is used to fine-tune the @code{gdbarch} structure for the
> +selected OS ABI.  There may be only one handler for a given OS ABI
> +for each BFD architecture.

It would be good to have an index entry here for those people who are
looking for ways of fine-tuning gdbarch.  Here's what I'd use:

  @cindex fine-tuning @code{gdbarch} structure.

> +@deftypefun const char *gdbarch_osabi_name (enum gdb_osabi @var{osabi})
> +Return the name of the OS ABI corresponding to @var{osabi}.
> +@end deftypefun

I'd suggest to have here a list of known values in enum gdb_osabi.
Otherwise, the reader will have to look them up in the sources, which
I find annoying when reading the docs (if they want me to look at the
sources, why bother documenting stuff at all?).

It might also be a good idea to tell what header file defines those
values, so that if the docs ever gets out of sync, the actual list
could be looked up.