Allow Architecture::GetInstructionText to Return Multiple Lines of Text

[ehntoo]

What is the feature you'd like to have?
I would like to be able to return multiple lines of text from a custom architecture plugin's GetInstructionText function. This could come in the form of a new line separator InstructionTextToken type, rendering of a \n TextToken as a newline in assembly listings, or by some other method.

Is your feature request related to a problem?
In the Hexagon architecture, instructions are bundled into "packets". To correctly interpret and render the start and end of packets and to detect certain flow control operations, it is necessary to examine the whole packet at once. The Hexagon support plugin from Google (https://github.com/google/binja-hexagon) achieves this by keeping their own packet context database, but this carries a large memory overhead and limits Binary Ninja to only a single Hexagon binary open at a time.

As an alternative to keeping a separate context database in the architecture plugin, I'd like to handle parsing/lifting/printing an entire packet at a time. Hexagon packets can contain up to four instructions with additional modifiers, making them very difficult to scan if condensed to one line, motivating this feature request.

Are any alternative solutions acceptable?
Support for referencing the binary view in the architecture plugin (#551) would likely also provide a solution for this issue.

Alternatively, on slack I was contemplating the possibility of providing a context buffer to GetInstructionText based on the instruction start address and length returned by GetInstructionInfo. This would allow GetInstructionText to nibble off the individual instructions in a packet one at a time, while still retaining access to the whole packet context.

Additional Information:
Slack post referenced regarding alternative solutions: https://binaryninja.slack.com/archives/C1E616ZSQ/p1729965962827819

[xusheng6]

Likely we will only do #551 instead of this one; but I am leaving this open for reference and discussions

[ehntoo]

Thanks for the response! As I've been working more with the Hexagon architecture, I think #551 is probably complimentary to this issue rather than a replacement. My changes to print all instructions in a packet on a single line have been working very well, the resulting assembly is just very wide and more difficult than it needs to be to read.

Getting access to the binary view from the architecture would allow for a hacky solution to packet handling, where each instruction decode would need to look backwards and forwards in the binary view to find adjacent packet boundaries. There are a number of cases where this would fall apart - section boundaries, padding between code compilation units, or any intentionally obfuscated code could lead to incorrect decodes as the previous packet finding heuristic could fail.

Treating a "packet" as a single atomic instruction parse/lift instead gets you some of the nice properties of binary ninja's existing behavior for "overlapping" instructions for variable-length architectures like x86, and I think being able to produce multiple lines for a single "instruction" would be valuable for a number of implicitly parallel/VLIW-like architectures.

Given the other view types already produce multiple lines per input address, I'd hope this could be a fairly uninvasive change. 🤞

[CouleeApps]

Just adding that we have internally discussed doing this for quite some time now, since there's a number of places that it would be useful even without #551 like thumb ITT blocks.

It does seem like this would be a rather big lift for the API though, as it's changing the signature on what might be the most critical path in custom architecture support. Will need a lot of type trickery and guard rails to implement cleanly without breaking years of existing plugins.

[plafosse]

We now allow GetInstructionText to emit newline tokens to return multiple lines I believe this was done in 5.2 or earlier.

[zznop]

This is addressed by the NewLineToken that we added in Binja 5.2. We use this token in our Qualcomm Hexagon and TMS320 C6x architecture plugins to model instruction packets.