# 帳票設計書 7-CPU情報一覧

## 概要

本ドキュメントは、libuvライブラリにおける `uv_cpu_info()` API関数の帳票設計書である。システムの全CPUコア情報（モデル名・クロック速度・CPU時間内訳）をuv_cpu_info_t構造体の配列として出力する機能について定義する。

### 本帳票の処理概要

本帳票は、システムに搭載されている全てのCPUコアの情報を動的配列として取得する機能を提供する。CPUの論理コアごとにモデル名、クロック速度、各状態（user/nice/sys/idle/irq）の累計時間が出力される。

**業務上の目的・背景**：システムのCPUリソース状況を把握し、CPU別の負荷分散状況やハードウェアスペックの確認に利用する。マルチコア環境でのスレッドアフィニティ設定やキャパシティプランニングの判断材料となる。

**帳票の利用シーン**：システム情報の収集、CPU別負荷モニタリング、ハードウェアインベントリ、キャパシティプランニング。

**主要な出力内容**：
1. model（char*）：CPUモデル名文字列
2. speed（int）：CPUクロック速度（MHz単位）
3. cpu_times.user（uint64_t）：ユーザーモード時間（ミリ秒）
4. cpu_times.nice（uint64_t）：nice時間（ミリ秒）
5. cpu_times.sys（uint64_t）：システムモード時間（ミリ秒）
6. cpu_times.idle（uint64_t）：アイドル時間（ミリ秒）
7. cpu_times.irq（uint64_t）：割り込み処理時間（ミリ秒）

**帳票の出力タイミング**：`uv_cpu_info(&cpu_infos, &count)` 呼び出し時に動的メモリ確保と共に出力される。使用後は `uv_free_cpu_info()` で解放が必要。

**帳票の利用者**：システム管理者、運用監視チーム、パフォーマンスエンジニア。

## 帳票種別

システム情報一覧（動的配列出力）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | N/A（C API呼び出し） | N/A | `uv_cpu_info(&cpu_infos, &count)` 関数呼び出し |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | メモリ動的配列（uv_cpu_info_t*） |
| 出力方法 | ポインタ経由で動的配列を返却 |
| 解放方法 | uv_free_cpu_info(cpu_infos, count) |

## 帳票レイアウト

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 備考 |
|----|-------|------|-------------|---------|------|
| 1 | model | CPUモデル名 | プラットフォーム依存 | char*（ヒープ割当） | macOS: sysctl, Linux: /proc/cpuinfo |
| 2 | speed | クロック速度 | プラットフォーム依存 | int（MHz） | macOS: sysctl hw.cpufrequency / 1000000 |
| 3 | cpu_times.user | ユーザーモード時間 | プラットフォーム依存 | uint64_t（ミリ秒） | cpu_ticks[0] * multiplier |
| 4 | cpu_times.nice | nice時間 | プラットフォーム依存 | uint64_t（ミリ秒） | cpu_ticks[3] * multiplier |
| 5 | cpu_times.sys | システムモード時間 | プラットフォーム依存 | uint64_t（ミリ秒） | cpu_ticks[1] * multiplier |
| 6 | cpu_times.idle | アイドル時間 | プラットフォーム依存 | uint64_t（ミリ秒） | cpu_ticks[2] * multiplier |
| 7 | cpu_times.irq | 割り込み処理時間 | プラットフォーム依存 | uint64_t（ミリ秒） | macOS: 0（非サポート） |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| cpu_infosポインタ | 結果配列を受け取るポインタ変数のアドレス | Yes |
| countポインタ | CPU数を受け取るint変数のアドレス | Yes |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | CPUコアインデックス | 昇順（0から順） |

## データベース参照仕様

### 参照テーブル一覧（プラットフォーム別）

| プラットフォーム | データソース | 取得方法 |
|----------------|------------|---------|
| macOS | Mach host_processor_info | host_processor_info(PROCESSOR_CPU_LOAD_INFO) |
| macOS | sysctl | machdep.cpu.brand_string, hw.cpufrequency |
| Linux | /proc/cpuinfo | ファイル読み込み・パース |
| Linux | /proc/stat | ファイル読み込み・パース |
| FreeBSD | sysctl | hw.model, kern.cp_times |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| multiplier | 1000 / sysconf(_SC_CLK_TCK) | 整数除算 | clock ticksからミリ秒への変換係数 |
| cpu_times.user | cpu_ticks[0] * multiplier | 整数乗算 | |
| cpu_times.nice | cpu_ticks[3] * multiplier | 整数乗算 | |
| cpu_times.sys | cpu_ticks[1] * multiplier | 整数乗算 | |
| cpu_times.idle | cpu_ticks[2] * multiplier | 整数乗算 | |
| speed（macOS） | cpufrequency / 1000000 | 整数除算 | Hz -> MHz変換 |

## 処理フロー

### 出力フロー（macOS版）

```mermaid
flowchart TD
    A[uv_cpu_info呼び出し] --> B[sysctlbynameでCPUモデル名取得]
    B --> C[sysctlbynameでCPUクロック速度取得]
    C --> D{cpuspeed == 0?}
    D -->|Yes| E[2400000000をデフォルト値として設定]
    D -->|No| F[host_processor_infoでCPU負荷情報取得]
    E --> F
    F --> G{成功?}
    G -->|No| H[UV_EINVAL返却]
    G -->|Yes| I[uv__mallocでcpu_infos配列を確保]
    I --> J{成功?}
    J -->|No| K[vm_deallocate後にUV_ENOMEM返却]
    J -->|Yes| L[各CPUコアのデータをコピー]
    L --> M[vm_deallocateでMachリソース解放]
    M --> N[0を返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| モデル名取得失敗 | sysctlbyname()がエラーを返した場合 | N/A | UV__ERR(errno)を返却 |
| プロセッサ情報取得失敗 | host_processor_info()がKERN_SUCCESS以外 | N/A | UV_EINVALを返却 |
| メモリ確保失敗 | uv__malloc()がNULLを返した場合 | N/A | Machリソース解放後にUV_ENOMEMを返却 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | CPU論理コア数（数件〜数百件） |
| 目標出力時間 | ミリ秒オーダー |
| 同時出力数上限 | N/A |

## セキュリティ考慮事項

CPU情報はハードウェアスペックの開示に該当する。仮想化環境ではホストのCPU情報が漏洩する可能性がある。

## 備考

- 返却されたcpu_infos配列は `uv_free_cpu_info(cpu_infos, count)` で解放する必要がある
- Linuxではmodelフィールドのメモリが一括確保されるため、uv_free_cpu_info()の実装が簡略化されている
- macOSでARM64 CPUの場合、hw.cpufrequencyが取得できない場合があり、デフォルト値2.4GHzが使用される
- cpu_times の各値はミリ秒単位（clock ticksにmultiplierを乗じて変換）

---

## コードリーディングガイド

本帳票を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_cpu_times_s構造体（1203-1209行目）のuser, nice, sys, idle, irqフィールド（全てミリ秒単位のuint64_t） |
| 1-2 | uv.h | `include/uv.h` | uv_cpu_info_s構造体（1211-1215行目）のmodel, speed, cpu_timesメンバ |

#### Step 2: エントリーポイントを理解する（macOS版）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | darwin.c | `src/unix/darwin.c` | uv_cpu_info()（190-245行目）のmacOS固有実装 |

**主要処理フロー**:
1. **202-206行目**: sysctlbynameでCPUモデル名取得（machdep.cpu.brand_string -> hw.modelフォールバック）
2. **208-214行目**: sysctlbynameでCPUクロック速度取得（0の場合は2.4GHzをデフォルト設定）
3. **216-220行目**: host_processor_info(PROCESSOR_CPU_LOAD_INFO)でCPU負荷情報取得
4. **222-226行目**: uv__mallocで配列メモリ確保
5. **230-241行目**: 各CPUコアのtick値をmultiplierでミリ秒に変換しコピー
6. **242行目**: vm_deallocateでMachリソース解放

#### Step 3: メモリ解放を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | uv-common.c | `src/uv-common.c` | uv_free_cpu_info()（952-964行目）のプラットフォーム別解放ロジック |

### プログラム呼び出し階層図

```
uv_cpu_info(cpu_infos, count)              [プラットフォーム別]
    |
    +-- [macOS] src/unix/darwin.c:190
    |       +-- sysctlbyname("machdep.cpu.brand_string")
    |       +-- sysctlbyname("hw.cpufrequency")
    |       +-- host_processor_info(PROCESSOR_CPU_LOAD_INFO)
    |       +-- uv__malloc() / uv__strdup()
    |
    +-- [Linux] src/unix/linux.c:1695
    |       +-- /proc/cpuinfo読み込み
    |       +-- /proc/stat読み込み
    |
    +-- [FreeBSD] src/unix/freebsd.c:182
            +-- sysctl(hw.model, kern.cp_times)
```

### データフロー図

```
[入力]                          [処理]                      [出力]

[macOS]                         uv_cpu_info()               uv_cpu_info_t** (配列)
sysctl -----> model名           darwin.c:190                [0].model = "Apple M1"
sysctl -----> cpufrequency      配列確保                     [0].speed = 2400
host_processor_info -> ticks    tick -> ms変換               [0].cpu_times.user = ...
                                strdup(model)                [0].cpu_times.nice = ...
                                                             [0].cpu_times.sys = ...
                                                             [0].cpu_times.idle = ...
                                                             [0].cpu_times.irq = 0
                                                             *count = numcpus
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | uv_cpu_info_t/uv_cpu_times_s構造体定義、API宣言 |
| darwin.c | `src/unix/darwin.c` | ソース | macOS版uv_cpu_info()実装 |
| linux.c | `src/unix/linux.c` | ソース | Linux版uv_cpu_info()実装 |
| freebsd.c | `src/unix/freebsd.c` | ソース | FreeBSD版uv_cpu_info()実装 |
| uv-common.c | `src/uv-common.c` | ソース | uv_free_cpu_info()実装 |
