RFC: Code Annotations for Unicorn Modifications

[tbe]

I have seen the call for help with the pending 2.2.0 release and QEMU upgrades by @wtdcode.

In my opinion, missing code annotations in Unicorn modifications are a major pain point.

Problem

QEMU upgrades are painful because we can't easily see:

• Why code was changed
• What type of modification it is
• Which QEMU changes might break our stuff

Solution

Annotate Unicorn-specific code with inline comments:

/* UNICORN-BEGIN: hook-system, intercept exceptions before do_interrupt */
if (cpu->exception_index < EXCP_INTERRUPT) {
    struct uc_struct *uc = cpu->uc;  /* UNICORN-MOD: api-change */

    HOOK_FOREACH(uc, hook, UC_HOOK_INTR) {
        ...
    }
}
/* UNICORN-END */

/* UNICORN-STUB: device-removal, NVIC not needed */
void armv7m_nvic_set_pending(void *opaque, int irq, bool secure) { }

Categories

Modifications could be placed in categories. Some common ones I found during analysis of the codebase:

• api-change - Function signatures (adding uc_struct param)
• hook-system - Hook code generation
• state-management - Execution control (stop_request, etc)
• device-removal - Stubbed device code
• context-passing - Threading uc_struct everywhere
• memory-hook - Memory instrumentation

How This Would Help

Maintenance:

• Contributors get a clear understanding of changes to upstream
• Easy to search code for existing, similar changes

QEMU upgrades:

• Scripts can extract all annotations and generate a list of affected areas
• Compare QEMU changes against our modifications

New contributors:

• Learn what we changed and why
• Follow established patterns

Basic Tooling Ideas

• Commit hooks: Ensure changes to QEMU are documented
• Diff analysis: Scripts could compare a target QEMU version and identify conflicts and resolutions

AI Assistance

While I am against using AI coding agents to actually write code, leveraging them to identify what needs to be done for:

• Upgrading QEMU to a higher version
• Backporting fixes
• Implementing/replacing features

could allow contributors with less time on their hand, to provide fixes and features, while outsourcing some of the research work to AI.

Questions

• What is the stance from @aquynh and @wtdcode on this?
• Are there other projects that do similar things?

Next Steps

I don't think it would be wise to backfill the current code, as a QEMU upgrade is incoming. I would suggest implementing such a concept DURING this rebase.

Tooling can be added later, once the foundation is there.

[aquynh]

Definitely a good thing to do. Can you send pull req? Thanks

…

On Wed, 29 Oct 2025, 21:36 tbe, ***@***.***> wrote: I have seen the call for help with the pending 2.2.0 release and QEMU upgrades by @wtdcode <https://github.com/wtdcode>. In my opinion, missing code annotations in Unicorn modifications are a major pain point. Problem QEMU upgrades are painful because we can't easily see: - Why code was changed - What type of modification it is - Which QEMU changes might break our stuff Solution Annotate Unicorn-specific code with inline comments: /* UNICORN-BEGIN: hook-system, intercept exceptions before do_interrupt */if (cpu->exception_index < EXCP_INTERRUPT) { struct uc_struct *uc = cpu->uc; /* UNICORN-MOD: api-change */ HOOK_FOREACH(uc, hook, UC_HOOK_INTR) { ... } }/* UNICORN-END */ /* UNICORN-STUB: device-removal, NVIC not needed */void armv7m_nvic_set_pending(void *opaque, int irq, bool secure) { } Categories Modifications could be placed in categories. Some common ones I found during analysis of the codebase: - api-change - Function signatures (adding uc_struct param) - hook-system - Hook code generation - state-management - Execution control (stop_request, etc) - device-removal - Stubbed device code - context-passing - Threading uc_struct everywhere - memory-hook - Memory instrumentation How This Would Help *Maintenance:* - Contributors get a clear understanding of changes to upstream - Easy to search code for existing, similar changes *QEMU upgrades:* - Scripts can extract all annotations and generate a list of affected areas - Compare QEMU changes against our modifications *New contributors:* - Learn what we changed and why - Follow established patterns Basic Tooling Ideas - *Commit hooks:* Ensure changes to QEMU are documented - *Diff analysis:* Scripts could compare a target QEMU version and identify conflicts and resolutions AI Assistance While I am against using AI coding agents to actually write code, leveraging them to identify what needs to be done for: - Upgrading QEMU to a higher version - Backporting fixes - Implementing/replacing features could allow contributors with less time on their hand, to provide fixes and features, while outsourcing some of the research work to AI. Questions - What is the stance from @aquynh <https://github.com/aquynh> and @wtdcode <https://github.com/wtdcode> on this? - Are there other projects that do similar things? Next Steps I don't think it would be wise to backfill the current code, as a QEMU upgrade is incoming. I would suggest implementing such a concept DURING this rebase. Tooling can be added later, once the foundation is there. — Reply to this email directly, view it on GitHub <#2252>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABNQNYBQVJUTLZEWVKCTP7D32C7F7AVCNFSM6AAAAACKRWFBPKVHI2DSMVQWIX3LMV43ERDJONRXK43TNFXW4OZZGA4DIOJYGQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[tbe]

Of course, i will. I am currently working on fixing Interrupt handling on armv7m, so i will prepare a PR with some example from there, and then we can discuss possible impacts and changes with some more detail.

[wtdcode]

I once tried the porting with AI tools. Honestly, the process is incredibly smooth and in most cases the code generated is expected.

BUT, a few issues prevent me from going this way further:

• Hard to ask AI to keep the current style, or even current code. For example, for a file with 10 functions and you ask AI to rewrite one of the functions. Sometimes, AI slightly changes the other nine functions, which is quite annoying and hard to discover.
• Insufficient unit tests for the current code base. Note, it is one of the main issues with manual porting, too, but AI-generated code without unit tests is scarier, honestly.
• Manual fixing AI code also needs huge amount of time, plus the overhead of writing prompts.

But yeah, I'm not against annotating the region Unicorn hacks and actually if you read a bit through the code, you will find that I'm already more or less doing this.

[tbe]

I currently use Claude to fill in the tagging comments, that works well. But

Hard to ask AI to keep the current style, or even current code.

Yes, suddenly claude decides that he no longer uses a diff to upstream, but he is searching for patterns...

I will try to do an AI assisted "rebase" on 5.2.0 for the qemu/target/arm subtree in the next days, lets see how this goes.

But yeah, I'm not against annotating the region Unicorn hacks and actually if you read a bit through the code, you will find that I'm already more or less doing this.

Yeah, heavily used parts are well documented. But some have not seen changes since the 2.0 rebase, and are full of surprises ;)