Debian Codegraph @

lib/binary/ftype.scm

raw
1 ;;;
2 ;;; binary.ftype - foreign types and foreign objects
3 ;;;
4 ;;; Copyright (c) 2011-2024 Shiro Kawai <[email protected]>
5 ;;;
6 ;;; Redistribution and use in source and binary forms, with or without
7 ;;; modification, are permitted provided that the following conditions
8 ;;; are met:
9 ;;;
10 ;;; 1. Redistributions of source code must retain the above copyright
11 ;;; notice, this list of conditions and the following disclaimer.
12 ;;;
13 ;;; 2. Redistributions in binary form must reproduce the above copyright
14 ;;; notice, this list of conditions and the following disclaimer in the
15 ;;; documentation and/or other materials provided with the distribution.
16 ;;;
17 ;;; 3. Neither the name of the authors nor the names of its contributors
18 ;;; may be used to endorse or promote products derived from this
19 ;;; software without specific prior written permission.
20 ;;;
21 ;;; THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 ;;; "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 ;;; LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 ;;; A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 ;;; OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 ;;; SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
27 ;;; TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
28 ;;; PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
29 ;;; LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
30 ;;; NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
31 ;;; SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 ;;;
33
34 ;; This module provides means to define and manipulate
35 ;; structured binary data.
36 ;;
37 ;; Foreign types and foreign objects
38 ;;
39 ;; A @emph{foreign type}, or @code{ftype}, refers to a way of representing
40 ;; external data used outside the Scheme world. Ftypes are first-class
41 ;; objects in Gauche. It can be used to extract or construct structured data
42 ;; from/in a plain bytevector (@code{u8vector}) and read from / write to
43 ;; ports.
44 ;;
45 ;; A @emph{foreign object} , or @code{fobject}, is a Scheme object
46 ;; that packages a chunk of binary data (@emph{storage}) with ftype.
47 ;; It behaves like a Scheme record---it can have slots and you can
48 ;; get and set values.
49 ;; However, it is possible to share storage among different Scheme objects.
50 ;; For example, you can read binary data (e.g. image file content)
51 ;; into an u8vector, then extract a part of it (e.g. image header)
52 ;; as an fobject. When you do so, the extracted fobject shares its storage
53 ;; with the original u8vector; you can modify the header of the image
54 ;; content through the extracted fobject. You may thing fobject as
55 ;; a typed reference to a certain memory.
56
57 (define-module binary.ftype
58 (use gauche.uvector)
59 (use gauche.record)
60 (use gauche.sequence)
61 (use scheme.list)
62 (use srfi.13)
63 (use binary.io)
64 (use util.match)
65 (export
66 ;; predefined primitive ftypes
67 ftype:schar ftype:uchar ftype:short ftype:ushort ftype:int ftype:uint
68 ftype:long ftype:ulong ftype:longlong ftype:ulonglong
69 ftype:int8 ftype:uint8 ftype:int16 ftype:uint16 ftype:int32 ftype:uint32
70 ftype:int64 ftype:uint64
71 ftype:float ftype:double
72
73 bitfield
74
75 ;; type metainformation
76 ftype ftype-name ftype-size ftype-alignment ftype-endian
77 ftype-getter ftype-putter
78
79 ftype:struct ftype:struct-slots
80 ftype:slot ftype:slot-name ftype:slot-type ftype:slot-position
81 make-fstruct-type
82 define-fstruct-type
83
84 fobject fobject? fobject-type fobject-storage fobject-offset
85 make-fobject
86
87 fobject-copy fobject-copy!/uv fobject-copy!
88
89 get-fobject put-fobject!
90 read-fobject!/uv read-fobject write-fobject/uv write-fobject
91 fobject-ref fobject-set! fobject-ref/uv fobject-set!/uv
92 ))
93 (select-module binary.ftype)
94
95 ;; Metainformation of foreign type.
96 ;;
97 ;; ftype base class and predefined primitive types
98 ;; +-- ftype:struct user-defined struct
99 ;; +-- ftype:array uniform array of ftype instances.
100 ;; +-- ftype:bitfield integer with limited width
101 ;; (+-- ftype:pointer maybe, if we support ffi through this.)
102 ;; (+-- ftype:function maybe, if we support ffi through this.)
103 ;;
104
105 ;; The base class. The constructor is private, since the user code
106 ;; never needs to call it.
107 (define-record-type ftype %make-ftype #t
108 name ; for diagnostics
109 size ; size in bytes
110 alignment ; natrual alignment of this type. can be overridden.
111 endian ; #f to obey context. symbol to enfoce specific endian.
112 getter ; uvector pos endian -> value ; pos is aligned
113 putter ; uvector pos value endian -> void ; pos is aligned
114 )
115
116 ;; NB: this may not be needed if we have standard printer for structs.
117 (define-method write-object ((ftd ftype) port)
118 (format port "#<ftype ~a>" (ftype-name ftd)))
119
120 (define-record-type (ftype:struct ftype) %make-ftype:struct #t
121 slots ; an assoc list of name and ftype:slot
122 )
123
124 (define-record-type (ftype:array ftype) %make-ftype:array #t
125 (element-type ftype-element-type) ; ftype
126 (num-elements ftype-num-elements) ; count
127 (element-alignment ftype-element-alignment) ; default to natural alignment
128 ; of element-type, can be
129 ; overridden.
130 )
131
132 ;; Auxiliary structure to keep each slot's info of ftype:struct.
133 ;; This isn't a subtype of ftype.
134 (define-record-type ftype:slot #t #t
135 name ; slot name
136 type ; ftype
137 position ; byte offset
138 )
139
140 ;; Auxiliary structure to keep bitfield slot in ftype:struct.
141 ;; When fstruct is defined, bitfield slot needs to be deginated with
142 ;; bit-width and signed/unsigned. The initializer of fstruct fills
143 ;; bit-position.
144 (define-record-type (ftype:bitfield ftype) %make-ftype:bitfield #t
145 bit-position ; start bit position
146 bit-width ; width
147 )
148
149 (define (bitfield width)
150 (make-ftype:bitfield #f #f width 0))
151
152 (define (make-ftype:bitfield name signed? bitwidth bitpos)
153 (let* ([octets (div (+ bitwidth 7) 8)]
154 [size (ash 1 (integer-length (- octets 1)))]
155 [align size]
156 [geti (if signed? get-sint get-uint)]
157 [puti (if signed? put-sint! put-uint!)])
158 (%make-ftype:bitfield name size align #f
159 (^[uv pos endian]
160 (bit-field (geti uv pos endian)
161 bitpos
162 (+ bitpos bitwidth)))
163 (^[uv pos val endian]
164 (puti uv pos
165 (copy-bit-field (geti uv pos endian)
166 val
167 bitpos
168 (+ bitpos bitwidth))))
169 bitpos
170 bitwidth)))
171
172 ;;
173 ;; Foreign object instance.
174 ;;
175
176 ;; An instance of fobject.
177 (define-record-type fobject %make-fobject fobject?
178 type ; ftype:struct
179 storage ; u8vector. NB: The storage may be shared.
180 offset ; byte offset within <storage>
181 )
182
183 ;; NB: this may not be needed if we have standard printer for structs.
184 (define-method write-object ((fst fobject) port)
185 (format port "#<fobject ~a>"
186 (ftype-name (fobject-type fst))))
187
188 ;;========================================================================
189 ;; Primitive ftypes.
190 ;;
191 (define *%primtype-info* (with-module binary.io (%primitive-type-info)))
192 (define (%primtype-size prim-name) (cadr (assq prim-name *%primtype-info*)))
193 (define (%primtype-align prim-name) (caddr (assq prim-name *%primtype-info*)))
194
195 (define (%primtype name get put!)
196 (let* ([sname (x->string name)]
197 [prim-name (cond [(string-prefix? "u" sname)
198 (string->symbol (string-drop sname 1))]
199 [(eq? 'schar name) 'char] ;special case
200 [else name])])
201 (%make-ftype name
202 (%primtype-size prim-name)
203 (%primtype-align prim-name)
204 #f get put!)))
205
206 (define (%intproc name n)
207 (let1 procs `((1 ,get-s8 ,get-u8 ,put-s8! ,put-u8!)
208 (2 ,get-s16 ,get-u16 ,put-s16! ,put-u16!)
209 (4 ,get-s32 ,get-u32 ,put-s32! ,put-u32!)
210 (8 ,get-s64 ,get-u64 ,put-s64! ,put-u64!))
211 (list-ref (assq (%primtype-size name) procs) n)))
212
213 (define get-schar get-s8)
214 (define get-uchar get-u8)
215 (define get-short (%intproc 'short 1))
216 (define get-ushort (%intproc 'short 2))
217 (define get-int (%intproc 'int 1))
218 (define get-uint (%intproc 'int 2))
219 (define get-long (%intproc 'long 1))
220 (define get-ulong (%intproc 'long 2))
221 (define get-longlong (%intproc 'longlong 1))
222 (define get-ulonglong (%intproc 'longlong 2))
223 (define get-float get-f32)
224 (define get-double get-f64)
225
226 (define put-schar! put-s8!)
227 (define put-uchar! put-u8!)
228 (define put-short! (%intproc 'short 3))
229 (define put-ushort! (%intproc 'short 4))
230 (define put-int! (%intproc 'int 3))
231 (define put-uint! (%intproc 'int 4))
232 (define put-long! (%intproc 'long 3))
233 (define put-ulong! (%intproc 'long 4))
234 (define put-longlong! (%intproc 'longlong 3))
235 (define put-ulonglong!(%intproc 'longlong 4))
236 (define put-float! put-f32!)
237 (define put-double! put-f64!)
238
239 (define ftype:schar (%primtype 'schar get-schar put-schar!))
240 (define ftype:uchar (%primtype 'uchar get-uchar put-uchar!))
241 (define ftype:short (%primtype 'short get-short put-short!))
242 (define ftype:ushort (%primtype 'ushort get-ushort put-ushort!))
243 (define ftype:int (%primtype 'int get-int put-int!))
244 (define ftype:uint (%primtype 'uint get-uint put-uint!))
245 (define ftype:long (%primtype 'long get-long put-long!))
246 (define ftype:ulong (%primtype 'ulong get-ulong put-ulong!))
247 (define ftype:longlong (%primtype 'longlong get-longlong put-longlong!))
248 (define ftype:ulonglong (%primtype 'ulonglong get-ulonglong put-ulonglong!))
249 (define ftype:float (%primtype 'float get-float put-float!))
250 (define ftype:double (%primtype 'double get-double put-double!))
251 (define ftype:int8 (%primtype 'int8 get-s8 put-s8!))
252 (define ftype:uint8 (%primtype 'uint8 get-u8 put-u8!))
253 (define ftype:int16 (%primtype 'int16 get-s16 put-s16!))
254 (define ftype:uint16 (%primtype 'uint16 get-u16 put-u16!))
255 (define ftype:int32 (%primtype 'int32 get-s32 put-s32!))
256 (define ftype:uint32 (%primtype 'uint32 get-u32 put-u32!))
257 (define ftype:int64 (%primtype 'int64 get-s64 put-s64!))
258 (define ftype:uint64 (%primtype 'uint64 get-u64 put-u64!))
259
260 ;;
261 ;; Utilities
262 ;;
263
264 (define-inline (%round val align) ;assumes align is power of 2.
265 (if (or (= val 0) (= align 0))
266 val
267 (logand (+ val (- align 1)) (lognot (- align 1)))))
268
269 (define (%check-size ftype uvector pos which)
270 (when (< (- (uvector-size uvector) pos) (ftype-size ftype))
271 (case which
272 [(src) (errorf "source uvector too short to extract \
273 fobject of type ~s" ftype)]
274 [(dest) (errorf "destination uvector too small to put \
275 fobject of type ~s" ftype)]
276 [else (error "[internal] invalid which argument:" which)])))
277
278 (define (%adjust-pos ftype uvector pos alignment)
279 (let1 align (or alignment (ftype-alignment ftype))
280 (rlet1 pos (%round pos align)
281 (%check-size ftype uvector pos 'src))))
282
283 (define (%get-slot-desc ftd slot)
284 (let1 s (assq slot (ftype:struct-slots ftd))
285 (unless s (errorf "ftype ~a does't have such slot: ~s" ftd slot))
286 (cdr s)))
287
288 ;;========================================================================
289 ;; foreign struct building blocks
290 ;;
291
292 ;; slots :: ((name type) ...)
293 (define (make-fstruct-type name slots endian alignment)
294 (receive [slot-descriptors size] (compute-fstruct-slots slots alignment)
295 (rec ftype
296 (%make-ftype:struct name size
297 (or alignment (compute-fstruct-alignment slots))
298 endian
299 (rec (fobject-get uv pos endian)
300 (%check-size ftype uv pos 'src)
301 (%make-fobject ftype uv pos))
302 (rec (fobject-put! uv pos val endian)
303 (%check-size ftype uv pos 'dest)
304 (let1 off (fobject-offset val)
305 (uvector-copy! uv pos
306 (fobject-storage val)
307 off
308 (+ off size))))
309 slot-descriptors))))
310
311 (define (compute-fstruct-alignment slots)
312 (apply max (map (^p (ftype-alignment (cadr p))) slots)))
313
314 ;; Returns <<[ftype:slot] size>>
315 (define (compute-fstruct-slots slots alignment)
316 (define (do-slot slots ss pos)
317 (match slots
318 [() (values (reverse ss) pos)]
319 [([name type] . slots)
320 (let* ([align (if alignment
321 (min alignment (ftype-alignment type))
322 (ftype-alignment type))]
323 [pos (%round pos align)])
324 (if (ftype:bitfield? type)
325 (do-bitfield name type slots ss pos 0)
326 (do-slot slots
327 `((,name . ,(make-ftype:slot name type pos)) ,@ss)
328 (+ pos (ftype-size type)))))]))
329 (define (do-bitfield name type slots ss pos bitpos)
330 (let* ([w (ftype:bitfield-bit-width type)]
331 [s `(,name
332 . ,(make-ftype:slot name
333 (make-ftype:bitfield `(bits ,w ,bitpos)
334 #f
335 bitpos
336 w)
337 pos))])
338 (match slots
339 [() (do-slot slots (cons s ss) (+ pos (div (+ bitpos 7) 8)))]
340 [([name type] . rest)
341 (if (ftype:bitfield? type)
342 (do-bitfield name type rest (cons s ss) pos (+ bitpos w))
343 (do-slot slots (cons s ss) (+ pos (div (+ bitpos 7) 8))))])))
344 (do-slot slots '() 0))
345
346 ;;
347 ;; Generic accessors.
348 ;;
349
350 (define (get-fobject ftype uvector pos :optional (endian #f) (alignment #f))
351 (let1 pos (%adjust-pos ftype uvector pos alignment)
352 ((ftype-getter ftype)
353 uvector pos (or endian (ftype-endian ftype)))))
354
355 (define (put-fobject! ftype uvector pos val
356 :optional (endian #f) (alignment #f))
357 (let1 pos (%adjust-pos ftype uvector pos alignment)
358 ((ftype-putter ftype)
359 uvector pos val (or endian (ftype-endian ftype)))))
360
361 ;; NB: If we allow variable fields, we need to interpret the content.
362 ;; It may also be an option to allow specifying endian and/or alignment
363 ;; which is different from the internal representation, and let this
364 ;; procedure to do the conversion. Still not sure if it is worth.
365 (define (read-fobject!/uv ftype uvector pos
366 :optional (port (current-input-port)))
367 (check-arg u8vector? uvector)
368 (%check-size ftype uvector pos 'dest)
369 (let* ([size (ftype-size ftype)]
370 [end (+ pos size)])
371 (let loop ([pos pos]
372 [nread 0])
373 (let1 nread (+ nread (read-block! uvector port pos end))
374 (if (< nread size)
375 (loop (+ pos nread) nread)
376 nread)))))
377
378 (define (read-fobject ftype :optional (port (current-input-port)))
379 (let1 v (make-u8vector (ftype-size ftype) 0)
380 (read-fobject!/uv ftype v 0 port)
381 (get-fobject ftype v 0)))
382
383 (define (write-fobject/uv ftype uvector pos
384 :optional (port (current-output-port)))
385 (check-arg u8vector? uvector)
386 (%check-size ftype uvector pos 'src)
387 (write-block uvector port pos (+ pos (ftype-size ftype))))
388
389 (define (write-fobject fobject :optional (port (current-output-port)))
390 (write-fobject/uv (fobject-type fobject)
391 (fobject-storage fobject)
392 (fobject-offset fobject)
393 port))
394
395 ;; NB: support endian switch
396 (define (fobject-ref/uv ftd slot uvector pos)
397 (let1 s (%get-slot-desc ftd slot)
398 ((ftype-getter (ftype:slot-type s))
399 uvector (+ pos (ftype:slot-position s))
400 #f))) ;endian
401
402 (define (fobject-set!/uv ftd slot uvector pos val)
403 (let1 s (%get-slot-desc ftd slot)
404 ((ftype-putter (ftype:slot-type s))
405 uvector (+ pos (ftype:slot-position s)) val
406 #f))) ;endian
407
408 (define (fobject-ref obj slot)
409 (fobject-ref/uv (fobject-type obj) slot
410 (fobject-storage obj) (fobject-offset obj)))
411
412 (define (fobject-set! obj slot val)
413 (fobject-set!/uv (fobject-type obj) slot
414 (fobject-storage obj) (fobject-offset obj) val))
415
416 ;; Initializes byte vector v, returns fobject of type ftype.
417 ;; TODO: allow constructing fobjects other than fstructs.
418 (define (init-fobject! ftype v pos . initargs)
419 (let loop ([args initargs])
420 (cond [(null? args) (%make-fobject ftype v 0)]
421 [(null? (cdr args)) (error "odd number of initargs:" initargs)]
422 [(not (keyword? (car args)))
423 (error "keyword required for initarg, but got:" (car args))]
424 [else (let1 slot (string->symbol (keyword->string (car args)))
425 (fobject-set!/uv ftype slot v pos (cadr args)))
426 (loop (cddr args))])))
427
428 (define (make-fobject ftype . initargs)
429 (let1 v (make-u8vector (ftype-size ftype) 0)
430 (apply init-fobject! ftype v 0 initargs)))
431
432 (define (fobject-copy obj)
433 (let ([type (fobject-type obj)]
434 [off (fobject-offset obj)])
435 (%make-fobject type
436 (u8vector-copy (fobject-storage obj)
437 off (+ off (ftype-size type)))
438 0)))
439
440 ;; TODO: Should it be a bytewise copy, or should adjust endian, padding etc?
441 ;; Should it check types, or just blindly copy the vector?
442
443 (define (fobject-copy!/uv dest-uvector pos src)
444 (%check-size (fobject-type src) dest-uvector pos 'dest)
445 (uvector-copy! dest-uvector pos
446 (fobject-storage src)
447 (fobject-offset src)))
448
449 (define (fobject-copy! dest src)
450 ;; TODO: check type compatibility?
451 (let ([dest-vec (fobject-storage dest)]
452 [dest-off (fobject-offset dest)])
453 (%check-size (fobject-type src) dest-vec dest-off 'dest)
454 (uvector-copy! dest-vec dest-off
455 (fobject-storage src)
456 (fobject-offset src))
457 dest))
458
459 ;;========================================================================
460 ;; farray
461 ;;
462
463
464 ;;========================================================================
465 ;; High-level macro
466 ;;
467 ;; define-fstruct-type name ctor-name pred-name (slot-spec ...) options ...
468 ;; Creates ftype:struct, and defines the following procedures.
469 ;;
470 ;; Constructor & filler
471 ;;
472 ;; make-NAME . initargs => fstruct
473 ;; init-NAME! uvector pos . initargs
474 ;;
475 ;; Accessors and modifiers
476 ;;
477 ;; NAME-SLOT fstruct => object
478 ;; NAME-SLOT-set! fstruct val => void
479 ;; get-NAME-SLOT uvector pos :optional endian => object
480 ;; put-NAME-SLOT! uvector pos val :optional endian
481 ;;
482 ;; NAME is bound to a newly created fstruct-type
483 ;;
484 ;; <slot-spec> := (slot-name ftype-expr) ;FTYPE-EXPR is evaluated.
485 ;;
486
487 (define-macro (define-fstruct-type name ctor-name pred-name slots . options)
488 (let* ([yname (unwrap-syntax name)]
489 [maker (cond
490 [(identifier? ctor-name) ctor-name]
491 [(eq? ctor-name #t) (string->symbol #"make-~yname")]
492 [(eq? ctor-name #f) #f]
493 ;; TODO: support inheritance like define-record-type
494 [else (error "invalid define-fstruct-type: ctor-name \
495 must be a symbol or a boolean, but got:"
496 ctor-name)])]
497 [pred (cond
498 [(identifier? pred-name) pred-name]
499 [(eq? pred-name #t) (string->symbol #"~|yname|?")]
500 [(eq? pred-name #f) #f]
501 [else (error "invalid define-fstruct-type: pred-name \
502 must be a symbol or a boolean, but got:"
503 pred-name)])]
504 [initializer (string->symbol #"init-~|yname|!")])
505 ;; Kludge to get hygienity
506 (define (->id x) ((with-module gauche.internal make-identifier) x
507 (find-module 'binary.ftype) '()))
508 (define (make-slot-procs sname type)
509 (let ([.ref (string->symbol #"~|yname|-~|sname|")]
510 [.set! (string->symbol #"~|yname|-~|sname|-set!")]
511 [.get (string->symbol #"get-~|yname|-~|sname|")]
512 [.put! (string->symbol #"put-~|yname|-~|sname|!")])
513 `(begin
514 (define (,.ref obj)
515 (,(->id 'fobject-ref) obj ',sname))
516 (define (,.set! obj val)
517 (,(->id 'fobject-set!) obj ',sname val))
518 (define (,.get vec pos)
519 (,(->id 'fobject-ref/uv) ,name ',sname vec pos))
520 (define (,.put! vec pos val)
521 (,(->id 'fobject-set!/uv) ,name ',sname vec pos val)))))
522
523 `(begin
524 (define ,name (,(->id 'make-fstruct-type) ',yname
525 (list
526 ,@(map (^s `(list ',(unwrap-syntax (car s)) ,(cadr s)))
527 slots))
528 #f #f))
529 ,(if maker
530 `(define (,maker . initargs)
531 (apply ,(->id 'make-fobject) ,name initargs))
532 '(begin))
533 ,(if pred
534 `(define (,pred obj)
535 (and (fobject? obj)
536 (eq? (fobject-type obj) ,name)))
537 '(begin))
538 (define (,initializer v pos . initargs)
539 (apply ,(->id 'init-fobject!) ,name v pos initargs))
540 ,@(map (^s (make-slot-procs (unwrap-syntax (car s)) (cadr s))) slots)
541 )))
542
543 ;;
544 ;; Debugging aid
545 ;;
546 (define-method describe-slots ((fd ftype))
547 (print "fstruct slots:")
548 (format #t " off slot type\n")
549 (dolist [slot (ftype:struct-slots fd)]
550 (format #t " ~3d ~10a::~a~%"
551 (ftype:slot-position (cdr slot))
552 (car slot)
553 (ftype-name (ftype:slot-type (cdr slot))))))