[FEATURE] Add detailed documentation for ARM branch condition codes in hover/intellisense

[StrideZhou]

[FEATURE] Add detailed documentation for ARM branch condition codes in hover/intellisense

Feature Description

Enhance ArmLS's on-hover documentation to include detailed explanations of ARM condition code suffixes (e.g., EQ, NE, CS/HS, CC/LO, MI, PL, VS, VC, HI, LS, GE, LT, GT, LE) when users hover over conditional branch instructions like B.EQ, B.NE, B.LT, etc.

The documentation should include:

• The meaning of each condition code suffix
• Which CPSR/NZCV flags are tested (Z, C, N, V)
• The logical condition expression (e.g., EQ: Z==1, NE: Z==0)
• Example usage patterns with CMP, TST, or other flag-setting instructions
• Distinction between AArch32 (A32/T32) and AArch64 (A64) conditional execution semantics

Problem Statement

Currently, ArmLS provides on-hover documentation for instruction mnemonics and operands, but conditional branch instructions with condition code suffixes (e.g., B.EQ label) may not display clear explanations of:

1. What condition the suffix represents
2. Which processor flags are evaluated
3. How the condition relates to preceding comparison instructions

Proposed Solution

1. Extend the hover provider to parse condition code suffixes from instruction mnemonics (e.g., extract EQ from B.EQ)
2. Add a condition code reference database within ArmLS containing:

   {
     "EQ": { "meaning": "Equal", "flags_tested": "Z", "condition": "Z==1", "aliases": [] },
     "NE": { "meaning": "Not equal", "flags_tested": "Z", "condition": "Z==0", "aliases": [] },
     "CS": { "meaning": "Carry set", "flags_tested": "C", "condition": "C==1", "aliases": ["HS"] },
     "CC": { "meaning": "Carry clear", "flags_tested": "C", "condition": "C==0", "aliases": ["LO"] },
     // ... all 16 standard condition codes
   }

3. Display enriched hover content when hovering B.EQ:

   B.EQ (Branch if Equal)
   ---------------------
   Condition: Z flag == 1 (set)
   Flags tested: Z (Zero)
   Typical usage: After CMP or TST instruction
   
   Example:
     CMP R0, R1
     B.EQ labels_equal  ; Branch if R0 == R1
   

4. Architecture-aware documentation: Differentiate behavior between:
   • AArch32: Most instructions support conditional execution
   • AArch64: Only branch instructions support condition codes; general instructions use CSEL/CSINC etc.
5. Optional: Add quick-info tooltips for individual condition suffixes when hovering just the EQ portion of B.EQ

Alternative Solutions

1. Link to external Arm Developer documentation: Add URLs to official condition code references in hover text. Drawback: Requires internet access and context-switching.
2. Expand general instruction documentation: Include condition code info in every conditional instruction's docs. Drawback: Redundant and increases maintenance burden.
3. Add a dedicated "Condition Codes" hover target: Allow hovering standalone EQ, NE, etc. tokens. Drawback: Requires parser changes to recognize suffixes as independent tokens.
4. Leverage vscode-armls extension: Implement documentation in the VS Code extension layer. Drawback: Reduces portability to other LSP-compatible editors.

Additional Context

• Official Arm condition code reference: https://developer.arm.com/documentation/100069/0606/Condition-Codes/Condition-code-suffixes
• ArmLS already implements hover for mnemonics, so this is a natural extension of existing functionality
• This feature would particularly benefit:
  • Students learning ARM assembly
  • Developers porting code between ARM architectures
  • Reverse engineers analyzing conditional logic

Example workflow improvement:

CMP  R0, #10
; User hovers over "B.HI" below:
B.HI  greater_than_10  ; Hover shows: "Branch if Higher (unsigned): C==1 && Z==0"

Related search terms users might expect to work: B.EQ documentation, ARM condition codes hover, branch condition flags armls

• I have searched for existing feature requests