Clarify alignment "hint" being in "base 2 logarithmic representation"?

[hjorthjort]

I want to share a point of confusion that arose when I was reading the spec, and suggest how it could be alleviated. I got stuck for quite some time on this paragraph.

In file: spec/document/core/syntax/instructions.rst

The text on memory instructions says:

They all take a memory immediate |memarg| that contains an address offset and an alignment hint (in base 2 logarithmic representation).

Reading this, I was confused on 3 accounts:

1. My immediate interpretation was that offset and alignment would both be in logarithmic representation.
2. I didn't understand what was meant by an integer being in "base 2 logarithmic representation".
3. I didn't understand what "hint" was supposed to mean.

Maybe this could be alleviated by some rewording, though I don't have a suggestion.

However, what cleared it up for me was the note at the bottom of page 66:

The alignment \memarg.\ALIGN in load and store instructions does not affect the semantics. It is an indication that the offset \X{ea} at which the memory is accessed is intended to satisfy the property \X{ea} \mod 2^{\memarg.\ALIGN} = 0.

Perhaps this note, or a similar one, could be included adjacent to the introduction of memarg?

[ericprud]

@rossberg, is it your expectation that #966 addresses this?
@hjorthjort, can this be closed?

[rossberg]

Ah, yes. That hasn't landed yet, because I somehow forgot about it. Applied the suggestion last discussed on the issue, if somebody can approve I'll land and we can close this.

[hjorthjort]

The new wording is absolutely better. I still think that at first reading I might parse it as both offset and alignment are exponents of powers of 2. I agree that the singular "power" disambiguates it, but that's easy to miss/gloss over. Even clearer might be something like

an address offset and the expected alignment (the latter being expressed as the exponent of a power of 2)

But I'm not sure, and if you think the above becomes a bit too wordy, I'm happy with the new wording.

[rossberg]

Closed via #966.