c2ffi

Documentation

Overview

Package c2ffi parses c2ffi JSON output and converts it to specmodel.Spec.

Index

• func Convert(data []byte, opts ConvertOptions) (*specmodel.Spec, error)
• func ConvertFile(path string, opts ConvertOptions) (*specmodel.Spec, error)
• func ExtractMacros(ndkSysroot string, targetHeaders []string) (map[string]int64, error)
• func Invoke(opts InvokeOptions) ([]byte, error)
• type ConvertOptions
• type Declaration
• type Field
• type InvokeOptions
• type Manifest
• type Parameter
• type Rule
• type TypeRef

Functions

func Convert

func Convert(
	data []byte,
	opts ConvertOptions,
) (*specmodel.Spec, error)

Convert parses c2ffi JSON data and converts it to a specmodel.Spec.

func ConvertFile

func ConvertFile(
	path string,
	opts ConvertOptions,
) (*specmodel.Spec, error)

ConvertFile reads a c2ffi JSON file and converts it to a specmodel.Spec.

func ExtractMacros

func ExtractMacros(
	ndkSysroot string,
	targetHeaders []string,
) (map[string]int64, error)

ExtractMacros parses C header files for #define integer constants. Only macros from headers matching targetHeaders (suffix match) are included.

func Invoke

func Invoke(opts InvokeOptions) ([]byte, error)

Invoke preprocesses each NDK header with NDK clang (to strip availability attributes that c2ffi can't handle), then runs c2ffi on each preprocessed header and merges the JSON arrays.

Types

type ConvertOptions

type ConvertOptions struct {
	Module        string
	SourcePackage string

	// TargetHeaders limits extraction to declarations from these headers.
	// Each entry is a suffix match against the location path (e.g., "android/looper.h").
	TargetHeaders []string

	// Rules filters declarations by accept/ignore regex patterns.
	Rules []Rule

	// NDKHeaderDirs are directories to scan for callback typedef params
	// (c2ffi doesn't provide function pointer typedef parameters).
	NDKHeaderDirs []string

	// NDKSysroot is the NDK sysroot include directory for extracting
	// #define macro constants from original (pre-preprocessed) headers.
	NDKSysroot string
}

ConvertOptions configures the c2ffi JSON → spec YAML conversion.

type Declaration

type Declaration struct {
	Tag      string `json:"tag"`
	Name     string `json:"name"`
	NS       int    `json:"ns"`
	ID       int    `json:"id"`
	Location string `json:"location"`

	// Function fields.
	Variadic   bool        `json:"variadic"`
	Inline     bool        `json:"inline"`
	Parameters []Parameter `json:"parameters"`
	ReturnType *TypeRef    `json:"return-type"`

	// Typedef field.
	Type *TypeRef `json:"type"`

	// Enum and struct fields share the same JSON key "fields".
	// Enum fields have Name+Value; struct fields have Name+Type+BitOffset.
	Fields []Field `json:"fields"`

	// Struct-specific.
	BitSize      int `json:"bit-size"`
	BitAlignment int `json:"bit-alignment"`
}

Declaration is one top-level entry in c2ffi's JSON output array. c2ffi outputs a flat JSON array of tagged objects — functions, typedefs, enums, structs, etc.

type Field

type Field struct {
	Tag          string   `json:"tag"`
	Name         string   `json:"name"`
	Value        uint64   `json:"value"`         // enum constant value
	BitOffset    int      `json:"bit-offset"`    // struct field offset
	BitSize      int      `json:"bit-size"`      // struct field size
	BitAlignment int      `json:"bit-alignment"` // struct field alignment
	Type         *TypeRef `json:"type"`          // struct field type
}

Field is used for both enum constants and struct fields. c2ffi reuses the "fields" JSON key for both.

type InvokeOptions

type InvokeOptions struct {
	// C2FFIBin is the path to the c2ffi binary.
	C2FFIBin string

	// NDKSysroot is the NDK sysroot include directory
	// (e.g., .../sysroot/usr/include).
	NDKSysroot string

	// NDKPath is the root NDK directory (e.g., .../ndk/28.0.13004108).
	// Used to find NDK clang for preprocessing.
	NDKPath string

	// Includes are the header files to process
	// (e.g., ["android/looper.h", "camera/NdkCameraDevice.h"]).
	Includes []string

	// Target is the clang target triple (default: aarch64-linux-android35).
	Target string
}

InvokeOptions configures how to run c2ffi on NDK headers.

type Manifest

type Manifest struct {
	Generator struct {
		PackageName string   `yaml:"PackageName"`
		Includes    []string `yaml:"Includes"`
	} `yaml:"GENERATOR"`
	Translator struct {
		Rules struct {
			Global []Rule `yaml:"global"`
		} `yaml:"Rules"`
	} `yaml:"TRANSLATOR"`
}

Manifest holds the relevant fields from capi/manifests/*.yaml.

type Parameter

type Parameter struct {
	Tag  string  `json:"tag"`
	Name string  `json:"name"`
	Type TypeRef `json:"type"`
}

Parameter is a function parameter in c2ffi output.

type Rule

type Rule struct {
	Action string `yaml:"action"`
	From   string `yaml:"from"`
}

Rule is one accept/ignore filter rule from the manifest.

type TypeRef

type TypeRef struct {
	Tag          string   `json:"tag"`
	Type         *TypeRef `json:"type"`
	BitSize      int      `json:"bit-size"`
	BitAlignment int      `json:"bit-alignment"`

	// Struct/enum inline (for typedef targets like ":enum").
	Name   string  `json:"name"`
	ID     int     `json:"id"`
	Fields []Field `json:"fields"`

	// Array.
	Size int `json:"size"`
}

TypeRef describes a type in c2ffi's JSON. Types are recursive: a pointer is {"tag": ":pointer", "type": {...}}.