document-haness/docs/virtualization/final/.techviz/qemu-block-backend-forms/spec.json

{
  "version": "1.1",
  "id": "qemu-block-backend-forms",
  "title": "virtqueue 뒤 QEMU block backend의 세 형태",
  "question": "Guest /dev/vda 요청이 VM boundary를 넘은 뒤 QEMU에서 qcow2, RAW, Host block device 중 어느 backend로 이어지는가",
  "type": "architecture",
  "direction": "LR",
  "audience": [
    "virtio-blk와 QEMU block backend 경계를 이해하려는 개발자",
    "Guest disk 이름만으로 Host backend를 단정하지 않으려는 운영자"
  ],
  "summary": "Guest /dev/vda의 I/O는 virtio-blk·virtqueue를 지나 Host userspace의 QEMU block backend로 넘어간다. backend는 qcow2 file, RAW file, Host block device 세 형태일 수 있다. 파일 backend는 Host filesystem을 경유하고, Host block device는 파일이 아닌 장치를 backend로 쓴다.",
  "alt": "Guest의 /dev/vda가 virtio-blk와 virtqueue를 지나 QEMU block backend에 도착한 뒤 qcow2 파일, RAW 파일, Host block device 세 갈래로 나뉘는 구조도. 그 아래 Host block stack은 별도 Concept이 맡아 이 그림에서는 다시 합치지 않는다.",
  "long_description": "왼쪽에서 Guest /dev/vda 요청이 virtio-blk와 virtqueue를 지나 VM boundary를 넘는다. QEMU block backend에서 qcow2 file, RAW file, Host block device 세 갈래로 나뉜다. qcow2와 RAW 노드에는 Host filesystem을 경유한다는 차이를, Host block device에는 파일 backend가 아니라는 차이를 적었다. 세 경로 아래의 Host block stack은 별도 Concept이 맡으므로 이 그림에서는 다시 합치지 않는다.",
  "source_context": {
    "document": "docs/virtualization/final/document.md",
    "document_sha256": "8c4ecc64c8cea9a4450ed7131fdd9cb2048dc092b66cd969f6346ed77887c210",
    "anchor": {
      "kind": "heading",
      "value": "제4부 — 스토리지 가상화",
      "line": 5791
    }
  },
  "composition": {
    "profile": "component-flow",
    "diagram_only": true,
    "reference_ids": [
      "payment-event-flow"
    ],
    "rationale": "핵심은 Guest disk 요청이 QEMU block backend를 지나 세 형태로 갈라지는 방향성이다. zone 상자보다 branch가 읽히는 것이 중요해 component-flow를 쓴다.",
    "focus_node": "backend"
  },
  "groups": [],
  "nodes": [
    {
      "id": "vda",
      "label": "/dev/vda",
      "kind": "storage",
      "role": "source",
      "description": "Guest가 보는 virtual disk.",
      "evidence": [
        {
          "start_line": 6355,
          "end_line": 6363
        }
      ],
      "assumption": false
    },
    {
      "id": "virtio-queue",
      "label": "virtio-blk · virtqueue",
      "kind": "component",
      "role": "service",
      "description": "Guest /dev/vda 요청을 virtio-blk가 받아 virtqueue에 싣는 경로를 한 노드로 묶었다.",
      "evidence": [
        {
          "start_line": 6355,
          "end_line": 6364
        }
      ],
      "assumption": false,
      "details": [
        "Guest",
        "VM boundary 직전"
      ]
    },
    {
      "id": "backend",
      "label": "QEMU block backend",
      "kind": "service",
      "role": "service",
      "emphasis": "primary",
      "description": "Guest virtual I/O를 실제 Host backend에 연결한다.",
      "evidence": [
        {
          "start_line": 6367,
          "end_line": 6387
        }
      ],
      "assumption": false
    },
    {
      "id": "qcow2",
      "label": "qcow2 file",
      "kind": "storage",
      "role": "service",
      "details": [
        "file backend",
        "mapping · metadata",
        "→ Host filesystem"
      ],
      "description": "sparse/COW 기능을 가진 file backend.",
      "evidence": [
        {
          "start_line": 6419,
          "end_line": 6460
        },
        {
          "start_line": 6512,
          "end_line": 6547
        }
      ],
      "assumption": false
    },
    {
      "id": "raw",
      "label": "RAW file",
      "kind": "storage",
      "role": "service",
      "description": "상대적으로 단순한 offset 대응을 쓰는 file backend.",
      "evidence": [
        {
          "start_line": 6512,
          "end_line": 6547
        }
      ],
      "assumption": false,
      "details": [
        "file backend",
        "offset 대응",
        "→ Host filesystem"
      ]
    },
    {
      "id": "block-device",
      "label": "Host block device",
      "kind": "storage",
      "role": "service",
      "details": [
        "/dev/...",
        "file 없음",
        "→ Host block stack"
      ],
      "description": "QEMU가 Host block device를 직접 backend로 사용할 수 있는 형태.",
      "evidence": [
        {
          "start_line": 6551,
          "end_line": 6575
        }
      ],
      "assumption": false
    }
  ],
  "edges": [
    {
      "id": "vda-virtio",
      "from": "vda",
      "to": "virtio-queue",
      "label": "block I/O",
      "kind": "request",
      "evidence": [
        {
          "start_line": 6355,
          "end_line": 6363
        }
      ],
      "assumption": false
    },
    {
      "id": "vq-backend",
      "from": "virtio-queue",
      "to": "backend",
      "label": "VM boundary",
      "kind": "request",
      "evidence": [
        {
          "start_line": 6362,
          "end_line": 6374
        }
      ],
      "assumption": false
    },
    {
      "id": "backend-qcow2",
      "from": "backend",
      "to": "qcow2",
      "label": "qcow2 backend",
      "kind": "data",
      "evidence": [
        {
          "start_line": 6369,
          "end_line": 6379
        },
        {
          "start_line": 6419,
          "end_line": 6460
        }
      ],
      "assumption": false
    },
    {
      "id": "backend-raw",
      "from": "backend",
      "to": "raw",
      "label": "RAW backend",
      "kind": "data",
      "evidence": [
        {
          "start_line": 6512,
          "end_line": 6547
        }
      ],
      "assumption": false
    },
    {
      "id": "backend-block",
      "from": "backend",
      "to": "block-device",
      "label": "block-device backend",
      "kind": "data",
      "evidence": [
        {
          "start_line": 6551,
          "end_line": 6575
        }
      ],
      "assumption": false
    }
  ],
  "legend": [],
  "metadata": {
    "rationale": "이 그림의 물음은 QEMU backend 세 형태의 경계 차이다. 세 경로가 결국 Host block stack으로 내려가는 것은 별도 Concept이 맡으므로, 재합류 노드는 빼고 각 backend detail에 다음 계층을 적었다."
  }
}