u2xbar 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
u2xbar/__init__.py ADDED
@@ -0,0 +1,25 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2026 Mete Balci
3
+
4
+ """Control tool and library for the u2xbar USB crossbar."""
5
+
6
+ from .discovery import FoundUnit, find_unit, list_units
7
+ from .errors import (
8
+ NoUnitError, ProtocolError, RequestError, SeveralUnitsError, U2xbarError, UnitError,
9
+ UnitTimeout,
10
+ )
11
+ from .protocol import Client, Event, Record
12
+ from .records import (
13
+ DevPort, HostDetach, HostPort, HubBoost, Measurement, Param, RegBlock, Status,
14
+ UnitInfo, Version,
15
+ )
16
+ from .unit import Unit
17
+
18
+ __version__ = "0.1.0"
19
+
20
+ __all__ = [
21
+ "Client", "DevPort", "Event", "FoundUnit", "HostDetach", "HostPort", "HubBoost",
22
+ "Measurement", "NoUnitError", "Param", "ProtocolError", "Record", "RegBlock",
23
+ "RequestError", "SeveralUnitsError", "Status", "U2xbarError", "Unit", "UnitError",
24
+ "UnitInfo", "UnitTimeout", "Version", "find_unit", "list_units",
25
+ ]
u2xbar/__main__.py ADDED
@@ -0,0 +1,6 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2026 Mete Balci
3
+
4
+ from .cli import run
5
+
6
+ run()
u2xbar/acceptance.py ADDED
@@ -0,0 +1,350 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2026 Mete Balci
3
+
4
+ """test enum and test moves: the acceptance tests that need the unit and this
5
+ computer's USB tree (Linux sysfs, through topo).
6
+
7
+ A device is known by VID:PID and its serial number string, or, without one,
8
+ by VID:PID and its hub port. Both tests start with a first pass that connects
9
+ every selected device port to the first selected host port and records the
10
+ device that appears on each.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import random
16
+ import time
17
+ from dataclasses import dataclass, field
18
+
19
+ from .errors import U2xbarError
20
+ from .kernlog import usb_errors
21
+ from .topo import HostTopo, UsbDevice
22
+
23
+ __all__ = ["Identity", "Placement", "PortsError", "Rig", "SetupError", "run_enum", "run_moves"]
24
+
25
+ POLL = 0.05 # seconds between sysfs scans
26
+ HIGH, FULL, LOW = "480", "12", "1.5" # the sysfs speed attribute, in Mb/s
27
+
28
+
29
+ class SetupError(U2xbarError):
30
+ """The test cannot start: a hub not found, no devices, a device that
31
+ does not enumerate in the first pass."""
32
+
33
+
34
+ class PortsError(U2xbarError):
35
+ """The ports chosen do not allow the test."""
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class Identity:
40
+ vid: str | None
41
+ pid: str | None
42
+ serial: str | None
43
+ port: int # the hub port, which tells devices without a serial number apart
44
+ speed: str | None = field(default=None, compare=False)
45
+
46
+ @classmethod
47
+ def of(cls, device: UsbDevice, port: int) -> Identity:
48
+ return cls(device.vid, device.pid, device.serial, port, device.speed)
49
+
50
+ def matches(self, device: UsbDevice | None, port: int) -> bool:
51
+ if device is None or (device.vid, device.pid) != (self.vid, self.pid):
52
+ return False
53
+ return device.serial == self.serial if self.serial else port == self.port
54
+
55
+ def __str__(self):
56
+ name = f"{self.vid}:{self.pid}"
57
+ if self.serial:
58
+ return f"{name} {self.serial}"
59
+ return f"{name} (no serial, hub port {self.port})"
60
+
61
+
62
+ def describe(device: UsbDevice) -> str:
63
+ return f"{device.vid}:{device.pid} {device.serial or '(no serial)'} {device.speed}M"
64
+
65
+
66
+ def _where(spots) -> str:
67
+ return ", ".join(f"host {h} (hub port {p})" for h, p in spots)
68
+
69
+
70
+ @dataclass
71
+ class Placement:
72
+ """One connection of a device port to a host port and what came of it."""
73
+
74
+ dev: int
75
+ host: int
76
+ ok: bool = False
77
+ seconds: float | None = None # from the (last) connect until it was there
78
+ speed: str | None = None
79
+ retries: int = 0
80
+ note: str = ""
81
+ kernel: list[str] = field(default_factory=list)
82
+
83
+
84
+ class Rig:
85
+ """The unit, the computer's USB tree and the timing of one test run.
86
+
87
+ scan() returns the HostTopo list of every host port of the unit.
88
+ """
89
+
90
+ def __init__(self, unit, scan, hosts, devices, timeout, poll=POLL, out=print,
91
+ clock=time.monotonic, sleep=time.sleep):
92
+ self.unit = unit
93
+ self.scan = scan
94
+ self.hosts = list(hosts)
95
+ self.devices = list(devices)
96
+ self.timeout = timeout
97
+ self.poll = poll
98
+ self.out = out
99
+ self.clock = clock
100
+ self.sleep = sleep
101
+
102
+ # --- the USB tree --------------------------------------------------------------
103
+
104
+ def snapshot(self) -> dict[tuple[int, int], UsbDevice]:
105
+ """(host port, hub port) -> the device there, for every hub found."""
106
+ snap = {}
107
+ for h in self.scan():
108
+ for p in h.ports:
109
+ if p.device is not None:
110
+ snap[(h.host, p.port)] = p.device
111
+ return snap
112
+
113
+ def check_hubs(self) -> list[HostTopo]:
114
+ hubs = self.scan()
115
+ missing = [h.host for h in hubs if h.hub is None and h.host in self.hosts]
116
+ if missing:
117
+ raise SetupError("; ".join(f"host {h}: hub not found" for h in missing)
118
+ + " (connect the host port to this computer, or leave it out "
119
+ "with --hosts)")
120
+ return hubs
121
+
122
+ def _until(self, done):
123
+ """Scans until done(snapshot) or the timeout; returns (ok, seconds, snapshot)."""
124
+ start = self.clock()
125
+ while True:
126
+ snap = self.snapshot()
127
+ t = self.clock() - start
128
+ if done(snap):
129
+ return True, t, snap
130
+ if t >= self.timeout:
131
+ return False, t, snap
132
+ self.sleep(self.poll)
133
+
134
+ def wait_gone(self, idents) -> list[tuple[int, int]]:
135
+ """Waits until none of these devices shows; returns where they still are."""
136
+ def gone(snap):
137
+ return not self._spots(snap, idents)
138
+
139
+ _, _, snap = self._until(gone)
140
+ return self._spots(snap, idents)
141
+
142
+ @staticmethod
143
+ def _spots(snap, idents):
144
+ return sorted(k for k, u in snap.items() if any(i.matches(u, k[1]) for i in idents))
145
+
146
+ # --- first pass ----------------------------------------------------------------
147
+
148
+ def discover(self) -> tuple[dict[int, Identity], dict[int, str]]:
149
+ """Connects every selected device port to the first selected host port.
150
+ Returns the identity of each device found and, for each device port
151
+ whose device did not enumerate (ufp=1, no USB device), a note."""
152
+ self.check_hubs()
153
+ self.unit.disconnect("all")
154
+ stale = self._until(lambda snap: not any(k[1] in self.devices for k in snap))[2]
155
+ stale = {k: u for k, u in stale.items() if k[1] in self.devices}
156
+ if stale:
157
+ raise SetupError("devices still show after disconnect all: "
158
+ + "; ".join(f"host {h} hub port {p}: {describe(u)}"
159
+ for (h, p), u in sorted(stale.items())))
160
+ h0 = self.hosts[0]
161
+ for d in self.devices:
162
+ self.unit.connect(d, h0)
163
+
164
+ def complete(snap):
165
+ return all(snap.get((h0, d)) is not None and snap[(h0, d)].speed
166
+ for d in self.devices)
167
+
168
+ _, _, snap = self._until(complete)
169
+ found = {d: Identity.of(snap[(h0, d)], d) for d in self.devices
170
+ if snap.get((h0, d)) is not None and snap[(h0, d)].vid}
171
+ ufp = {p.port: p.ufp for p in self.unit.status().devices}
172
+ broken = {d: f"dev {d}: a device is attached (ufp=1) but no USB device appeared on "
173
+ f"host {h0} within {self.timeout:g} s"
174
+ for d in self.devices if d not in found and ufp.get(d)}
175
+ self.out(f"first pass, every device port on host {h0}:")
176
+ for d in self.devices:
177
+ if d in found:
178
+ self.out(f" dev {d}: {found[d]} {found[d].speed}M")
179
+ elif d in broken:
180
+ self.out(f" dev {d}: attached (ufp=1), no USB device")
181
+ else:
182
+ self.out(f" dev {d}: no device")
183
+ return found, broken
184
+
185
+ # --- one connection ------------------------------------------------------------
186
+
187
+ def place(self, d: int, h: int, ident: Identity, speed_ok, full_speed: bool) -> Placement:
188
+ """Connects device port d to host port h and waits until the device is
189
+ on h's hub at hub port d and on no other hub. A full-speed device that
190
+ comes up as low speed or not at all gets one retry (USB2517 errata
191
+ DS80000628A, Module 4: a port reset early in a frame can detect a
192
+ full-speed device as low speed)."""
193
+ result = Placement(d, h)
194
+ while True:
195
+ start = self.clock()
196
+ self.unit.connect(d, h)
197
+ state, t, here, others = self._arrive(d, h, ident, full_speed, start)
198
+ retry = (full_speed and result.retries == 0
199
+ and (state == "low" or (state == "timeout" and here is None and not others)))
200
+ if not retry:
201
+ break
202
+ result.retries += 1
203
+ why = "low speed (1.5M)" if state == "low" else \
204
+ f"did not appear within {self.timeout:g} s"
205
+ self.out(f" retry: dev {d} on host {h}: {why}")
206
+ self.unit.disconnect(d)
207
+ self.wait_gone([ident])
208
+ result.seconds = t
209
+ result.speed = here.speed if here is not None else None
210
+ if state == "ok":
211
+ if speed_ok(here.speed):
212
+ result.ok = True
213
+ else:
214
+ result.note = f"speed {here.speed}M, expected {_expected(speed_ok)}"
215
+ elif state == "low":
216
+ result.note = "low speed (1.5M) after a retry"
217
+ elif here is None:
218
+ result.note = (f"appeared on {_where(others)} instead of host {h}" if others
219
+ else f"did not appear within {self.timeout:g} s")
220
+ elif not ident.matches(here, d):
221
+ result.note = f"a different device at hub port {d}: {describe(here)}"
222
+ else:
223
+ result.note = f"also on {_where(others)}"
224
+ if not result.ok:
225
+ result.seconds = None
226
+ return result
227
+
228
+ def _arrive(self, d, h, ident, full_speed, start):
229
+ while True:
230
+ snap = self.snapshot()
231
+ t = self.clock() - start
232
+ here = snap.get((h, d))
233
+ others = [k for k, u in snap.items() if k != (h, d) and ident.matches(u, k[1])]
234
+ if ident.matches(here, d) and here.speed:
235
+ if full_speed and here.speed == LOW:
236
+ return "low", t, here, others
237
+ if not others:
238
+ return "ok", t, here, others
239
+ if t >= self.timeout:
240
+ return "timeout", t, here, others
241
+ self.sleep(self.poll)
242
+
243
+
244
+ def _expected(speed_ok):
245
+ return getattr(speed_ok, "expected", "?")
246
+
247
+
248
+ def _speeds(*speeds):
249
+ def ok(speed):
250
+ return speed in speeds
251
+ ok.expected = " or ".join(f"{s}M" for s in speeds)
252
+ return ok
253
+
254
+
255
+ # --- test enum -------------------------------------------------------------------------
256
+
257
+
258
+ @dataclass
259
+ class EnumResult:
260
+ devices: dict[int, Identity]
261
+ steps: list[Placement]
262
+ broken: dict[int, str]
263
+
264
+ @property
265
+ def ok(self) -> bool:
266
+ return not self.broken and all(s.ok for s in self.steps)
267
+
268
+
269
+ def run_enum(rig: Rig, allow_full_speed=(), kernel_log=None) -> EnumResult:
270
+ """Each selected host port with each device port that has a device, one
271
+ at a time: 480M (12M on the ports in allow_full_speed), on no other hub,
272
+ gone after the disconnect, and no USB errors in the kernel log."""
273
+ found, broken = rig.discover()
274
+ if not found and not broken:
275
+ raise SetupError("no device on any selected device port")
276
+ rig.unit.disconnect("all")
277
+ rig.wait_gone(found.values())
278
+ steps = []
279
+ for h in rig.hosts:
280
+ for d, ident in sorted(found.items()):
281
+ if kernel_log is not None:
282
+ kernel_log.mark()
283
+ full = d in allow_full_speed
284
+ step = rig.place(d, h, ident, _speeds(HIGH, FULL) if full else _speeds(HIGH), full)
285
+ rig.unit.disconnect(d)
286
+ still = rig.wait_gone([ident])
287
+ if still:
288
+ step.ok = False
289
+ step.note = "; ".join(filter(None, [
290
+ step.note, f"still on {_where(still)} after disconnect"]))
291
+ if kernel_log is not None:
292
+ step.kernel = [r.text for r in usb_errors(kernel_log.since_mark())]
293
+ if step.kernel:
294
+ step.ok = False
295
+ step.note = "; ".join(filter(None, [step.note, "USB errors in the kernel log"]))
296
+ rig.out(f"host {h} dev {d}: " + (f"{step.speed}M in {step.seconds:.2f} s"
297
+ if step.ok else f"FAIL {step.note}"))
298
+ steps.append(step)
299
+ rig.unit.disconnect("all")
300
+ return EnumResult(found, steps, broken)
301
+
302
+
303
+ # --- test moves ------------------------------------------------------------------------
304
+
305
+
306
+ @dataclass
307
+ class MovesResult:
308
+ count: int
309
+ failures: list[tuple[int, int, int, Placement]] = field(default_factory=list)
310
+ retries: int = 0
311
+ slowest: tuple[float, int, int, int] | None = None # seconds, move, dev, host
312
+
313
+ @property
314
+ def ok(self) -> bool:
315
+ return not self.failures
316
+
317
+
318
+ def run_moves(rig: Rig, count: int, seed: int) -> MovesResult:
319
+ """count random moves of the device ports that have devices among the
320
+ selected host ports; the moves depend only on the seed and the ports."""
321
+ if len(rig.hosts) < 2:
322
+ raise PortsError("test moves needs at least two host ports")
323
+ found, broken = rig.discover()
324
+ if broken:
325
+ raise SetupError("; ".join(broken[d] for d in sorted(broken)))
326
+ if not found:
327
+ raise SetupError("no device on any selected device port")
328
+ rng = random.Random(seed)
329
+ ports = sorted(found)
330
+ at = {d: rig.hosts[0] for d in ports}
331
+ result = MovesResult(count)
332
+ for i in range(1, count + 1):
333
+ d = rng.choice(ports)
334
+ h = rng.choice([x for x in rig.hosts if x != at[d]])
335
+ ident = found[d]
336
+ full = ident.speed == FULL
337
+ step = rig.place(d, h, ident, _speeds(ident.speed), full)
338
+ result.retries += step.retries
339
+ line = f"move {i}/{count}: dev {d} host {at[d]} -> {h}: "
340
+ if step.ok:
341
+ rig.out(line + f"{step.speed}M in {step.seconds:.2f} s"
342
+ + (f" after {step.retries} retry" if step.retries else ""))
343
+ if result.slowest is None or step.seconds > result.slowest[0]:
344
+ result.slowest = (step.seconds, i, d, h)
345
+ else:
346
+ rig.out(line + f"FAIL {step.note}")
347
+ result.failures.append((i, d, at[d], step))
348
+ at[d] = h
349
+ rig.unit.disconnect("all")
350
+ return result
u2xbar/blockread.py ADDED
@@ -0,0 +1,151 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2026 Mete Balci
3
+
4
+ """test read: the sequential read rate of a block device, read-only.
5
+
6
+ The device is opened O_RDONLY, with O_DIRECT where the system and the file
7
+ system allow it (open(2)), so the page cache is bypassed. Without O_DIRECT the
8
+ tool drops the device's cached pages with posix_fadvise(POSIX_FADV_DONTNEED)
9
+ (posix_fadvise(2)) before it reads and behind each block.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import errno
15
+ import math
16
+ import mmap
17
+ import os
18
+ import stat
19
+ import time
20
+ from dataclasses import dataclass
21
+
22
+ from .errors import U2xbarError
23
+
24
+ __all__ = ["BLOCK", "ReadResult", "ReadUsageError", "mounted", "read_test"]
25
+
26
+ BLOCK = 4 * 1024 * 1024 # bytes per read
27
+ SECTOR = 4096 # O_DIRECT needs lengths in whole logical blocks; 4096 covers 512 and 4K
28
+ MB = 1_000_000
29
+ MOUNTS = "/proc/mounts" # fstab(5) format; spaces in names are \040
30
+ PROGRESS = 5.0 # seconds between progress lines
31
+
32
+
33
+ class ReadUsageError(U2xbarError):
34
+ """The device cannot be read as asked: missing, mounted, too small."""
35
+
36
+
37
+ @dataclass
38
+ class ReadResult:
39
+ bytes: int
40
+ seconds: float
41
+ mb_s: float
42
+ mode: str # O_DIRECT, or posix_fadvise DONTNEED
43
+ baseline: float | None = None
44
+ margin: float | None = None
45
+ ok: bool | None = None # None without a baseline
46
+
47
+
48
+ def _unescape(field):
49
+ return field.replace("\\040", " ").replace("\\011", "\t").replace("\\134", "\\")
50
+
51
+
52
+ def mounted(device: str) -> list[str]:
53
+ """`<source> on <mount point>` for the device and each of its partitions
54
+ (sdb1, nvme0n1p1, mmcblk0p1) that is mounted."""
55
+ real = os.path.realpath(device)
56
+ found = []
57
+ try:
58
+ with open(MOUNTS, encoding="utf-8", errors="replace") as f:
59
+ lines = f.read().splitlines()
60
+ except OSError:
61
+ return found
62
+ for line in lines:
63
+ fields = line.split()
64
+ if len(fields) < 2 or not fields[0].startswith("/"):
65
+ continue
66
+ source = os.path.realpath(_unescape(fields[0]))
67
+ rest = source[len(real):] if source.startswith(real) else None
68
+ if rest is not None and (rest == "" or rest.isdigit()
69
+ or (rest[:1] == "p" and rest[1:].isdigit())):
70
+ found.append(f"{_unescape(fields[0])} on {_unescape(fields[1])}")
71
+ return found
72
+
73
+
74
+ def _open(path):
75
+ flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0)
76
+ direct = getattr(os, "O_DIRECT", 0)
77
+ if direct:
78
+ try:
79
+ return os.open(path, flags | direct), "O_DIRECT"
80
+ except OSError as e:
81
+ if e.errno != errno.EINVAL: # EINVAL: the file system has no O_DIRECT
82
+ raise
83
+ return os.open(path, flags), "posix_fadvise DONTNEED"
84
+
85
+
86
+ def _drop(fd, offset, length):
87
+ advise = getattr(os, "posix_fadvise", None)
88
+ if advise:
89
+ advise(fd, offset, length, os.POSIX_FADV_DONTNEED)
90
+
91
+
92
+ def check(device: str, force: bool = False) -> None:
93
+ """Refuses what is not a block device (or a regular file) or is mounted."""
94
+ try:
95
+ st = os.stat(device)
96
+ except OSError as e:
97
+ raise ReadUsageError(f"{device}: {e.strerror}") from None
98
+ if not (stat.S_ISBLK(st.st_mode) or stat.S_ISREG(st.st_mode)):
99
+ raise ReadUsageError(f"{device} is not a block device")
100
+ busy = mounted(device)
101
+ if busy and not force:
102
+ raise ReadUsageError(f"{device} is mounted ({', '.join(busy)}); unmount it, "
103
+ "or read it anyway with --force")
104
+
105
+
106
+ def read_test(device: str, size: int, baseline: float | None = None, margin: float = 3.0,
107
+ out=print, clock=time.monotonic, on_block=None) -> ReadResult:
108
+ """Reads `size` bytes (rounded up to whole 4096-byte sectors, at most to
109
+ the end of the device) from the start of the device and returns the rate
110
+ in MB/s (10^6 bytes per second). With a baseline, ok is whether the rate
111
+ is at least baseline * (1 - margin/100).
112
+ """
113
+ fd, mode = _open(device)
114
+ try:
115
+ end = os.lseek(fd, 0, os.SEEK_END)
116
+ if end < size:
117
+ raise ReadUsageError(f"{device} holds only {end} bytes, less than {size}")
118
+ size = min(math.ceil(size / SECTOR) * SECTOR, end)
119
+ os.lseek(fd, 0, os.SEEK_SET)
120
+ if mode != "O_DIRECT":
121
+ _drop(fd, 0, 0) # 0 length: to the end
122
+ buf = mmap.mmap(-1, BLOCK) # page-aligned, as O_DIRECT needs
123
+ view = memoryview(buf)
124
+ done = 0
125
+ start = last = clock()
126
+ try:
127
+ while done < size:
128
+ # whole sectors for O_DIRECT; the last read stops at the end
129
+ want = min(BLOCK, math.ceil((size - done) / SECTOR) * SECTOR)
130
+ n = os.readv(fd, [view[:want]])
131
+ if n <= 0:
132
+ raise ReadUsageError(f"{device} ended after {done} bytes")
133
+ if mode != "O_DIRECT":
134
+ _drop(fd, done, n)
135
+ done += n
136
+ if on_block:
137
+ on_block(n)
138
+ now = clock()
139
+ if now - last >= PROGRESS:
140
+ last = now
141
+ out(f" {done / 1e9:.2f} of {size / 1e9:.2f} GB, "
142
+ f"{done / MB / (now - start):.1f} MB/s")
143
+ finally:
144
+ view.release()
145
+ buf.close()
146
+ seconds = clock() - start
147
+ finally:
148
+ os.close(fd)
149
+ rate = done / MB / seconds if seconds > 0 else math.inf
150
+ ok = None if baseline is None else rate >= baseline * (1 - margin / 100)
151
+ return ReadResult(done, seconds, rate, mode, baseline, margin if baseline else None, ok)