for review: update trace/README

[Fergus Henderson]

Zoltan, can you please review this one?

--------------------

Estimated hours taken: 0.25

trace/README:
	Improve the documentation by describing the use of `saved_regs',
	and fix a copy of types (s/_hp()/_regs()/).

Index: trace/README
===================================================================
RCS file: /home/mercury1/repository/mercury/trace/README,v
retrieving revision 1.1
diff -u -r1.1 README
--- README	1998/11/06 10:35:39	1.1
+++ README	1998/11/09 05:09:05
@@ -10,13 +10,24 @@
 called directly from Mercury code, via MR_trace() in
 runtime/mercury_trace_base.c.
 
-For all code in this directory, the usual convention is that the
-normal Mercury registers are in their normal locations, not in the
-fake_reg copies, while the transient (register window) registers,
+One of the first things it does is to save the original values
+of the Mercury registers in a variable called `saved_regs'.
+The reason it needs to do this is that the code here may
+modify registers, e.g. by allocating memory using incr_hp
+or by calling Mercury code.  Once the original values of
+the registers have been saved, the trace subsystem is free
+to modify the Mercury registers.
+
+So for all code in this directory, the usual convention is that the
+original values of the Mercury registers are in `saved_regs',
+while the current (scratch) values for the normal non-transient
+Mercury registers etc. are in their normal locations, not in the
+fake_reg copies, and the transient (register window) registers,
 if any, are in the fake_reg copies.
+
 Any code which uses macros such as incr_hp(), list_cons(),
 make_aligned_string(), etc. that modify the heap pointer must call
-restore_transient_hp() beforehand and must call save_transient_hp()
+restore_transient_regs() beforehand and must call save_transient_regs()
 afterwards.  The simplest way to do this is to use the macro
 MR_USE_HP() in trace/mercury_trace_util.h.
 

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "Binaries may die
WWW: <http://www.cs.mu.oz.au/~fjh>  |   but source code lives forever"
PGP: finger fjh at 128.250.37.3        |     -- leaked Microsoft memo.