Revamp flags to allow fine grained control over aliasing by moste00 · Pull Request #3008 · capstone-engine/capstone

moste00 · 2026-07-31T20:52:56Z

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 · 2026-08-01T13:34:13Z

@slate5
Please take a look as well.

Rot127 · 2026-08-09T17:01:56Z

-  Note that `+noalias` "overpowers" `noaliascompressed` in the second case: despite `+noaliascompressed` being false, meaning aliases are wanted for compressed instructions, `+noalias` being true means ALL aliases are supressed, and this takes precedence. Other than that, case 1 and case 3 work as intuitively expected, and case 4 is redundant. 
-
-  So a single-sentence description of this table is: if `+noalias` is given then no aliases will be printed for any instruction, but if not given then aliases will be printed for non-compressed instruction and alias printing for compressed instruction futher checks `+noaliascompressed` before proceeding.
+- Added RISC-V syntax/detail options for selecting real, uncompressed-real, or alias-preferred printing/details:


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:

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.

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.

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).

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}

@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 ?

This table looks good!
Putting one for details, one for text there is a good idea. Thanks!

…d details flag, other renaming

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 · 2026-08-16T19:01:14Z

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.

Co-authored-by: Rot127 <45763064+Rot127@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 93 out of 101 changed files in this pull request and generated 2 comments.

Suppressed comments (2)

arch/RISCV/RISCVInstPrinter.c:97

isUncompressedRealDetail() currently treats any detail mode other than REAL or ALIAS as "uncompressed real". This makes the default "CS_OPT_DETAIL" (only CS_OPT_ON set) look like uncompressed-real details, which is likely unintended and also breaks text/detail mode matching.
arch/RISCV/RISCVInstPrinter.c:102
isAliasDetail() currently requires CS_OPT_DETAIL_ALIAS to be set, but the historical/default behavior for "CS_OPT_DETAIL" is alias-derived details unless CS_OPT_DETAIL_REAL (or now UNCOMPRESSED_REAL) is requested. Treating the default as non-alias makes textAndDetailModesMatch false in the common default case and forces a second decode pass.

+static bool isAliasSyntax(const MCInst *MI)
+{
+	return MI->csh->syntax & CS_OPT_SYNTAX_ALIAS;
+}


Rot127 · 2026-08-22T12:04:03Z

@moste00 Also check the suppressed comments please.

… at all flags combinations

moste00 · 2026-08-23T01:02:08Z

@moste00 Also check the suppressed comments please.

Done, it's really only complaining about a typo and a check for the default-alias-syntax logic not being general enough (it catches only the explicit flag, not the absence of any flag). There is a complaint about the uncompressed real details being the default for details that I don't think is relevant, we agreed before that it should be the default when no details flag is mentioned.

I prettified the tables for both syntax and details and linked them as both images and as tables. I think this long PR is finally ready to land?

revamp flags to allow fine grained control over aliasing

199cd1e

github-actions Bot added RISCV Arch Python Bindings CS-core-files auto-sync Auto-Sync-files Auto-Sync Documentation labels Jul 31, 2026

Rot127 requested changes Aug 1, 2026

View reviewed changes

Comment thread bindings/python/capstone/__init__.py

Comment thread docs/cs_v6_release_guide.md

Comment thread arch/RISCV/RISCVInstPrinter.c Outdated

moste00 added 2 commits August 8, 2026 20:15

increase test coverage

bbefdfd

add docs and formatting

b27ccb5

Rot127 requested changes Aug 9, 2026

View reviewed changes

augment tests to ensure more coverage for all combinations of text an…

4791092

…d details flag, other renaming

Rot127 requested a lite review from Copilot August 16, 2026 18:55

Copilot AI reviewed Aug 16, 2026

Update cstool/cstool.c

2f401d1

Co-authored-by: Rot127 <45763064+Rot127@users.noreply.github.com>

moste00 force-pushed the feature/riscv_operands_details branch from 1656592 to 2f401d1 Compare August 16, 2026 19:11

Rot127 requested a lite review from Copilot August 22, 2026 11:53

Copilot started reviewing on behalf of Rot127 August 22, 2026 11:54 View session

Copilot AI reviewed Aug 22, 2026

View reviewed changes

Comment thread docs/cs_v6_release_guide.md Outdated

Comment thread arch/RISCV/RISCVInstPrinter.c

Comment on lines +82 to +85

static bool isAliasSyntax(const MCInst *MI)

{

return MI->csh->syntax & CS_OPT_SYNTAX_ALIAS;

}

moste00 added 3 commits August 22, 2026 23:31

add comprehensive test case coverage for all instruction combinations…

8f6975f

… at all flags combinations

fix issues legacy assertion

2f3ba82

enhance docs with table

45c3288

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`
...

Uh oh!

Conversation

moste00 commented Jul 31, 2026

Uh oh!

Rot127 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Rot127 commented Aug 1, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Rot127 Aug 9, 2026

Choose a reason for hiding this comment

Uh oh!

moste00 Aug 9, 2026

Choose a reason for hiding this comment

Uh oh!

moste00 Aug 9, 2026

Choose a reason for hiding this comment

Uh oh!

moste00 Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

Rot127 Aug 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

moste00 commented Aug 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Rot127 commented Aug 22, 2026

Uh oh!

moste00 commented Aug 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Rot127 Aug 22, 2026 •

edited

Loading