documenting utrace callbacks better

[Frank Ch. Eigler]

Hi -

While hacking on the gdb stub thingie, I needed several irc talks with
roland to understand what I was seeing.  Some improved kerneldocs may
help matters.  Specifically ...

- The report_signal callback's block of description is too dense.  It
would be better to discuss the REPORT and HANDLER cases separately,
with respect to which input parameters are expected to be initialized,
and what return action values are valid.

Actually it would be nice for the overall signal handling process to
be illustrated as a timing diagram, listing the sequence of calls that
may arrive, and what actions at each stage may be typical.

- The UTRACE_SINGLESTEP action appears to require setting up a quiesce
callback echoing the utrace_control() request in order for it to
become effective.  (Without a quiesce, the singlestep request gets
lost and turned into a resume or something.)  The documentation
suggests setting up such a callback "may be" needed, but actually
it "is really" needed.


- FChE