# Aios Shell Implementation Guide

## Overview

Aiosのインタラクティブシェル実装についての詳細ガイド。

## Implementation History

### Phase 1: Initial Attempt (Failed)

**実装内容:**
```rust
// keyboard.rs - 複雑な実装
use core::convert::TryFrom;

static SCANCODE_TO_ASCII: [u8; 128] = [
    // 複雑なマッピングテーブル
];

unsafe fn inb(port: u16) -> u8 {
    // 危険なポートアクセス
}
```

**問題:**
- Page table panic (`page_table*.rs:105:25`)
- ポートI/O競合
- 配列サイズ不一致

### Phase 2: Safe Approach (Partially Working)

**実装内容:**
```rust
// keyboard_safe.rs
unsafe fn try_inb(port: u16) -> Option<u8> {
    // 遅延付きアクセス
    for _ in 0..1000 {
        core::arch::asm!("nop");
    }
    // ... 安全なアクセス
}
```

**結果:**
- パニックは解決
- キーボード入力が機能しない

### Phase 3: Basic Implementation (Success)

**実装内容:**
```rust
// keyboard_basic.rs - シンプルなアプローチ
pub fn has_key() -> bool {
    unsafe {
        let status: u8;
        core::arch::asm!(
            "in al, 0x64",
            out("al") status,
            options(nomem, nostack, preserves_flags)
        );
        (status & 1) != 0
    }
}
```

**結果:**
- パニック解決
- キーボード入力動作
- スキャンコード正常取得

## Architecture

### Keyboard Driver (`keyboard_basic.rs`)

```rust
/// PS/2キーボードの状態確認
pub fn has_key() -> bool

/// 生スキャンコードの読み取り
pub fn read_scancode() -> u8

/// スキャンコードからASCII文字への変換
pub fn scancode_to_char(scancode: u8) -> Option<char>
```

**キーマッピング:**
```rust
match scancode {
    0x1E => Some('a'),  // A key
    0x30 => Some('b'),  // B key
    0x2E => Some('c'),  // C key
    // ...
    0x39 => Some(' '),  // Space
    0x1C => Some('\n'), // Enter
    _ => None,
}
```

### Shell Core (`main.rs`)

**State Management:**
```rust
static mut INPUT_BUFFER: [u8; 64] = [0; 64];
static mut INPUT_POS: usize = 0;
static mut CURSOR_ROW: usize = 12;
static mut CURSOR_COL: usize = 6;
```

**Input Processing:**
```rust
fn process_char(ch: char) {
    match ch {
        '\n' => execute_command(),
        '\u{8}' => handle_backspace(),
        ' '..='~' => add_char_to_buffer(ch),
        _ => { /* ignore */ }
    }
}
```

**Command Execution:**
```rust
fn execute_command() {
    let cmd = core::str::from_utf8(&INPUT_BUFFER[..INPUT_POS])?;
    match cmd {
        "help" => show_help(),
        "version" => show_version(),
        "echo" => echo_test(),
        "clear" => clear_screen(),
        _ => show_unknown_command(cmd),
    }
}
```

## Key Features

### 1. Real-time Input
- キー押下の即座の反映
- バックスペース対応
- 文字制限（64文字）

### 2. Command Processing
- Enter キーでコマンド実行
- コマンド履歴（将来実装予定）
- エラーハンドリング

### 3. Available Commands

**help**
```
Aios Commands:
  help    - Show this help
  version - Show version
  echo    - Echo test
  clear   - Clear screen
```

**version**
```
Aios 2.0 - AI Operating System
Interactive Shell with Keyboard Support
```

**echo**
```
Hello from Aios Interactive Shell!
```

**clear**
- 画面全体をクリア
- カーソル位置をリセット

### 4. Input Handling

**Scancode Processing:**
```rust
loop {
    if keyboard_basic::has_key() {
        let scancode = keyboard_basic::read_scancode();
        
        // キーリリースを除外
        if scancode != last_scancode && (scancode & 0x80) == 0 {
            last_scancode = scancode;
            
            if let Some(ch) = keyboard_basic::scancode_to_char(scancode) {
                process_char(ch);
            }
        }
    }
    
    // CPU負荷軽減
    for _ in 0..1000 {
        unsafe { core::arch::asm!("nop"); }
    }
}
```

## VGA Text Mode Interface

### Screen Layout
```
Row 0:  "Aios - AI Operating System"     (Center)
Row 1:  "Interactive Shell Ready"           (Center)  
Row 2:  "Type 'help' for commands"          (Center)
Row 3:  [Empty]
Row 4:  [Empty]
Row 5:  aios> [user input]                  (Prompt)
Row 6+: [Command output]
```

### Character Display
```rust
pub fn print_char(c: u8, x: usize, y: usize) {
    if x >= 80 || y >= 25 { return; }
    
    unsafe {
        let vga = &mut *VGA_BUFFER;
        vga.chars[y][x] = (0x0f << 8) | (c as u16);
        //                 ^^^^         ^^^^^^^^^^
        //                 Color        Character
        //                 (White/Black) (ASCII)
    }
}
```

**Color Scheme:**
- `0x0f` = White text on black background
- Format: `(color << 8) | character`

## Testing Procedures

### 1. Scancode Debug Test
```rust
// 目的: キーボード入力の確認
// 表示: "Scancode: 0x1E -> 'a'"
```

### 2. Interactive Shell Test
```bash
# テストシーケンス
1. help <Enter>       # ヘルプ表示確認
2. version <Enter>    # バージョン情報確認
3. echo <Enter>       # エコーテスト確認
4. clear <Enter>      # 画面クリア確認
5. invalid <Enter>    # エラーハンドリング確認
```

### 3. Input Edge Cases
```bash
# テストケース
- 空のコマンド (Enter のみ)
- 長いコマンド (64文字以上)
- バックスペースの動作
- 連続入力
```

## Performance Considerations

### CPU Usage
```rust
// 軽量な遅延ループ
for _ in 0..1000 {
    unsafe { core::arch::asm!("nop"); }
}
```

### Memory Usage
- Input buffer: 64 bytes
- VGA buffer: Direct access (no buffering)
- Static variables: Minimal usage

### Polling Frequency
- 高頻度ポーリング（遅延1000サイクル）
- CPU halt命令は使用しない（応答性重視）

## Known Limitations

### 1. Character Set
- ASCII printable characters only (`' '` to `'~'`)
- 日本語等のマルチバイト文字は未対応
- 特殊キー（F1-F12, Arrow keys）は未対応

### 2. Input Features
- コマンド履歴なし
- Tab補完なし
- 行編集機能なし（カーソル移動等）

### 3. Display
- 80x25 text mode固定
- スクロール機能なし
- 色変更機能なし

## Future Enhancements

### 1. Advanced Input
```rust
// 計画中の機能
- Command history (↑/↓ keys)
- Tab completion
- Line editing (←/→ keys)
- Multi-line input
```

### 2. Extended Commands
```rust
// 追加予定のコマンド
- ls       // File listing
- cat      // File content
- mkdir    // Directory creation
- cd       // Change directory
- ps       // Process list
- claude   // AI integration
```

### 3. Display Improvements
```rust
// 計画中の機能
- Scrolling support
- Color themes
- Multiple windows
- Status bar
```

## Debugging Tips

### 1. Scancode Debugging
```rust
// スキャンコード確認用
print_str("Raw: 0x", x, y);
print_hex(scancode);
```

### 2. Buffer State Debugging
```rust
// バッファ状態確認
print_str("Pos: ", x, y);
print_number(INPUT_POS);
```

### 3. QEMU Console Output
```bash
# QEMUでの詳細ログ
qemu-system-x86_64 -kernel kernel.bin -d int,cpu
```

## Build Configuration

### Cargo.toml
```toml
[package]
name = "aios-kernel"
version = "0.2.0"
edition = "2021"

[dependencies]
bootloader = "0.9.23"
```

### Build Command
```bash
# 開発用
cargo bootimage --release

# テスト用
./scpt/bootimage-test.sh
```

## Success Metrics

実装成功の判定基準：

1. **キーボード入力**: 文字入力が画面に表示される
2. **コマンド実行**: `help`コマンドが正常動作
3. **バックスペース**: 文字削除が正常動作
4. **エラーハンドリング**: 不明コマンドでエラー表示
5. **画面管理**: `clear`コマンドで画面クリア

全ての機能が正常動作することを確認済み。