std.hardware.usb

Der USB-Stack implementiert alle USB-Host-Operationen direkt via Linux usbdevfs-ioctls — kein libusb, keine externen Abhängigkeiten. Alle Transfers (Control, Bulk, Interrupt, Isochronous) sind vollständig in Lyx implementiert.

Import-Muster: Jede Sub-Unit wird einzeln importiert, je nach benötigtem Funktionsumfang:

import std.hardware.usb_discovery;
import std.hardware.usb_control;
import std.hardware.usb_bulk;

→ std.hardware · Standard Library

Der Stack ist in 13 Sub-Units gegliedert, die aufeinander aufbauen:

Rohe Linux-Syscall-Wrapper. Alle anderen Sub-Units bauen darauf auf.

Konstanten:

Funktionen:

Hilfstypen für Verzeichnis-Parsing und Pfad-Operationen. Wird intern von usb_discovery genutzt.

Alle USB-Descriptor-Typen, Struct-Definitionen und Accessor-Funktionen.

Descriptor-Typ-Konstanten:

Transfer-Typ und Richtung:

Struct-Größen:

Lyx-Typen:

type UsbEndpoint = struct {
  address: int64; direction: int64; number: int64;
  transfer_type: int64; max_packet: int64; interval: int64;
};

type UsbInterface = struct {
  interface_number: int64; alternate_setting: int64;
  class_code: int64; subclass_code: int64; protocol_code: int64;
  num_endpoints: int64; endpoints: int64;   // Zeiger auf alloc'd Array
};

type UsbDevice = struct {
  vendor_id: int64; product_id: int64; device_class: int64;
  usb_version: int64; bus_num: int64; dev_num: int64;
  handle: int64;   // fd — bleibt offen
  num_configs: int64; configs: int64;
};

Accessor-Funktionen (Auswahl):

Liest den vollständigen Descriptor-Strom von einem geöffneten USB-fd und baut daraus einen vollständigen Config/Interface/Endpoint-Baum.

Hinweis: UsbParseConfiguration setzt den Dateizeiger via lseek auf 0 zurück (Kernel-fd ist seekbar). Class-spezifische Descriptoren (HID-Report etc.) werden stillschweigend übersprungen.

Scannt /dev/bus/usb/ nach einem Gerät mit gegebener VID/PID. Öffnet das gefundene Gerät und parst automatisch seine Konfiguration.

Verwendung:

import std.hardware.usb_discovery;
import std.hardware.usb_parse;

var dev: int64 := UsbAllocDevice();
if (UsbFindDevice(0x046D, 0xC52B, dev) == USB_FIND_OK) {
  // dev.handle ist geöffnet, Konfiguration geparst
}

Control-Transfers und Interface-Claim/Release via usbdevfs-ioctls.

IOCTL-Codes:

Request-Typen (USB 2.0 §9.4):

Funktionen:

Synchrone Bulk-Transfers via USBDEVFS_BULK (0x40185502).

Rückgabe: Übertragene Bytes (≥ 0) oder negativer Fehlercode (z.B. -ETIMEDOUT, -ENODEV).

Asynchrone Interrupt-Transfers via URBs (Kernel-interne Puffer). Ablauf: allokieren → befüllen → einreichen → warten → auswerten → erneut einreichen.

IOCTL-Codes:

URB-Struct (56 Bytes, Feld-Offsets als Konstanten URB_OFF_*):

Funktionen:

Verwendung (einfacher HID-Empfang):

import std.hardware.usb_interrupt;

var buf:  int64 := alloc(64);
var urb:  int64 := UsbSubmitInterruptRead(dev_fd, 0x81, buf, 64, 0);
var done: int64 := UsbWaitForUrb(dev_fd, 1000);
if (done != 0 && UsbUrbStatus(done) == 0) {
  var n: int64 := UsbUrbActualLength(done);
  // buf enthält n Bytes HID-Daten
  UsbFreeUrb(urb);
}

Typsichere Endpoint-Wrapper: UsbBulkOutEndpoint hat nur Write-Operationen, UsbBulkInEndpoint nur Read. Falsche Richtung erzeugt einen Sentinel-fd (dev_fd=-1) → alle Ops geben -1.

Typen: UsbBulkOutEndpoint, UsbBulkInEndpoint, UsbInterruptInEndpoint

Endpoint-Registry: Adressen einmalig unter einem Schlüssel registrieren, danach nur noch per Schlüssel nutzen — keine Adresse beim Aufruf nötig.

import std.hardware.usb_endpoint_bind;

con EP_DATA_OUT: int64 := 1;
con EP_DATA_IN:  int64 := 2;

var reg: int64 := UsbEpRegistryAlloc();
UsbDefOutEndpoint(reg, EP_DATA_OUT, dev_fd, 0x01, 1000);
UsbDefInEndpoint(reg, EP_DATA_IN,  dev_fd, 0x81, 1000);

UsbEpWrite(reg, EP_DATA_OUT, dataPtr, 64);
UsbEpRead(reg, EP_DATA_IN, recvBuf, 64);

Isochronous Transfers für Audio/Video. ISO-URBs enthalten N angehängte Paket-Deskriptoren (usbdevfs_iso_packet_desc, je 12 Bytes) direkt hinter dem Basis-URB (Offset 56).

Idempotenter Claim/Release-Zustandsautomat: doppeltes Claim ist No-op, Release ohne vorheriges Claim ebenfalls.

Pool mit 4 vorbelegten URBs für überlappende Interrupt-Transfers. Während ein URB verarbeitet wird, warten die anderen bereits im Kernel. UsbUrbPoolPoll gibt den Entry-Index zurück — kein Callback-Mechanismus nötig.

Wichtig: Bei UsbUrbPoolGetStatus(urbp, idx) == -ENODEV (Gerät abgesteckt) nicht erneut einreichen.

import std.hardware.usb_urb_pool;

var pool: int64 := UsbUrbPoolAlloc(dev_fd, 0x81, 64);
UsbUrbPoolInit(pool);

while (true) {
  var idx: int64 := UsbUrbPoolPoll(pool, 2000);
  if (idx < 0) { break; }

  if (UsbUrbPoolGetStatus(pool, idx) == 0) {
    var data: int64 := UsbUrbPoolGetBuffer(pool, idx);
    var len:  int64 := UsbUrbPoolGetActualLen(pool, idx);
    // data enthält len Bytes
    UsbUrbPoolResubmit(pool, idx);
  }
}
UsbUrbPoolFree(pool);

import std.hardware.usb_parse;
import std.hardware.usb_discovery;
import std.hardware.usb_control;
import std.hardware.usb_bulk;

fn main(): int64 {
  var dev: int64 := UsbAllocDevice();
  if (UsbFindDevice(0x1234, 0x5678, dev) != USB_FIND_OK) {
    return -1;
  }
  var fd: int64 := peek64(dev + 48);    // dev.handle

  if (UsbClaimInterface(fd, 0) < 0) { return -2; }

  var txBuf: int64 := alloc(64);
  poke8(txBuf, 0x01);
  var sent: int64 := UsbBulkWrite(fd, 0x01, txBuf, 64, 1000);

  var rxBuf: int64 := alloc(64);
  var recv: int64 := UsbBulkRead(fd, 0x81, rxBuf, 64, 1000);

  UsbReleaseInterface(fd, 0);
  usb_close(fd);
  free(txBuf, 64); free(rxBuf, 64);
  return 0;
}

Letzte Aktualisierung: 2026-06-07