feat: 가상화 문서들 추가

docs/virtualization/final/.techviz/vm-exit-handling-cycle/spec.json

@@ -0,0 +1,240 @@
+{
+  "version": "1.1",
+  "id": "vm-exit-handling-cycle",
+  "title": "VM Exit 은 KVM 에서 끝나기도 하고 QEMU userspace 까지 가기도 한다",
+  "question": "VM Exit 이 난 뒤 제어권은 어디까지 올라갔다가 어떻게 Guest 로 돌아오는가",
+  "type": "flow",
+  "direction": "LR",
+  "audience": [
+    "VM 안의 지연을 계층별로 가르려는 사람",
+    "KVM 실행 경로를 처음 읽는 사람"
+  ],
+  "summary": "VM Exit 은 KVM 에서 Exit Reason 을 보고 두 갈래로 나뉘며, 커널 안에서 끝난 갈래와 QEMU userspace 를 거친 갈래가 어느 쪽이든 VM Entry 를 지나 Guest 실행으로 돌아온다.",
+  "alt": "Guest 에서 VM Exit 으로 KVM 에 닿은 뒤 커널 처리와 QEMU 처리 두 갈래로 갈라졌다가 VM Entry 로 다시 Guest 실행 재개에 모이는 흐름도.",
+  "long_description": "왼쪽에서 오른쪽으로 읽는다. 왼쪽 끝에 Guest 가 있고 VM Exit 이 KVM 으로 제어권을 넘긴다. KVM 은 Exit Reason 을 확인해 두 갈래 중 하나를 고른다. 커널 안에서 처리할 수 있는 Exit 은 Kernel 쪽 KVM 커널 처리로 가고, userspace 처리가 필요한 Exit 만 KVM_RUN 이 반환되면서 Userspace 쪽 QEMU 로 간다. QEMU 는 필요한 장치 동작을 처리한 뒤 KVM_RUN 을 다시 호출한다. 두 갈래는 오른쪽 끝에서 다시 만나며 어느 쪽이든 VM Entry 를 지나 Guest 실행 재개로 돌아온다. 무엇이 Exit 을 부르는지와 Exit 이 잦을 때 무엇을 함께 보는지는 본문의 표와 문단이 맡는다.",
+  "source_context": {
+    "document": "docs/virtualization/final/document.md",
+    "document_sha256": "181e2b3cc8a45bae81e7e8193d026937c4d586ae4495d3b2c323eb7e6abcfadd",
+    "anchor": {
+      "kind": "heading",
+      "value": "9. VM Exit 이후 처리",
+      "line": 493
+    }
+  },
+  "composition": {
+    "profile": "component-flow",
+    "diagram_only": true,
+    "reference_ids": [
+      "payment-event-flow"
+    ],
+    "rationale": "이 절이 주장하는 것은 제어권이 한 방향으로 지나가는 경로와 그 경로가 Exit Reason 에서 갈렸다가 다시 만난다는 것이다. sequence 는 참여자마다 생명선을 세우고 메시지를 시각 순서로 세우는데 이 절에는 갈래가 있어 한 줄로 세울 수 없고, orchestrator-workers 는 KVM 아래에 교체 가능한 워커들을 두는 그림이라 커널 갈래와 userspace 갈래가 서로 다른 경계에 있다는 사실이 지워진다.",
+    "focus_node": "kvm"
+  },
+  "groups": [],
+  "nodes": [
+    {
+      "id": "guest",
+      "label": "Guest",
+      "kind": "service",
+      "role": "source",
+      "shape": "box",
+      "description": "VM Exit 이 나기 직전까지 실행 중이던 Guest.",
+      "evidence": [
+        {
+          "start_line": 498,
+          "end_line": 501
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "kvm",
+      "label": "KVM",
+      "kind": "service",
+      "role": "service",
+      "shape": "box",
+      "emphasis": "primary",
+      "details": [
+        "Exit Reason"
+      ],
+      "description": "VM Exit 을 받아 Exit Reason 을 확인하고 갈래를 고르는 자리.",
+      "evidence": [
+        {
+          "start_line": 495,
+          "end_line": 495
+        },
+        {
+          "start_line": 502,
+          "end_line": 504
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "kvm-kernel-handling",
+      "label": "KVM 커널 처리",
+      "kind": "service",
+      "role": "service",
+      "shape": "box",
+      "description": "커널 안에서 끝낼 수 있는 Exit 을 처리하는 갈래. QEMU 까지 올라가지 않는다.",
+      "evidence": [
+        {
+          "start_line": 508,
+          "end_line": 510
+        },
+        {
+          "start_line": 531,
+          "end_line": 531
+        }
+      ],
+      "assumption": false,
+      "details": [
+        "Kernel"
+      ]
+    },
+    {
+      "id": "qemu",
+      "label": "QEMU",
+      "kind": "service",
+      "role": "service",
+      "shape": "box",
+      "details": [
+        "Userspace",
+        "device emulation",
+        "KVM_RUN 재호출"
+      ],
+      "description": "userspace 처리가 필요한 Exit 에서만 개입하는 갈래.",
+      "evidence": [
+        {
+          "start_line": 510,
+          "end_line": 516
+        },
+        {
+          "start_line": 533,
+          "end_line": 533
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "guest-resume",
+      "label": "Guest 실행 재개",
+      "kind": "service",
+      "role": "sink",
+      "shape": "box",
+      "description": "두 갈래가 다시 만나는 자리. VM Exit 은 VM 종료가 아니라 여기로 돌아온다.",
+      "evidence": [
+        {
+          "start_line": 521,
+          "end_line": 524
+        },
+        {
+          "start_line": 529,
+          "end_line": 529
+        }
+      ],
+      "assumption": false
+    }
+  ],
+  "edges": [
+    {
+      "id": "exit-to-kvm",
+      "from": "guest",
+      "to": "kvm",
+      "label": "VM Exit",
+      "kind": "control",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 495,
+          "end_line": 495
+        },
+        {
+          "start_line": 498,
+          "end_line": 502
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "kernel-branch",
+      "from": "kvm",
+      "to": "kvm-kernel-handling",
+      "label": "커널 처리 가능",
+      "kind": "control",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 504,
+          "end_line": 510
+        },
+        {
+          "start_line": 531,
+          "end_line": 531
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "userspace-branch",
+      "from": "kvm",
+      "to": "qemu",
+      "label": "KVM_RUN return",
+      "kind": "control",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 508,
+          "end_line": 512
+        },
+        {
+          "start_line": 533,
+          "end_line": 533
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "kernel-reentry",
+      "from": "kvm-kernel-handling",
+      "to": "guest-resume",
+      "label": "VM Entry",
+      "kind": "control",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 518,
+          "end_line": 524
+        },
+        {
+          "start_line": 531,
+          "end_line": 531
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "userspace-reentry",
+      "from": "qemu",
+      "to": "guest-resume",
+      "label": "VM Entry",
+      "kind": "control",
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 514,
+          "end_line": 524
+        },
+        {
+          "start_line": 533,
+          "end_line": 533
+        }
+      ],
+      "assumption": false
+    }
+  ],
+  "legend": [],
+  "metadata": {
+    "rationale": "flow 로 고른 이유는 이 절이 답하는 물음이 「제어권이 어디까지 갔다가 어떻게 돌아오는가」이기 때문이다. Kernel·Userspace 를 경계 상자로 그리면 두 상자가 같은 열에서 겹쳐(check-figure-overlap 15750px²) 어느 노드가 어느 경계인지 오히려 흐려져 노드의 details 로 내렸다. 무엇이 Exit 을 부르는지(§8)와 Exit 이 잦을 때 무엇을 함께 보는지는 본문 표가 이미 맡고 있어 그림에 넣지 않았다."
+  }
+}