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 +25 -0
- u2xbar/__main__.py +6 -0
- u2xbar/acceptance.py +350 -0
- u2xbar/blockread.py +151 -0
- u2xbar/cli.py +812 -0
- u2xbar/dfu.py +127 -0
- u2xbar/discovery.py +61 -0
- u2xbar/errors.py +39 -0
- u2xbar/kernlog.py +172 -0
- u2xbar/protocol.py +234 -0
- u2xbar/records.py +212 -0
- u2xbar/topo.py +87 -0
- u2xbar/unit.py +180 -0
- u2xbar-0.1.0.dist-info/METADATA +235 -0
- u2xbar-0.1.0.dist-info/RECORD +19 -0
- u2xbar-0.1.0.dist-info/WHEEL +5 -0
- u2xbar-0.1.0.dist-info/entry_points.txt +2 -0
- u2xbar-0.1.0.dist-info/licenses/LICENSE +21 -0
- u2xbar-0.1.0.dist-info/top_level.txt +1 -0
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
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)
|