lvgen

Documentation

Overview

Package lvgen contains the instructions for regenerating the libvirt bindings. We do this by parsing the remote_protocol.x file included in the libvirt sources. Bindings will be generated if you run `go generate` in this directory.

Index

• Constants
• Variables
• func AddCase()
• func AddConst(name, val string) error
• func AddDeclaration(identifier, itype string)
• func AddEnumAutoVal(name string) error
• func AddEnumVal(name, val string) error
• func AddEnumValMeta(name, val, meta string) error
• func AddFixedArray(identifier, itype, len string)
• func AddOptValue(identifier, itype string)
• func AddStruct()
• func AddUnion()
• func AddVariableArray(identifier, itype, len string)
• func Generate(proto io.Reader) error
• func StartCase(dvalue string)
• func StartEnum(name string)
• func StartStruct(name string)
• func StartTypedef()
• func StartUnion(name string)
• type Case
• type ConstItem
• type Decl
  • func NewDecl(identifier, itype string) *Decl
  • func (decl *Decl) GetUnion() Union
• type Generator
• type Lexer
  • func NewLexer(rdr io.Reader) (*Lexer, error)
  • func (l *Lexer) Error(s string)
  • func (l *Lexer) Lex(st *yySymType) int
  • func (l *Lexer) Run()
• type Proc
• type ProcMeta
• type Structure
• type Typedef
• type Union

Constants

const BOOL = 57346

const CASE = 57347

const CHAR = 57364

const CONST = 57348

const CONSTANT = 57366

const DEFAULT = 57349

const DOUBLE = 57350

const ENUM = 57351

const ERROR = 57367

const FLOAT = 57352

const HYPER = 57361

const IDENTIFIER = 57365

const INT = 57362

const METADATACOMMENT = 57370

const OPAQUE = 57353

const PROGRAM = 57368

const SHORT = 57363

const STRING = 57354

const STRUCT = 57355

const SWITCH = 57356

const TYPEDEF = 57357

const UNION = 57358

const UNSIGNED = 57359

const VERSION = 57369

const VOID = 57360

Variables

var CurrentEnumVal int64

CurrentEnumVal is the auto-incrementing value assigned to enums that aren't explicitly given a value.

var CurrentStruct structStack

CurrentStruct will point to a struct record if we're in a struct declaration. When the parser adds a declaration, it will be added to the open struct if there is one.

Functions

func AddCase

func AddCase()

AddCase is called when the parser finishes parsing a case.

func AddConst

func AddConst(name, val string) error

AddConst adds a new constant to the parser's list.

func AddDeclaration

func AddDeclaration(identifier, itype string)

AddDeclaration is called by the parser when it find a declaration (int x). The declaration will be added to any open container (such as a struct, if the parser is working through a struct definition.)

func AddEnumAutoVal

func AddEnumAutoVal(name string) error

AddEnumAutoVal adds an enum to the list, using the automatically-incremented value. This is called when the parser finds an enum definition without an explicit value.

func AddEnumVal

func AddEnumVal(name, val string) error

AddEnumVal will add a new enum value to the list.

func AddEnumValMeta

func AddEnumValMeta(name, val, meta string) error

AddEnumValMeta will add a new enum value with attached metadata to the list. Metadata is parsed from annotations in libvirt RPC description file that are in block comment preceding every function in enum, it looks like this: /**

• @generate: both
• @readstream: 1
• @sparseflag: VIR_STORAGE_VOL_DOWNLOAD_SPARSE_STREAM
• @acl: storage_vol:data_read */

See full description of possible annotations in libvirt's src/remote/remote_protocol.x at the top of remote_procedure enum. We're parsing only @readstream and @writestream annotations at the moment.

func AddFixedArray

func AddFixedArray(identifier, itype, len string)

AddFixedArray is called by the parser to add a fixed-length array to the current container (struct, union, etc). Fixed-length arrays are not length- prefixed.

func AddOptValue

func AddOptValue(identifier, itype string)

AddOptValue is called by the parser to add an optional value. These are declared in the protocol definition file using a syntax that looks like a pointer declaration, but are actually represented by a variable-sized array with a maximum size of 1.

func AddStruct

func AddStruct()

AddStruct is called when the parser has finished parsing a struct. It adds the now-complete struct definition to the generator's list.

func AddUnion

func AddUnion()

AddUnion is called by the parser when it has finished processing a union type. It adds the union to the generator's list and clears the CurrentUnion pointer. We handle unions by declaring an interface for the union type, and adding methods to each of the cases so that they satisfy the interface.

func AddVariableArray

func AddVariableArray(identifier, itype, len string)

AddVariableArray is called by the parser to add a variable-length array. Variable-length arrays are prefixed with a 32-bit unsigned length, and may also have a maximum length specified.

func Generate

func Generate(proto io.Reader) error

Generate will output go bindings for libvirt. The lvPath parameter should be the path to the root of the libvirt source directory to use for the generation.

func StartCase

func StartCase(dvalue string)

StartCase is called when the parser finds a case statement within a union.

func StartEnum

func StartEnum(name string)

StartEnum is called when the parser has found a valid enum.

func StartStruct

func StartStruct(name string)

StartStruct is called from the parser when a struct definition is found, but before the member declarations are processed.

func StartTypedef

func StartTypedef()

StartTypedef is called when the parser finds a typedef.

func StartUnion

func StartUnion(name string)

StartUnion is called by the parser when it finds a union declaraion.

Types

type Case

type Case struct {
	CaseName        string
	DiscriminantVal string
	Decl
}

Case holds a single case of a discriminated union.

var CurrentCase *Case

CurrentCase holds the current case record while the parser is in a union and a case statement.

type ConstItem

type ConstItem struct {
	Name   string
	LVName string
	Val    string
}

ConstItem stores an const's symbol and value from the parser. This struct is also used for enums.

type Decl

type Decl struct {
	Name, LVName, Type string
}

Decl records a declaration, like 'int x' or 'remote_nonnull_string str'

func NewDecl

func NewDecl(identifier, itype string) *Decl

NewDecl returns a new declaration struct.

func (*Decl) GetUnion

func (decl *Decl) GetUnion() Union

GetUnion returns the type information for a union. If the provided type name isn't a union, this will return a zero-value Union type.

type Generator

type Generator struct {
	// Enums holds the enum declarations. The type of enums is always int32.
	Enums []Decl
	// EnumVals holds the list of enum values found by the parser. In sunrpc as
	// in go, these are not separately namespaced.
	EnumVals []ConstItem
	// Consts holds all the const items found by the parser.
	Consts []ConstItem
	// Structs holds a list of all the structs found by the parser
	Structs []Structure
	// StructMap is a map of the structs we find for quick searching.
	StructMap map[string]int
	// Typedefs holds all the type definitions from 'typedef ...' lines.
	Typedefs []Typedef
	// Unions holds all the discriminated unions.
	Unions []Union
	// UnionMap is a map of the unions we find for quick searching.
	UnionMap map[string]int
	// Procs holds all the discovered libvirt procedures.
	Procs []Proc
}

Generator holds all the information parsed out of the protocol file.

var Gen Generator

Gen accumulates items as the parser runs, and is then used to produce the output.

type Lexer

type Lexer struct {
	// contains filtered or unexported fields
}

Lexer stores the state of this lexer.

func NewLexer

func NewLexer(rdr io.Reader) (*Lexer, error)

NewLexer will return a new lexer for the passed-in reader.

func (*Lexer) Error

func (l *Lexer) Error(s string)

Error is called by the parser when it finds a problem.

func (*Lexer) Lex

func (l *Lexer) Lex(st *yySymType) int

Lex gets the next token.

func (*Lexer) Run

func (l *Lexer) Run()

Run starts the lexer, and should be called in a goroutine.

type Proc

type Proc struct {
	Num            int64  // The libvirt procedure number.
	Name           string // The name of the go func.
	LVName         string // The name of the libvirt proc this wraps.
	Args           []Decl // The contents of the args struct for this procedure.
	Ret            []Decl // The contents of the ret struct for this procedure.
	ArgsStruct     string // The name of the args struct for this procedure.
	RetStruct      string // The name of the ret struct for this procedure.
	ReadStreamIdx  int    // The index of read stream in function argument list
	WriteStreamIdx int    // The index of read stream in function argument list
}

Proc holds information about a libvirt procedure the parser has found.

type ProcMeta

type ProcMeta struct {
	ReadStream  int
	WriteStream int
}

ProcMeta holds information from annotations attached to a libvirt procedure

type Structure

type Structure struct {
	Name    string
	LVName  string
	Members []Decl
}

Structure records the name and members of a struct definition.

type Typedef

type Typedef struct {
	Decl
}

Typedef holds the name and underlying type for a typedef.

var CurrentTypedef *Typedef

CurrentTypedef will point to a typedef record if we're parsing one. Typedefs can define a struct or union type, but the preferred for is struct xxx{...}, so we may never see the typedef form in practice.

type Union

type Union struct {
	Name             string
	DiscriminantType string
	Cases            []Case
}

Union holds a "discriminated union", which consists of a discriminant, which tells you what kind of thing you're looking at, and a number of encodings.

var CurrentUnion *Union

CurrentUnion holds the current discriminated union record.