FAQ? How do I multi-arch my target?

[Andrew Cagney <ac131313@cygnus.com>]

Hello,

Here is the next in a set of notes about multi-arch - getting GDB to
support architectural variants (and orthogonal architectures):

In this note I'll give some suggestions for how the maintainer of a
given target should go about converting things so that they use the
multi-arch framework.

Broadly there are two strategies:


	1.	Convert everything at once.

		Fail


	2.	Incrementally convert/clean/commit
		your targets changes.

		Succeed.

I'd recommend the second strategy using the following as guidelines for
what to attack where.



Preparation:

Step 0 is always establish that control - build / test your target as it
currently stands.  While  at it. it wouldn't hurt to fix a few bugs :-)

With the control established and tested freeze it.



Suggested conversion sequence:



Remove EXTRA_FRAME_INFO and FRAME_FIND_SAVED_REGS:

These two macro's have been deprecated.

FRAME_FIND_SAVED_REGS was replaced by FRAME_INIT_SAVED_REGS. 
EXTRA_FRAME_INFO has been deleted.  For examples of how to re-do the
code see the d10v and the mn10300.



Replace REGISTER_NAMES with REGISTER_NAME():

The REGISTER_NAMES initialization string has been deprecated.

Instead there is a per architecture function.  See d10v-tdep.c for a
very simple implementation.



Incrementally convert all code and function macro's to proper C
functions:

I've already converted a number of these.  However, for each target
there are plenty more.  Ensure that each function being created
maintains name-space purity (ex d10v_, mips_...).



Create your XXX-tdep.c:XXX_gdbarch_init() function:

In theory, this function only needs the following:
	static struct gdbarch *
	d10v_gdbarch_init (info, arches)
	     struct gdbarch_info info;
	     struct gdbarch_list *arches;
	{
	  struct gdbarch *gdbarch;
	  /* there is only one d10v architecture */
	  if (arches != NULL)
	    return arches->gdbarch;
	  gdbarch = gdbarch_alloc (&info, NULL);
	  return gdbarch;
	}
In truth, as noted below, you may need to initialize several predicate
macros.


Check for any new predicate macros (*_P):

Glance through gdbarch.h, looking for any predicate macro's that your
target doesn't define.  For each of these either add a definition to
your tm-XXX.h file or add a line to your XXX_gdbarch_init() function
providing an initial value.

Please let me know which macro's you identify.



Update XXX-tdep.c:_initialize_XXX() and register your architecture.

EX:
	  if (GDB_MULTI_ARCH)
	    register_gdbarch_init (bfd_arch_d10v, d10v_gdbarch_init);



Define GDB_MULTI_ARCH 1 in your tm-*.h file:

This is probably the most difficult stage.
Add:

	#ifndef GDB_MULTI_ARCH
	#define GDB_MULTI_ARCH 1
	#endif

to the top of your tm-XXX.h file.  Rebuild and then run GDB vis:

	gdb/gdb
	(gdb)
	(gdb) set archdebug 1
	(gdb) file x-y-z
	....

If all goes well, gdb will report the current value of all the
architecture dependent macro's. At this stage must are still being taken
from hardwired definitions in your tm-XXX.h file.  Failing that, an
internal error message reporting an uninitialised architecture vector
member will be reported.

Test it.  There will most likely be problems stemming from the
introduction of new predicate macro's that test for target features. 
Please let me know of any problem macro's you find.



Slowly convert your target macro's:

See d10v-tdep.c/config/d10v/tm-d10v.h.

Expand the XXX_gdbarch_init() function so that it fully populates the
architecture vector.  As you convert each macro, wrap it in #if
!GDB_MULTI_ARCH / #endif so that it is possible to revert the code back
to pre-multi-arch days.

If you find a macro missing from the architecture vector, let me know
and I'll add it.  At present the architecture vector only contains the
minimum set of macro's to get a small set of targets up and running.



Raise GDB_MULTI_ARCH to 2:

This final step enables a string of checks in gdbarch() that ensure that
the target architecture vector was fully initialized.



Keep an eye on gdb@sourceware watching for updates and additions.

	Andrew