On this page:
5.1 Headers
header?
make-header
header
5.2 Compilation
compile-header
query?
query: sizeof
query: offset
query: expr
system-compiler
5.3 Layouts
layout?
primitive-layout?
ref-layout?
struct-layout?
union-layout?
array-layout?
pointer-layout?
enum-layout?
layout-size
layout-offset
struct-layout-lookup
union-layout-lookup
deref-layout
5.4 Application Binary Interfaces (ABI’s)
abi
abi-lookup
abi-lookup-typedef
abi-lookup-tag
serialize-abi
deserialize-abi
read-abi
write-abi
Version: 4.1.5.3

5 Header Compilation

This library provides facilities for extracting and compiling C header information to generate architecture-specific binary layout information. This is particularly useful for writing code that interacts with the PLT Scheme foreign library – see FFI: PLT Scheme Foreign Interface.

Specifically, the foreign library’s pointer-manipulation procedures such as ptr-ref and ptr-set! can be used to read and write to arbitrary addresses, which can be computed using layout information.

 (require (planet dherman/c:3:1/header))

5.1 Headers

(header? x)  boolean?
  x : any

Determines whether x is a header.

(make-header components)  header?
  components : (listof (or/c decl? header?))

Constructs a header.

(header component ...+)  header?
  component : (or/c decl? header?)

Constructs a header.

Examples:

  > (define example.h
      (make-header (include/reader "example.h"
                                   (make-program-reader))))
  > (define time.h
      (header
       (struct tm ([int tm_sec]
                   [int tm_min]
                   [int tm_hour]
                   [int tm_mday]
                   [int tm_mon]
                   [int tm_year]
                   [int tm_wday]
                   [int tm_yday]
                   [int tm_isdst]))))

Using the Scribble @-reader, the latter example could be rewritten with embedded C syntax as:

  (define time.h
    (make-header
     @program{
       struct tm {
           int tm_sec;
           int tm_min;
           int tm_hour;
           int tm_mday;
           int tm_mon;
           int tm_year;
           int tm_wday;
           int tm_yday;
           int tm_isdst;
       };
     }))

5.2 Compilation

(compile-header header compiler)  abi?
  header : header?
  compiler : ((listof query?) -> (listof uint))

Compiles header using the given compiler, producing an ABI. See Application Binary Interfaces (ABI’s).

A header compiler must recognize the following types of queries.

(query? x)  boolean?
  x : any

Determines whether x is a query

(struct query:sizeof (type))
  type : any

A query to determine the size of the type represented by type.

(struct query:offset (type field))
  type : any
  field : symbol?

A query to determine the offset of field in type.

(struct query:expr (expr))
  expr : any

A query to determine the value of the integer expression expr.

(system-compiler [#:include<> include<> 
  #:include include 
  exe]) 
  ((listof query?) -> (listof uint))
  include<> : (listof string?) = '()
  include : (listof string?) = '()
  exe : ((-> any) -> any) = gcc

A header compiler that delegates to an external C compiler, presumably installed on the current system. The queries are converted into a series of C statements which are assembled into a C program that produces the answers. The include<> list is used to generate the list of system C headers to be included in the generated C program, and the include list is the list of path strings for local headers included in the generated C program. The gcc compiler is used by default, but this can be overridden by providing an alternative system compiler for the exe argument.

5.3 Layouts

(layout? x)  boolean?
  x : any

(primitive-layout? x)  boolean?
  x : layout?

(ref-layout? x)  boolean?
  x : layout?

(struct-layout? x)  boolean?
  x : layout?

(union-layout? x)  boolean?
  x : layout?

(array-layout? x)  boolean?
  x : layout?

(pointer-layout? x)  boolean?
  x : layout?

(enum-layout? x)  boolean?
  x : layout?

(layout-size x)  uint
  x : layout?

(layout-offset x path)  uint
  x : (or/c struct-layout? union-layout? enum-layout?)
  path : (or/c symbol? (listof symbol?))

(struct-layout-lookup x name)  layout?
  x : struct-layout?
  name : symbol?

(union-layout-lookup x name)  layout?
  x : union-layout?
  name : symbol?

(deref-layout x)  layout?
  x : layout?

5.4 Application Binary Interfaces (ABI’s)

An Application Binary Interface (ABI) provides information about the binary representation of C datatypes on a particular architecture.

(struct abi (typedefs tags))
  typedefs : (hasheqof symbol? layout?)
  tags : (hasheqof symbol? layout?)

An ABI. The typedefs are a table of type definitions and the tags are a table of struct, union, and enum tag definitions.

As a convenience, ABI structures can be used as procedures, which is equivalent to calling abi-lookup with the ABI structure as the first argument.

(abi-lookup abi name)  layout?
  abi : abi?
  name : symbol?

Looks up the definition of name in abi, searching the type definitions first, and failing that, the tag definitions.

(abi-lookup-typedef abi name)  layout?
  abi : abi?
  name : symbol?

Looks up the type definition of name in abi.

(abi-lookup-tag abi name)  layout?
  abi : abi?
  name : symbol?

Looks up the type tag definition of name in abi.

(serialize-abi abi)  sexp?
  abi : abi?

Serializes abi as an S-expression.

(deserialize-abi input)  abi?
  input : sexp?

Deserializes input as a representation of an ABI.

(read-abi [in])  abi?
  in : input-port? = (current-input-port)

Reads a serialized ABI from in.

(write-abi abi [out])  any
  abi : abi?
  out : output-port? = (current-output-port)

Serializes abi and writes it to out.