[PATCH]: powerpc documentation: Clarify why twi appears in the i/o macros.

[Linas Vepstas]

On Fri, Dec 08, 2006 at 10:54:56PM +0100, Segher Boessenkool wrote:
> >>+ * A data-dependent branch followed by an isync ensures that no
> >
> >I think it's potentially confusing to talk about data-dependent
> >branches when what the code does is a twi instruction.  Even if you
> >argue that a twi is a data-dependent branch (and I disagree with that,
> >since a trap is not a branch),
> 
> If you argue it is *not* a branch, where in the architecture
> documentation can we find any language that gives us the
> guarantee we depend on here?

How about this wording: "A data-dependent branch, or trap word, 
followed by an isync ensures that ..."

> >that wouldn't be obvious to a casual
> >reader of the code.

I was trying to understand why the spidernet driver seemed to 
behave in the crazy ways that it does, and I decided to scrutinize 
this code. Even if one is relatively familiar with the overall
powerpc architecture (as I am), the effect of the twi/isync 
was far from obvious, and left me scratching my head.

> >In other words, I don't think the comment
> >clarifies the situation very much.

Later on, I tripped over some text written by Segher, that
made a lightbulb go off in my head ... and thus I was motiviated
to plagiarizingly cut-n-paste it into here.  So this block of 
text clarified things a lot for me, it "hit the spot".

Now, what I don't know is how accurate it really is ... I don't
know if there aren't any strange deviations on 403 or 601 or 
any of the modern embedded processors, or whatever. But the text
certainly makes me beleive I now know what's going on. As a
service to the next person who scratches thier head in wonderment, 
we should have at least something written up here.

--linas