Article # 565, added by Geoworks, historical record
| first | previous | index | next | last |

What does the "on_stack" directive mean in an .asm file?




Q. What does the "on_stack" directive do in a .asm file?

A. on_stack passes a string to Swat to tell it where registers and
   return addresses are saved on the stack. this allows Swat to
   backtrace through functions that don't conform to its expectation of
   calling procedure. For example, if you jump from one procedure to
   another procedure, swat is unable to backtrace because it can't find a
   call on the stack to the routine it's in. however, if you put an
   "on_stack retf" declaration at the start of the routine that gets
   jumped to, then you tell swat that at ss:sp it will find the far
   return address and it will be able to backtrace. registers are
   declared starting from what ss:sp points to and moving up, thus:

   foo 	proc far jmp
	on_stack	retf
	push	ax, bx, cx
	on_stack	cx bx ax retf

   would tell Swat the right information.

   A couple tricks, though:
	- if a function contains an on_stack directive, Swat gives up all
	  responsibility for figuring out what's on the stack; it trusts
	  what's in the on_stack string. this means that when you push
	  registers on the stack, you need to generate a new on_stack
	  directive telling swat about the new register
	- if you push a bunch of registers, it's usually sufficient to just
	  put an on_stack at the end of the sequence for all the registers.
	  this means that if the thread context-switches away during that
	  sequence, you won't be able to backtrace the thread, but how often
	  does that really happen?
	- swat knows nothing about control flow in the function. as far as
	  it's concerned, on_stack is valid from the place at which it's set
	  through to the end of the function, unless another on_stack is
	  encountered.
	- if you push the flags register, say register "cc" is on the stack
	  (condition codes).
	- if the old xipPage mapping is pushed, say register "xipPage" is on
	  the stack.
	- possible return types are "retn", "retf", "iret", "ret=register"
	  if a near return address is in a register, and stackbot=xx.yy
	  if the return address is in the stack below TPD_stackBot. xx is the
	  name of the structure there, and yy is the field within it (can also
	  be of the form xx.yy,zz where zz is the name of the field that
	  contains the previous xipPage, meaning this function changed the XIP
	  page mapping)