feat: 가상화 문서들 추가

2026-09-10 08:54:05 +09:00
parent e9f6a93327
commit 43e1aadef0
695 changed files with 153404 additions and 12754 deletions
@@ -0,0 +1,226 @@
+{
+  "version": "1.1",
+  "id": "virtio-balloon-inflate-deflate",
+  "title": "balloon target 은 VM Boundary 를 건너 driver 에 닿고 확보한 page 는 같은 경계를 되건너 온다",
+  "question": "Host 가 balloon target 을 바꾸면 그 요청은 어떤 순서로 어느 경계를 건너 Guest 안의 driver 까지 가고, 확보된 page 는 어떻게 Host 로 돌아오는가",
+  "type": "sequence",
+  "direction": "LR",
+  "audience": [
+    "Host RAM 압박에 ballooning 을 쓸지 판단하려는 사람",
+    "Guest 안의 메모리 압박을 Host 조치와 이어 보려는 사람"
+  ],
+  "summary": "balloon target 조정은 Host Memory Management 에서 QEMU 쪽 device 와 virtqueue 를 지나 VM Boundary 를 넘어 Guest kernel 의 driver 까지 가고, driver 가 확보한 Guest page 는 같은 경계를 반대 방향으로 되건너 Host 의 회수 가능 backing 이 된다.",
+  "alt": "virtio-balloon Driver, virtqueue, QEMU virtio-balloon Device, Host Memory Management 네 참여자 사이의 순서도. 앞 세 메시지는 오른쪽에서 왼쪽으로 Guest 안으로 들어가고 뒤 세 메시지는 왼쪽에서 오른쪽으로 Host 로 돌아온다.",
+  "long_description": "참여자는 왼쪽부터 Guest kernel 의 virtio-balloon Driver, virtqueue, QEMU virtio-balloon Device, Host Memory Management 네 개다. 메시지는 위에서 아래로 읽는다. 1번은 Host Memory Management 가 QEMU 쪽 device 에 balloon target 조정을 보내는 것이고, 2번에서 그 요청이 virtqueue 로 내려가면서 VM Boundary 를 넘고, 3번에서 Guest kernel 의 driver 에 balloon target 이 닿는다. 여기서 방향이 바뀐다. 4번에서 driver 가 확보한 Guest page 를 virtqueue 에 올리고, 5번에서 그것이 다시 VM Boundary 를 넘어 QEMU 쪽 device 로 가고, 6번에서 device 가 Host Memory Management 에 회수 가능 backing 으로 넘긴다. target 을 올릴 때와 내릴 때 Guest 가 쓸 수 있는 memory 가 어느 쪽으로 움직이는지는 본문의 표가 맡는다.",
+  "source_context": {
+    "document": "docs/virtualization/final/document.md",
+    "document_sha256": "181e2b3cc8a45bae81e7e8193d026937c4d586ae4495d3b2c323eb7e6abcfadd",
+    "anchor": {
+      "kind": "heading",
+      "value": "65. virtio-balloon 구조",
+      "line": 3008
+    }
+  },
+  "composition": {
+    "profile": "sequence",
+    "diagram_only": true,
+    "reference_ids": [
+      "payment-approval-sequence"
+    ],
+    "rationale": "이 절과 다음 절이 세운 것은 조각들의 나열이 아니라 balloon 요청이 지나는 차례와 그 차례가 VM Boundary 를 두 번 건넌다는 사실이다. two-zone-pipeline 으로 구역 둘을 그려 보니 같은 구역 안의 이음이 캔버스 맨 위로 튀어 올라가고 경계 라벨이 건너편 상자에 먹혔다. orchestrator-workers 는 QEMU 아래에 교체 가능한 워커들을 두는 그림이라 driver 가 Guest 안에 있다는 사실이 지워진다. sequence 는 참여자를 한 줄로 세우고 메시지에 번호를 붙이므로 경계를 두 번 건너는 왕복이 그대로 드러난다.",
+    "focus_node": "balloon-driver"
+  },
+  "groups": [],
+  "nodes": [
+    {
+      "id": "balloon-driver",
+      "label": "virtio-balloon Driver",
+      "kind": "driver",
+      "role": "participant",
+      "shape": "box",
+      "emphasis": "primary",
+      "details": [
+        "Guest Kernel"
+      ],
+      "description": "Guest kernel 쪽 balloon driver. target 을 받아 Guest page 를 확보한다.",
+      "evidence": [
+        {
+          "start_line": 3013,
+          "end_line": 3015
+        },
+        {
+          "start_line": 3046,
+          "end_line": 3046
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "virtqueue",
+      "label": "virtqueue",
+      "kind": "queue",
+      "role": "participant",
+      "shape": "box",
+      "description": "Guest 와 QEMU 가 balloon 요청을 주고받는 공유 큐. VM Boundary 바로 안쪽이다.",
+      "evidence": [
+        {
+          "start_line": 3017,
+          "end_line": 3017
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "qemu-balloon-device",
+      "label": "QEMU virtio-balloon\nDevice",
+      "kind": "service",
+      "role": "participant",
+      "shape": "box",
+      "description": "Host 쪽 balloon device. 경계를 넘어온 내용을 Host memory management 로 넘긴다.",
+      "evidence": [
+        {
+          "start_line": 3022,
+          "end_line": 3022
+        },
+        {
+          "start_line": 3037,
+          "end_line": 3041
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "host-memory-management",
+      "label": "Host Memory\nManagement",
+      "kind": "service",
+      "role": "participant",
+      "shape": "box",
+      "description": "balloon target 을 정하는 쪽이자 회수 기회가 생기는 자리.",
+      "evidence": [
+        {
+          "start_line": 3025,
+          "end_line": 3025
+        },
+        {
+          "start_line": 3034,
+          "end_line": 3037
+        }
+      ],
+      "assumption": false
+    }
+  ],
+  "edges": [
+    {
+      "id": "target-adjust",
+      "from": "host-memory-management",
+      "to": "qemu-balloon-device",
+      "label": "Balloon target 조정",
+      "kind": "control",
+      "order": 1,
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 3034,
+          "end_line": 3041
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "target-crosses-in",
+      "from": "qemu-balloon-device",
+      "to": "virtqueue",
+      "label": "VM Boundary",
+      "kind": "control",
+      "order": 2,
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 3017,
+          "end_line": 3022
+        },
+        {
+          "start_line": 3041,
+          "end_line": 3046
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "target-to-driver",
+      "from": "virtqueue",
+      "to": "balloon-driver",
+      "label": "Balloon target",
+      "kind": "control",
+      "order": 3,
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 3013,
+          "end_line": 3017
+        },
+        {
+          "start_line": 3043,
+          "end_line": 3046
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "pages-secured",
+      "from": "balloon-driver",
+      "to": "virtqueue",
+      "label": "Guest pages 확보",
+      "kind": "data",
+      "order": 4,
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 3046,
+          "end_line": 3050
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "pages-cross-out",
+      "from": "virtqueue",
+      "to": "qemu-balloon-device",
+      "label": "VM Boundary",
+      "kind": "data",
+      "order": 5,
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 3017,
+          "end_line": 3025
+        }
+      ],
+      "assumption": false
+    },
+    {
+      "id": "reclaimable-backing",
+      "from": "qemu-balloon-device",
+      "to": "host-memory-management",
+      "label": "회수 가능 backing",
+      "kind": "data",
+      "order": 6,
+      "style": "solid",
+      "evidence": [
+        {
+          "start_line": 3022,
+          "end_line": 3028
+        },
+        {
+          "start_line": 3077,
+          "end_line": 3079
+        }
+      ],
+      "assumption": false
+    }
+  ],
+  "legend": [],
+  "metadata": {
+    "rationale": "sequence 로 고른 이유는 §65 의 구조가 §66 의 차례와 붙어야 뜻이 나기 때문이다. 구조만 그리면 화살표가 한 방향뿐이고, 차례만 적으면 경계가 어디인지 안 보인다. deflate 쪽 절(§68)은 prepare 가 잡아 온 문맥(L2986-L3083) 밖이라 그 방향은 그리지 않았고, target 을 올릴 때와 내릴 때 Guest usable memory 가 어느 쪽으로 가는지는 기록 본문의 표가 이미 맡고 있어 그림에 넣지 않았다. 노드 라벨의 줄바꿈은 렌더러가 22자까지만 접기 때문에 넣었다 — 접지 않으면 글자가 상자 밖으로 나간다."
+  }
+}