We need rationale for the less obvious aspects in the spec

[tony-cole]

Re: riscv-cheri-v0.8.2.pdf

This could be in boxes or as notes or in some cases just references to other parts of the document where it is explained.

For instance:

Why is CAP_MAX_E = MXLEN - MW + 2, what is the +2 for?

I know the answers to following (now), but it was not clear to start with:

Why is the Exponent split in to ET and EB?
Why are the top 2-bits of T missing?
What is LMSB for?
Why is LMSB set to T8 for (MXLEN == 32) in: LMSB = (MXLEN == 32) ? T8 : 0?

[andresag01]

I agree that the rationale for these (and many more decisions) are not laid out in this specification. I think this is acceptable because it is an ISA specification and I expect most people reading to be purely interested on the function rather than the rational of how the ISA was constructed, so we should avoid polluting the text with too much content that is generally unnecessary to most people. However, I agree that there should be rational for some things here, particularly if there is a significant difference between the choice made here when compared to CHERI v9 -- I do not think it is the case with most questions you wrote in the ticket though.

For a detailed explanation and rationale of the capability encoding, please read the CHERI v9 spec and the CHERI Concentrate paper which are both referenced from this spec.

What do you think?

[carlrobshaw]

I agree with @andresag01 that we should keep the ISA specification as concise as possible. @tony-cole does have a good point, though and we should have a better justification and explanation for why the design choices were made. We have previously discussed adding a programming guide, maybe we need a design guide too? In this specific case, as you say, we could refer to the original CHERI concentrate paper and explain the changes we have made and why they were made.