From 4b748379d5e843d735f237d0807df24e3c699989 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 3 Nov 2025 06:37:51 +0000
Subject: [PATCH 1/4] Initial plan


From e99c33cd2153b9bd6662b164ffa65946ec93893c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 3 Nov 2025 06:42:50 +0000
Subject: [PATCH 2/4] Add comprehensive QEMU architecture documentation

Co-authored-by: VideoGPU <6801937+VideoGPU@users.noreply.github.com>
---
 ARCHITECTURE.md | 481 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 481 insertions(+)
 create mode 100644 ARCHITECTURE.md

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000000000..ec56e4e6bc5de
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,481 @@
+# QEMU Architecture Overview
+
+**Version:** 10.1.50  
+**Last Updated:** 2025-11-03  
+**Purpose:** Comprehensive architectural reference for understanding QEMU codebase structure
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Core Architecture](#core-architecture)
+3. [Major Subsystems](#major-subsystems)
+4. [Directory Structure](#directory-structure)
+5. [Target Architectures](#target-architectures)
+6. [Build System](#build-system)
+7. [Key Technologies](#key-technologies)
+
+## Introduction
+
+QEMU (Quick Emulator) is a generic and open-source machine and userspace emulator and virtualizer. It provides:
+
+- **Full System Emulation**: Emulates complete machines in software without hardware virtualization
+- **User Mode Emulation**: Runs binaries compiled for one architecture on another architecture
+- **Virtualization**: Integrates with hypervisors (KVM, Xen, HVF, WHPX) for near-native performance
+
+### Key Capabilities
+- Dynamic binary translation using TCG (Tiny Code Generator)
+- Support for 20+ target architectures
+- Integration with multiple acceleration frameworks
+- Comprehensive device emulation
+- Live migration support
+- Snapshot and record/replay functionality
+
+## Core Architecture
+
+### High-Level Components
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    User Interfaces                       │
+│         (Monitor, GDB, QAPI, GUI, CLI)                  │
+└─────────────────────────────────────────────────────────┘
+                            │
+┌─────────────────────────────────────────────────────────┐
+│              Device Emulation (hw/)                      │
+│  CPU, Memory, PCI, USB, Network, Storage, Display, etc. │
+└─────────────────────────────────────────────────────────┘
+                            │
+┌─────────────────────────────────────────────────────────┐
+│           QEMU Object Model (QOM)                        │
+│      Type System, Properties, Lifecycle Management       │
+└─────────────────────────────────────────────────────────┘
+                            │
+┌─────────────────────────────────────────────────────────┐
+│              CPU Emulation (target/)                     │
+│     Architecture-specific CPU implementation             │
+└─────────────────────────────────────────────────────────┘
+                            │
+┌─────────────────────────────────────────────────────────┐
+│            Acceleration Layer (accel/)                   │
+│     TCG, KVM, HVF, WHPX, Xen, MSHV, NVMM               │
+└─────────────────────────────────────────────────────────┘
+                            │
+┌─────────────────────────────────────────────────────────┐
+│              Support Infrastructure                      │
+│  Block I/O, Network, Migration, Memory, Tracing, etc.   │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Execution Modes
+
+1. **System Mode** (`-softmmu`): Full machine emulation
+   - Emulates complete hardware including CPU, RAM, peripherals
+   - Used for running operating systems
+   
+2. **User Mode** (`linux-user`, `bsd-user`): Application-level emulation
+   - Emulates only CPU and system calls
+   - Runs binaries compiled for different architectures
+
+## Major Subsystems
+
+### 1. TCG (Tiny Code Generator)
+**Location:** `tcg/`, `target/*/tcg/`
+
+The dynamic binary translator that converts guest instructions to host instructions:
+- **Translation Blocks (TB)**: Basic unit of translated code
+- **IR (Intermediate Representation)**: Architecture-independent intermediate language
+- **Direct Block Chaining**: Optimizes TB transitions
+- **Register Allocation**: Maps guest registers to host registers
+
+### 2. QOM (QEMU Object Model)
+**Location:** `qom/`, `include/qom/`
+
+Object-oriented framework for QEMU:
+- **Type System**: Dynamic type registration and inheritance
+- **Properties**: Expose internal state for configuration
+- **Lifecycle Management**: Object creation, initialization, destruction
+- **Composition Tree**: Represents machine hierarchy (`info qom-tree`)
+
+### 3. Device Emulation
+**Location:** `hw/`
+
+Comprehensive hardware emulation organized by type:
+- **CPU devices** (`hw/cpu/`)
+- **Memory controllers** (`hw/mem/`)
+- **PCI/PCIe devices** (`hw/pci/`, `hw/pci-bridge/`, `hw/pci-host/`)
+- **Storage controllers** (`hw/ide/`, `hw/scsi/`, `hw/nvme/`)
+- **Network devices** (`hw/net/`)
+- **Display adapters** (`hw/display/`)
+- **Input devices** (`hw/input/`)
+- **USB controllers and devices** (`hw/usb/`)
+- **Interrupt controllers** (`hw/intc/`)
+- **Timers** (`hw/timer/`)
+- **DMA controllers** (`hw/dma/`)
+
+### 4. Block Layer
+**Location:** `block/`, `block.c`, `blockdev.c`
+
+Handles all disk image and block device operations:
+- **Image Formats**: qcow2, raw, vmdk, vdi, vhdx, etc.
+- **Block Drivers**: File, network (NBD, iSCSI, NFS), backend support
+- **I/O Scheduling**: Throttling, queuing, priorities
+- **Snapshots**: Internal and external snapshot support
+- **Encryption**: LUKS support
+
+### 5. Acceleration Frameworks
+**Location:** `accel/`
+
+Hardware and software acceleration:
+- **TCG** (`accel/tcg/`): Software dynamic translation
+- **KVM** (`accel/kvm/`): Linux Kernel-based Virtual Machine
+- **HVF** (`accel/hvf/`): macOS Hypervisor Framework
+- **WHPX** (Windows): Windows Hypervisor Platform
+- **Xen** (`accel/xen/`): Xen hypervisor integration
+- **MSHV** (`accel/mshv/`): Microsoft Hypervisor
+- **QTest** (`accel/qtest/`): Testing framework
+
+### 6. Memory Management
+**Location:** `system/`, `include/exec/memory.h`
+
+- **AddressSpace**: Represents view of memory from device/CPU perspective
+- **MemoryRegion**: Represents a region of memory or I/O
+- **RAMBlock**: Physical RAM allocation
+- **IOMMU**: I/O memory management unit support
+- **Dirty Tracking**: For live migration and snapshots
+
+### 7. Migration
+**Location:** `migration/`
+
+Live migration and snapshot functionality:
+- **Migration Protocols**: TCP, Unix sockets, exec, fd
+- **State Serialization**: VMState framework
+- **Compression**: Multi-threaded compression
+- **Post-copy Migration**: Allows faster migration start
+- **COLO-FT**: Coarse-grained Lock-stepping for fault tolerance
+
+### 8. QAPI (QEMU API)
+**Location:** `qapi/`
+
+Machine-readable API definition:
+- **Schema Definition**: JSON schema for commands and events
+- **Code Generation**: Automatic C code generation
+- **QMP (QEMU Machine Protocol)**: JSON-based management protocol
+- **HMP (Human Monitor Protocol)**: Human-readable command interface
+
+### 9. Tracing
+**Location:** `trace/`, `trace-events`
+
+Performance analysis and debugging:
+- **Multiple Backends**: log, ftrace, dtrace, syslog, simple
+- **Dynamic Enable/Disable**: Runtime control of trace points
+- **Zero-overhead**: When disabled, minimal performance impact
+
+### 10. Guest Agent (QEMU GA)
+**Location:** `qga/`
+
+Agent running inside guest for management:
+- **Guest Information**: OS version, network config, filesystem info
+- **Guest Control**: File operations, command execution
+- **Integration**: Works with management tools like libvirt
+
+## Directory Structure
+
+### Top-Level Directories
+
+| Directory | Purpose |
+|-----------|---------|
+| `accel/` | Acceleration frameworks (TCG, KVM, HVF, etc.) |
+| `audio/` | Audio backend implementations |
+| `authz/` | Authorization framework |
+| `backends/` | Various host resource backends (RNG, crypto, memory) |
+| `block/` | Block device and image format implementations |
+| `bsd-user/` | BSD user mode emulation |
+| `chardev/` | Character device backends (serial, parallel, etc.) |
+| `common-user/` | Common code for user mode emulation |
+| `configs/` | Build configuration files |
+| `contrib/` | Community-contributed tools and plugins |
+| `crypto/` | Cryptographic algorithm implementations |
+| `disas/` | Disassemblers for various architectures |
+| `docs/` | Comprehensive documentation |
+| `dump/` | VM memory dump functionality |
+| `ebpf/` | eBPF support for virtio-net RSS |
+| `fpu/` | Floating-point emulation |
+| `fsdev/` | VirtFS (9P filesystem) support |
+| `gdbstub/` | GDB remote debugging protocol implementation |
+| `gdb-xml/` | Architecture descriptions for GDB |
+| `host/` | Host-specific optimized code |
+| `hw/` | Hardware device emulation |
+| `include/` | Header files (mirrors source structure) |
+| `io/` | I/O channel abstractions |
+| `libdecnumber/` | Decimal number arithmetic library |
+| `linux-headers/` | Linux kernel headers for KVM |
+| `linux-user/` | Linux user mode emulation |
+| `migration/` | Live migration framework |
+| `monitor/` | Monitor (HMP/QMP) implementation |
+| `nbd/` | Network Block Device server |
+| `net/` | Network backend support |
+| `pc-bios/` | Pre-built firmware and boot images |
+| `plugins/` | TCG plugin framework |
+| `python/` | Python build and test utilities |
+| `qapi/` | QAPI schema definitions |
+| `qga/` | QEMU Guest Agent |
+| `qobject/` | QEMU Object implementation |
+| `qom/` | QEMU Object Model implementation |
+| `replay/` | Record/replay framework |
+| `roms/` | Source for firmware and ROMs |
+| `rust/` | Rust integration (new devices in Rust) |
+| `scripts/` | Build, test, and utility scripts |
+| `scsi/` | SCSI subsystem support |
+| `semihosting/` | Semihosting implementation |
+| `stats/` | Statistics monitoring |
+| `storage-daemon/` | QEMU storage daemon |
+| `stubs/` | Stub functions for minimal builds |
+| `subprojects/` | Meson subprojects |
+| `system/` | System mode implementation (CPU, MMU, boot) |
+| `target/` | Target architecture-specific code |
+| `tcg/` | Tiny Code Generator |
+| `tests/` | Test suite |
+| `tools/` | Standalone tools |
+| `trace/` | Tracing framework |
+| `ui/` | User interface implementations (GTK, SDL, VNC, etc.) |
+| `util/` | Utility functions |
+
+### Key Source Files
+
+| File | Purpose |
+|------|---------|
+| `block.c` | Block layer core (256K+ lines) |
+| `blockdev.c` | Block device management (114K lines) |
+| `blockjob.c` | Block job operations |
+| `configure` | Build configuration script |
+| `meson.build` | Meson build system configuration |
+| `qemu-img.c` | Disk image utility (187K lines) |
+| `qemu-io.c` | Block I/O testing tool |
+| `qemu-nbd.c` | NBD server utility |
+
+## Target Architectures
+
+**Location:** `target/`
+
+QEMU supports the following target architectures:
+
+| Architecture | Directory | Description |
+|--------------|-----------|-------------|
+| **x86** | `target/i386/` | Intel/AMD x86 (32-bit and 64-bit) |
+| **ARM** | `target/arm/` | ARM (32-bit and 64-bit/AArch64) |
+| **RISC-V** | `target/riscv/` | RISC-V (32-bit and 64-bit) |
+| **PowerPC** | `target/ppc/` | PowerPC (32-bit and 64-bit) |
+| **MIPS** | `target/mips/` | MIPS (32-bit and 64-bit) |
+| **S390x** | `target/s390x/` | IBM System/390 and z/Architecture |
+| **SPARC** | `target/sparc/` | SPARC and SPARC64 |
+| **Alpha** | `target/alpha/` | DEC Alpha |
+| **HPPA** | `target/hppa/` | HP PA-RISC |
+| **M68K** | `target/m68k/` | Motorola 68000 |
+| **LoongArch** | `target/loongarch/` | LoongArch 64-bit |
+| **Xtensa** | `target/xtensa/` | Tensilica Xtensa |
+| **Hexagon** | `target/hexagon/` | Qualcomm Hexagon DSP |
+| **AVR** | `target/avr/` | Atmel AVR |
+| **Microblaze** | `target/microblaze/` | Xilinx MicroBlaze |
+| **OpenRISC** | `target/openrisc/` | OpenRISC 1000 |
+| **CRIS** | `target/cris/` | Axis CRIS |
+| **RX** | `target/rx/` | Renesas RX |
+| **SH4** | `target/sh4/` | SuperH |
+| **TriCore** | `target/tricore/` | Infineon TriCore |
+
+### Target Architecture Structure
+
+Each target contains:
+- **TCG Translation**: Guest instruction to TCG IR conversion
+- **CPU Models**: Definitions for different CPU variants
+- **Helper Functions**: Complex operations called from translated code
+- **GDB Support**: Architecture-specific GDB integration
+- **Machine Definitions**: Board and system configurations
+
+## Build System
+
+### Configuration
+
+**Tool:** `configure` (shell script) + Meson
+
+**Usage:**
+```bash
+mkdir build
+cd build
+../configure [options]
+make
+```
+
+**Key Configuration Options:**
+- `--target-list`: Select target architectures to build
+- `--enable-kvm`: Enable KVM support
+- `--enable-debug`: Build with debug symbols
+- `--disable-werror`: Disable -Werror
+- `--enable-rust`: Enable Rust support (requires rustc >= 1.83.0)
+
+### Build System Files
+
+| File | Purpose |
+|------|---------|
+| `configure` | Main configuration script |
+| `meson.build` | Meson build definitions (top-level) |
+| `meson_options.txt` | Build options |
+| `Makefile` | Make wrapper around Meson |
+| `*/meson.build` | Per-directory build definitions |
+
+### Build Outputs
+
+- **System Mode Binaries**: `qemu-system-<arch>`
+- **User Mode Binaries**: `qemu-<arch>`
+- **Tools**: `qemu-img`, `qemu-io`, `qemu-nbd`, etc.
+
+## Key Technologies
+
+### 1. Dynamic Binary Translation (DBT)
+
+QEMU uses TCG for efficient guest-to-host translation:
+- **Translation Phase**: Guest instructions → TCG IR → Host instructions
+- **Execution Phase**: Execute translated code with periodic interrupt checks
+- **Optimization**: Block chaining, register allocation, constant propagation
+
+### 2. Device Models
+
+Devices are implemented using QOM:
+```c
+// Device structure
+typedef struct MyDevice {
+    DeviceState parent_obj;
+    // Device state
+} MyDevice;
+
+// Register device type
+static const TypeInfo my_device_info = {
+    .name = TYPE_MY_DEVICE,
+    .parent = TYPE_DEVICE,
+    .instance_size = sizeof(MyDevice),
+};
+```
+
+### 3. Memory Regions
+
+Memory is organized hierarchically:
+```c
+MemoryRegion *system_memory;  // Root memory region
+MemoryRegion *ram;            // RAM region
+MemoryRegion *rom;            // ROM region
+MemoryRegion *mmio;           // MMIO region
+```
+
+### 4. QAPI/QMP
+
+Machine-manageable interface:
+```json
+// QMP command
+{ "execute": "query-status" }
+
+// QMP response
+{ "return": { "status": "running" } }
+```
+
+## Architecture Patterns
+
+### Event Loop
+
+QEMU uses an event-driven architecture:
+- **Main Loop** (`system/main-loop.c`): Central event dispatcher
+- **AIO Context** (`util/aio-*.c`): Asynchronous I/O handling
+- **IOThread** (`iothread.c`): Additional event loops for I/O
+
+### Coroutines
+
+Block layer uses coroutines for async operations:
+- **Cooperative Multitasking**: Explicit yield points
+- **Stack Management**: Per-coroutine stacks
+- **Zero-copy**: Efficient I/O operations
+
+### Visitors Pattern
+
+Serialization uses visitor pattern:
+- **QObject Visitor**: JSON serialization
+- **String Visitor**: String representation
+- **VMState**: Migration state serialization
+
+## Testing Infrastructure
+
+**Location:** `tests/`
+
+### Test Categories
+
+1. **Unit Tests** (`tests/unit/`): Low-level functionality tests
+2. **QTest** (`tests/qtest/`): Device emulation tests
+3. **TCG Tests** (`tests/tcg/`): CPU instruction tests
+4. **Functional Tests** (`tests/functional/`): Full VM boot tests
+5. **I/O Tests** (`tests/qemu-iotests/`): Block layer tests
+
+### CI/CD
+
+- **GitLab CI** (`.gitlab-ci.yml`, `.gitlab-ci.d/`)
+- **Docker Containers** (`tests/docker/`)
+- **Multiple Platforms**: Linux, Windows, macOS, BSD
+
+## Maintenance Notes
+
+This document serves as a living reference for QEMU's architecture. It should be updated when:
+
+1. **Major architectural changes** are merged to master
+2. **New subsystems** are added
+3. **Directory structure** changes significantly
+4. **Key technologies** are replaced or updated
+
+### Update Process
+
+1. Monitor commits to the master branch
+2. Review architectural impact of changes
+3. Update relevant sections in this document
+4. Commit with descriptive message referencing the upstream changes
+
+## References
+
+- **Official Documentation**: https://www.qemu.org/documentation/
+- **Developer Docs**: https://www.qemu.org/docs/master/devel/index.html
+- **Wiki**: https://wiki.qemu.org/
+- **Source Repository**: https://gitlab.com/qemu-project/qemu
+- **Mailing List**: qemu-devel@nongnu.org
+
+## Quick Reference
+
+### Common Commands
+
+```bash
+# Build QEMU
+./configure && make -j$(nproc)
+
+# Run x86-64 VM
+qemu-system-x86_64 -m 2G -cdrom image.iso
+
+# Create disk image
+qemu-img create -f qcow2 disk.qcow2 20G
+
+# Run with KVM acceleration
+qemu-system-x86_64 -enable-kvm -m 4G disk.img
+
+# User mode (run ARM binary on x86)
+qemu-arm ./arm-binary
+
+# Monitor commands
+info qtree        # Device tree
+info mtree        # Memory tree
+info qom-tree     # QOM composition tree
+```
+
+### Important Files to Know
+
+- `MAINTAINERS`: Subsystem maintainers and file ownership
+- `VERSION`: Current QEMU version
+- `COPYING`, `LICENSE`: Licensing information
+- `README.rst`: Quick start guide
+- `docs/`: Comprehensive documentation
+
+---
+
+**Document Version:** 1.0  
+**QEMU Version:** 10.1.50  
+**Last Updated:** 2025-11-03

From 9b497f0aa7e6d7cf51b6e84d72d8d663d28725d1 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 3 Nov 2025 06:44:07 +0000
Subject: [PATCH 3/4] Update README and add architecture maintenance guide

Co-authored-by: VideoGPU <6801937+VideoGPU@users.noreply.github.com>
---
 .github/ARCHITECTURE_MAINTENANCE.md | 142 ++++++++++++++++++++++++++++
 README.rst                          |   3 +
 2 files changed, 145 insertions(+)
 create mode 100644 .github/ARCHITECTURE_MAINTENANCE.md

diff --git a/.github/ARCHITECTURE_MAINTENANCE.md b/.github/ARCHITECTURE_MAINTENANCE.md
new file mode 100644
index 0000000000000..f12cad9aa4538
--- /dev/null
+++ b/.github/ARCHITECTURE_MAINTENANCE.md
@@ -0,0 +1,142 @@
+# Architecture Documentation Maintenance Guide
+
+## Purpose
+
+This guide describes how to maintain `ARCHITECTURE.md` to keep it synchronized with changes to the QEMU codebase as they are pushed to master.
+
+## When to Update
+
+The architecture documentation should be reviewed and updated when:
+
+1. **Major Subsystem Changes**: New subsystems added or existing ones significantly refactored
+2. **Directory Restructuring**: Top-level directories added, removed, or reorganized
+3. **New Target Architectures**: Support for new CPU architectures added
+4. **Build System Changes**: Significant changes to configure/Meson build system
+5. **API Changes**: Major changes to core APIs (QOM, QAPI, TCG, etc.)
+6. **Version Updates**: QEMU version number changes
+
+## Update Process
+
+### 1. Monitor Master Branch
+
+Watch for commits to the master branch that might affect architecture:
+
+```bash
+git log --oneline origin/master --since="1 week ago" -- \
+  accel/ hw/ target/ include/ docs/devel/ meson.build configure
+```
+
+### 2. Review Changes
+
+For architectural changes, review:
+- Commit messages and linked issues
+- Changed files and their documentation
+- Developer mailing list discussions
+- Release notes
+
+### 3. Update ARCHITECTURE.md
+
+Update relevant sections:
+
+```bash
+# Edit the architecture document
+vi ARCHITECTURE.md
+
+# Update the "Last Updated" date
+# Update the QEMU version if changed
+# Update affected sections
+```
+
+### 4. Verify Accuracy
+
+Check that documentation matches reality:
+
+```bash
+# Verify directory structure
+ls -la | diff - <(grep "^\| \`.*\`" ARCHITECTURE.md | sed ...)
+
+# Check target architectures
+ls target/ | diff - <(grep target/ ARCHITECTURE.md | ...)
+
+# Verify subsystem locations
+```
+
+### 5. Commit Changes
+
+```bash
+git add ARCHITECTURE.md
+git commit -m "docs: Update architecture documentation for [change description]
+
+References: [commit hash or issue number]"
+```
+
+## Key Sections to Monitor
+
+### High Priority
+
+- **Target Architectures**: New CPU support is frequently added
+- **Major Subsystems**: Core functionality changes
+- **Directory Structure**: Reorganization affects navigation
+
+### Medium Priority
+
+- **Build System**: Changes to configure/Meson
+- **Key Technologies**: API updates
+- **Acceleration Frameworks**: New accelerator support
+
+### Low Priority
+
+- **Minor version updates**: Keep VERSION field current
+- **Reference links**: Ensure external links remain valid
+
+## Review Schedule
+
+- **Weekly**: Check for major architectural changes
+- **Monthly**: Review and update version information
+- **Per Release**: Comprehensive review before each QEMU release
+
+## Automation Opportunities
+
+Consider automating:
+
+1. **Directory Structure**: Script to generate directory tree from filesystem
+2. **Target List**: Extract from `target/` directory
+3. **Subsystem Detection**: Parse MAINTAINERS file for new subsystems
+4. **Version Sync**: Extract from VERSION file
+
+Example automation script:
+
+```bash
+#!/bin/bash
+# update-architecture-doc.sh
+
+VERSION=$(cat VERSION)
+sed -i "s/\*\*Version:\*\*.*/\*\*Version:\*\* $VERSION/" ARCHITECTURE.md
+sed -i "s/\*\*Last Updated:\*\*.*/\*\*Last Updated:\*\* $(date +%Y-%m-%d)/" ARCHITECTURE.md
+
+# Add more automated updates as needed
+```
+
+## Collaboration
+
+- **Mailing List**: Subscribe to qemu-devel@nongnu.org for architectural discussions
+- **GitLab Issues**: Watch for architecture-impacting issues
+- **Pull Requests**: Review PRs for architectural changes
+- **Documentation PRs**: Submit updates as separate documentation PRs
+
+## Contact
+
+For questions about architecture documentation maintenance:
+- Mailing List: qemu-devel@nongnu.org
+- Issue Tracker: https://gitlab.com/qemu-project/qemu/-/issues
+
+## Resources
+
+- [QEMU Developer Documentation](https://www.qemu.org/docs/master/devel/index.html)
+- [MAINTAINERS File](../MAINTAINERS)
+- [Contributing Guide](https://wiki.qemu.org/Contribute/SubmitAPatch)
+
+---
+
+**Document Version:** 1.0  
+**Last Updated:** 2025-11-03
diff --git a/README.rst b/README.rst
index b120a1f69e93f..f30cfb3e4ad62 100644
--- a/README.rst
+++ b/README.rst
@@ -41,6 +41,9 @@ current development version that is available at
 folder in the source tree, and is built by `Sphinx
 <https://www.sphinx-doc.org/en/master/>`_.
 
+For a comprehensive overview of QEMU's architecture, codebase structure,
+and major subsystems, see ``ARCHITECTURE.md`` in the root directory.
+
 
 Building
 ========

From 227e48e02de3708262118d1a2279b8d6e6315059 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 3 Nov 2025 06:45:23 +0000
Subject: [PATCH 4/4] Add quick reference guide for QEMU architecture

Co-authored-by: VideoGPU <6801937+VideoGPU@users.noreply.github.com>
---
 ARCHITECTURE_QUICK_REF.md | 121 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 121 insertions(+)
 create mode 100644 ARCHITECTURE_QUICK_REF.md

diff --git a/ARCHITECTURE_QUICK_REF.md b/ARCHITECTURE_QUICK_REF.md
new file mode 100644
index 0000000000000..4c645f2119542
--- /dev/null
+++ b/ARCHITECTURE_QUICK_REF.md
@@ -0,0 +1,121 @@
+# QEMU Architecture Quick Reference
+
+This is a condensed reference for quick lookups. For comprehensive details, see `ARCHITECTURE.md`.
+
+## What is QEMU?
+
+QEMU = Quick Emulator: A versatile machine emulator and virtualizer
+
+**Version:** 10.1.50
+
+## Core Modes
+
+1. **System Mode** (`qemu-system-*`): Full machine emulation
+2. **User Mode** (`qemu-*`): Run binaries for different architectures
+
+## Key Directories
+
+| Dir | What |
+|-----|------|
+| `target/` | CPU architectures (21 supported) |
+| `hw/` | Hardware devices (70+ categories) |
+| `accel/` | Accelerators (TCG, KVM, HVF, etc.) |
+| `block/` | Disk images and block devices |
+| `tcg/` | Binary translator |
+| `qom/` | Object model |
+| `docs/` | Documentation |
+| `tests/` | Test suite |
+
+## Major Subsystems
+
+1. **TCG**: Dynamic binary translation
+2. **QOM**: Object model and type system
+3. **Device Emulation**: Hardware simulation
+4. **Block Layer**: Storage and disk images
+5. **Migration**: Live VM migration
+6. **QAPI**: Management API (QMP/HMP)
+7. **Memory**: Address space management
+8. **Tracing**: Performance debugging
+
+## Supported Architectures
+
+x86, ARM, RISC-V, PowerPC, MIPS, S390x, SPARC, Alpha, HPPA, M68K, LoongArch, Xtensa, Hexagon, AVR, MicroBlaze, OpenRISC, RX, SH4, TriCore, and more.
+
+## Build System
+
+- **Config**: `./configure` (shell script)
+- **Build**: Meson + Make
+- **Rust**: Optional (requires rustc >= 1.83.0)
+
+## Common Commands
+
+```bash
+# Build
+./configure && make -j$(nproc)
+
+# Run VM
+qemu-system-x86_64 -m 2G -cdrom image.iso
+
+# Create disk
+qemu-img create -f qcow2 disk.qcow2 20G
+
+# User mode
+qemu-arm ./arm-binary
+
+# Monitor
+info qtree      # Device tree
+info mtree      # Memory tree
+info qom-tree   # Object tree
+```
+
+## Testing
+
+- `tests/unit/` - Unit tests
+- `tests/qtest/` - Device tests
+- `tests/tcg/` - CPU instruction tests
+- `tests/functional/` - Full VM tests
+- `tests/qemu-iotests/` - Block layer tests
+
+## Resources
+
+- **Docs**: `docs/` directory, https://www.qemu.org/documentation/
+- **Architecture**: `ARCHITECTURE.md` (detailed)
+- **Maintenance**: `.github/ARCHITECTURE_MAINTENANCE.md`
+- **Maintainers**: `MAINTAINERS` file
+- **Mailing List**: qemu-devel@nongnu.org
+- **Source**: https://gitlab.com/qemu-project/qemu
+
+## Architecture Layers
+
+```
+User Interfaces (Monitor, GDB, QAPI)
+         ↓
+  Device Emulation (hw/)
+         ↓
+    Object Model (QOM)
+         ↓
+  CPU Emulation (target/)
+         ↓
+   Acceleration (accel/)
+         ↓
+Support Infrastructure (block, net, migration)
+```
+
+## File Size Reference
+
+- `block.c`: 256K lines
+- `blockdev.c`: 114K lines
+- `qemu-img.c`: 187K lines
+- Total C/H files: Millions of lines
+
+## Contributing
+
+1. Subscribe to qemu-devel@nongnu.org
+2. Follow `docs/devel/submitting-a-patch.rst`
+3. Use `git format-patch` and `git send-email`
+4. Include `Signed-off-by` line
+
+---
+
+**For detailed information, see:** `ARCHITECTURE.md`  
+**Last Updated:** 2025-11-03