io

package
v1.2.23 Latest Latest
Warning

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

 Go to latest Published: Jul 22, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIN, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Index

Constants

View Source 
const (
	// PC_NAME gives the name used for the program counter in traces.
	PC_NAME = "$pc"
	// RET_NAME gives the name used for the return line in traces.
	RET_NAME = "$ret"
	// IS_PC_PREFIX gives the prefix used for the one-hot program counter
	// selector lines in traces.  A selector for PC value v is named
	// "$is_pc_<v>".
	IS_PC_PREFIX = "$is_pc_"
	// AT_FLAG_PREFIX name of binary flag names for multi-line address increments
	AT_FLAG_PREFIX = "$at_flag_"
	// ACCESS_BIT_NAME name of binary flag for non-padding rows
	ACCESS_BIT_NAME = "$access_bit"
)
View Source 
const FAIL uint = math.MaxUint - 1

FAIL is used to signal that a given instruction returns with an exception from the enclosing function.

View Source 
const RETURN uint = math.MaxUint

RETURN is used to signal that a given instruction returns from the enclosing function.

View Source 
const UNKNOWN_BUS = math.MaxUint

UNKNOWN_BUS signals a bus which is unknown.

View Source 
const (
	// UNUSED_REGISTER provides a simple way to distinguish registers and
	// constants in certain instructions.
	UNUSED_REGISTER = math.MaxUint
)

Variables

This section is empty.

Functions

func AtFlagName added in v1.2.21 

func AtFlagName(k uint) string

AtFlagName returns the name of the binary "at flag" register for address limb k, used to locate the carry-stop limb on a multi-limb address increment.

func CheckTargetRegisters 

func CheckTargetRegisters(targets []RegisterId, regs []Register) error

CheckTargetRegisters performs some simple checks on a set of target registers being written. Firstly, they cannot be input registers (as this are always constant). Secondly, we cannot write to the same register more than once (i.e. a conflicting write).

func InferPadding 

func InferPadding[T Instruction](fn Component[T], executor *Executor[T])

InferPadding attempts to infer suitable padding values for a function, based on those padding values provided for its inputs (which default to 0). In essence, this constructs a witness for the function in question.

func ReadBitSlice 

func ReadBitSlice(offset uint, width uint, value big.Int, sign bool) big.Int

ReadBitSlice reads a slice of bits starting at a given offset in a give value. For example, consider the value is 10111000 and we have offset=1 and width=4, then the result is 1100.

func RegistersReversedToString 

func RegistersReversedToString(rids []RegisterId, regs []Register) string

RegistersReversedToString returns a string representation for zero or more registers in reverse order, separated by a comma. This is useful, for example, when printing the left-hand side of an assignment.

func RegistersToString 

func RegistersToString(rids []RegisterId, regs []Register) string

RegistersToString returns a string representation for zero or more registers separated by a comma.

func SelectorName added in v1.2.21 

func SelectorName(line uint) string

SelectorName returns the name of the one-hot program counter selector register for the instruction at the given (zero-based) code line. The PC value for code line c is c+1 (PC==0 is reserved for padding).

Types

type Bus 

type Bus struct {
	// Bus name
	Name module.Name
	// Global bus identifier.  This uniquely identifies the bus across all
	// functions and components.
	BusId uint
	// Determines the address lines of this bus.
	AddressLines []RegisterId
	// Determiunes the data lines of this bus.
	DataLines []RegisterId
}

Bus describes an I/O bus referred to within a function. Every function can connect with zero or more buses. For example, making a function call requires a bus for the target function. Each bus consists of some number of _address lines_ and some number of _data lines_. Reading a value from the bus requires setting the address lines, then reading the data lines. Likewise, put a value onto the bus requires setting both the address and data lines.

func NewBus 

func NewBus(name module.Name, id uint, address []RegisterId, data []RegisterId) Bus

NewBus constructs a new bus with the given components.

func UnlinkedBus 

func UnlinkedBus(name module.Name) Bus

UnlinkedBus constructs a new bus which is not yet connected with anything. Rather it simply has a name which will be used later to establish the connection.

func (*Bus) Address 

func (p *Bus) Address() []RegisterId

Address returns the "address lines" for this bus. That is, the registers which hold the various components of the address.

func (*Bus) Data 

func (p *Bus) Data() []RegisterId

Data returns the "data lines" for this bus. That is, the registers which hold the various data values (either being read or written).

func (*Bus) IsUnlinked 

func (p *Bus) IsUnlinked() bool

IsUnlinked checks whether a given bus has been linked already or not.

func (*Bus) Split 

func (p *Bus) Split(mapping register.LimbsMap, _ agnostic.RegisterAllocator) Bus

Split this micro code using registers of arbirary width into one or more micro codes using registers of a fixed maximum width.

func (*Bus) String 

func (p *Bus) String() string

type Component 

type Component[T Instruction] interface {
	register.ConstMap
	schema.ModuleView

	// IsAtomic determines the lookup protocol for this component. Specifically,
	// for non-atomic units, we must filter the rows based on a selector when
	// performing lookups.
	IsAtomic() bool

	// Inputs returns the set of input registers for this component.  This exact
	// meaning of these depends upon the unit in question.  For example, inputs
	// correspond to parameters (for functions), address lines (for memories),
	// etc.
	Inputs() []Register

	// NumInputs returns the number of input registers for this component.
	NumInputs() uint

	// NumOutputs returns the number of output registers for this component.
	NumOutputs() uint

	// Outputs returns the set of output registers for this function.  This
	// exact meaning of these depends upon the unit in question.  For example,
	// outputs correspond to returns (for functions), data lines (for memories),
	// etc.
	Outputs() []Register

	// Validate that this component is well-formed.  For example, for a function
	// we must ensure that no instructions have conflicting writes, that all
	// temporaries have been allocated, etc.  The maximum bit capacity of the
	// underlying field is needed for various calculations as part of this.
	Validate(fieldWidth uint) []error
}

Component defines a distinct entity within the system, such as a function, or a read-only memory or a static reference table. Units contain registers, some of which may be marked as inputs/outputs and others as internal, etc.

type ComponentInstance 

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

ComponentInstance captures the mapping from inputs (i.e. parameters) to outputs (i.e. returns) for a particular instance of a given function.

func (ComponentInstance) Cmp 

func (p ComponentInstance) Cmp(other ComponentInstance) int

Cmp comparator for the I/O registers of a particular function instance. Observe that, since functions are always deterministic, this only considers the inputs (as the outputs follow directly from this).

func (ComponentInstance) Get 

func (p ComponentInstance) Get(arg uint) big.Int

Get value of given input or output argument for this instance.

func (ComponentInstance) Outputs 

func (p ComponentInstance) Outputs() []big.Int

Outputs returns the output values for this function instance.

type ComponentTrace 

type ComponentTrace[T Instruction] struct {
	// contains filtered or unexported fields
}

ComponentTrace captures all instances for a given component, and provides a (thread-safe) API for calling to compute its output for a given set of inputs.

func NewFunctionTrace 

func NewFunctionTrace[T Instruction](fn Component[T]) *ComponentTrace[T]

NewFunctionTrace constructs an empty trace for a given function.

func (*ComponentTrace[T]) Call 

func (p *ComponentTrace[T]) Call(inputs []big.Int, iomap Map) ComponentInstance

Call this function to determine its outputs for a given set of inputs. If this instance has been seen before, it will simply return that. Otherwise, it will execute the function to determine the correct outputs.

func (*ComponentTrace[T]) Count 

func (p *ComponentTrace[T]) Count() uint

Count the number of instances recorded as part of this function's trace.

type Executor 

type Executor[T Instruction] struct {
	// contains filtered or unexported fields
}

Executor provides a mechanism for executing a program efficiently and generating a suitable top-level trace. Executor implements the io.Map interface.

func NewExecutor 

func NewExecutor[T Instruction](program Program[T]) *Executor[T]

NewExecutor constructs a new executor.

func (*Executor[T]) Count 

func (p *Executor[T]) Count() uint

Count the total number of instances currently recorded in this executor.

func (*Executor[T]) Instance 

func (p *Executor[T]) Instance(bus uint) ComponentInstance

Instance returns a valid instance of the given bus.

func (*Executor[T]) Instances 

func (p *Executor[T]) Instances(bus uint) []ComponentInstance

Instances returns accrued function instances for the given bus.

func (*Executor[T]) Read 

func (p *Executor[T]) Read(bus uint, address []big.Int, _ uint) []big.Int

Read implementation for the io.Map interface.

func (*Executor[T]) Write 

func (p *Executor[T]) Write(bus uint, address []big.Int, values []big.Int)

Write implementation for the io.Map interface.

type Function 

type Function[T Instruction] struct {
	// contains filtered or unexported fields
}

Function defines a distinct functional entity within the system. Functions accepts zero or more inputs and produce zero or more outputs. Functions declare zero or more internal registers for use, and their interpretation is given by a sequence of zero or more instructions.

func NewFunction 

func NewFunction[T Instruction](name module.Name, public bool, registers []Register, buses []Bus,
	code []T) Function[T]

NewFunction constructs a new function with the given components.

func (*Function[T]) AllocateRegister 

func (p *Function[T]) AllocateRegister(kind register.Type, name string, width uint, padding big.Int) RegisterId

AllocateRegister allocates a new register of the given kind, name and width into this function.

func (*Function[T]) Buses 

func (p *Function[T]) Buses() []Bus

Buses returns the set of all buses used by any instruction within this function.

func (*Function[T]) Code 

func (p *Function[T]) Code() []T

Code returns the instructions making up the body of this function.

func (*Function[T]) CodeAt 

func (p *Function[T]) CodeAt(i uint) T

CodeAt returns the ith instruction making up the body of this function.

func (*Function[T]) ConstRegister 

func (p *Function[T]) ConstRegister(constant uint8) RegisterId

ConstRegister implementation for register.ConstMap interface

func (*Function[T]) GobDecode 

func (p *Function[T]) GobDecode(data []byte) error

nolint

func (*Function[T]) GobEncode 

func (p *Function[T]) GobEncode() ([]byte, error)

nolint

func (*Function[T]) HasRegister 

func (p *Function[T]) HasRegister(name string) (RegisterId, bool)

HasRegister checks whether a register with the given name exists and, if so, returns its register identifier. Otherwise, it returns false.

func (*Function[T]) Inputs 

func (p *Function[T]) Inputs() []Register

Inputs returns the set of input registers for this function.

func (*Function[T]) IsAtomic 

func (p *Function[T]) IsAtomic() bool

IsAtomic determines whether or not this is a "one line function". That is, where every instance of this function occupies exactly one line in the corresponding trace. This is useful to know, as certain optimisations can be applied for one line functions (e.g. no PC register is required).

func (*Function[T]) IsNative 

func (p *Function[T]) IsNative() bool

IsNative reports whether this module corresponds to a function backed by a native circuit. Assembly-level functions are never native; only ZkC modules can be.

func (*Function[T]) IsPublic 

func (p *Function[T]) IsPublic() bool

IsPublic determines whether or not this is an "externally visible" function or not. The differences between internal and external functions is small. Specifically, internal functions are not visible in the generated trace interface; likewise, they are hidden by default in the inspector.

func (*Function[T]) IsStatic 

func (p *Function[T]) IsStatic() bool

IsStatic reports whether this module is a static reference table. Assembly-level functions are never static.

func (*Function[T]) IsSynthetic 

func (p *Function[T]) IsSynthetic() bool

IsSynthetic modules are generated during compilation, rather than being provided by the user. At this time, functions can never be synthetic

func (*Function[T]) Name 

func (p *Function[T]) Name() module.Name

Name returns the name of this function.

func (*Function[T]) NumInputs 

func (p *Function[T]) NumInputs() uint

NumInputs returns the number of input registers for this function.

func (*Function[T]) NumOutputs 

func (p *Function[T]) NumOutputs() uint

NumOutputs returns the number of output registers for this function.

func (*Function[T]) Outputs 

func (p *Function[T]) Outputs() []Register

Outputs returns the set of output registers for this function.

func (*Function[T]) Register 

func (p *Function[T]) Register(id register.Id) Register

Register returns the ith register used in this function.

func (*Function[T]) Registers 

func (p *Function[T]) Registers() []Register

Registers returns the set of all registers used during execution of this function.

func (*Function[T]) String 

func (p *Function[T]) String() string

func (*Function[T]) Validate 

func (p *Function[T]) Validate(fieldWidth uint) []error

Validate that this function and all instructions contained therein is well-formed. For example, that instructions have no conflicting writes, that all temporaries have been allocated, etc. The maximum bit capacity of the underlying field is needed for this calculation, to allow instructions to check it does not overflow the underlying field.

func (*Function[T]) Width 

func (p *Function[T]) Width() uint

Width returns the number of registers in this module.'

type InOutInstruction 

type InOutInstruction interface {
	// Bus returns information about the bus.  Observe that prior to Link being
	// called, this will return an unlinked bus.
	Bus() Bus
}

InOutInstruction is simply a kind of instruction which performs some kind of I/O operation via a bus.

type Instruction 

type Instruction interface {
	// Execute this instruction with the given local and global state.  The next
	// program counter position is returned, or io.RETURN if the enclosing
	// function has terminated (i.e. because a return instruction was
	// encountered).
	Execute(state State) uint
	// Registers returns the set of registers read this micro instruction.
	RegistersRead() []RegisterId
	// Registers returns the set of registers written by this micro instruction.
	RegistersWritten() []RegisterId
	// Validate that this instruction is well-formed.  For example, that it is
	// balanced, that there are no conflicting writes, that all temporaries have
	// been allocated, etc.  The maximum bit capacity of the underlying field is
	// needed for this calculation, so as to allow an instruction to check it
	// does not overflow the underlying field.
	Validate(fieldWidth uint, fn register.Map) error
	// Produce a suitable string representation of this instruction.  This is
	// primarily used for debugging.
	String(fn register.Map) string
}

Instruction provides an abstract notion of an executable "machine instruction".

type Map 

type Map interface {
	// Read a set of n values at a given address on a bus.  The exact meaning of
	// this depends upon the I/O peripheral connected to the bus.  For example,
	// if its a function then the function is executed with the given address as
	// its arguments, producing some number of outputs.  Likewise, if its a
	// memory, then this will return the current value stored in that address,
	// etc.  Finally, the number of expected values must match that provided by
	// the underlying component.
	Read(bus uint, address []big.Int, n uint) []big.Int
	// Write a set of values to a given address on a bus.  This only makes sense
	// for writeable memory, such Random Access Memory (RAM).  In contrast,
	// functions and Read-Only Memory (ROM) are not considered writeable.
	Write(bus uint, address []big.Int, values []big.Int)
}

Map represents the interface between the different components of a program. It provides a way to send messages to and from components. The core abstraction of a bus are the "address lines" and the "data lines". For example, to read from a bus we set the desired address on the address lines and then read off the result from the data lines. Likewise, to write to a bus, we set both the address and data lines, etc. This mechanism abstracts the various I/O peripherals found within a program, such as functions, Random Access Memory, etc.

type Program 

type Program[T Instruction] struct {
	// contains filtered or unexported fields
}

Program encapsulates one of more functions together, such that one may call another, etc. Furthermore, it provides an interface between assembly components and the notion of a Schema.

func NewProgram 

func NewProgram[T Instruction](components []Component[T]) Program[T]

NewProgram constructs a new program using a given level of instruction.

func (*Program[T]) Component 

func (p *Program[T]) Component(id uint) Component[T]

Component returns the ith entity in this program.

func (*Program[T]) Components 

func (p *Program[T]) Components() []Component[T]

Components returns all functions making up this program.

func (*Program[T]) GobDecode 

func (p *Program[T]) GobDecode(data []byte) error

GobDecode a previously encoded option

func (*Program[T]) GobEncode 

func (p *Program[T]) GobEncode() (data []byte, err error)

GobEncode an option. This allows it to be marshalled into a binary form.

type Register 

type Register = register.Register

Register defines the notion of a register within a function.

type RegisterId 

type RegisterId = register.Id

RegisterId abstracts the notion of a register id.

type State 

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

State collects together local state necessary for executing a given instruction. This contrasts with an I/O Map which represents the non-local state.

func EmptyState 

func EmptyState(pc uint, registers []register.Register, io Map) State

EmptyState constructs an initially empty state at the given PC value. One can then set register values as needed via Store.

func InitialState 

func InitialState(inputs []big.Int, registers []register.Register, buses []Bus, iomap Map) State

InitialState constructs a suitable initial state for executing a given function with the given arguments.

func NewState 

func NewState(state []big.Int, registers []register.Register, io Map) State

NewState constructs a new state instance from the given state values.

func (*State) Clone 

func (p *State) Clone() State

Clone this state, producing a disjoint state.

func (*State) Goto 

func (p *State) Goto(pc uint)

Goto updates the program counter for this state to a given value.

func (*State) In 

func (p *State) In(bus Bus)

In performs an I/O read across a given bus. More specifically, it reads the value at a given address on the bus.

func (*State) Internal 

func (p *State) Internal() []big.Int

Internal provides access to the internal state. Obviously care should be taken with this.

func (*State) IsTerminal 

func (p *State) IsTerminal() bool

IsTerminal checks whether this is a terminating state, or not.

func (*State) Load 

func (p *State) Load(reg RegisterId) *big.Int

Load value of a given register from this state.

func (*State) LoadN 

func (p *State) LoadN(registers []RegisterId) []big.Int

LoadN reads the values of zero or more registers from this state.

func (*State) Out 

func (p *State) Out(bus Bus)

Out performs an I/O write across a given bus. More specifically, it sets the value at a given address on the bus.

func (*State) Outputs 

func (p *State) Outputs() []big.Int

Outputs extracts values from output registers of the given state.

func (*State) Pc 

func (p *State) Pc() uint

Pc returns the current program counter position.

func (*State) Registers 

func (p *State) Registers() []register.Register

Registers returns the set of registers used within this state.

func (*State) Store 

func (p *State) Store(reg RegisterId, value big.Int)

Store value to a given register from this state.

func (*State) StoreAcross 

func (p *State) StoreAcross(value big.Int, registers ...RegisterId)

StoreAcross a given value across a set of registers, splitting its bits as necessary. The target registers are given with the least significant first. For example, consider writing 01100010 to registers [R1, R2] of type u4. Then, after the write, we have R1=0010 and R2=0110.

func (*State) StoreN 

func (p *State) StoreN(registers []RegisterId, values []big.Int)

StoreN writes a set of zero or more values to a corresponding set of registers in this state.

func (*State) String 

func (p *State) String() string

String produces a string representation of the given execution state.

func (*State) Terminate 

func (p *State) Terminate()

Terminate marks this state as being terminal.

func (*State) Terminated 

func (p *State) Terminated() bool

Terminated determines whether this state represents a terminated function execution.

Source Files

View all Source files

Directories

Path Synopsis
dfa
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.