embeddedpy 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.
Potentially problematic release.
This version of embeddedpy might be problematic. Click here for more details.
- embeddedpy/__init__.py +55 -0
- embeddedpy/arrays.py +142 -0
- embeddedpy/bytes.py +65 -0
- embeddedpy/compiler/__init__.py +55 -0
- embeddedpy/compiler/__main__.py +8 -0
- embeddedpy/compiler/api.py +337 -0
- embeddedpy/compiler/cgen_helpers.py +298 -0
- embeddedpy/compiler/checker.py +244 -0
- embeddedpy/compiler/checker_pass1.py +3229 -0
- embeddedpy/compiler/checker_pass2.py +1879 -0
- embeddedpy/compiler/cli.py +310 -0
- embeddedpy/compiler/codegen.py +2407 -0
- embeddedpy/compiler/config.py +186 -0
- embeddedpy/compiler/errors.py +26 -0
- embeddedpy/compiler/frontend.py +381 -0
- embeddedpy/compiler/irtypes.py +663 -0
- embeddedpy/compiler/lang_api.py +163 -0
- embeddedpy/compiler/modules.py +583 -0
- embeddedpy/compiler/preprocessor.py +364 -0
- embeddedpy/compiler/runtime_lib.py +1395 -0
- embeddedpy/compiler/type_symbols.py +278 -0
- embeddedpy/enums.py +20 -0
- embeddedpy/interop.py +444 -0
- embeddedpy/io.py +119 -0
- embeddedpy/memory.py +196 -0
- embeddedpy/pointers.py +552 -0
- embeddedpy/strings.py +68 -0
- embeddedpy/types.py +510 -0
- embeddedpy-0.1.0.dist-info/METADATA +258 -0
- embeddedpy-0.1.0.dist-info/RECORD +34 -0
- embeddedpy-0.1.0.dist-info/WHEEL +5 -0
- embeddedpy-0.1.0.dist-info/entry_points.txt +2 -0
- embeddedpy-0.1.0.dist-info/licenses/LICENSE +21 -0
- embeddedpy-0.1.0.dist-info/top_level.txt +1 -0
embeddedpy/pointers.py
ADDED
|
@@ -0,0 +1,552 @@
|
|
|
1
|
+
"""The pointer category of embeddedpy: a purely functional pointer API.
|
|
2
|
+
|
|
3
|
+
Public usage: `from embeddedpy.pointers import ptr`.
|
|
4
|
+
|
|
5
|
+
The types ``Ptr`` / ``Func`` themselves live in ``embeddedpy.types`` (they are
|
|
6
|
+
language-level types with dereferencing semantics); this module only provides the
|
|
7
|
+
**functions that operate on pointers**.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from .arrays import (
|
|
11
|
+
_decode,
|
|
12
|
+
_elem_size,
|
|
13
|
+
_encode,
|
|
14
|
+
_flat_get,
|
|
15
|
+
_flat_set,
|
|
16
|
+
_list_shape,
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
# The simulation backend for bare addresses (MMIO) on the CPython development track.
|
|
20
|
+
#
|
|
21
|
+
# On the C track a bare address points at a real hardware register, and poke/peek read
|
|
22
|
+
# and write the physical address directly; the CPython track has no real hardware, so a
|
|
23
|
+
# "address -> value" backing dictionary absorbs pokes and supplies peeks, letting the
|
|
24
|
+
# development track also run the "write register then read it back" code path without a
|
|
25
|
+
# hard fork from the C track. The key is (address, element byte size); accesses of
|
|
26
|
+
# different widths never interfere with each other; an address that was never written reads
|
|
27
|
+
# back 0 (consistent with C's "uninitialized is readable").
|
|
28
|
+
_MMIO: "dict" = {}
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _mmio_get(addr: int, elem_size: int) -> object:
|
|
32
|
+
return _MMIO.get((addr, elem_size), 0)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def _mmio_set(addr: int, elem_size: int, value: object) -> None:
|
|
36
|
+
_MMIO[(addr, elem_size)] = value
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def mmio_reset() -> None:
|
|
40
|
+
"""Clear the simulated register backend (for testing)."""
|
|
41
|
+
_MMIO.clear()
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class _Ptr:
|
|
45
|
+
"""The pointer object on the CPython side, using a mutable cell to simulate C's
|
|
46
|
+
address-of and dereference.
|
|
47
|
+
|
|
48
|
+
Six forms:
|
|
49
|
+
- cell: points at a writable unit (scalar alias)
|
|
50
|
+
- array: points at an element offset of a fixed-length array (supports 2-D flat addressing)
|
|
51
|
+
- attr: points at a struct field
|
|
52
|
+
- addr: a bare address (MMIO scenario; not dereferenceable under CPython)
|
|
53
|
+
- heap: a heap memory block (allocated by mem.alloc, backed by a bytearray)
|
|
54
|
+
- bytes: an own byte copy (the output of data), byte-addressable and writable,
|
|
55
|
+
detached from the original value; _byte_text decides whether reads yield a char or a byte
|
|
56
|
+
|
|
57
|
+
Note: under CPython scalars are immutable, so ptr(x) does not truly alias the original
|
|
58
|
+
variable x; but once the same code is compiled to C it gains full pointer-alias semantics.
|
|
59
|
+
ptr.null() produces a null pointer whose boolean value is False (corresponding to C's NULL).
|
|
60
|
+
"""
|
|
61
|
+
|
|
62
|
+
__slots__ = (
|
|
63
|
+
"_kind", "_is_null", "_freed", "_src_id", "_cell", "_base", "_offset",
|
|
64
|
+
"_shape", "_obj", "_name", "_addr", "_elem_size",
|
|
65
|
+
"_heap", "_heap_len", "_elem_type", "_byte_text",
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
def __init__(self, value: object = None, is_null: bool = False) -> None:
|
|
69
|
+
self._kind = "cell"
|
|
70
|
+
self._is_null = is_null
|
|
71
|
+
self._freed = False
|
|
72
|
+
self._src_id = None
|
|
73
|
+
self._cell = [None if is_null else value]
|
|
74
|
+
self._base = None
|
|
75
|
+
self._offset = 0
|
|
76
|
+
self._shape = None
|
|
77
|
+
self._obj = None
|
|
78
|
+
self._name = None
|
|
79
|
+
self._addr = None
|
|
80
|
+
self._elem_size = 0
|
|
81
|
+
self._heap = None
|
|
82
|
+
self._heap_len = 0
|
|
83
|
+
self._elem_type = None
|
|
84
|
+
# The element form of a byte-copy pointer: True=char (text) / False=uchar (bytes) / None=numeric
|
|
85
|
+
self._byte_text = None
|
|
86
|
+
|
|
87
|
+
# ------------------------------------------------------------ Construction
|
|
88
|
+
|
|
89
|
+
@classmethod
|
|
90
|
+
def _make_array(cls, base: list, offset: int) -> "_Ptr":
|
|
91
|
+
p = cls(None)
|
|
92
|
+
p._kind = "array"
|
|
93
|
+
p._base = base
|
|
94
|
+
p._offset = offset
|
|
95
|
+
p._shape = _list_shape(base)
|
|
96
|
+
return p
|
|
97
|
+
|
|
98
|
+
@classmethod
|
|
99
|
+
def _make_attr(cls, obj: object, name: str) -> "_Ptr":
|
|
100
|
+
p = cls(None)
|
|
101
|
+
p._kind = "attr"
|
|
102
|
+
p._obj = obj
|
|
103
|
+
p._name = name
|
|
104
|
+
return p
|
|
105
|
+
|
|
106
|
+
@classmethod
|
|
107
|
+
def _make_addr(cls, addr: int, elem_size: int) -> "_Ptr":
|
|
108
|
+
p = cls(None)
|
|
109
|
+
p._kind = "addr"
|
|
110
|
+
p._addr = addr
|
|
111
|
+
p._elem_size = elem_size
|
|
112
|
+
return p
|
|
113
|
+
|
|
114
|
+
@classmethod
|
|
115
|
+
def _make_heap(
|
|
116
|
+
cls, buf: bytearray, elem_type: object, elem_size: int, count: int
|
|
117
|
+
) -> "_Ptr":
|
|
118
|
+
"""Heap memory block: backed by a bytearray, addressed by element size."""
|
|
119
|
+
p = cls(None)
|
|
120
|
+
p._kind = "heap"
|
|
121
|
+
p._heap = buf
|
|
122
|
+
p._elem_type = elem_type
|
|
123
|
+
p._elem_size = elem_size
|
|
124
|
+
p._heap_len = count
|
|
125
|
+
return p
|
|
126
|
+
|
|
127
|
+
@classmethod
|
|
128
|
+
def _make_byte_copy(cls, raw: bytes, text: bool) -> "_Ptr":
|
|
129
|
+
"""Byte-copy pointer: copy raw into an own buffer, addressed by **byte**.
|
|
130
|
+
|
|
131
|
+
``text`` decides the element form on dereference: a text pointer reads one character
|
|
132
|
+
(str), a byte pointer reads one byte (bytes), aligned with the char / uchar print form
|
|
133
|
+
on the C track. The copy is writable; a poke only changes the copy and does not affect
|
|
134
|
+
the original value.
|
|
135
|
+
"""
|
|
136
|
+
p = cls(None)
|
|
137
|
+
p._kind = "bytes"
|
|
138
|
+
p._obj = bytearray(raw)
|
|
139
|
+
p._elem_size = 1
|
|
140
|
+
p._byte_text = text
|
|
141
|
+
return p
|
|
142
|
+
|
|
143
|
+
def _copy(self) -> "_Ptr":
|
|
144
|
+
p = _Ptr(None)
|
|
145
|
+
p._kind = self._kind
|
|
146
|
+
p._is_null = self._is_null
|
|
147
|
+
p._freed = self._freed
|
|
148
|
+
p._src_id = self._src_id
|
|
149
|
+
p._cell = self._cell
|
|
150
|
+
p._base = self._base
|
|
151
|
+
p._offset = self._offset
|
|
152
|
+
p._shape = self._shape
|
|
153
|
+
p._obj = self._obj
|
|
154
|
+
p._name = self._name
|
|
155
|
+
p._addr = self._addr
|
|
156
|
+
p._elem_size = self._elem_size
|
|
157
|
+
p._heap = self._heap
|
|
158
|
+
p._heap_len = self._heap_len
|
|
159
|
+
p._elem_type = self._elem_type
|
|
160
|
+
p._byte_text = self._byte_text
|
|
161
|
+
return p
|
|
162
|
+
|
|
163
|
+
# ------------------------------------------------------------ Read/Write
|
|
164
|
+
|
|
165
|
+
def _read(self) -> object:
|
|
166
|
+
if self._freed:
|
|
167
|
+
raise RuntimeError("use of a freed pointer")
|
|
168
|
+
if self._kind == "cell":
|
|
169
|
+
return self._cell[0]
|
|
170
|
+
if self._kind == "array":
|
|
171
|
+
return _flat_get(self._base, self._shape, self._offset)
|
|
172
|
+
if self._kind == "attr":
|
|
173
|
+
return getattr(self._obj, self._name)
|
|
174
|
+
if self._kind == "heap":
|
|
175
|
+
return self._heap_read()
|
|
176
|
+
if self._kind == "bytes":
|
|
177
|
+
# Byte copy: read the current position's one byte according to the element form.
|
|
178
|
+
buf = self._obj
|
|
179
|
+
if not isinstance(buf, (bytes, bytearray)):
|
|
180
|
+
raise TypeError("byte copy expects a byte buffer")
|
|
181
|
+
if self._offset >= len(buf):
|
|
182
|
+
raise IndexError("byte buffer read out of bounds")
|
|
183
|
+
b = buf[self._offset]
|
|
184
|
+
if self._byte_text is None:
|
|
185
|
+
return b
|
|
186
|
+
if self._byte_text:
|
|
187
|
+
return bytes((b,)).decode("latin-1")
|
|
188
|
+
return bytes((b,))
|
|
189
|
+
if self._kind == "addr":
|
|
190
|
+
# Bare address (MMIO): the development track has no real hardware, so read from
|
|
191
|
+
# the simulation backend.
|
|
192
|
+
return _mmio_get(self._addr, self._elem_size)
|
|
193
|
+
raise RuntimeError("raw address cannot be dereferenced under CPython")
|
|
194
|
+
|
|
195
|
+
def _write(self, value: object) -> None:
|
|
196
|
+
if self._freed:
|
|
197
|
+
raise RuntimeError("use of a freed pointer")
|
|
198
|
+
if self._kind == "cell":
|
|
199
|
+
self._cell[0] = value
|
|
200
|
+
elif self._kind == "array":
|
|
201
|
+
_flat_set(self._base, self._shape, self._offset, value)
|
|
202
|
+
elif self._kind == "attr":
|
|
203
|
+
setattr(self._obj, self._name, value)
|
|
204
|
+
elif self._kind == "heap":
|
|
205
|
+
self._heap_write(value)
|
|
206
|
+
elif self._kind == "bytes":
|
|
207
|
+
# Byte copy is writable; the written value only affects the copy, the original
|
|
208
|
+
# remains unchanged.
|
|
209
|
+
buf = self._obj
|
|
210
|
+
if not isinstance(buf, bytearray):
|
|
211
|
+
raise TypeError("byte copy expects a writable byte buffer")
|
|
212
|
+
if self._offset >= len(buf):
|
|
213
|
+
raise IndexError("byte buffer write out of bounds")
|
|
214
|
+
buf[self._offset] = _byte_value(value)
|
|
215
|
+
elif self._kind == "addr":
|
|
216
|
+
# Bare address (MMIO): the development track has no real hardware, so write to the
|
|
217
|
+
# simulation backend so that a peek after a poke is consistent.
|
|
218
|
+
_mmio_set(self._addr, self._elem_size, value)
|
|
219
|
+
else:
|
|
220
|
+
raise RuntimeError("raw address cannot be written under CPython")
|
|
221
|
+
|
|
222
|
+
def _heap_read(self) -> object:
|
|
223
|
+
"""Read one element from a heap memory block, decoded using C's fixed-width semantics."""
|
|
224
|
+
buf = self._heap
|
|
225
|
+
assert buf is not None
|
|
226
|
+
size = self._elem_size
|
|
227
|
+
start = self._offset * size
|
|
228
|
+
end = start + size
|
|
229
|
+
if end > len(buf):
|
|
230
|
+
raise IndexError("heap memory read out of bounds")
|
|
231
|
+
raw = bytes(buf[start:end])
|
|
232
|
+
return _decode(raw, self._elem_type)
|
|
233
|
+
|
|
234
|
+
def _heap_write(self, value: object) -> None:
|
|
235
|
+
"""Write one element into a heap memory block, encoded using C's fixed-width semantics."""
|
|
236
|
+
buf = self._heap
|
|
237
|
+
assert buf is not None
|
|
238
|
+
size = self._elem_size
|
|
239
|
+
start = self._offset * size
|
|
240
|
+
end = start + size
|
|
241
|
+
if end > len(buf):
|
|
242
|
+
raise IndexError("heap memory write out of bounds")
|
|
243
|
+
buf[start:end] = _encode(value, self._elem_type)
|
|
244
|
+
|
|
245
|
+
# ------------------------------------------------- Struct fields (pointer base)
|
|
246
|
+
|
|
247
|
+
def _pointee(self) -> object:
|
|
248
|
+
"""Dereference to the final pointed-to object, piercing through multiple pointer layers.
|
|
249
|
+
|
|
250
|
+
Corresponds to C's ``*p`` (one layer) and ``**p`` (multiple layers); when the pointer
|
|
251
|
+
points at a struct it returns the struct object itself.
|
|
252
|
+
"""
|
|
253
|
+
if self._is_null:
|
|
254
|
+
raise RuntimeError("null pointer dereference")
|
|
255
|
+
obj = self._read()
|
|
256
|
+
while isinstance(obj, _Ptr):
|
|
257
|
+
if obj._is_null:
|
|
258
|
+
raise RuntimeError("null pointer dereference")
|
|
259
|
+
obj = obj._read()
|
|
260
|
+
return obj
|
|
261
|
+
|
|
262
|
+
def _field_get(self, name: str) -> object:
|
|
263
|
+
"""Read a struct field: corresponds to C's ``p->f``."""
|
|
264
|
+
obj = self._pointee()
|
|
265
|
+
try:
|
|
266
|
+
return getattr(obj, name)
|
|
267
|
+
except AttributeError:
|
|
268
|
+
raise AttributeError(
|
|
269
|
+
f"{type(obj).__name__} object has no field {name!r}"
|
|
270
|
+
) from None
|
|
271
|
+
|
|
272
|
+
def _field_set(self, name: str, value: object) -> None:
|
|
273
|
+
"""Write a struct field: corresponds to C's ``p->f = v``."""
|
|
274
|
+
obj = self._pointee()
|
|
275
|
+
if not hasattr(obj, name):
|
|
276
|
+
raise AttributeError(
|
|
277
|
+
f"{type(obj).__name__} object has no field {name!r}"
|
|
278
|
+
)
|
|
279
|
+
setattr(obj, name, value)
|
|
280
|
+
|
|
281
|
+
def __getattr__(self, name: str) -> object:
|
|
282
|
+
"""Struct field read: ``p.f`` is equivalent to C's ``p->f``.
|
|
283
|
+
|
|
284
|
+
Only triggered when ordinary attribute lookup fails, so slots and built-in attributes
|
|
285
|
+
are unaffected.
|
|
286
|
+
"""
|
|
287
|
+
# An unassigned __slots__ slot also reaches here and must be rejected immediately,
|
|
288
|
+
# otherwise it would form a recursion with the slot access inside _read().
|
|
289
|
+
if name in _Ptr.__slots__ or (name.startswith("__") and name.endswith("__")):
|
|
290
|
+
raise AttributeError(name)
|
|
291
|
+
return self._field_get(name)
|
|
292
|
+
|
|
293
|
+
def __setattr__(self, name: str, value: object) -> None:
|
|
294
|
+
"""Struct field write: ``p.f = v`` is equivalent to C's ``p->f = v``."""
|
|
295
|
+
if name in _Ptr.__slots__ or (name.startswith("__") and name.endswith("__")):
|
|
296
|
+
object.__setattr__(self, name, value)
|
|
297
|
+
return
|
|
298
|
+
self._field_set(name, value)
|
|
299
|
+
|
|
300
|
+
def _skip(self, n: int) -> "_Ptr":
|
|
301
|
+
if self._kind == "array":
|
|
302
|
+
return _Ptr._make_array(self._base, self._offset + n)
|
|
303
|
+
if self._kind == "addr":
|
|
304
|
+
p = self._copy()
|
|
305
|
+
p._addr = self._addr + n * (self._elem_size or 1)
|
|
306
|
+
return p
|
|
307
|
+
if self._kind == "heap":
|
|
308
|
+
p = self._copy()
|
|
309
|
+
p._offset = self._offset + n
|
|
310
|
+
return p
|
|
311
|
+
if self._kind == "bytes":
|
|
312
|
+
# Byte copy: offset is counted in bytes; after skip it still points at the same copy.
|
|
313
|
+
buf = self._obj
|
|
314
|
+
if not isinstance(buf, (bytes, bytearray)):
|
|
315
|
+
raise TypeError("byte copy expects a byte buffer")
|
|
316
|
+
if self._offset + n > len(buf):
|
|
317
|
+
raise IndexError("byte buffer offset out of bounds")
|
|
318
|
+
p = self._copy()
|
|
319
|
+
p._offset = self._offset + n
|
|
320
|
+
return p
|
|
321
|
+
if self._kind == "cell" and isinstance(self._cell[0], _Ptr):
|
|
322
|
+
return self._cell[0]._skip(n)
|
|
323
|
+
if self._kind == "cell" and n == 0:
|
|
324
|
+
# Consistent with C: &x + 0 still points at x
|
|
325
|
+
return self
|
|
326
|
+
raise RuntimeError("this pointer does not support offset arithmetic")
|
|
327
|
+
|
|
328
|
+
# ------------------------------------------------------------ Truthiness
|
|
329
|
+
|
|
330
|
+
def __bool__(self) -> bool:
|
|
331
|
+
return not self._is_null
|
|
332
|
+
|
|
333
|
+
# -------------------------------------------------- Equality (by address, corresponds to C's p == q)
|
|
334
|
+
|
|
335
|
+
def _addr_key(self) -> tuple:
|
|
336
|
+
"""The address identity of a pointer.
|
|
337
|
+
|
|
338
|
+
Corresponds to C's "two pointers compare by address": they are equal only if they point
|
|
339
|
+
at the same place. The cell form uses the **source object identity** (``_src_id``)
|
|
340
|
+
rather than the list's id -- because ``ptr.ref(x)`` creates a new cell container each
|
|
341
|
+
time, yet the C side takes the same variable.
|
|
342
|
+
"""
|
|
343
|
+
if self._is_null:
|
|
344
|
+
return ("null",)
|
|
345
|
+
if self._kind == "addr":
|
|
346
|
+
return ("addr", self._addr)
|
|
347
|
+
if self._kind == "array":
|
|
348
|
+
return ("array", id(self._base), self._offset)
|
|
349
|
+
if self._kind == "attr":
|
|
350
|
+
return ("attr", id(self._obj), self._name)
|
|
351
|
+
if self._kind == "heap":
|
|
352
|
+
return ("heap", id(self._heap), self._offset)
|
|
353
|
+
if self._kind == "bytes":
|
|
354
|
+
return ("bytes", id(self._obj), self._offset)
|
|
355
|
+
if self._src_id is not None:
|
|
356
|
+
return ("cell", self._src_id)
|
|
357
|
+
return ("cell", id(self._cell))
|
|
358
|
+
|
|
359
|
+
def __eq__(self, other: object) -> bool:
|
|
360
|
+
if not isinstance(other, _Ptr):
|
|
361
|
+
return NotImplemented
|
|
362
|
+
return self._addr_key() == other._addr_key()
|
|
363
|
+
|
|
364
|
+
def __ne__(self, other: object) -> bool:
|
|
365
|
+
result = self.__eq__(other)
|
|
366
|
+
if result is NotImplemented:
|
|
367
|
+
return result
|
|
368
|
+
return not result
|
|
369
|
+
|
|
370
|
+
def __hash__(self) -> int:
|
|
371
|
+
return hash(self._addr_key())
|
|
372
|
+
|
|
373
|
+
def __repr__(self) -> str:
|
|
374
|
+
if self._is_null:
|
|
375
|
+
return "ptr.null()"
|
|
376
|
+
if self._kind == "addr":
|
|
377
|
+
return f"ptr(0x{self._addr:X})"
|
|
378
|
+
if self._kind == "array":
|
|
379
|
+
return f"ptr(array@{self._offset})"
|
|
380
|
+
if self._kind == "attr":
|
|
381
|
+
return f"ptr({self._name})"
|
|
382
|
+
return f"ptr({self._cell[0]!r})"
|
|
383
|
+
|
|
384
|
+
def _ref(x: object) -> _Ptr:
|
|
385
|
+
"""The common implementation of taking an address."""
|
|
386
|
+
if x is None:
|
|
387
|
+
raise TypeError(
|
|
388
|
+
"ptr(x) does not accept None; use ptr.null() for a null pointer"
|
|
389
|
+
)
|
|
390
|
+
if isinstance(x, _Ptr):
|
|
391
|
+
return _Ptr(x)
|
|
392
|
+
if isinstance(x, list):
|
|
393
|
+
return _Ptr._make_array(x, 0)
|
|
394
|
+
p = _Ptr(x)
|
|
395
|
+
# Record the source object identity: two ptr.ref(same variable) calls are the same address
|
|
396
|
+
# on the C side; here we use it to make pointer comparison consistent with C (the _cell is a
|
|
397
|
+
# fresh container each time and cannot be used for this).
|
|
398
|
+
p._src_id = id(x)
|
|
399
|
+
return p
|
|
400
|
+
|
|
401
|
+
class _PtrAPI:
|
|
402
|
+
"""A purely functional pointer API.
|
|
403
|
+
|
|
404
|
+
Correspondence:
|
|
405
|
+
ptr.ref(x) -> &x take address
|
|
406
|
+
ptr.null() -> NULL null pointer
|
|
407
|
+
ptr.peek(p) -> *p read
|
|
408
|
+
ptr.poke(p, v) -> *p = v write
|
|
409
|
+
ptr.skip(p, n) -> p + n offset (by element)
|
|
410
|
+
ptr.field(s, "f") -> &s.f field address
|
|
411
|
+
ptr.from_int(a, T) -> (T*)a bare address
|
|
412
|
+
ptr.cast(p, T) -> (T*)p type re-interpretation
|
|
413
|
+
|
|
414
|
+
The legacy form ptr(x) (equivalent to ptr.ref(x)) is also kept; the two styles can be
|
|
415
|
+
mixed.
|
|
416
|
+
"""
|
|
417
|
+
|
|
418
|
+
__slots__ = ()
|
|
419
|
+
|
|
420
|
+
def __call__(self, x: object) -> _Ptr:
|
|
421
|
+
"""Legacy address-of: ptr(x) is equivalent to ptr.ref(x)."""
|
|
422
|
+
return _ref(x)
|
|
423
|
+
|
|
424
|
+
def ref(self, x: object) -> _Ptr:
|
|
425
|
+
"""Take an address, corresponding to C's &x."""
|
|
426
|
+
return _ref(x)
|
|
427
|
+
|
|
428
|
+
def null(self) -> _Ptr:
|
|
429
|
+
"""A null pointer, corresponding to C's NULL."""
|
|
430
|
+
return _Ptr(None, is_null=True)
|
|
431
|
+
|
|
432
|
+
def peek(self, p: object) -> object:
|
|
433
|
+
"""Dereferenced read, corresponding to C's *p."""
|
|
434
|
+
if not isinstance(p, _Ptr):
|
|
435
|
+
raise TypeError("ptr.peek requires a pointer")
|
|
436
|
+
if p._is_null:
|
|
437
|
+
raise RuntimeError("null pointer dereference")
|
|
438
|
+
return p._read()
|
|
439
|
+
|
|
440
|
+
def poke(self, p: object, value: object) -> None:
|
|
441
|
+
"""Dereferenced write, corresponding to C's *p = v."""
|
|
442
|
+
if not isinstance(p, _Ptr):
|
|
443
|
+
raise TypeError("ptr.poke expects a pointer")
|
|
444
|
+
if p._is_null:
|
|
445
|
+
raise RuntimeError("null pointer dereference")
|
|
446
|
+
p._write(value)
|
|
447
|
+
|
|
448
|
+
def skip(self, p: object, n: int) -> _Ptr:
|
|
449
|
+
"""Pointer offset, corresponding to C's p + n (by element)."""
|
|
450
|
+
if not isinstance(p, _Ptr):
|
|
451
|
+
raise TypeError("ptr.skip expects a pointer")
|
|
452
|
+
return p._skip(int(n))
|
|
453
|
+
|
|
454
|
+
def field(self, obj: object, name: str) -> _Ptr:
|
|
455
|
+
"""Take a struct field address, corresponding to C's &s.f.
|
|
456
|
+
|
|
457
|
+
The first argument may be a struct value or a pointer to a struct
|
|
458
|
+
(corresponding to C's ``&p->f``).
|
|
459
|
+
"""
|
|
460
|
+
if not isinstance(name, str):
|
|
461
|
+
raise TypeError("ptr.field field name must be a string")
|
|
462
|
+
target = obj
|
|
463
|
+
if isinstance(target, _Ptr):
|
|
464
|
+
# Pointer base: first dereference to the struct object, then take the field address.
|
|
465
|
+
target = target._pointee()
|
|
466
|
+
if not hasattr(target, name):
|
|
467
|
+
raise AttributeError(f"no field named {name}")
|
|
468
|
+
return _Ptr._make_attr(target, name)
|
|
469
|
+
|
|
470
|
+
def from_int(self, addr: int, elem_type: object = None) -> _Ptr:
|
|
471
|
+
"""Construct a bare-address pointer, corresponding to C's (T*)addr."""
|
|
472
|
+
return _Ptr._make_addr(int(addr), _elem_size(elem_type))
|
|
473
|
+
|
|
474
|
+
def cast(self, p: object, elem_type: object) -> _Ptr:
|
|
475
|
+
"""Pointer type re-interpretation, corresponding to C's (T*)p."""
|
|
476
|
+
if not isinstance(p, _Ptr):
|
|
477
|
+
raise TypeError("ptr.cast requires a pointer")
|
|
478
|
+
q = p._copy()
|
|
479
|
+
if q._kind == "addr":
|
|
480
|
+
q._elem_size = _elem_size(elem_type)
|
|
481
|
+
return q
|
|
482
|
+
|
|
483
|
+
ptr = _PtrAPI()
|
|
484
|
+
|
|
485
|
+
|
|
486
|
+
def _byte_value(v: object) -> int:
|
|
487
|
+
"""Fold a pointer element down to a single byte value.
|
|
488
|
+
|
|
489
|
+
The element may be a numeric value (``Ptr[uint8]`` / heap memory) or a single-byte
|
|
490
|
+
character family member (``char`` is a 1-character text, ``uchar`` / ``schar`` are 1-byte
|
|
491
|
+
byte strings).
|
|
492
|
+
"""
|
|
493
|
+
if isinstance(v, bool):
|
|
494
|
+
return int(v)
|
|
495
|
+
if isinstance(v, int):
|
|
496
|
+
return v & 0xFF
|
|
497
|
+
if isinstance(v, str):
|
|
498
|
+
raw = v.encode("utf-8")
|
|
499
|
+
if len(raw) != 1:
|
|
500
|
+
raise ValueError("a char element must hold exactly one byte")
|
|
501
|
+
return raw[0]
|
|
502
|
+
if isinstance(v, bytes):
|
|
503
|
+
if len(v) != 1:
|
|
504
|
+
raise ValueError("a byte element must hold exactly one byte")
|
|
505
|
+
return v[0]
|
|
506
|
+
raise TypeError(f"cannot read a byte from {type(v).__name__}")
|
|
507
|
+
|
|
508
|
+
|
|
509
|
+
def _read_byte_view(p: object, n: int) -> bytes:
|
|
510
|
+
"""Read n bytes from "pointer + byte length" (CPython track).
|
|
511
|
+
|
|
512
|
+
Corresponds to the C track's ``(const unsigned char *)p`` plus a length. The pointer may be
|
|
513
|
+
a byte copy (the output of ``data``), an array/heap pointer, or a raw byte string.
|
|
514
|
+
"""
|
|
515
|
+
if isinstance(n, bool) or not isinstance(n, int):
|
|
516
|
+
raise TypeError("byte length must be an integer")
|
|
517
|
+
if n < 0:
|
|
518
|
+
raise ValueError("byte length cannot be negative")
|
|
519
|
+
if isinstance(p, _Ptr):
|
|
520
|
+
if p._is_null:
|
|
521
|
+
raise RuntimeError("null pointer dereference")
|
|
522
|
+
if p._kind == "bytes":
|
|
523
|
+
buf = p._obj
|
|
524
|
+
if not isinstance(buf, (bytes, bytearray)):
|
|
525
|
+
raise TypeError("byte copy expects a byte buffer")
|
|
526
|
+
end = p._offset + n
|
|
527
|
+
if end > len(buf):
|
|
528
|
+
raise ValueError("byte length exceeds the buffer")
|
|
529
|
+
return bytes(buf[p._offset:end])
|
|
530
|
+
out = bytearray()
|
|
531
|
+
cur = p
|
|
532
|
+
for _ in range(n):
|
|
533
|
+
out.append(_byte_value(cur._read()))
|
|
534
|
+
cur = cur._skip(1)
|
|
535
|
+
return bytes(out)
|
|
536
|
+
raw: bytes
|
|
537
|
+
if isinstance(p, bytes):
|
|
538
|
+
raw = p
|
|
539
|
+
elif isinstance(p, bytearray):
|
|
540
|
+
raw = bytes(p)
|
|
541
|
+
elif isinstance(p, str):
|
|
542
|
+
raw = p.encode("utf-8")
|
|
543
|
+
else:
|
|
544
|
+
raise TypeError("from_ptr expects a pointer to a byte buffer")
|
|
545
|
+
if n > len(raw):
|
|
546
|
+
raise ValueError("byte length exceeds the buffer")
|
|
547
|
+
return raw[:n]
|
|
548
|
+
|
|
549
|
+
|
|
550
|
+
__all__ = [
|
|
551
|
+
"ptr",
|
|
552
|
+
]
|
embeddedpy/strings.py
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
"""Byte entry/exit points for text buffers.
|
|
2
|
+
|
|
3
|
+
External usage: ``from embeddedpy.strings import strings``.
|
|
4
|
+
|
|
5
|
+
``Str`` is an immutable value with a length; the C-side character buffer interface
|
|
6
|
+
wants a raw address + length. This module provides an explicit pair of entry/exit
|
|
7
|
+
points between the two representations:
|
|
8
|
+
|
|
9
|
+
- ``strings.data(s)``: copy out a byte copy and return a ``char *`` pointing to it;
|
|
10
|
+
- ``strings.from_ptr(p, n)``: copy from "pointer + byte length" into a text value.
|
|
11
|
+
|
|
12
|
+
Both directions copy: the outgoing copy and the incoming text are detached from each
|
|
13
|
+
other. Use ``strings.byte_len(s)`` for the byte length and ``len(s)`` for the character
|
|
14
|
+
count; the buffer has no NUL terminator -- pointer and length are used as a pair.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from typing import Any
|
|
18
|
+
|
|
19
|
+
from .pointers import _Ptr, _read_byte_view
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class _StringsAPI:
|
|
23
|
+
"""Text buffer API: free functions, no methods introduced."""
|
|
24
|
+
|
|
25
|
+
__slots__ = ()
|
|
26
|
+
|
|
27
|
+
@staticmethod
|
|
28
|
+
def data(s: Any) -> Any:
|
|
29
|
+
"""Get a byte-copy pointer of the text (corresponds to C's ``char *``).
|
|
30
|
+
|
|
31
|
+
Copy: the bytes are copied into an owned buffer, and a pointer to the copy is
|
|
32
|
+
returned. Modifying the copy does not affect the original text; the copy is
|
|
33
|
+
byte-addressable and can be read/written with ``ptr.peek`` / ``ptr.poke`` and
|
|
34
|
+
moved byte-wise with ``ptr.skip``.
|
|
35
|
+
"""
|
|
36
|
+
if isinstance(s, bytes):
|
|
37
|
+
raw = s
|
|
38
|
+
elif isinstance(s, str):
|
|
39
|
+
raw = s.encode("utf-8")
|
|
40
|
+
else:
|
|
41
|
+
raise TypeError("strings.data expects a string or bytes")
|
|
42
|
+
return _Ptr._make_byte_copy(raw, text=True)
|
|
43
|
+
|
|
44
|
+
@staticmethod
|
|
45
|
+
def byte_len(s: Any) -> int:
|
|
46
|
+
"""Byte length (not the character count). Use ``len(s)`` for the character count."""
|
|
47
|
+
if isinstance(s, bytes):
|
|
48
|
+
return len(s)
|
|
49
|
+
if isinstance(s, str):
|
|
50
|
+
return len(s.encode("utf-8"))
|
|
51
|
+
raise TypeError("strings.byte_len expects a string or bytes")
|
|
52
|
+
|
|
53
|
+
@staticmethod
|
|
54
|
+
def from_ptr(p: Any, n: Any) -> Any:
|
|
55
|
+
"""Build text from "pointer + byte length" (corresponds to C's ``char *`` + length).
|
|
56
|
+
|
|
57
|
+
Copy: the resulting text is detached from the original buffer, so it is unaffected
|
|
58
|
+
even if the original buffer later becomes invalid. The length is measured in
|
|
59
|
+
**bytes**, not the character count; the bytes must be valid UTF-8.
|
|
60
|
+
"""
|
|
61
|
+
return _read_byte_view(p, n).decode("utf-8")
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
strings = _StringsAPI()
|
|
65
|
+
|
|
66
|
+
__all__ = [
|
|
67
|
+
"strings",
|
|
68
|
+
]
|