[LLVMdev] Suggestions for improvements to the GC docs.

[Talin]

I'm re-re-reading the "Accurate Garbage Collection with LLVM", and I'm
realizing that there are some parts of this document I find confusing.

1) I think that the term 'stack map' should be defined more precisely.
For example, in one place it says "LVM automatically computes a stack
map", and elsewhere it says "The compiler plugin is responsible for
generating code which conforms to the binary interface defined by
library, most essentially the stack map". At first glance, this seems
contradictory - who is generating the stack map, LLVM, or the compiler
plugin? The problem is that the words "stack map" are being used to
refer to two different things, one which is computed by LLVM, the
other generated by the compiler plugin.

Also, a definition of what a stack map is, and what it contains, would
be helpful.

2) It says LLVM does not address "discovery or registration of stack
frame descriptors." I'm not sure what is meant by a "stack frame
descriptor". Is this the same as a stack map?

3) The shadow-stack collector is presented as "an easy way to get
started". However, it doesn't give many hints as to what the next
logical evolutionary step would be - what method would you normally
use for crawling the various stack frames if you didn't want to pay
the performance penalty of maintaining the shadow stack? Something
like libunwind perhaps?

4) A more general question: In the barrier intrinsics, is there any
constraint on the values that the object pointer and the derived
pointer can take? In particular, I am thinking about the case where
you have an object, such as an ArrayList, in which there are two
separate non-contiguous allocations: A fixed-length "header" part, and
a variable-length "tail" part. Assume that the header part uses type
tags, but the tail part is just a raw data buffer. From a GC
perspective, it may be simplest to treat these as a single object,
such that only the head part gets added to the work queue, and both
are traced by the same tracer function. This implies, however, that
when calling gcwrite(), the 'derived' pointer might be in a different
memory block than the 'object' pointer, and may even be located at a
negative offset from it.

More questions to follow as I come up with them...

--
-- Talin