From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 30912 invoked by alias); 15 May 2002 06:58:58 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 30873 invoked from network); 15 May 2002 06:58:29 -0000 Received: from unknown (HELO localhost.redhat.com) (24.112.240.27) by sources.redhat.com with SMTP; 15 May 2002 06:58:29 -0000 Received: from cygnus.com (localhost [127.0.0.1]) by localhost.redhat.com (Postfix) with ESMTP id E6E003E60 for ; Wed, 15 May 2002 02:58:25 -0400 (EDT) Message-ID: <3CE20711.90407@cygnus.com> Date: Tue, 14 May 2002 23:58:00 -0000 From: Andrew Cagney User-Agent: Mozilla/5.0 (X11; U; NetBSD macppc; en-US; rv:1.0rc1) Gecko/20020429 X-Accept-Language: en-us, en MIME-Version: 1.0 To: gdb-patches@sources.redhat.com Subject: [rfa/rfc] Revised multi-arch process Content-Type: multipart/mixed; boundary="------------040902030803040102090401" X-SW-Source: 2002-05/txt/msg00585.txt.bz2 This is a multi-part message in MIME format. --------------040902030803040102090401 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Content-length: 257 Hello, Attached is a revised process for converting a target to the multi-arch framework. I'm especially interested in comments from people who have just done a conversion (how near to reality is the below?). (It also adds it do the doco, Eli?) Andrew --------------040902030803040102090401 Content-Type: text/plain; name="diffs" Content-Transfer-Encoding: 7bit Content-Disposition: inline; filename="diffs" Content-length: 5076 2002-05-15 Andrew Cagney * gdbint.texinfo (Target Architecture Definition): Add section ``Converting an existing Target Architecture to Multi-arch''. Index: gdbint.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v retrieving revision 1.84 diff -u -r1.84 gdbint.texinfo --- gdbint.texinfo 13 May 2002 17:20:59 -0000 1.84 +++ gdbint.texinfo 15 May 2002 06:54:38 -0000 @@ -3764,6 +3764,165 @@ @file{config/tm-@var{os}.h}. +@section Converting an existing Target Architecture to Multi-arch + +This section describes the current accepted best practice for converting +an an existing target architecture to the multi-arch framework. + +The process consists of generating, testing, posting and committing a +sequence of patches. Each patch must contain a single change, for +instance: + +@itemize @bullet + +@item +Directly convert a group of functions into macros (the conversion does +not change the behavior of any of the functions). + +@item +Replace a non-multi-arch with a multi-arch mechanism (e.g., +@code{FRAME_INFO}). + +@item +Enable multi-arch level one + +@item +Delete one or more files + +@end itemize + +@noindent +There isn't a size limit on a patch, however, more smaller patches are +strongly encouraged. + +Since each patch is well defined, and since each change has been tested +and shows no regressions, the patches are considered @emph{fairly} +obvious. Such patches do not need approval. Occasional steps in the +process may be more complicated and less clear. The developer is +expected to use their judgment and is encouraged to seek advice as +needed. + +@subsection Preparation + +The first step is to establish control. Build (with @option{-Werror} +enabled) and test the target so that there is a baseline against which +the debugger can be compared. + +At no stage can the test results regress or @value{GDBN} stop compiling +with @option{-Werror}. + +@subsection Add the multi-arch initialization code + +The objective of this step is to establish the basic multi-arch +framework. It involves + +@itemize @bullet + +@item +The addition of a @code{@var{arch}_gdbarch_init} function@footnote{The +above is from the original example and uses K&R C. @value{GDBN} +has since converted to ISO C but lets ignore that.} that creates +the architecture: +@smallexample +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; +@} +@end smallexample +@noindent +@emph{} + +@item +A per-architecture dump function to print any architecture specific +information: +@smallexample +static void +mips_dump_tdep (struct gdbarch *current_gdbarch, + struct ui_file *file) +@{ + @dots{} code to print architecture specific info @dots{} +@} +@end smallexample + +@item +A change to @code{_initialize_@var{arch}_tdep} to register this new +architecture: +@smallexample +void +_initialize_mips_tdep (void) +@{ + gdbarch_register (bfd_arch_mips, mips_gdbarch_init, + mips_dump_tdep); +@end smallexample + +@item +Add the macro @code{GDB_MULTI_ARCH}, defined as 0 (zero), to the file@* +@file{config/@var{arch}/tm-@var{arch}.h}. + +@end itemize + +@subsection Update multi-arch incompatible mechanisms + +Some mechanisms do not work with multi-arch. They include: + +@table @code +@item EXTRA_FRAME_INFO +Delete. +@item FRAME_FIND_SAVED_REGS +Replaced with @code{FRAME_INIT_SAVED_REGS} +@end table + +@noindent +At this stage you could also consider converting the macros into +functions. + +@subsection Prepare for multi-arch level to one + +Temporally set @code{GDB_MULTI_ARCH} to GDB_MULTI_ARCH_PARTIAL and then +build and start @value{GDBN} (the change should not be committed). +@value{GDBN} may not build, and once built, it may die with an internal +error listing the architecture methods that must be provided. + +Fix any build problems (patch(es)). + +Convert all the architecture methods listed, which are only macros, into +functions (patch(es)). + +Update @code{@var{arch}_gdbarch_init} to set all the missing +architecture methods and wrap the corresponding macros in @code{#if +!GDB_MULTI_ARCH} (patch(es)). + +@subsection Set multi-arch level one + +Change the value of @code{GDB_MULTI_ARCH} to GDB_MULTI_ARCH_PARTIAL (a +single patch). + +Any problems with throwing ``the switch'' should have been fixed +already. + +@subsection Convert remaining macros + +Suggest converting macros into functions (and setting the corresponding +architecture method) in small batches. + +@subsection Set multi-arch level to two + +This should go smoothly. + +@subsection Delete the TM file + +The @file{tm-@var{arch}.h} can be deleted. @file{@var{arch}.mt} and +@file{configure.in} updated. + + @node Target Vector Definition @chapter Target Vector Definition --------------040902030803040102090401--