ponkan-python 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.
Files changed (39) hide show
  1. ponkan_python-0.1.0.dist-info/METADATA +157 -0
  2. ponkan_python-0.1.0.dist-info/RECORD +39 -0
  3. ponkan_python-0.1.0.dist-info/WHEEL +4 -0
  4. ponkan_python-0.1.0.dist-info/entry_points.txt +5 -0
  5. ponkan_python-0.1.0.dist-info/licenses/LICENSE +22 -0
  6. ponkan_python-0.1.0.dist-info/licenses/NOTICE.md +14 -0
  7. py3dscapture/__init__.py +36 -0
  8. py3dscapture/artifacts.py +66 -0
  9. py3dscapture/capture.py +599 -0
  10. py3dscapture/devices/__init__.py +1 -0
  11. py3dscapture/devices/n3dsxl_ftd3.py +238 -0
  12. py3dscapture/errors.py +120 -0
  13. py3dscapture/hardware_gate.py +143 -0
  14. py3dscapture/image/__init__.py +1 -0
  15. py3dscapture/image/frame.py +166 -0
  16. py3dscapture/protocol/__init__.py +1 -0
  17. py3dscapture/protocol/layout_3ds.py +60 -0
  18. py3dscapture/protocol/n3dsxl.py +249 -0
  19. py3dscapture/protocol/sizes.py +128 -0
  20. py3dscapture/py.typed +1 -0
  21. py3dscapture/streaming/__init__.py +1 -0
  22. py3dscapture/streaming/buffers.py +156 -0
  23. py3dscapture/streaming/engine.py +285 -0
  24. py3dscapture/streaming/policies.py +157 -0
  25. py3dscapture/streaming/stats.py +254 -0
  26. py3dscapture/tools/__init__.py +1 -0
  27. py3dscapture/tools/capture_raw.py +44 -0
  28. py3dscapture/tools/list_devices.py +68 -0
  29. py3dscapture/tools/raw_to_png.py +251 -0
  30. py3dscapture/tools/stream_n3dsxl.py +152 -0
  31. py3dscapture/transport/__init__.py +1 -0
  32. py3dscapture/transport/d3xx_backend.py +850 -0
  33. py3dscapture/transport/d3xx_native.py +268 -0
  34. py3dscapture/transport/d3xx_native_streaming.py +306 -0
  35. py3dscapture/transport/d3xx_streaming.py +202 -0
  36. py3dscapture/transport/ftd3_backend.py +275 -0
  37. py3dscapture/transport/ftd3_pipe.py +387 -0
  38. py3dscapture/transport/libusb_async.py +134 -0
  39. py3dscapture/transport/libusb_backend.py +357 -0
@@ -0,0 +1,387 @@
1
+ """FTD3 command pipe payloads and transfer wrapper."""
2
+
3
+ from struct import pack
4
+ from typing import Final
5
+
6
+ from py3dscapture.devices.n3dsxl_ftd3 import N3DSXLDevice
7
+ from py3dscapture.errors import Ftd3CommandContext, Ftd3CommandError, UnsupportedDevice
8
+ from py3dscapture.protocol.sizes import N3DSXL_FTD3_COMMAND_PIPE_ID
9
+
10
+ FTD3_COMMAND_CREATE_PIPE_ID: Final = 0x82
11
+ FTD3_COMMAND_TIMEOUT_MS: Final = 500
12
+ FTD3_COMMAND_ABORT_ID: Final = 0
13
+ FTD3_COMMAND_RW_OPERATION_PREPARE_ID: Final = 1
14
+ FTD3_COMMAND_SET_STREAM_PIPE_ID: Final = 2
15
+ FTD3_COMMAND_CREATE_ID: Final = 3
16
+ FTD3_COMMAND_DESTROY_ID: Final = 3
17
+ FTD3_COMMAND_PAYLOAD_SIZE: Final = 20
18
+
19
+
20
+ def build_create_pipe_payload(*, command_id: int = 0) -> bytes:
21
+ """Build the cc3dsfs create-pipe command payload.
22
+
23
+ Args:
24
+ command_id: Monotonic command sequence number encoded into the payload.
25
+
26
+ Returns:
27
+ Twenty-byte little-endian FTD3 command payload.
28
+
29
+ Raises:
30
+ ValueError: ``command_id`` does not fit in an unsigned 32-bit field.
31
+ """
32
+ return _build_ptr_payload(
33
+ command_id=command_id,
34
+ pipe=FTD3_COMMAND_CREATE_PIPE_ID,
35
+ command=FTD3_COMMAND_CREATE_ID,
36
+ )
37
+
38
+
39
+ def build_abort_pipe_payload(pipe: int, *, command_id: int = 0) -> bytes:
40
+ """Build the cc3dsfs abort-pipe command payload.
41
+
42
+ Args:
43
+ pipe: Pipe ID encoded into the command payload.
44
+ command_id: Monotonic command sequence number encoded into the payload.
45
+
46
+ Returns:
47
+ Twenty-byte little-endian FTD3 command payload.
48
+
49
+ Raises:
50
+ ValueError: ``pipe`` does not fit in an unsigned byte, or
51
+ ``command_id`` does not fit in an unsigned 32-bit field.
52
+ """
53
+ return _build_ptr_payload(command_id=command_id, pipe=pipe, command=FTD3_COMMAND_ABORT_ID)
54
+
55
+
56
+ def build_destroy_pipe_payload(pipe: int, *, command_id: int = 0) -> bytes:
57
+ """Build the cc3dsfs destroy-pipe command payload.
58
+
59
+ Args:
60
+ pipe: Pipe ID encoded into the command payload.
61
+ command_id: Monotonic command sequence number encoded into the payload.
62
+
63
+ Returns:
64
+ Twenty-byte little-endian FTD3 command payload.
65
+
66
+ Raises:
67
+ ValueError: ``pipe`` does not fit in an unsigned byte, or
68
+ ``command_id`` does not fit in an unsigned 32-bit field.
69
+ """
70
+ return _build_ptr_payload(command_id=command_id, pipe=pipe, command=FTD3_COMMAND_DESTROY_ID)
71
+
72
+
73
+ def build_set_stream_pipe_payload(pipe: int, length: int, *, command_id: int = 0) -> bytes:
74
+ """Build the cc3dsfs set-stream-pipe command payload.
75
+
76
+ Args:
77
+ pipe: Pipe ID encoded into the command payload.
78
+ length: Stream transfer length in bytes.
79
+ command_id: Monotonic command sequence number encoded into the payload.
80
+
81
+ Returns:
82
+ Twenty-byte little-endian FTD3 command payload.
83
+
84
+ Raises:
85
+ ValueError: ``pipe`` does not fit in an unsigned byte, ``length`` does
86
+ not fit in an unsigned 32-bit field, or ``command_id`` does not fit
87
+ in an unsigned 32-bit field.
88
+ """
89
+ return _build_len_payload(
90
+ command_id=command_id,
91
+ pipe=pipe,
92
+ command=FTD3_COMMAND_SET_STREAM_PIPE_ID,
93
+ length=length,
94
+ )
95
+
96
+
97
+ def build_prepare_read_payload(pipe: int, length: int, *, command_id: int = 0) -> bytes:
98
+ """Build the cc3dsfs prepare-read command payload.
99
+
100
+ Args:
101
+ pipe: Pipe ID that will be read after prepare.
102
+ length: Requested read length in bytes.
103
+ command_id: Monotonic command sequence number encoded into the payload.
104
+
105
+ Returns:
106
+ Twenty-byte little-endian FTD3 command payload.
107
+
108
+ Raises:
109
+ ValueError: ``pipe`` does not fit in an unsigned byte, ``length`` does
110
+ not fit in an unsigned 32-bit field, or ``command_id`` does not fit
111
+ in an unsigned 32-bit field.
112
+ """
113
+ return _build_len_payload(
114
+ command_id=command_id,
115
+ pipe=pipe,
116
+ command=FTD3_COMMAND_RW_OPERATION_PREPARE_ID,
117
+ length=length,
118
+ )
119
+
120
+
121
+ def build_prepare_write_payload(pipe: int, length: int, *, command_id: int = 0) -> bytes:
122
+ """Build the cc3dsfs prepare-write command payload.
123
+
124
+ Args:
125
+ pipe: Pipe ID that will be written after prepare.
126
+ length: Payload length in bytes.
127
+ command_id: Monotonic command sequence number encoded into the payload.
128
+
129
+ Returns:
130
+ Twenty-byte little-endian FTD3 command payload.
131
+
132
+ Raises:
133
+ ValueError: ``pipe`` does not fit in an unsigned byte, ``length`` does
134
+ not fit in an unsigned 32-bit field, or ``command_id`` does not fit
135
+ in an unsigned 32-bit field.
136
+ """
137
+ return _build_len_payload(
138
+ command_id=command_id,
139
+ pipe=pipe,
140
+ command=FTD3_COMMAND_RW_OPERATION_PREPARE_ID,
141
+ length=length,
142
+ )
143
+
144
+
145
+ class Ftd3Pipe:
146
+ """FTD3 command wrapper over an accepted N3DSXL session.
147
+
148
+ This adapter sends cc3dsfs-compatible command payloads through the dedicated
149
+ FTD3 command pipe before bulk reads and writes.
150
+ """
151
+
152
+ backend_kind = "libusb"
153
+
154
+ def __init__(self, session: N3DSXLDevice, *, first_command_id: int = 0) -> None:
155
+ """Create a pipe wrapper for one safe N3DSXL session.
156
+
157
+ Args:
158
+ session: Open N3DSXL device session that owns the USB handle.
159
+ first_command_id: First command sequence number to encode.
160
+
161
+ Raises:
162
+ UnsupportedDevice: ``session`` is not an ``N3DSXLDevice``.
163
+ """
164
+ if not isinstance(session, N3DSXLDevice):
165
+ raise UnsupportedDevice
166
+ self.session = session
167
+ self._next_command_id = first_command_id
168
+
169
+ def create_pipe(self) -> None:
170
+ """Send the create-pipe command.
171
+
172
+ Raises:
173
+ Ftd3CommandError: The command pipe write fails or transfers only a
174
+ partial payload.
175
+ """
176
+ self._send_command(
177
+ command_name="create_pipe",
178
+ pipe=FTD3_COMMAND_CREATE_PIPE_ID,
179
+ payload=build_create_pipe_payload(command_id=self._take_command_id()),
180
+ )
181
+
182
+ def reconnect_after_drain(self) -> None:
183
+ """Keep protocol compatibility; libusb path keeps the current session.
184
+
185
+ D3XX reconnect behavior is implemented by the native fallback handle.
186
+ """
187
+
188
+ def abort_pipe(self, pipe: int) -> None:
189
+ """Send cc3dsfs' abort, abort, destroy sequence for one pipe.
190
+
191
+ Args:
192
+ pipe: Pipe ID to abort and destroy.
193
+
194
+ Raises:
195
+ ValueError: ``pipe`` does not fit in an unsigned byte.
196
+ Ftd3CommandError: Any command write fails or transfers only a
197
+ partial payload.
198
+ """
199
+ self._send_command(
200
+ command_name="abort_pipe",
201
+ pipe=pipe,
202
+ payload=build_abort_pipe_payload(pipe, command_id=self._take_command_id()),
203
+ )
204
+ self._send_command(
205
+ command_name="abort_pipe",
206
+ pipe=pipe,
207
+ payload=build_abort_pipe_payload(pipe, command_id=self._take_command_id()),
208
+ )
209
+ self._send_command(
210
+ command_name="destroy_pipe",
211
+ pipe=pipe,
212
+ payload=build_destroy_pipe_payload(pipe, command_id=self._take_command_id()),
213
+ )
214
+
215
+ def set_stream_pipe(self, pipe: int, length: int) -> None:
216
+ """Send the set-stream-pipe command.
217
+
218
+ Args:
219
+ pipe: Pipe ID to configure for streaming reads.
220
+ length: Transfer length in bytes.
221
+
222
+ Raises:
223
+ ValueError: ``pipe`` or ``length`` cannot be encoded.
224
+ Ftd3CommandError: Command write fails or transfers only a partial
225
+ payload.
226
+ """
227
+ self._send_command(
228
+ command_name="set_stream_pipe",
229
+ pipe=pipe,
230
+ payload=build_set_stream_pipe_payload(
231
+ pipe,
232
+ length,
233
+ command_id=self._take_command_id(),
234
+ ),
235
+ requested_length=length,
236
+ )
237
+
238
+ def read_pipe(self, pipe: int, length: int, timeout_ms: int = FTD3_COMMAND_TIMEOUT_MS) -> bytes:
239
+ """Prepare and read from a bulk pipe.
240
+
241
+ Args:
242
+ pipe: Bulk IN pipe or endpoint ID.
243
+ length: Maximum number of bytes to read.
244
+ timeout_ms: Bulk read timeout in milliseconds.
245
+
246
+ Returns:
247
+ Bytes read from the USB handle.
248
+
249
+ Raises:
250
+ ValueError: ``pipe`` or ``length`` cannot be encoded in the prepare
251
+ command.
252
+ Ftd3CommandError: Prepare or bulk read fails.
253
+ """
254
+ prepare = build_prepare_read_payload(pipe, length, command_id=self._take_command_id())
255
+ self._send_command(
256
+ command_name="prepare_read",
257
+ pipe=pipe,
258
+ payload=prepare,
259
+ requested_length=length,
260
+ )
261
+ try:
262
+ return self.session.handle.bulk_read(pipe, length, timeout_ms)
263
+ except Exception as exc:
264
+ raise Ftd3CommandError(
265
+ Ftd3CommandContext(
266
+ command_name="read_pipe",
267
+ pipe=pipe,
268
+ payload_length=0,
269
+ requested_length=length,
270
+ transferred=None,
271
+ )
272
+ ) from exc
273
+
274
+ def write_pipe(
275
+ self,
276
+ pipe: int,
277
+ payload: bytes,
278
+ timeout_ms: int = FTD3_COMMAND_TIMEOUT_MS,
279
+ ) -> int:
280
+ """Prepare and write to a bulk pipe.
281
+
282
+ Args:
283
+ pipe: Bulk OUT pipe or endpoint ID.
284
+ payload: Bytes to write after prepare.
285
+ timeout_ms: Bulk write timeout in milliseconds.
286
+
287
+ Returns:
288
+ Number of payload bytes transferred by the handle.
289
+
290
+ Raises:
291
+ ValueError: ``pipe`` or payload length cannot be encoded in the
292
+ prepare command.
293
+ Ftd3CommandError: Prepare or bulk write fails.
294
+ """
295
+ prepare = build_prepare_write_payload(
296
+ pipe,
297
+ len(payload),
298
+ command_id=self._take_command_id(),
299
+ )
300
+ self._send_command(
301
+ command_name="prepare_write",
302
+ pipe=pipe,
303
+ payload=prepare,
304
+ requested_length=len(payload),
305
+ )
306
+ try:
307
+ return self.session.handle.bulk_write(pipe, payload, timeout_ms)
308
+ except Exception as exc:
309
+ raise Ftd3CommandError(
310
+ Ftd3CommandContext(
311
+ command_name="write_pipe",
312
+ pipe=pipe,
313
+ payload_length=len(payload),
314
+ requested_length=len(payload),
315
+ transferred=None,
316
+ )
317
+ ) from exc
318
+
319
+ def _send_command(
320
+ self,
321
+ *,
322
+ command_name: str,
323
+ pipe: int,
324
+ payload: bytes,
325
+ requested_length: int | None = None,
326
+ ) -> None:
327
+ try:
328
+ transferred = self.session.handle.bulk_write(
329
+ N3DSXL_FTD3_COMMAND_PIPE_ID,
330
+ payload,
331
+ FTD3_COMMAND_TIMEOUT_MS,
332
+ )
333
+ except Exception as exc:
334
+ raise Ftd3CommandError(
335
+ Ftd3CommandContext(
336
+ command_name=command_name,
337
+ pipe=pipe,
338
+ payload_length=len(payload),
339
+ requested_length=requested_length,
340
+ transferred=None,
341
+ )
342
+ ) from exc
343
+ if transferred != len(payload):
344
+ raise Ftd3CommandError(
345
+ Ftd3CommandContext(
346
+ command_name=command_name,
347
+ pipe=pipe,
348
+ payload_length=len(payload),
349
+ requested_length=requested_length,
350
+ transferred=transferred,
351
+ )
352
+ )
353
+
354
+ def _take_command_id(self) -> int:
355
+ command_id = self._next_command_id
356
+ self._next_command_id += 1
357
+ return command_id
358
+
359
+
360
+ def _build_ptr_payload(*, command_id: int, pipe: int, command: int) -> bytes:
361
+ return _build_preamble(command_id=command_id, pipe=pipe, command=command) + pack("<QI", 0, 0)
362
+
363
+
364
+ def _build_len_payload(*, command_id: int, pipe: int, command: int, length: int) -> bytes:
365
+ _validate_u32(length)
366
+ return _build_preamble(command_id=command_id, pipe=pipe, command=command) + pack(
367
+ "<IQ",
368
+ length,
369
+ 0,
370
+ )
371
+
372
+
373
+ def _build_preamble(*, command_id: int, pipe: int, command: int) -> bytes:
374
+ _validate_u32(command_id)
375
+ _validate_u8(pipe)
376
+ _validate_u8(command)
377
+ return pack("<IBBH", command_id, pipe, command, 0)
378
+
379
+
380
+ def _validate_u8(value: int) -> None:
381
+ if not 0 <= value <= 0xFF:
382
+ raise ValueError
383
+
384
+
385
+ def _validate_u32(value: int) -> None:
386
+ if not 0 <= value <= 0xFFFFFFFF:
387
+ raise ValueError
@@ -0,0 +1,134 @@
1
+ """Async transfer boundary for streaming."""
2
+
3
+ from typing import Protocol
4
+
5
+ from py3dscapture.streaming.buffers import RawFrameSlot
6
+
7
+
8
+ class AsyncTransferCallback(Protocol):
9
+ """Callback invoked when one raw transfer completes.
10
+
11
+ Backends must keep callback work small. The callback records metadata and
12
+ must not perform decoding, blocking queue puts, or synchronous USB calls.
13
+ """
14
+
15
+ def __call__(
16
+ self,
17
+ slot_index: int,
18
+ transferred: int,
19
+ status: int,
20
+ completed_ns: int,
21
+ ) -> None:
22
+ """Record completion metadata.
23
+
24
+ Args:
25
+ slot_index: Raw slot that completed.
26
+ transferred: Number of bytes written into the slot.
27
+ status: Backend status code, where zero means success.
28
+ completed_ns: Monotonic completion timestamp.
29
+ """
30
+ ...
31
+
32
+
33
+ class AsyncTransferBackend(Protocol):
34
+ """Minimal async transfer backend used by StreamingEngine.
35
+
36
+ Implementations own transfer submission, cancellation, drain, and resource
37
+ release. They write into preallocated ``RawFrameSlot`` buffers.
38
+ """
39
+
40
+ def submit_read(
41
+ self,
42
+ slot: RawFrameSlot,
43
+ *,
44
+ length: int,
45
+ callback: AsyncTransferCallback,
46
+ ) -> None:
47
+ """Submit one async read into a preallocated slot.
48
+
49
+ Args:
50
+ slot: Checked-out raw slot whose buffer will receive bytes.
51
+ length: Number of bytes to read into the slot.
52
+ callback: Completion callback invoked when the read settles.
53
+
54
+ Raises:
55
+ ValueError: ``length`` does not fit in the slot buffer.
56
+ RuntimeError: The backend has been released or is cancelling.
57
+ """
58
+ ...
59
+
60
+ def cancel_all(self) -> None:
61
+ """Cancel submitted transfers.
62
+
63
+ Implementations should request cancellation for in-flight work without
64
+ blocking indefinitely.
65
+ """
66
+ ...
67
+
68
+ def drain(self) -> None:
69
+ """Drain cancellation/completion callbacks.
70
+
71
+ Returns only after submitted work has either completed or been
72
+ cancelled according to backend semantics.
73
+ """
74
+ ...
75
+
76
+ def release(self) -> None:
77
+ """Release backend resources.
78
+
79
+ Implementations should be idempotent and close any owned handles after
80
+ cancellation and drain have completed.
81
+ """
82
+ ...
83
+
84
+
85
+ class LibusbAsyncBackend:
86
+ """Placeholder for a hardware-backed libusb async implementation.
87
+
88
+ The libusb async hardware path is intentionally gated by the local hardware
89
+ work unit. Tests can use the protocol to inject fake async backends.
90
+ """
91
+
92
+ def submit_read(
93
+ self,
94
+ slot: RawFrameSlot,
95
+ *,
96
+ length: int,
97
+ callback: AsyncTransferCallback,
98
+ ) -> None:
99
+ """Submit one async read into a preallocated slot.
100
+
101
+ Args:
102
+ slot: Checked-out raw slot whose buffer would receive bytes.
103
+ length: Number of bytes requested.
104
+ callback: Completion callback for a real implementation.
105
+
106
+ Raises:
107
+ NotImplementedError: The hardware implementation is not enabled.
108
+ """
109
+ _ = slot, length, callback
110
+ raise NotImplementedError("hardware async backend is gated by local_013 hardware tests")
111
+
112
+ def cancel_all(self) -> None:
113
+ """Cancel submitted transfers.
114
+
115
+ Raises:
116
+ NotImplementedError: The hardware implementation is not enabled.
117
+ """
118
+ raise NotImplementedError("hardware async backend is gated by local_013 hardware tests")
119
+
120
+ def drain(self) -> None:
121
+ """Drain cancellation/completion callbacks.
122
+
123
+ Raises:
124
+ NotImplementedError: The hardware implementation is not enabled.
125
+ """
126
+ raise NotImplementedError("hardware async backend is gated by local_013 hardware tests")
127
+
128
+ def release(self) -> None:
129
+ """Release backend resources.
130
+
131
+ Raises:
132
+ NotImplementedError: The hardware implementation is not enabled.
133
+ """
134
+ raise NotImplementedError("hardware async backend is gated by local_013 hardware tests")