gapil

package
v0.0.0-...-6c7272e Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 13, 2022 License: Apache-2.0 Imports: 11 Imported by: 0

README

Graphics API Language

The Graphics API Language is used to describe in detail the interface and required behaviour of a graphics API. From these API files, much of GAPII, GAPIR and GAPIS is generated.

Data types

Builtin types
Typename Description
void used to denote no return value, or a pointer to untyped memory (void*)
string a sequence of characters
bool architecture dependent sized boolean value
char architecture dependent sized character value
int architecture dependent sized signed integer
uint architecture dependent sized unsigned integer
size architecture dependent sized integer used for sizes
s8 8-bit signed integer
u8 8-bit unsigned integer
s16 16-bit signed integer
u16 16-bit unsigned integer
s32 32-bit signed integer
u32 32-bit unsigned integer
s64 64-bit signed integer
u64 64-bit unsigned integer
f32 32-bit floating-pointer number
f64 64-bit floating-pointer number
Named types

A number of different types can be defined within the API file.

Each of the following types can be preceded with any number of annotations.

Class

Class types define objects that can hold fields and methods.

Class instances can be used as value types or be shared using references.

Classes are declared using the syntax:

class name {
  field_type_1 field_name_1
  ...
  field_type_N field_name_N
}
Enum

Enum types define a collection of name-integer pairs within a named scope.

Enums may contain multiple names with the same value.

Enums are declared using the syntax:

enum name {
  name_1 = value_1
  ...
  name_N = value_N
}
Bitfield

Bitfield types define a collection of name-integer pairs within a named scope.

Bitfields have special operators for performing bitwise tests.

Bitfields are declared using the syntax:

bitfield name {
  name_1 = value_1
  ...
  name_N = value_N
}
Alias

Aliases create a new type derived from an existing type. Templates may chose to emit a new type for aliases in the target code-generated language.

Aliased types may have annotations.

Aliases are declared using the syntax:

type base_type alias_name
Map

Maps are a set of key-value pairs.

map!(u32, u32) uint_to_uint_map

The key must be a comparable type (or string). Maps have the following operations

x := uint_to_uint_map[2]; // Access
uint_to_uint_map[2] = x; // Insert
for index, key, value in uint_to_uint_map {} // Iteration

The Access operation returns the value in question, or a default value if it did not exist in the map.

The insert operations inserts the given value at the given location in the map.

Iterating a map will iterate over the indices/keys/values in the map.

DenseMap

DenseMaps are a specialization of Map

dense_map!(u32, u32) uint_to_uint_map

They have the same semantics as Map, although their underlying storage is different. They are optimized for a set of small sequential keys. They take an amount of storage on the order of the largest key inserted into the map. They must be keyed on an unsigned integer value.

Commands

Commands are declared with a C-style function signature, prefixed with cmd.

cmd GLboolean glIsEnabled(GLenum capability) {
  // command body
}

Each command may be prefixed with one or more annotations.

@frame_start
cmd EGLBoolean eglSwapBuffers(EGLDisplay display, void* surface) {
  // ...
}

Global fields

At the top-level scope of an API file, fields can be declared with optional initializers.

f32 aGlobalF32      // Default-initialized to 0
u8  aGlobalU8  = 4  // Initialized to 4

These fields are initialized before any command is executed

Statements

Builtin statements
read(T[] src)

read is used to signal that the specified memory slice is read by the command.

For GAPII the read statement will instruct the interceptor to observe src before invoking the real driver function.

For GAPIR the read statement will instruct the replay system to fill the corresponding memory range with the observed memory before invoking the call.

The read statement is an implicit pre-fence statement.

write(T[] dst)

write is used to signal that the specified memory slice is written by the command.

For GAPII the write statement will instruct the interceptor to observe dst after invoking the real driver function.

For GAPIR the write statement will instruct the replay system to perform any output-value remappings after invoking the call.

The write statement is an implicit post-fence statement.

copy(T[] dst, T[] src)

copy will copy min(len(src), len(dst)) elements from src to dst, and perform the corresponding read() and write() logic on src and dst, respectively.

The copy statement is an implicit pre and post-fence statement.

fence

Statements need to be split into those that are executed before the call to the function, and those that need to be executed after the call to the function.

For example consider a function that performs a read-modify-write operation on the provided buffer:

cmd void RMW(u8* buffer, u32 size) {
  read(buffer[0:size])
  // implicit fence
  write(buffer[0:size])
}

In this example, the GAPII interceptor needs to perform a read observation on buffer before calling the driver's RMW function, and a write observation after calling the driver's RMW function.

For commands that do not use the explicit fence statement, an implicit fence will be inserted between all pre-fence statements and all post-fence statements in the command. The logic to find this insertion point is currently pretty simple, and may fail with a compilation error if a single insertion point cannot be found. In these cases you should explicitly add a fence statement to the command.

Annotations

An annotation is a custom attribute that can be placed on named types and commands.

Annotations can take the form:

@name

@name(arg1, arg2, arg3)

Annotations are for use by the templates when using the apic [template] (../cmd/apic/template.go) or [validate] (../cmd/apic/validate.go) commands, but otherwise have no effect.

Documentation

Overview

Package gapil holds the main interface to the api language libraries. It provides functions for going from api files to abstract syntax trees and processed semantic trees.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CheckErrors

func CheckErrors(apiName string, errs parse.ErrorList, maxErrors int) error

CheckErrors will, if len(errs) > 0, print each of the error messages for the specified api and then return the list as a single error. If errs is zero length, CheckErrors does nothing and returns nil.

func Parse

func Parse(apiname string) (*ast.API, parse.ErrorList)

Parse parses the api file with a default Processor. See Processor.Parse for details.

func Resolve

func Resolve(apiname string) (*semantic.API, parse.ErrorList)

Resolve resolves the api file with a default Processor. See Processor.Resolve for details.

Types

type Loader

type Loader interface {
	// Find recieves the path to a desired import relative to the current file.
	// The path it is supplied may not be valid, the loader should transform it
	// into a valid path if possible or return a fully invalid path if the api
	// file cannot be found.
	Find(path file.Path) file.Path
	// Load takes a path returned by Find and returns the content the path
	// represents, or an error if the path was not valid.
	Load(file.Path) ([]byte, error)
}

Loader is the interface to something that finds and loads api imports.

func NewDataLoader

func NewDataLoader(data []byte) Loader

func NewSearchLoader

func NewSearchLoader(search file.PathList) Loader

type ParseResult

type ParseResult struct {
	API  *ast.API
	Errs parse.ErrorList
}

ParseResult holds the result of parsing a file.

type Processor

type Processor struct {
	*semantic.Mappings
	Loader              Loader
	Parsed              map[string]ParseResult // guarded by parsedLock
	Resolved            map[string]ResolveResult
	ResolveOnParseError bool // If true, resolving will be attempted even if parsing failed.
	Options             resolver.Options
	// contains filtered or unexported fields
}

Processor holds the state when resolving multiple api files.

func NewProcessor

func NewProcessor() *Processor

NewProcessor returns a new initialized Processor.

func (*Processor) Parse

func (p *Processor) Parse(path string) (*ast.API, parse.ErrorList)

Parse returns an ast that represents the supplied filename. It if the file has already been parsed, the cached ast will be returned, otherwise it invokes parser.Parse on the content of the supplied file name. It is safe to parse multiple files simultaniously.

func (*Processor) Resolve

func (p *Processor) Resolve(apiname string) (*semantic.API, parse.ErrorList)

Resolve returns a semantic.API that represents the supplied api file name. If the file has already been resolved, the cached semantic tree is returned, otherwise the file and all dependant files are parsed using Processor.Parse. Recursive calls are made to Resolve for all named imports, and then finally the ast and all included ast's are handed to resolver.Resolve to do semantic processing.

type ResolveResult

type ResolveResult struct {
	API  *semantic.API
	Errs parse.ErrorList
}

ResolveResult holds the result of parsing a file.

Directories

Path Synopsis
Package analysis performs static program data flow analysis of an API file.
Package analysis performs static program data flow analysis of an API file.
Package ast holds the set of types used in the abstract syntax tree representation of the api language.
Package ast holds the set of types used in the abstract syntax tree representation of the api language.
Package bapi exposes functions for serializing and deserializing resolved APIs.
Package bapi exposes functions for serializing and deserializing resolved APIs.
Package compiler implements the core gapil language compiler.
Package compiler implements the core gapil language compiler.
mangling
Package mangling exposes a minimal collection of types used to build mangled strings using any of the sub-packages.
Package mangling exposes a minimal collection of types used to build mangled strings using any of the sub-packages.
mangling/c
Package c implements a basic symbol mangling for that is compatible with C.
Package c implements a basic symbol mangling for that is compatible with C.
mangling/ia64
Package ia64 implements a subset of the symbol mangling for the itanium ABI (standard for GCC).
Package ia64 implements a subset of the symbol mangling for the itanium ABI (standard for GCC).
plugins/cloner
Package cloner is a plugin for the gapil compiler to generate deep clone functions for reference types, maps and commands.
Package cloner is a plugin for the gapil compiler to generate deep clone functions for reference types, maps and commands.
plugins/encoder
Package encoder is a plugin for the gapil compiler to generate command and state encode functions.
Package encoder is a plugin for the gapil compiler to generate command and state encode functions.
plugins/encoder/test/encoder_pb
Package encoder_pb describes the serialization format for the serialzation test api.
Package encoder_pb describes the serialization format for the serialzation test api.
plugins/replay
Package replay is a plugin for the gapil compiler to generate replay streams for commands.
Package replay is a plugin for the gapil compiler to generate replay streams for commands.
testutils
Package testutils implements reusable helpers for writing compiler tests.
Package testutils implements reusable helpers for writing compiler tests.
Package constset provides structures for storing large numbers of value-string pairs efficently.
Package constset provides structures for storing large numbers of value-string pairs efficently.
Package executor provides an interface for executing compiled API programs.
Package executor provides an interface for executing compiled API programs.
Package format registers and implements the "format" apic command.
Package format registers and implements the "format" apic command.
The langsvr command implements a language server for the graphics API language.
The langsvr command implements a language server for the graphics API language.
Package parser implements a parser for converting the api language into abstract syntax trees.
Package parser implements a parser for converting the api language into abstract syntax trees.
Package resolver implements a semantic resolving for the api language.
Package resolver implements a semantic resolving for the api language.
Package semantic holds the set of types used in the abstract semantic graph representation of the api language.
Package semantic holds the set of types used in the abstract semantic graph representation of the api language.
printer
Package printer provides a human-readable printer for the semantic tree nodes.
Package printer provides a human-readable printer for the semantic tree nodes.
Package serialization contains constants and utility methods used to serialize .gfxtrace files.
Package serialization contains constants and utility methods used to serialize .gfxtrace files.
Package validate registers and implements the "validate" apic command.
Package validate registers and implements the "validate" apic command.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL