reorder capability chapter to show cap layout first

[axel-h]

Show the encoding first, then describe the field. This is what many other specs also do. When reading the specification, it gives a better overview what the rest of the chapter is about as one can picture something.

[axel-h]

Aligned with the changes proposed in #19

[Timmmm]

I agree this is much better.

[axel-h]

rebased, separated changes to different commits to allow better tracking.

[sorear]

It would be useful to start the chapter with a picture of the programmer's view of a capability. IMO it is extremely unuseful to start with a picture of the compressed capability bit representation, since the compression format is difficult to understand without first understanding the valid values of the abstract fields.

[Timmmm]

I agree it might seem weird but I definitely remember reading it and thinking "it's talking about all these things (bounds, permissions, etc.) but what are they?". Showing the compressed capability first gives you something concrete to explain.

Currently it's like trying to explain a car to someone that has never seen one before by saying "the components of a car are: wheels, engine, windows, ..." rather than than "here is a picture of a car, these bits are called the wheels, etc."

So yeah, it's backwards if you're writing a functional program, but I still think it's much much clearer. And I distinctly recall starting to read the "components of a capability, giving up, searching for the diagram and thinking 'this should be first'". If there are two of us with the exact same thought...

[Timmmm]

I think the wording could be refined after this is merged but it probably makes sense just to move things first.

[sorear]

What would people think about replacing everything between EF and BE in the introductory picture with a single BOUNDS field, and deferring the details of how the bounds are encoded until the bounds encoding chapter, in much the same way that we don't call out individual bits in SDP and AP and defer those to their respective chapters? (Don't block the merge on account of this question, this is a proposal for post-merge refinement.)

[arichardson]

What would people think about replacing everything between EF and BE in the introductory picture with a single BOUNDS field, and deferring the details of how the bounds are encoded until the bounds encoding chapter, in much the same way that we don't call out individual bits in SDP and AP and defer those to their respective chapters? (Don't block the merge on account of this question, this is a proposal for post-merge refinement.)

I think grouping the fields together would be very helpful. Not sure if we need two separate diagrams for that, maybe the asciidoc diagramming tool could allow us to add some shading and a legend or a grouping annotation? I would assume this is possible but I've not used it before.

I believe reording makes a lot of sense and is clearer.

[Timmmm]

Yeah I agree, a BOUNDS field makes loads of sense. Something like this?

The other thing that I think would make things clearer is a separate diagram for E=0, but that can probably wait, or maybe go in a separate explanatory document.

[bytefield]
----
(def svg-attrs {:style "background-color:white"})
(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 30}])
(defattrs :bg-yellow {:fill "#ffffc0"})
(def row-height 80)
(def row-header-fn nil)
(def left-margin 30)
(def right-margin 30)
(def bottom-margin 30)
(def boxes-per-row 32)
(draw-column-headers {:height 50 :font-size 26 :labels [
    "63" "" "" "57"
    "56" "53"
    "52" "48"
    "47" "" "" "" "" "" "" "" "28"
    "27"
    "26" "" "" "" "" "" "" "" "" "" "" "" "" "0"
]})

(draw-box "Reserved"    {:span 4})
(draw-box "SDP"         {:span 2})
(draw-box "AP"          {:span 2})
(draw-box "Reserved"    {:span 9})
(draw-box "S"           {:span 1})
(draw-box "BOUNDS"      [{:span 14} :bg-yellow])
(draw-box "Address"     {:span 32})
----

[bytefield]
----
(def svg-attrs {:style "background-color:white"})
(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 30}])
(defattrs :bg-yellow {:fill "#ffffc0"})
(def row-height 80)
(def left-margin 30)
(def right-margin 30)
(def bottom-margin 30)
(def boxes-per-row 14)
(draw-column-headers {:height 50 :font-size 26 :labels [
    "26"
    "25" "" "" "17"
    "16" "14"
    "13" "" "" "" "3"
    "2" "0"
]})

(draw-box "EF"          [{:span 1} :bg-yellow])
(draw-box "T[11:3]"     [{:span 4} :bg-yellow])
(draw-box "TE"          [{:span 2} :bg-yellow])
(draw-box "B[13:3]"     [{:span 5} :bg-yellow])
(draw-box "BE"          [{:span 2} :bg-yellow])
----

[axel-h]

I think the wording could be refined after this is merged but it probably makes sense just to move things first.

have have moved this out to other PRs, so here is just the reordering.

a BOUNDS field makes loads of sense. Something like this?

Yes, this look easier for the initial picture, then the dedicated BOUNDS section can break this down. Having separate Diagrams for EF 0/1 also make it easier to understand this.

[arichardson]

I think the wording could be refined after this is merged but it probably makes sense just to move things first.

have have moved this out to other PRs, so here is just the reordering.

a BOUNDS field makes loads of sense. Something like this?

Yes, this look easier for the initial picture, then the dedicated BOUNDS section can break this down. Having separate Diagrams for EF 0/1 also make it easier to understand this.

Agreed, I think both of these changes will make it easier to understand.

[arichardson]

LGTM, just one non-blocking comment.

[axel-h]

Rebased again. Since this is approved, I am not doing any significant changes here. The Main purpose of this PR was changing the order in the chapter to make this easier for the reader. Content change like suggested in #23 (comment) could be a follow-up then. If there is no plan to merge this reordering, please say so and close this PR.