libs-base/Source/mframe/README

   This directory contains files used for the 'mframe' software in gstep-base.

   These files are part of the GNUstep Base Library.

   Copyright (C) 1996, 1997, 1998 Free Software Foundation, Inc.

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.
   
   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.
   
   You should have received a copy of the GNU Library General Public
   License along with this library; if not, write to the Free
   Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA.

   The code in this directory was written by
   Richard Frith-Macdonald <richard@brainstorm.co.uk>.
   Inspiration for (and some of the code of) this software came from the
   original mframe.m by Andrew McCallum, the gcc compiler, and the
   libFoundation software by Ovidiu Predescu and Mircea Oancea.
   The algorithms used are copied from gcc and are copyright the Free
   Software Foundation.  Many code fragments are derived from gcc either
   directly or by way of libFoundation.

   The sections of code (and comments) to do with the MFRAME_ARG_ENCODING()
   macro for sparc, hppa and powerpc were derived in part from libFoundation
   (for which, much thanks) avoiding the need to extract the relevent details
   directly from the gcc source in these cases.  The originals from which
   these fragments came the additional credit/copyright -

     Copyright (C) 1995, 1996, 1998 Ovidiu Predescu and Mircea Oancea.
     All rights reserved.

     Author: Ovidiu Predescu <ovidiu@bx.logicnet.ro>

     This file is part of libFoundation.

     Permission to use, copy, modify, and distribute this software and its
     documentation for any purpose and without fee is hereby granted, provided
     that the above copyright notice appear in all copies and that both that
     copyright notice and this permission notice appear in supporting
     documentation.

     We disclaim all warranties with regard to this software, including all
     implied warranties of merchantability and fitness, in no event shall
     we be liable for any special, indirect or consequential damages or any
     damages whatsoever resulting from loss of use, data or profits, whether in
     an action of contract, negligence or other tortious action, arising out of
     or in connection with the use or performance of this software.


Purpose -

   The files in these directories are used by the configuration script to build
   a machine/operating-system specific 'mframe.h' file containing macros used
   to access stack frames.
   The 'mframe.h' file is simply built by wrapping a system dependent file
   between mframe.head and mframe.foot

Advice on porting -

    See unknown/generic for an example of the following macros

MFRAME_STACK_STRUCT
	This should be defined to 1 if functions return structures by value
	using the method where the caller places a pointer on the stack.
	Define this to 0 otherwise (eg. when the pointer to the structure is
	passed in a register).

MFRAME_SMALL_STRUCT
	This is the size of the largest structure returned by value on
	the stack.  Normally gcc returns structures of up to 8 bytes on
	the stack.  If your system never returns structures on the stack,
	set this to zero rather than 8.
	NB. If __builtin_apply_args() always returns an argframe for
	structure return via pointer, you should also define this to zero.

MFRAME_STRUCT_BYREF
	This should be defined to 1 if structure arguments are passed in
	the stack frame by reference, 0 otherwise.

MFRAME_ARGS_SIZE
	This must be set to the value computed by the apply_args_size()
	function in expr.c in the gcc source.  It is the size of the
	area of memory allocated in which to pass arguments to a function.
	If you can't figure out how to determine this (hack expr.c to print
	the result of the function the first time it's called) - try using a
	value like 128 - which will probably be far larger than required
	(and therefore somewhat inefficient) but will most likely work.

MFRAME_RESULT_SIZE
	This must be set to the value computed by the apply_result_size()
	function in expr.c in the gcc source.  It is the size of the area
	of memory allocated in which to return a value from a function.
	If you can't figure out how to determine this (hack expr.c to print
	the result of the function the first time it's called) - try using a
	value like 128 - which will probably be far larger than required
	(and therefore somewhat inefficient) but will most likely work.

MFRAME_FLT_IN_FRAME_AS_DBL
	This should be defined as 1 if float parameters to functions and
	objective-c methods are passed on the stack as double values.
	Otherwise it should not be defined.

MFRAME_STRUCT_ADDR(ARGFRAME,TYPES)
	If a function returns a structure by copying it into a location
	whose address is set by the caller, this macro must return that
	address within the argframe.
	Otherwise the macro must return zero.

MFRAME_ARGS
	This macro should define a data type to be used for recording
	information about the arguments list of a method.
	See 'CUMULATIVE_ARGS' in the configuration file for your system
	in gcc for a parallel example.

MFRAME_INIT_ARGS(CUM, RTYPE)
	This macro is used to initialise a variable (CUM) of the type
	defined by MFRAME_ARGS.  The RTYPE value is the type encoding for the
	method return type, it is needed so that CUM can take int account any
	invisible first argument used for returning structures by value.
	See 'INIT_CUMULATIVE_ARGS' in the configuration file for your system
	in gcc for a parallel example.

MFRAME_ARG_ENCODING(CUM,TYPES,STACK,DEST)
	This macro is used to to determine the encoding of arguments.
	You will have to write this macro for your system by examining the
	gcc source code to determine how the compiler does this on your
	system - look for the usage of CUMULATIVE_ARGS an INIT_CUMULATIVE_ARGS
	in the configuration files for your hardware and operating system in
	the gcc (or egcs) source, and make your macro mirror it's operation.

	Before initial entry,
	  CUM should have been initialised using the MFRAME_INIT_ARGS() macro,
	  TYPES should be a (const char*) variable initialised to a
	    type-encoding string listing the arguments of a function/method,
	  STACK should be an integer variable of value 0 in which the size of
	    the stack arguments will be accumulated,
	  DEST should be a (char*) variable initialised to a pointer to a
	    buffer into which the full type encoding will be written.
	After each use of the macro, TYPES is advanced to point to the next
	argument, and DEST is advanced to point after the encoding of the
	previous argument.
	Of course, you must ensure that the buffer pointed to by DEST is
	large enough so that it does not overflow!
	You will be safe if your buffer is at least ten times as big as
	the type-encoding string you start from.