QUAC 100 Troubleshooting

Diagnostic procedures, error code reference, LED interpretation, and solutions for common issues with the QUAC 100 accelerator.

LED Status Indicators #

The QUAC 100 has five status LEDs visible on the card bracket. These provide immediate visual diagnostics without requiring software access.

Diagnostic Commands #

# Full system information
$ quac-info --all
QUAC 100 Device Information
  Device:           /dev/quac0
  Serial:           QUAC-2025-A-001842
  Firmware:         1.2.0.18432-7
  Driver:           2.1.0
  PCIe:             Gen4 x16 (31.5 GB/s)
  Temperature:      42°C (nominal)
  Power:            168W / 310W budget
  Engines:          4× NTT (1 GHz), 4× QRNG
  Memory:           16 GB DDR4 (2× 8 GB @ 2400 MT/s)
  Keys Stored:      247 / 65536
  Uptime:           14d 6h 22m

# Run full self-test
$ quac-selftest --verbose
[1/7] Memory BIST ............... PASS (16,384 MB, 2.1s)
[2/7] NTT Engine KAT ........... PASS (4 engines, 48 vectors)
[3/7] ML-KEM KAT ............... PASS (512/768/1024)
[4/7] ML-DSA KAT ............... PASS (44/65/87)
[5/7] QRNG Health .............. PASS (4 sources, SP 800-90B)
[6/7] Inter-chip Links ......... PASS (6 links, 0 errors)
[7/7] Power Rails .............. PASS (all within ±5%)
Self-test: PASSED (4.7s)

# Performance benchmark
$ quac-bench --quick
ML-KEM-768  Encaps:  814,221 ops/sec   (1.23 μs avg)
ML-KEM-768  Decaps:  798,104 ops/sec   (1.25 μs avg)
ML-DSA-65   Sign:    215,053 ops/sec   (4.65 μs avg)
ML-DSA-65   Verify:  512,820 ops/sec   (1.95 μs avg)
QRNG:                112.4 MB/sec

# Check PCIe link details
$ quac-info --pcie
PCIe Link Status:
  Current:  Gen4 x16 (31.5 GB/s)
  Maximum:  Gen5 x16 (63.0 GB/s)
  NUMA:     Node 0
  BDF:      0000:3b:00.0
  MPS:      256 bytes
  MRRS:     512 bytes
  AER:      Enabled, 0 errors

Common Issues #

Device Not Detected

Symptoms: quac_device_count() returns 0, lspci does not show the device, PWR LED is off or amber.

# Step 1: Check physical installation
- Verify card is fully seated in PCIe x16 slot
- Verify 6-pin Molex aux power cable is connected (required!)
- Check that PCIe slot provides ≥75W (not all x16 slots do)

# Step 2: Check BIOS/UEFI settings
- Ensure PCIe slot is enabled in BIOS
- Check "Above 4G Decoding" is ENABLED (required for BAR mapping)
- Check "SR-IOV" is enabled if using virtual functions

# Step 3: Verify on Linux
$ lspci -d 1ed9:        # Dyber vendor ID
$ dmesg | grep -i quac
$ ls /dev/quac*

# Step 4: Verify driver is loaded
$ lsmod | grep quac100
$ modprobe quac100
$ dmesg | tail -20

PCIe Link Degraded

Symptoms: LINK LED is amber, quac-info --pcie shows lower generation or width than expected, reduced throughput.

# Check current vs. maximum link capability
$ quac-info --pcie
  Current:  Gen3 x8    ← degraded!
  Maximum:  Gen5 x16

# Common causes:
# 1. Card in a x8 physical slot → move to x16 slot
# 2. Motherboard only supports Gen3 → expected behavior
# 3. PCIe riser cable signal integrity → use shorter cable
# 4. Dirty or damaged gold fingers → clean with isopropanol

# Linux: force link retraining
$ echo 1 > /sys/bus/pci/devices/0000:3b:00.0/link_retrain
$ sleep 2
$ quac-info --pcie

Thermal Throttling

Symptoms: TEMP LED amber/red, reduced throughput, quac_get_health() reports high temperature.

# Check temperature
$ quac-info --thermal
Die Temperatures:
  U0 (KEM Engine):    72°C  [WARNING]
  U1 (QRNG Engine):   68°C  [OK]
  U2 (NTT Engine):    75°C  [WARNING]
  U3 (SIG Engine):    71°C  [WARNING]
  Board:              55°C  [OK]
Throttle Status: ACTIVE (reducing clock by 15%)

# Resolution:
# - Ensure ≥200 LFM airflow across the card
# - Verify chassis fans are operational
# - Check for obstructed vents or adjacent hot components
# - Operating range: 0°C to 50°C ambient
# - The card requires a dual-width slot spacing for cooling

Driver Issues

# Linux: Driver fails to load
$ sudo modprobe quac100
modprobe: ERROR: could not insert 'quac100': Required key not available

# Cause: Secure Boot rejects unsigned kernel module
# Fix: Sign the module or disable Secure Boot
$ sudo /usr/src/linux-headers-$(uname -r)/scripts/sign-file sha256 \
    /path/to/MOK.priv /path/to/MOK.der \
    /lib/modules/$(uname -r)/extra/quac100.ko

# Linux: Permission denied when accessing device
$ quac-info
Error: QUAC_ERROR_PERMISSION_DENIED (-12)

# Fix: Add user to quac group, or check udev rules
$ sudo usermod -aG quac $USER
# Log out and back in, then verify:
$ groups | grep quac
$ ls -la /dev/quac0
crw-rw---- 1 root quac 240, 0 Jan 15 10:00 /dev/quac0

# Windows: Device shows with yellow exclamation in Device Manager
# Fix: Install the signed driver from the QuantaCore SDK
# Run: C:\Program Files\Dyber\QuantaCore\drivers\quac100-setup.exe

Performance Below Expected

# Expected: 814K ML-KEM-768 encaps/sec
# Actual:   ~200K ops/sec

# Diagnosis checklist:
# 1. Check PCIe link speed (Gen3 = ~50% of Gen4 throughput)
$ quac-info --pcie

# 2. Check for thermal throttling
$ quac-info --thermal

# 3. Verify NUMA affinity — cross-socket PCIe adds latency
$ numactl --hardware
$ cat /sys/class/quac/quac0/numa_node
# Pin your application to the matching NUMA node:
$ numactl --cpunodebind=0 --membind=0 ./your_application

# 4. Use batch operations instead of single-shot
# Single-shot: ~300K ops/sec (PCIe round-trip dominated)
# Batch (256): ~814K ops/sec (amortized PCIe overhead)

# 5. Use DMA-friendly buffers
# malloc() buffers require kernel bounce copies
# quac_alloc() returns page-aligned DMA-capable memory

# 6. Check for firmware update (newer versions may improve perf)
$ quac-info --firmware

Firmware Update Failure

# Signature verification failure
$ sudo quac-fw update firmware.dfw
Error: Package signature verification FAILED

# Causes:
# - Corrupted download → re-download and verify SHA-384 checksum
# - Tampered package → only use packages from releases.dyber.org
# - Expired signing certificate → update quac-fw tool first

# Anti-rollback rejection
$ sudo quac-fw update older-firmware.dfw
Error: Security revision 5 is lower than device counter 7.
       Rollback to this version is blocked.

# This is by design — you cannot install firmware with a lower
# security revision than the eFUSE counter. Contact Dyber support
# if you need assistance with version compatibility.

# Update interrupted (power loss during write)
# The device will automatically boot from the backup partition.
# Re-run the update after verifying system stability.
$ sudo quac-fw status --device 0
  Active Partition:  B (backup — fallback after interrupted update)
  Partition A:       CORRUPTED (incomplete write)
  Recovery:          Re-run firmware update to repair Partition A

QRNG Health Failure

# quac_random_bytes() returns QUAC_ERROR_HARDWARE
# quac-selftest shows: QRNG Health ... FAIL

# The QRNG runs continuous health tests per SP 800-90B.
# A failure means one or more entropy sources fell below
# minimum entropy thresholds.

# Check individual source health:
$ quac-info --qrng
QRNG Source Status:
  Source 0:  HEALTHY  (7.94 bits/byte min-entropy)
  Source 1:  HEALTHY  (7.93 bits/byte min-entropy)
  Source 2:  FAILED   (6.21 bits/byte — below 7.0 threshold)
  Source 3:  HEALTHY  (7.95 bits/byte min-entropy)
Combined:    DEGRADED (3 of 4 sources healthy)

# The device will continue operating with reduced QRNG throughput
# as long as ≥2 sources are healthy. If <2 sources are healthy,
# all cryptographic operations requiring entropy are blocked.

# Resolution:
# - Reboot the device: sudo quac-fw reboot --device 0
# - If persistent, contact Dyber support — may indicate
#   hardware degradation of an entropy source

Error Code Quick Reference #

Getting Support #

If the issue persists after following the troubleshooting steps above, contact Dyber support with the following diagnostic bundle:

# Generate a support diagnostic bundle
$ sudo quac-diag --bundle --output /tmp/quac-support.tar.gz
Collecting:
  Device info ............ OK
  Driver logs ............ OK
  Firmware version ....... OK
  Self-test results ...... OK
  PCIe link status ....... OK
  Thermal history ........ OK
  Kernel messages ........ OK
  SDK version ............ OK
Bundle saved: /tmp/quac-support.tar.gz (2.4 MB)

# Send to: support@dyber.org
# Include your serial number ($ quac-info --serial)