Use more descriptive return values for `uc_emu_start`

[elicn]

The uc_emu_start function may be called with one or more arguments that determine when the emulation should stop: by last instruction address, timeout or instructions count. Unicorn also provides an API to set additional exit points that terminate the emulation once hit.

As of current version, uc_emu_start returns a value that indicates whether emulation terminated gracefully or not. However, it will be useful for the user to get an indication for the "termination reason" to allow them to handle it properly.

Possible termination reasons (non-exhaustive list):

• Hit end address
• Timeout elapsed
• Exhausted instructions count
• Hit an exit point
• Emulation stopped by uc_emu_stop
• Hit an unhandled exception (e.g.: performed an invalid write that was not handled by an appropriate hook)
• Hit an internal exception (i.e. reached an invalid internal state)

Further thinking: Having multiple normal and abnormal termination reasons might require re-thinking the way return values are enumerated. One way to address that is to adopt an approach similar to POSIX errors: negative return values for errors, positive return values for benign situations and zero for success.

[wtdcode]

Thanks for the advice. I get your point and that's on my (very long, unfortunately) TODO list. There actually exists such errno internally but not really ready for end users. I would prefer to retrieve "stop reasons" using a new uc_ctl as there is a lot of existing code checking 0 for success.

[elicn]

Good to know. Maybe it worth enumerating all planned enhancements somewhere so people can vote or add their thoughts.

I am not a big fan of retrieving the termination reasons using a new ctl.. Of course, it has the advantage of keeping consistency with the existing API, but at the same time it complicates the code and turns a common pattern of calling a function and making decisions according to its return value - to something more cumbersome. If breaking existing patterns is a no-go, consider doing so in a major release [as far as I can tell there are 'too many' features and enhancements that were put on hold because of that reason]. Another approach is to mask the 'ctl' approach with an intuitive binding, but then the binding API will have to change.

[wtdcode]

Another approach is to mask the 'ctl' approach with an intuitive binding, but then the binding API will have to change.

This is cool and I vote for this.