{"id":50938483,"url":"https://github.com/johnwbyrd/llvm-docs","last_synced_at":"2026-06-17T11:32:28.673Z","repository":{"id":337611552,"uuid":"1136578633","full_name":"johnwbyrd/llvm-docs","owner":"johnwbyrd","description":"Process and design documentation for LLVM and LLVM-MOS features","archived":false,"fork":false,"pushed_at":"2026-02-10T11:45:44.000Z","size":96,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-10T16:21:52.079Z","etag":null,"topics":["clang","llvm","llvm-clang","llvm-mos","llvm-pass","tablegen"],"latest_commit_sha":null,"homepage":"https://www.llvm-mos.com","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnwbyrd.png","metadata":{"files":{"readme":"README.md","changelog":"changes.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-18T00:04:37.000Z","updated_at":"2026-02-10T11:45:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/johnwbyrd/llvm-docs","commit_stats":null,"previous_names":["johnwbyrd/llvm-docs"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/johnwbyrd/llvm-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnwbyrd%2Fllvm-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnwbyrd%2Fllvm-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnwbyrd%2Fllvm-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnwbyrd%2Fllvm-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnwbyrd","download_url":"https://codeload.github.com/johnwbyrd/llvm-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnwbyrd%2Fllvm-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34447264,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clang","llvm","llvm-clang","llvm-mos","llvm-pass","tablegen"],"created_at":"2026-06-17T11:32:27.907Z","updated_at":"2026-06-17T11:32:28.661Z","avatar_url":"https://github.com/johnwbyrd.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LLVM-MOS Development Guide for Claude\n\nThis file provides guidance to Claude Code when working with the LLVM-MOS repository located at `~/git/llvm-mos`.\n\n## Project Overview\n\nLLVM-MOS is a fork of LLVM that adds support for the MOS 65xx series of microprocessors (6502 and variants). It extends LLVM's code generation infrastructure to target vintage 8-bit processors commonly found in retro computers and embedded systems. The project includes a complete backend implementation with specialized optimizations for the unique constraints of 6502-based systems.\n\n## Build Output Handling\n\n**CRITICAL: NEVER pipe build output through `tail`, `head`, or similar truncation commands.**\n\nAll build commands MUST redirect output to a temporary file, then read the file afterwards:\n```bash\n# CORRECT - capture full output\ncmake --build build --target check-lld 2\u003e\u00261 | tee /tmp/build-output.log\n# Then read the relevant parts:\ncat /tmp/build-output.log  # or tail -100 /tmp/build-output.log\n\n# WRONG - loses important error context\ncmake --build build --target check-lld 2\u003e\u00261 | tail -60\n```\n\nLong-running builds produce megabytes of output. Piping through `tail` loses:\n- Early compilation errors that cause later failures\n- Warning messages that explain the root cause\n- Test names and line numbers needed for debugging\n\nAlways capture to a file first, then examine as needed.\n\n## Essential Build Commands\n\n### Initial Configuration\n```bash\n# Configure with MOS cache (recommended)\ncmake -C clang/cmake/caches/MOS.cmake -G Ninja -S llvm -B build\n\n# Add additional projects if needed\ncmake -C clang/cmake/caches/MOS.cmake -C .vscode/jbyrd-dev.cmake -DLLVM_ENABLE_PROJECTS=\"clang;clang-tools-extra;lld;lldb\" -S llvm -B build\n\n# Debug build with assertions\ncmake -C clang/cmake/caches/MOS.cmake -C .vscode/jbyrd-dev.cmake -DCMAKE_BUILD_TYPE=Debug -DLLVM_ENABLE_ASSERTIONS=On -S llvm -B build\n```\n\n### Building and Testing\n\n**CRITICAL: NEVER run `ninja` directly to build llvm-mos.** Always use either:\n1. `cmake --build build` (recommended)\n2. The full build script: `~/git/llvm-mos/.vscode/build-all.sh`\n\nRunning `ninja lld` or similar direct ninja invocations skips crucial steps:\n- Cross-compilation of the MOS runtime libraries (builtins, compiler-rt)\n- Installation of headers and libraries to the install directory\n- Proper sequencing of dependent targets\n\nThis creates subtle, hard-to-debug issues where the installed toolchain uses stale components. **Always do a full build!**\n\n```bash\n# Build all components (CORRECT)\ncmake --build build\n\n# Build and install (primary build command - CORRECT)\ncmake --build ~/git/llvm-mos/build --config Debug --target install --\n\n# Full rebuild including picolibc and test binaries (RECOMMENDED)\n~/git/llvm-mos/.vscode/build-all.sh\n\n# Build specific target - AVOID unless you know what you're doing\n# cmake --build build --target lld\n\n# Run all tests\ncmake --build build --target check-all\n\n# Run LLVM-specific tests\ncmake --build build --target check-llvm\n\n# Run MOS-specific tests\nllvm-lit build/test/CodeGen/MOS/\n\n# Run specific test file\nllvm-lit llvm/test/CodeGen/MOS/hello-world.ll\n```\n\n### Code Quality\n```bash\n# Format code (uses LLVM style)\nclang-format -i path/to/file.cpp\n\n# Format all modified files\nfind . -name \"*.cpp\" -o -name \"*.h\" | xargs clang-format -i\n\n# Update test CHECK lines\npython3 llvm/utils/update_llc_test_checks.py llvm/test/CodeGen/MOS/*.ll\n```\n\n## Architecture Overview\n\n### MOS Backend Structure\n\n**Core Target Files** (`llvm/lib/Target/MOS/`):\n- `MOSTargetMachine.cpp/.h` - Main target machine implementation\n- `MOSInstrInfo.td` - Real 6502 instruction definitions\n- `MOSInstrPseudos.td` - Pseudo instructions for code generation\n- `MOSRegisterInfo.td` - Register definitions including \"imaginary registers\"\n- `MOSDevices.td` - Processor variant definitions (6502, 65C02, W65816, etc.)\n\n**Key Optimization Passes**:\n- `MOSZeroPageAlloc.cpp` - Allocates frequently-used values to zero-page memory\n- `MOSStaticStackAlloc.cpp` - Converts dynamic to static stack allocation\n- `MOSCopyOpt.cpp` - Optimizes register-to-register copies\n- `MOSIndexIV.cpp` - Optimizes induction variables for indexed addressing\n- `MOSNonReentrant.cpp` - Optimizes non-reentrant functions\n- `MOSLateOptimization.cpp` - Post-register allocation optimizations\n\n**GlobalISel Support**:\n- `MOSCallLowering.cpp` - Function call/return handling\n- `MOSLegalizerInfo.cpp` - Legal operation definitions\n- `MOSRegisterBankInfo.cpp` - Register bank selection\n- `MOSInstructionSelector.cpp` - Final instruction selection\n\n### Register Architecture\n\nThe MOS backend uses an innovative approach to handle the 6502's limited register set:\n\n**Real Registers**: A, X, Y (8-bit), S (stack pointer), P (processor status)\n\n**Imaginary Registers**: Up to 256 8-bit registers (`rc0`-`rc255`) and 128 16-bit pointer registers (`rs0`-`rs127`) that map to zero-page memory locations and are treated as physical registers for allocation.\n\n### Instruction Model\n\nTwo-layer instruction architecture:\n1. **Machine Instructions** - Models actual 6502 instruction set with all irregularities\n2. **Pseudo Instructions** - Regularized virtual instruction set for code generation, lowered during assembly printing\n\n## Testing Guidelines\n\n### Test Organization\n- **MOS CodeGen Tests**: `llvm/test/CodeGen/MOS/`\n- **Machine IR Tests**: Use `.mir` files for testing specific passes\n- **Assembly Tests**: Test different assembler syntax variants (generic, ca65, xa65)\n\n### Running Tests\n```bash\n# All MOS tests\nllvm-lit llvm/test/CodeGen/MOS/\n\n# Specific optimization pass tests\nllvm-lit llvm/test/CodeGen/MOS/zeropage.ll\nllvm-lit llvm/test/CodeGen/MOS/static-stack-alloc.ll\n\n# Run with specific FileCheck prefixes\nllvm-lit --param=target_triple=mos-unknown-unknown test.ll\n```\n\n### Test Utilities\n- Use `llvm/utils/update_llc_test_checks.py` to automatically generate CHECK lines\n- Use `llvm/utils/update_test_checks.py` for general test updates\n- FileCheck patterns should test both functionality and performance characteristics\n\n## Common Development Patterns\n\n### Adding New Instructions\n1. Define in `MOSInstrInfo.td` with appropriate instruction format\n2. Add pseudo version in `MOSInstrPseudos.td` if needed\n3. Update `MOSInstrInfo.cpp` for any special handling\n4. Add tests in `llvm/test/CodeGen/MOS/`\n\n### Adding Processor Variants\n1. Define new subtarget features in `MOSDevices.td`\n2. Update instruction predicates to use new features\n3. Add variant-specific tests\n\n### Optimization Pass Development\n1. Follow LLVM pass structure conventions\n2. Consider zero-page allocation implications\n3. Test with both optimized and unoptimized builds\n4. Verify performance on real 6502 code patterns\n\n## Key Configuration Details\n\n### Important CMake Variables\n- `LLVM_EXPERIMENTAL_TARGETS_TO_BUILD=\"MOS\"` - Enables MOS target\n- `LLVM_DEFAULT_TARGET_TRIPLE=\"mos-unknown-unknown\"` - Default target\n- `LLDB_INCLUDE_TESTS=OFF` - Disabled until stabilized\n- Uses `MinSizeRel` build type by default for space optimization\n\n### Processor Variants Supported\n- 6502 (original with BCD)\n- 6502X (with \"illegal\" opcodes)\n- 65C02, R65C02, W65C02 (CMOS variants)\n- W65816 (16-bit capable)\n- HUC6280 (PC Engine)\n- SPC700 (Nintendo sound processor)\n- 65CE02, 65DTV02, 4510, 45GS02\n\n## Running and Tracing Assembly Programs\n\nThe llvm-mc tool includes a built-in emulator for running MOS programs directly.\n\n### Quick Test (Single Command)\n```bash\n# Assemble and run with instruction trace (discard object file)\nllvm-mc --triple=mos -filetype=obj -o /dev/null --run --trace program.s\n\n# Example output:\n# 0    $0000  A=00 X=00 Y=00 S=FF P=20    lda  #66\n# 2    $0002  A=42 X=00 Y=00 S=FF P=20    ldx  #16\n# 4    $0004  A=42 X=10 Y=00 S=FF P=20    ldy  #32\n# 6    $0006  A=42 X=10 Y=20 S=FF P=20    brk\n```\n\n### Emulator Options\n```bash\n--run                    # Execute after assembly\n--trace                  # Print each instruction with register state\n--run-max-cycles=\u003cN\u003e     # Limit execution cycles (default 1M)\n--semihost=\u003cpath\u003e        # Enable file I/O sandboxed to directory\n```\n\nThe trace output columns are: cycle count, PC, register state (A/X/Y/S/P), instruction.\n\nBRK halts the emulator by default (exit code 0). See `.vscode/emulation.md` for full documentation.\n\n## Debugging MOS Programs\n\nThe `.vscode/` directory contains scripts for source-level debugging of MOS programs using LLDB and MAME.\n\n### Debug Session Scripts\n\n**Starting a debug session:**\n```bash\n# Start with default test binary (float_qsort_O0)\n.vscode/debug-start.sh\n\n# Start with specific binary\n.vscode/debug-start.sh /path/to/binary.elf\n```\n\nThis starts:\n- MAME with the `zbcm6502` machine and GDB stub on port 23946\n- LLDB with MCP server on port 59999\n- Sets a breakpoint on `partition` and continues to it\n\n**Stopping a debug session:**\n```bash\n.vscode/debug-stop.sh\n```\n\n**Always run `debug-stop.sh` before starting a new session.** Stale MAME processes will cause connection failures.\n\n### Connecting to LLDB\n\nClaude can send LLDB commands via the MCP server:\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"command\",\"arguments\":{\"command\":\"bt\"}}}' | nc localhost 59999\n```\n\nCommon commands: `bt` (backtrace), `frame variable`, `frame select N`, `register read`\n\n### Log Files\n- MAME: `/tmp/mame-debug.log`\n- LLDB: `/tmp/lldb-debug.log`\n\n### Test Binaries\n\nTest programs are in `~/git/dwarf-torture/`. Build with `.vscode/build-all.sh` which builds llvm-mos, picolibc, and dwarf-torture together.\n\n## Git Branch Management\n\n**CRITICAL: When creating branches from `upstream/main`, always use `--no-track`:**\n\n```bash\n# CORRECT - prevents accidental pushes to upstream\ngit checkout -b feature/my-branch upstream/main --no-track\n\n# WRONG - creates tracking to upstream, sync button will push to upstream!\ngit checkout -b feature/my-branch upstream/main\n```\n\nIf you forget `--no-track`, immediately fix the tracking:\n```bash\ngit branch --set-upstream-to=origin/feature/my-branch\n```\n\nThe VSCode sync button pushes to the tracked remote. If a branch tracks `upstream/main`, clicking sync will push directly to the main llvm-mos repo, which is almost never what you want.\n\n## Development Workflow\n\n1. **Build**: Use MOS.cmake cache file for consistent configuration\n2. **Test**: Run MOS-specific tests frequently during development\n3. **Format**: Apply clang-format before committing\n4. **Validate**: Ensure changes work across multiple processor variants\n5. **Document**: Update tests and documentation for new features\n\nThe codebase follows LLVM coding standards strictly. All changes should include appropriate tests and maintain compatibility with the existing processor variant ecosystem.\n\nWhen rendering change descriptions, DO NOT WRITE \"Co-Authored By Claude\" on ANYTHING. That is extremely offensive.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnwbyrd%2Fllvm-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnwbyrd%2Fllvm-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnwbyrd%2Fllvm-docs/lists"}