Macan - LLVM-MCA Visualizer for Neovim

A powerful Neovim plugin that brings LLVM Machine Code Analyzer (LLVM-MCA) directly into your editor with real-time dependency analysis, live updates, and interactive timeline visualization.

Features

• Live Analysis - Automatic LLVM-MCA analysis on file save with configurable debouncing
• Interactive Timeline - View instruction timelines with dependency highlighting
• Dependency Analysis - Real-time instruction dependency detection with cursor-based highlighting
• Smart Compilation - Automatic integration with compile_commands.json
• Flexible Configuration - Custom compile flags and CPU architecture settings
• Precise Analysis - Set start/end markers to analyze specific code sections
• Clean Interface - Streamlined commands with unified configuration management

Screenshot

Quick Start

Prerequisites

• Neovim 0.7+ with Lua support (I hope so... I can't be fully sure)
• LLVM Tools including llvm-mca and clang/clang++
• compile_commands.json in your project root (generated by CMake, Bear, etc.)

Installation

Using lazy.nvim

{
  'aelobdog/macan.nvim',
  config = function()
    require('macan').setup({
      -- Optional configuration
      live_update = {
        enabled = true,
        debounce_ms = 1000,
      },
      llvm_mca = {
        march = 'skylake',  -- Your CPU architecture
      }
    })
  end,
}

Using packer.nvim

use {
  'aelobdog/macan.nvim',
  config = function()
    require('macan').setup()
  end
}

Using vim-plug

Plug 'aelobdog/macan.nvim'

-- Add to your init.lua:
require('macan').setup()

Using dein.vim

call dein#add('aelobdog/macan.nvim')

Using pathogen

cd ~/.vim/bundle
git clone https://github.com/aelobdog/macan.nvim.git

Manual Installation

# Clone to Neovim's pack directory
git clone https://github.com/aelobdog/macan.nvim.git \
  ~/.local/share/nvim/site/pack/plugins/start/macan.nvim

Note: The plugin works immediately after installation with sensible defaults:

• Live updates enabled with 1000ms debounce
• Auto-runs analysis on file save
• Uses LLVM-MCA's default CPU detection
• All commands available immediately

Call setup() only if you want to customize these defaults.

Basic Usage

1. Open a C source file in your project
2. Set analysis boundaries:

   :MacanSetStart    " Mark analysis start point
   :MacanSetEnd      " Mark analysis end point
   

3. Run analysis:

   :MacanRunMCA      " Manual analysis
   

   Or just save the file for automatic analysis!

Commands Reference

Essential Commands

Command	Description
:MacanRunMCA	Run LLVM-MCA analysis manually
:MacanSetStart	Set analysis start point at current line
:MacanSetEnd	Set analysis end point at current line
:MacanClearMarkers	Clear start/end markers

Live Updates

Command	Description
:MacanLiveToggle	Toggle live updates (shows current status)

Display

Command	Description
:MacanShowRawOutput	Show raw LLVM-MCA output
:MacanCloseAnalysis	Close analysis window

Configuration

Command	Description
:MacanEditCompileFlags	Edit compile flags for current file
:MacanClearCustomFlags	Clear custom compile flags
:MacanSetMarch <arch>	Set CPU architecture (e.g., skylake)
:MacanSetCompiler <arch>	Set CPU architecture (e.g., skylake)
:MacanConfig [subcommand]	Unified configuration management

Help

Command	Description
:MacanHelp	Show all available commands

Configuration

Default Configuration

The plugin works immediately with these sensible defaults:

{
  live_update = {
    enabled = true,           -- Live updates enabled
    debounce_ms = 1000,      -- 1 second debounce
    auto_run_on_save = true, -- Analyze on save
  },
  llvm_mca = {
    path = "llvm-mca",       -- Use llvm-mca from PATH
    march = nil,             -- Auto-detect CPU architecture
    extra_args = "-iterations=1 -timeline -timeline-max-iterations=1 -timeline-max-cycles=1000"
  },
  ui = {
    dependency_highlight = true, -- Enable dependency highlighting
  }
}

Custom Configuration

To override defaults, call setup():

require('macan').setup({
  -- Only specify what you want to change
  live_update = {
    debounce_ms = 500,       -- Faster updates
  },
  llvm_mca = {
    march = 'skylake',       -- Specific CPU architecture
  }
})

MacanConfig Subcommands

The :MacanConfig command provides unified configuration management:

:MacanConfig                 " Show configuration status
:MacanConfig status          " Same as above
:MacanConfig march           " Show current CPU architecture
:MacanConfig march-list      " List common CPU architectures
:MacanConfig march-clear     " Clear CPU architecture setting
:MacanConfig flags           " Show current compile flags for file
:MacanConfig help            " Show config help

CPU Architecture Examples

:MacanSetMarch skylake       " Intel Skylake
:MacanSetMarch znver3        " AMD Zen 3
:MacanSetMarch apple-m1      " Apple M1
:MacanSetMarch generic       " Generic target

Usage Workflow

1. Project Setup

Ensure your project has a compile_commands.json file:

# Using CMake
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .

# Using Bear
bear -- make

# Using Ninja
ninja -t compdb > compile_commands.json

2. Analyze Code Section

-- In your C file:
void performance_critical_function() {
    // Place cursor here and run :MacanSetStart
    
    for (int i = 0; i < 1000; i++) {
        result += expensive_computation(data[i]);
    }
    
    // Place cursor here and run :MacanSetEnd
}

3. View Results

The analysis window shows:

• Summary Section: Key metrics (IPC, throughput, cycles, etc.)
• Timeline Section: Instruction-by-instruction execution timeline
• Interactive Features: Hover over instructions to see dependencies

4. Dependency Analysis

• Orange highlighting: Instructions that have dependencies
• Red highlighting: Instructions the current one depends on (when cursor hovering)
• Status line: Shows dependency details with register information

Understanding the Output

Summary Metrics

Iterations:          1000     " Number of simulation iterations
Instructions:        15       " Total instructions analyzed
Total Cycles:        45       " Execution cycles
Total uOps:          20       " Micro-operations

Dispatch Width:      4.00     " Maximum dispatch width
uOps Per Cycle:      0.44     " Average μops per cycle
IPC:                 0.33     " Instructions per cycle
Block RThroughput:   12.5     " Reciprocal throughput

Timeline Format

[0,0]    DER   .    .    .    .    .    .    " Instruction timeline
[0,1]    DeER  .    .    .    .    .    .    " D=Dispatch, E=Execute, R=Retire
[1,0]    .DER  .    .    .    .    .    .    

Troubleshooting

Common Issues

"llvm-mca is NOT available in PATH"

• Install LLVM tools: sudo apt install llvm (Ubuntu) or brew install llvm (macOS)
• Ensure llvm-mca is in your PATH

"Error getting compile command"

• Ensure compile_commands.json exists in your project root
• Verify the file contains an entry for your current C file
• Check that file paths in compile_commands.json are correct

"Please set both LLVM_MCA_START and LLVM_MCA_END markers"

• Use :MacanSetStart and :MacanSetEnd to mark the code section to analyze
• Both markers are required before running analysis

"No timeline found in output"

• Check that your marked code section contains actual instructions
• Verify the compile command works with :MacanConfig flags
• Use :MacanShowRawOutput to see the full LLVM-MCA output

Getting Help

• Run :MacanHelp for command reference
• Use :MacanConfig status to check configuration
• Check :messages for detailed error information

Contributing

We welcome contributions! Please see our contributing guidelines:

Development Setup

git clone https://github.com/aelobdog/macan.nvim.git
cd macan.nvim

# Install in Neovim for testing
ln -s $(pwd) ~/.local/share/nvim/site/pack/dev/start/macan.nvim

Code Structure

lua/macan/
├── init.lua              " Main plugin entry point
├── config.lua            " Configuration management
├── llvm_mca.lua         " LLVM-MCA integration
├── dependency_analysis.lua " Instruction dependency analysis
├── live_update.lua      " Live update functionality
├── output.lua           " Output display and formatting
├── markers.lua          " Start/end marker management
├── compile_commands.lua " compile_commands.json parsing
├── compile_flags_ui.lua " Custom compile flags UI
└── asmgen.lua          " Assembly generation

License

MIT License - see LICENSE file for details.

Acknowledgments

• LLVM Project for the excellent MCA tool
• Neovim community for the amazing editor and ecosystem
• Sonnet-4-thinking for happily assisting me with almost the entire process

---

Note: This plugin is primarily designed for C source files. For best results, use it with C projects that have proper compile_commands.json configuration.