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.

(require (planet dherman/c:2:0/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.