Revamp flags to allow fine grained control over aliasing

[moste00]

Your checklist for this pull request

• I've documented or updated the documentation of every API function and struct this PR changes.
• I've added tests that prove my fix is effective or that my feature works (if possible)

Detailed description

Implementing the extensive discussions here #2923 and here #2959.

Test plan

...

Closing issues

...

[Rot127]

I might have overlooked it because Github lags. But I don't see any tests with other combinations than real text.

Please add all the cases we discussed in the threads before here.
Especially the edge cases. And document them appropriately please.

[Rot127]

@slate5
Please take a look as well.

[Rot127]

If I haven't overlooked something, there are only the combination covered for:

CS_OPT_SYNTAX_REAL + default
CS_OPT_SYNTAX_REAL + CS_OPT_DETAIL_REAL
CS_OPT_SYNTAX_ALIAS + default
CS_OPT_SYNTAX_UNCOMPRESSED_REAL + default

So there are still the cases missing for:

CS_OPT_SYNTAX_REAL + CS_OPT_DETAIL_ALIAS
CS_OPT_SYNTAX_REAL + CS_OPT_DETAIL_UNCOMPRESSED_REAL
CS_OPT_SYNTAX_ALIAS + CS_OPT_DETAIL_REAL
CS_OPT_SYNTAX_ALIAS + CS_OPT_DETAIL_ALIAS
CS_OPT_SYNTAX_ALIAS + CS_OPT_DETAIL_UNCOMPRESSED_REAL
CS_OPT_SYNTAX_UNCOMPRESSED_REAL + CS_OPT_DETAIL_REAL
CS_OPT_SYNTAX_UNCOMPRESSED_REAL + CS_OPT_DETAIL_ALIAS
CS_OPT_SYNTAX_UNCOMPRESSED_REAL + CS_OPT_DETAIL_UNCOMPRESSED_REAL

I know it is annoying, but it is important that we have them checked at least twice. Ones with a normal instruction, once with a compressed.

I think it is better to add a new yaml file for those.

[moste00]

Never hurts to add tests, I will do that.

[moste00]

Ok I added more tests now, I also discovered there were some duplicate tests (character-for-character identical to other test cases), I deleted those.

I strongly oppose "the all possible combinations of flags for both compressed and non-compressed instructions", some combinations are really identical to others for some instruction types, for example UNCOMPRESSED_REAL doesn't do anything different from REAL to non-compressed instructions, so I'm not sure I see the value of really going full cartesian product.

I did add all 9 combinations of the 3x3 flags for representative instruction types.

[Rot127]

I am sorry, I didn't mentioned it in the first comment.
I was thinking more about a table like this:

Flag combination	normal insn	compressed instruction
CS_OPT_SYNTAX_REAL + default	asm: real insn text, details: real detail	asm: compressed real text, detail: compressed real details
CS_OPT_SYNTAX_REAL + CS_OPT_DETAIL_REAL	asm: real insn text, details: real detail	asm: compressed real text, detail: compressed real details
CS_OPT_SYNTAX_REAL + CS_OPT_DETAIL_ALIAS	asm: real insn text, details: alias detail	asm: compressed real text, detail: compressed alias details
...

The reason I prefer a table over sentences with pictures is two fold:

1. We must assume some new user starts using RISC-V and quickly wants to lookup what result a combination of flag will give them. They have only two kind of info: what flags they use, what type the instruction is. Reading long sentences with many commas is very error prone for that case.
2. The state machine pictures are not exhaustive, because they seem to only show the asm text case. The detail flags are missing in there, right? That makes it more confusing in combination with the next.

[moste00]

I see, but maybe it's wasteful to do every combination of two flags from the sets of flags ? they're completely orthogonal, no interaction whatsoever. It's never the case that a flag from one set affects the behaviour of another flag from a different set.

Maybe I thought about this so hard that it looks obvious though.

What makes this harder is that the *_ALIAS flag has like 5 different cases: full instruction prints as alias, compressed instruction prints as alias, full instruction prints as itself, compressed instruction prints as itself, compressed instruction uncompresses then prints as alias, compressed instruction uncompresses then prints as the equivalent normal instruction. Multiplying that by 6 (text alias flag with all 3 details flag, and details alias flag with all 3 text) would yield 30 cases (!). Most of that would be repetitive copy pasta, since varying text flags doesn't change details behaviour and varying the details flags doesn't change text behaviour.

How about just 2 seperate table for each sets of flags, each table having the 5 different cases for the alias (the other two are pretty tame and only discriminate between compressed and non-compressed like you sketched them).

[moste00]

Give me a sec to post a table that I think is much better than the cartesian product of {all text flags} x {all details flag} x {all instruction cases}

[moste00]

@Rot127 Sorry for the lateness, I was thinking about how to organize the diagram and had a false start with trying to implement in Google Docs and Google Sheets, before I had to fallback to html.

This could be embedded as either an image or plain html. It encodes a decision-tree-ish logic but in table form instead, what do you think about it ?

This table deals with text, but a similar table can be made for details and operands, and then the two tables can be put side by side under a single top-level decision like "wanting to change text" vs "wanting to change operands".

What do you think ?

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[moste00]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

Looks buggy, the PR has 3500 lines added and 3400 or so deleted, so less than 10K changed overall.