hdds-shm-viewer

Inspect HDDS shared memory segments used for zero-copy IPC.

Overview

hdds-shm-viewer scans /dev/shm for HDDS shared memory segments and displays their status. It shows segment types (writer/notify), control block information, ring buffer state, and memory usage. Useful for debugging shared memory transport issues.

Installation

From Source

cd hdds/tools/hdds-shm-viewer
cargo build --release

Binary at target/release/hdds-shm-viewer.

From Cargo

cargo install hdds-shm-viewer

Platform Support

Platform	Support
Linux	Full (uses /dev/shm)
macOS	Partial (POSIX shm)
Windows	Not supported

Usage

hdds-shm-viewer [OPTIONS] [SEGMENT]

Arguments:
  [SEGMENT]  Specific segment name to inspect (without /dev/shm prefix)

Options:
  -d, --domain <DOMAIN>  Filter by domain ID
  -v, --verbose          Show detailed slot information
  -f, --format <FORMAT>  Output format: pretty, json [default: pretty]
  -s, --summary          Show only summary statistics
  -h, --help             Print help
  -V, --version          Print version

Examples

List All HDDS Segments

hdds-shm-viewer

Output:

=== HDDS Shared Memory Segments ===

  WRITER hdds_d0_temperature_w0 (2.0 MB)
      [VALID] cap=1024 slots, head=4523, slot=2048B

  WRITER hdds_d0_sensor_data_w0 (1.0 MB)
      [VALID] cap=512 slots, head=891, slot=2048B

  NOTIFY hdds_notify_d0_w0 (4.0 KB)
      [VALID] cap=64 slots, head=4523, slot=64B

--- Summary ---
  Segments: 3 (2 writers, 1 notify)
  Total size: 3.0 MB
  Total messages: 9937

Filter by Domain

hdds-shm-viewer -d 42

Verbose Output

Show detailed control block information:

hdds-shm-viewer -v

Output:

=== HDDS Shared Memory Segments ===

  WRITER hdds_d0_temperature_w0 (2.0 MB)
      Magic: 0x48444453 [VALID]  Version: 1
      Capacity: 1024 slots  Slot size: 2048 bytes
      Head: 4523 (messages written)
      Ring fill: 427/1024 (41.7%)

  NOTIFY hdds_notify_d0_w0 (4.0 KB)
      Magic: 0x48444453 [VALID]  Version: 1
      Capacity: 64 slots  Slot size: 64 bytes
      Head: 4523 (messages written)
      Ring fill: 43/64 (67.2%)

Inspect Specific Segment

hdds-shm-viewer hdds_d0_temperature_w0

Summary Only

One-line output for scripting:

hdds-shm-viewer -s

Output:

segments=3 writers=2 notify=1 valid=3 size=3145728 messages=9937

JSON Output

hdds-shm-viewer -f json | jq .

Output:

{
  "segments": [
    {
      "name": "hdds_d0_temperature_w0",
      "type": "writer",
      "size": 2097152,
      "control": {
        "magic": 1212498003,
        "version": 1,
        "capacity": 1024,
        "slot_size": 2048,
        "head": 4523,
        "valid": true
      }
    }
  ]
}

Segment Types

Type	Name Pattern	Purpose
Writer	hdds_d{domain}_{topic}_w{id}	Ring buffer for topic data
Notify	hdds_notify_d{domain}_w{id}	Wake-up notifications to readers

Control Block Layout

Each HDDS SHM segment starts with a 64-byte control block:

Offset	Size	Field	Description
0	8	head	Write cursor (total messages written)
8	4	capacity	Number of slots in ring buffer
12	4	slot_size	Size of each slot in bytes
16	4	magic	0x48444453 ("HDDS" in ASCII)
20	4	version	Control block format version
24	40	reserved	Padding for future use

Understanding the Output

Magic Number

• 0x48444453 = Valid HDDS segment
• Other values = Corrupted or not an HDDS segment

Head Counter

The head value shows total messages ever written (not current ring position). The ring buffer index is head % capacity.

Ring Fill

In verbose mode, ring fill shows current buffer utilization:

• Low fill: Readers keeping up with writers
• High fill: Readers falling behind, risk of overwrite

Slot Size

Fixed size per message slot. Messages smaller than slot_size waste space; messages larger would be truncated (shouldn't happen with proper QoS).

Naming Convention

Segment names encode:

• d{N} - Domain ID
• Topic name (sanitized)
• _w{N} - Writer instance ID

Example: hdds_d0_sensor_data_w0

• Domain 0
• Topic: sensor_data
• Writer instance 0

Use Cases

Check SHM Health

hdds-shm-viewer -v | grep -E "(VALID|INVALID)"

All segments should show [VALID].

Monitor Message Throughput

Watch head counters grow:

watch -n 1 'hdds-shm-viewer -s'

Debug Memory Usage

Check total shared memory used by HDDS:

hdds-shm-viewer -f json | jq '[.segments[].size] | add'

Clean Stale Segments

List segments without running participants:

hdds-shm-viewer
# Then manually remove orphans:
# rm /dev/shm/hdds_d0_old_topic_w0

Verify Segment Creation

After starting a writer, confirm segment appears:

hdds-shm-viewer -d 0 -v | grep temperature

Troubleshooting

No Segments Found

1. HDDS processes may be using UDP transport only
2. Check if any HDDS applications are running
3. Verify /dev/shm is mounted and accessible

INVALID Magic

• Segment may be corrupted
• Segment may be from incompatible HDDS version
• File may not be an HDDS segment

Permission Denied

ls -la /dev/shm/hdds_*

Segments must be readable by current user. HDDS creates segments with owner permissions.

High Ring Fill

If ring fill approaches 100%:

• Readers are too slow
• Consider increasing capacity (QoS history depth)
• Check reader CPU usage

Exit Codes

Code	Meaning
0	Success
1	Error (no /dev/shm, permission denied, etc.)