# Driver IOCTLs and Buffer Formats

Reference documentation for the Dbgv.sys kernel driver interface used by DbgViewCli.

---

## Device Identity

| Property | Value |
|----------|-------|
| Device Type | `FILE_DEVICE_DBGMON` (`0x00008305`) |
| Driver File | `Dbgv.sys` |
| Service Name | `DBGV` |
| Registry Key | `HKLM\System\CurrentControlSet\Services\Dbgv` |
| Version | `0x320` |

---

## IOCTL Commands

All IOCTLs use `CTL_CODE(FILE_DEVICE_DBGMON, function, method, access)`.

| IOCTL Name | Function | Method | Description |
|------------|----------|--------|-------------|
| `DBGMON_hook` | `0x00` | `METHOD_BUFFERED` | Hook kernel debug output (start capturing DbgPrint) |
| `DBGMON_unhook` | `0x01` | `METHOD_BUFFERED` | Unhook kernel debug output (stop capturing) |
| `DBGMON_zerostats` | `0x02` | `METHOD_BUFFERED` | Clear the driver's internal output buffer |
| `DBGMON_getstats` | `0x03` | `METHOD_NEITHER` | Read accumulated debug output from driver buffer |
| `DBGMON_swallow` | `0x04` | `METHOD_BUFFERED` | Suppress pass-through of debug output to attached debuggers |
| `DBGMON_dontswallow` | `0x05` | `METHOD_BUFFERED` | Allow debug output to pass through to debuggers |
| `DBGMON_hookW32` | `0x06` | `METHOD_BUFFERED` | Hook Win32 debug output (session 0 global) |
| `DBGMON_unhookW32` | `0x07` | `METHOD_BUFFERED` | Unhook Win32 debug output |
| `DBGMON_getsequence` | `0x08` | `METHOD_BUFFERED` | Get current sequence number from driver |
| `DBGMON_version` | `0x09` | `METHOD_BUFFERED` | Get driver version (handshake) |
| `DBGMON_gettime` | `0x0A` | `METHOD_BUFFERED` | Get driver timer resolution |
| `DBGMON_remotequit` | `0x0B` | `METHOD_BUFFERED` | Signal remote agent to quit |
| `DBGMON_connect` | `0x0C` | `METHOD_BUFFERED` | Remote connection notification |
| `DBGMON_forcecr` | `0x0D` | `METHOD_BUFFERED` | Force carriage return on output lines |
| `DBGMON_dontforcecr` | `0x0E` | `METHOD_BUFFERED` | Don't force carriage return |
| `DBGMON_enabledbgfilter` | `0x0F` | `METHOD_BUFFERED` | Enable debug output filtering in driver |
| `DBGMON_restoredbgfilter` | `0x10` | `METHOD_BUFFERED` | Restore default debug output filtering |

---

## Buffer Structures

### STORE_BUF — Driver Output Buffer

The driver accumulates debug messages in a linked list of `STORE_BUF` pages.

```c
#define NUM_STORE_PAGES  1
#define MAX_STORE        (PAGE_SIZE * NUM_STORE_PAGES - 4 * sizeof(ULONG))
#define STORE_SIGNATURE  0xFEADDEAF

#pragma pack(1)
typedef struct _store {
    ULONG           Signature;       // Must be STORE_SIGNATURE
    ULONG           UpdateSequence;  // Incremented on each write
    struct _store * Next;            // Pointer to next buffer in chain
    ULONG           Len;             // Bytes used in Data[]
    char            Data[MAX_STORE]; // Packed ENTRY records
} STORE_BUF, *PSTORE_BUF;
#pragma pack()
```

**Size:** `STORESIZE = ((sizeof(STORE_BUF) + 0xFFF) / 0x1000)` pages

### STORE_BUF_DUMP64 — 64-bit Crash Dump Variant

For reading driver buffers from 64-bit crash dumps (pointer width differs):

```c
#pragma pack(1)
typedef struct _store_dump64 {
    ULONG           Signature;       // STORE_SIGNATURE
    ULONG           UpdateSequence;
    ULONGLONG       Next64;          // 8 bytes (64-bit kernel pointer)
    ULONG           Len;
    char            Data[MAX_STORE];
} STORE_BUF_DUMP64, *PSTORE_BUF_DUMP64;
#pragma pack()
```

### ENTRY — Individual Debug Output Record

Each entry in `Data[]` is packed sequentially:

```c
#pragma pack(1)
typedef struct {
    ULONG           seq;        // Sequence number
    LARGE_INTEGER   datetime;   // File time (100ns since 1601-01-01)
    LARGE_INTEGER   perftime;   // Performance counter value
    char            text[0];    // Null-terminated message string
} ENTRY, *PENTRY;
#pragma pack()
```

**Walking entries:** Advance by `sizeof(ENTRY) + strlen(entry->text) + 1`, aligned as needed. Validate that the next entry start does not exceed `Data + Len`.

### WIN32OUTPUT — Win32 Shared Memory Record

Used for DBWIN shared-memory capture (OutputDebugString):

```c
typedef struct _win32rec {
    struct _win32rec * next;       // Linked list pointer
    ULONG              sequence;   // Sequence number
    LARGE_INTEGER      time;       // Timestamp
    LARGE_INTEGER      perftime;   // Performance counter
    char               text[];     // Flexible array — null-terminated message
} WIN32OUTPUT, *PWIN32OUTPUT;
```

### CLIENT_RESOLUTION — Timer Resolution

Shared between service and GUI/CLI for timestamp calibration:

```c
typedef struct {
    LARGE_INTEGER   TimerResolution;
} CLIENT_RESOLUTION, *PCLIENT_RESOLUTION;
```

---

## Win32 DBWIN Shared Memory Protocol

DbgViewCli captures `OutputDebugString` by creating these named objects:

| Object Type | Name (Local Session) | Name (Global/Session 0) |
|-------------|---------------------|------------------------|
| Section (File Mapping) | `DBWIN_BUFFER` | `Global\DBWIN_BUFFER` |
| Event (buffer ready) | `DBWIN_BUFFER_READY` | `Global\DBWIN_BUFFER_READY` |
| Event (data ready) | `DBWIN_DATA_READY` | `Global\DBWIN_DATA_READY` |

**Protocol:**
1. Create the section and events with appropriate security descriptors
2. Signal `DBWIN_BUFFER_READY` to indicate buffer is available
3. Wait on `DBWIN_DATA_READY` — signaled when a process calls `OutputDebugString`
4. Read PID (first 4 bytes) + message text from the shared section
5. Signal `DBWIN_BUFFER_READY` again for the next message

---

## Boot Logging Registry Configuration

When boot logging is enabled, the driver loads at boot:

| Registry Value | Type | Data |
|----------------|------|------|
| `Start` | `REG_DWORD` | `0` (SERVICE_BOOT_START) |
| `Group` | `REG_SZ` | `System Bus Extender` |
| `Tag` | `REG_DWORD` | `1` |
| `Type` | `REG_DWORD` | `1` |
| `ImagePath` | `REG_EXPAND_SZ` | `System32\Drivers\Dbgv.sys` |

The driver binary must be copied to `%SystemRoot%\System32\Drivers\` before enabling.

# Output Formats

DbgViewCli supports three output formats selectable via `--format <text|csv|xml>`.

---

## Text Format (Default)

Tab-separated fields written to stdout. This is the default when `--format text` or no format is specified.

### Schema

```
<sequence>\t<timestamp>\t[<pid>]\t<message>\n
```

### Fields

| Field | Description | Example |
|-------|-------------|---------|
| Sequence | Monotonically increasing line number | `1`, `2`, `3` |
| Timestamp | Depends on `--elapsed`, `--clock`, `--clock-ms` | `0.123`, `14:30:05`, `14:30:05.123` |
| PID | Process ID in brackets (when `--pids` is on) | `[1234]` |
| Message | The debug output string | `MyDriver: Init complete` |

### Timestamp Modes

| Mode | Flag | Format | Example |
|------|------|--------|---------|
| Elapsed | `--elapsed` (default) | Seconds since capture start | `12.456` |
| Clock | `--clock` | Wall clock HH:MM:SS | `14:30:05` |
| Clock+ms | `--clock-ms` | Wall clock with milliseconds | `14:30:05.123` |

### Example Output

```
1	0.000	[4567]	MyApp: Starting initialization
2	0.001	[4567]	MyApp: Loading configuration
3	0.015	[4567]	MyApp: Configuration loaded
4	1.203	[4567]	MyApp: Ready
```

---

## CSV Format

Comma-separated values with header row. Selected via `--format csv`.

### Schema

```
"Sequence","Timestamp","PID","Message"
<seq>,"<timestamp>","<pid>","<message>"
```

### Rules

- All fields are quoted with double quotes
- Embedded double quotes in message text are escaped as `""`
- Newlines in messages are preserved within quotes
- Header row is emitted first

### Example Output

```csv
"Sequence","Timestamp","PID","Message"
"1","0.000","4567","MyApp: Starting initialization"
"2","0.001","4567","MyApp: Loading configuration"
"3","0.015","4567","Config value=""debug_level=3"""
"4","1.203","4567","MyApp: Ready"
```

---

## XML Format

Simple XML elements. Selected via `--format xml`.

### Schema

```xml
<?xml version="1.0" encoding="UTF-8"?>
<debugoutput>
  <entry seq="N" time="TIMESTAMP" pid="PID"><![CDATA[MESSAGE]]></entry>
  ...
</debugoutput>
```

### Elements

| Element/Attribute | Description |
|-------------------|-------------|
| `<debugoutput>` | Root element wrapping all entries |
| `<entry>` | Single debug output line |
| `@seq` | Sequence number |
| `@time` | Timestamp string (format depends on time mode) |
| `@pid` | Process ID (omitted if `--no-pids`) |
| CDATA content | The debug message text |

### Special Characters

- Message content is wrapped in `<![CDATA[...]]>` to avoid XML escaping issues
- If the message contains the literal string `]]>`, it must be split across CDATA sections

### Example Output

```xml
<?xml version="1.0" encoding="UTF-8"?>
<debugoutput>
  <entry seq="1" time="0.000" pid="4567"><![CDATA[MyApp: Starting initialization]]></entry>
  <entry seq="2" time="0.001" pid="4567"><![CDATA[MyApp: Loading configuration]]></entry>
  <entry seq="3" time="0.015" pid="4567"><![CDATA[MyApp: Config loaded]]></entry>
  <entry seq="4" time="1.203" pid="4567"><![CDATA[MyApp: Ready]]></entry>
</debugoutput>
```

---

## Log File Options

All formats can be written to a log file simultaneously with stdout output.

| Option | Description |
|--------|-------------|
| `--log <file>` | Write output to file |
| `--log-append` | Append to existing file instead of overwriting |
| `--log-limit <MB>` | Maximum log file size in megabytes |
| `--log-wrap` | When limit reached, wrap to beginning (ring buffer) |
| `--log-daily` | Create new file each day with date suffix (e.g., `debug_20250518.log`) |

### Daily Log File Naming

When `--log-daily` is used with `--log debug.log`:
- Day 1: `debug_20250518.log`
- Day 2: `debug_20250519.log`

---

## Status Output Format

The `--status` command outputs machine-readable key=value pairs:

```
running=true
paused=false
elevated=true
```

| Key | Type | Description |
|-----|------|-------------|
| `running` | boolean | Whether a DbgViewCli instance is actively capturing |
| `paused` | boolean | Whether the running instance is paused |
| `elevated` | boolean | Whether the current process has admin privileges |

# Remote Monitoring Protocol

DbgViewCli can connect to a remote machine running DbgView (GUI or service) and
receive debug output over TCP. This document describes the wire protocol.

---

## Connection

### Port Scanning

The client scans TCP ports `DBGVPORTLO` (2020) through `DBGVPORTHI` (2030) on the
target machine, attempting a connection on each until one succeeds.

| Constant | Value |
|----------|-------|
| `DBGVPORTLO` | 2020 |
| `DBGVPORTHI` | 2030 |
| Connection Timeout | 10 seconds (`REMOTE_CONNECT_TIMEOUT`) |
| Update Timeout | 30 minutes (`REMOTE_UPDATE_TIMEOUT`) |

### Connection Sequence

```
Client                              Remote Agent (DbgView)
  |                                       |
  |--- TCP connect (port 2020-2030) ----->|
  |                                       |
  |--- DBGMON_version (DWORD) ----------->|   Request version
  |<-- version (DWORD) ------------------|   Response
  |                                       |
  |--- DBGMON_hook (DWORD) -------------->|   Start kernel capture
  |--- DBGMON_swallow/dontswallow ------->|   Configure pass-through
  |--- DBGMON_forcecr/dontforcecr ------->|   Configure CR mode
  |                                       |
  |--- DBGMON_gettime (DWORD) ----------->|   Request timer resolution
  |<-- CLIENT_RESOLUTION (16 bytes) -----|   Timer resolution response
  |                                       |
  |           ... connected ...           |
```

---

## Version Handshake

After TCP connection is established:

1. Client sends `DBGMON_version` command (4 bytes, DWORD)
2. Remote responds with its driver version (4 bytes, DWORD)

### Version Interpretation

| Response Value | Meaning |
|----------------|---------|
| `DEBUGVIEW_VERSION` (0x320) | Compatible version — proceed |
| `0xFFFFFFFF & ~WIN9XVERSIONBIT` | Remote has no kernel driver loaded (Win32 only) |
| Any other value | Incompatible version — disconnect |

The high bit (`WIN9XVERSIONBIT = 0x80000000`) indicates a Windows 9x remote.

---

## Commands (Client → Remote)

All commands are sent as a single DWORD (4 bytes, little-endian).

| Command | IOCTL Value | Description |
|---------|-------------|-------------|
| `DBGMON_hook` | `CTL_CODE(0x8305, 0x00, ...)` | Start capturing kernel debug output |
| `DBGMON_unhook` | `CTL_CODE(0x8305, 0x01, ...)` | Stop capturing kernel debug output |
| `DBGMON_zerostats` | `CTL_CODE(0x8305, 0x02, ...)` | Clear output buffer |
| `DBGMON_getstats` | `CTL_CODE(0x8305, 0x03, ...)` | Request buffered output data |
| `DBGMON_swallow` | `CTL_CODE(0x8305, 0x04, ...)` | Suppress debug pass-through |
| `DBGMON_dontswallow` | `CTL_CODE(0x8305, 0x05, ...)` | Allow debug pass-through |
| `DBGMON_version` | `CTL_CODE(0x8305, 0x09, ...)` | Request version |
| `DBGMON_gettime` | `CTL_CODE(0x8305, 0x0A, ...)` | Request timer resolution |
| `DBGMON_remotequit` | `CTL_CODE(0x8305, 0x0B, ...)` | Tell remote agent to quit |
| `DBGMON_forcecr` | `CTL_CODE(0x8305, 0x0D, ...)` | Enable forced CR |
| `DBGMON_dontforcecr` | `CTL_CODE(0x8305, 0x0E, ...)` | Disable forced CR |

---

## Data Retrieval (Polling)

The client periodically requests accumulated debug output:

```
Client                              Remote Agent
  |                                       |
  |--- DBGMON_getstats (DWORD) --------->|
  |<-- STORE_BUF data (up to MAX_STORE) -|
  |                                       |
```

### Response Format

The remote sends raw `STORE_BUF.Data` content — a packed sequence of `ENTRY` records:

```c
typedef struct {
    ULONG           seq;        // Sequence number
    LARGE_INTEGER   datetime;   // File time
    LARGE_INTEGER   perftime;   // Performance counter
    char            text[0];    // Null-terminated message
} ENTRY, *PENTRY;
```

**Walking the buffer:**
```
offset = 0
while offset < bytesRead:
    entry = (ENTRY*)(buffer + offset)
    process entry->text
    offset += sizeof(ENTRY) + strlen(entry->text) + 1
```

### Timeout

The read uses a 500ms timeout. If no data arrives within that window, the client
continues its main loop (checking duration limits, exit signals, etc.).

---

## Disconnection

Graceful disconnect sequence:

```
Client                              Remote Agent
  |                                       |
  |--- DBGMON_unhook (DWORD) ----------->|   Stop capturing
  |--- DBGMON_remotequit (DWORD) ------->|   Request agent exit
  |                                       |
  |--- closesocket() ------------------->|   TCP close
```

If the connection is broken (remote closed or network error), the client detects
this via failed `ReadFile`/`WriteFile` and sets `Closing = TRUE` to prevent
further operations on that slot.

---

## Multi-Remote Support

DbgViewCli supports up to `MAXREMOTE` (10) simultaneous remote connections.
Each connection occupies a slot in the `g_ComputerInfo[MAXREMOTE]` array.

| Field | Description |
|-------|-------------|
| `Name` | Hostname or IP of the remote |
| `IpAddress` | Resolved IPv4 address (network byte order) |
| `Socket` | TCP socket handle |
| `Config` | Per-connection capture configuration |
| `NoDriver` | TRUE if remote has no kernel driver |
| `Closing` | TRUE if connection is being torn down |
| `Stats` | Allocated buffer for `DBGMON_getstats` responses |
| `ReadEvent` | Overlapped I/O event for async reads |
| `Time` | Remote's timer resolution |

---

## Security Considerations

- Remote monitoring uses **unencrypted TCP**. Do not use over untrusted networks.
- The remote agent must have DbgView running with network listening enabled.
- No authentication is performed beyond the version handshake.
- Consider using VPN or SSH tunneling for remote debug capture over WAN.