[rfa:doco] document frame_align()

[rfa:doco] document frame_align()

[Andrew Cagney]

[-- Attachment #1: Type: text/plain, Size: 125 bytes --]

Hello,

This documents the frame_align() architecture method.  It also clarifies 
the behavior of stack_align().

ok?
Andrew

[-- Attachment #2: diffs --]
[-- Type: text/plain, Size: 1849 bytes --]

2002-09-18  Andrew Cagney  <ac131313@redhat.com>

	* gdbint.texinfo (Target Architecture Definition): Revise
	description of STACK_ALIGN.  Add description of FRAME_ALIGN.

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.100
diff -u -r1.100 gdbint.texinfo
--- gdbint.texinfo	24 Aug 2002 00:21:37 -0000	1.100
+++ gdbint.texinfo	18 Sep 2002 16:19:24 -0000
@@ -3175,6 +3175,23 @@
 represented by @var{fi} does not have a stack frame associated with it.
 Otherwise return 0.
 
+@item frame_align (@var{address})
+@anchor frame_align
+@findex frame_align
+Define this to adjust @var{address} so that it meets the alignment
+requirements for the start of a new stack frame.  A stack frame's
+alignment requirements are typically stronger than a target processors
+stack alignment requirements (@pxref{STACK_ALIGN}).
+
+This function is used to ensure that, when creating a dummy frame, both
+the initial stack pointer and (if needed) the address of the return
+value are correctly aligned.
+
+Unlike @ref{STACK_ALIGN}, this function always adjusts the address in
+the direction of stack growth.
+
+By default, no frame based stack alignment is performed.
+
 @item FRAME_ARGS_ADDRESS_CORRECT
 @findex FRAME_ARGS_ADDRESS_CORRECT
 See @file{stack.c}.
@@ -3690,9 +3707,15 @@
 done.
 
 @item STACK_ALIGN (@var{addr})
+@anchor{STACK_ALIGN}
 @findex STACK_ALIGN
-Define this to adjust the address to the alignment required for the
-processor's stack.
+Define this to increase @var{addr} so that it meets the alignment
+requirements for the processor's stack.
+
+Unlike @ref{frame_align}, this function always adjusts @var{addr}
+upwards.
+
+By default, no stack alignment is performed.
 
 @item STEP_SKIPS_DELAY (@var{addr})
 @findex STEP_SKIPS_DELAY

Re: [rfa:doco] document frame_align()

[Richard Earnshaw]

> +Unlike @ref{frame_align}, this function always adjusts @var{addr}
> +upwards.
  ^^^^^^^^
Even for stack_grows_upwards machines?

R.

Re: [rfa:doco] document frame_align()

[Andrew Cagney]

> +Unlike @ref{frame_align}, this function always adjusts @var{addr}
>> +upwards.
> 
>   ^^^^^^^^
> Even for stack_grows_upwards machines?

Yes.  This is different to frame align.

Andrew

Re: [rfa:doco] document frame_align()

[Eli Zaretskii]

On Wed, 18 Sep 2002, Andrew Cagney wrote:

> This documents the frame_align() architecture method.  It also clarifies 
> the behavior of stack_align().
> 
> ok?

Yes.  However:

  Unlike @ref{STACK_ALIGN}, this function always adjusts the address

Please don't use this technique.  It sounds cute at first glance, but 
produces text in the Info version which looks awkwardly:

  Unlike *note STACK_ALIGN, this function always adjusts the address

Instead, do it more straightforwardly:

  Unlike @code{STACK_ALIGN} (@pxref{STACK_ALIGN}), ...

(In this particular case, the @pxref is actually redundant, since you 
have a @pxref like that a few lines before that.)

Re: [rfa:doco] document frame_align()

[Andrew Cagney]

> On Wed, 18 Sep 2002, Andrew Cagney wrote:
> 
> 
>> This documents the frame_align() architecture method.  It also clarifies 
>> the behavior of stack_align().
>> 
>> ok?
> 
> 
> Yes.  However:
> 
>   Unlike @ref{STACK_ALIGN}, this function always adjusts the address
> 
> Please don't use this technique.  It sounds cute at first glance, but 
> produces text in the Info version which looks awkwardly:
> 
>   Unlike *note STACK_ALIGN, this function always adjusts the address
> 
> Instead, do it more straightforwardly:
> 
>   Unlike @code{STACK_ALIGN} (@pxref{STACK_ALIGN}), ...

Ok.

> (In this particular case, the @pxref is actually redundant, since you 
> have a @pxref like that a few lines before that.)

Hmm, ok.  Gone.  Committed with just ``Unlike @code{STACK_ALIGN} ...''.

thanks,
Andrew