register

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: 14 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 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

Index

Constants

This section is empty.

Variables

View Source 
var (
	// INPUT_REGISTER signals a register used for holding the input values of a
	// function.
	INPUT_REGISTER = Type{uint8(0)}
	// OUTPUT_REGISTER signals a register used for holding the output values of
	// a function.
	OUTPUT_REGISTER = Type{uint8(1)}
	// COMPUTED_REGISTER signals a register whose values are computed from one
	// (or more) assignments during trace expansion.
	COMPUTED_REGISTER = Type{uint8(2)}
	// ZERO_REGISTER signals a register whose value is always 0.
	ZERO_REGISTER = Type{uint8(3)}
	// ONE_REGISTER signals a register whose value is always 1.
	ONE_REGISTER = Type{uint8(4)}
)

Functions

func LimbWidths 

func LimbWidths(maxWidth, regWidth uint) []uint

LimbWidths determines the limb widths for any register of the given size.

func LimbsMapToString 

func LimbsMapToString(p LimbsMap) string

LimbsMapToString provides a default method for converting a register limbs map into a simple string representation.

func MapToString 

func MapToString(p Map) string

MapToString provides a default method for converting a register map into a simple string representation.

func NewLimbsMap 

func NewLimbsMap[F any](field field.Config, module Map) limbsMap

NewLimbsMap constructs an appropriate register map for a given module and parameter combination.

func SplitConstant 

func SplitConstant(constant big.Int, limbWidths ...uint) []big.Int

SplitConstant splits a given constant into a number of "limbs". For example, consider splitting the constant 0x7b2d into 8bit limbs. Then, this function returns the array [0x2d,0x7b]. Observe that the least significant limb is always returned first (i.e. at index zero in the resulting array).

func ToString 

func ToString(rid Id) string

ToString provides a simplistic default string implementation for a RegisterId. This is useful primarily for debugging where we want to e.g. print a constraint but don't have access to an appropriate mapping, etc.

func WidthOfRegisters 

func WidthOfRegisters(regs []Register, rids []Id) uint

WidthOfRegisters returns the combined bitwidth of the given registers. For example, suppose we have three registers: x:u8, y:u8, z:u11. Then the combined width is 8+8+11=27.

func WidthsOfLimbs 

func WidthsOfLimbs(mapping LimbsMap, lids []LimbId) []uint

WidthsOfLimbs returns the limb bitwidths corresponding to a given set of identifiers.

Types

type AccessId 

type AccessId = trace.ColumnAccessId

AccessId is a wrapper around a column Id which adds a "relative shift" and "bitwidth window". That is, it identifies a column on a relative row from the given row, and allows only a portion of the original variable to be accessed.

type Allocator 

type Allocator[T any] interface {
	Map
	// Allocate a fresh register of the given width within the target module.
	// This is presumed to be a computed register, and automatically assigned a
	// unique name.  No assignment is included for the allocated register
	Allocate(prefix string, width uint) Id
	// Allocate n registers of the given width within the target module.
	// This is presumed to be a computed register, and automatically assigned a
	// unique name.  No assignment is included for the allocated register
	AllocateN(prefix string, widths []uint) []Id
	// Allocate a fresh register of the given width within the target module
	// *with* an assignment. This is declared as computed register, and
	// automatically assigned a unique name.
	AllocateWith(prefix string, width uint, assignment T) Id
	// Allocate n registers of the given width within the target module *with*
	// an assignment. These are all declared as computed registers, and
	// automatically assigned unique names.
	AllocateWithN(prefix string, assignment T, widths ...uint) []Id
	// Assignments returns any metadata assigned to an allocated register.
	Assignments() []util.Pair[[]Id, T]
	// Reset back to a given number of registers.  This is essentially for
	// "undoing" allocations in algorithms that perform speculative allocation.
	Reset(uint)
}

Allocator extends a register mapping with the ability to allocate new registers as necessary. This is useful, for example, in the context of register splitting for introducing new carry registers.

func NewAllocator 

func NewAllocator[T any](mapping Map) Allocator[T]

NewAllocator converts a mapping into a full allocator simply by wrapping the two fields.

type ConstMap 

type ConstMap interface {
	Map
	// ConstRegister returns the ID of a constant register which is either
	// always zero or always one (no other constants are supported at this
	// time).   If such a register does not already exist, then one is created.
	// This ensures constant registers are only included when they are actually
	// needed.
	ConstRegister(constant uint8) Id
}

ConstMap is a register map which additionally provides guaranteed access to a constant (binary) register. That is, a register which is always either "0" or always either "1".

type DynamicPolynomial 

type DynamicPolynomial = Polynomial[AccessId]

DynamicPolynomial represents a polynomial over "relative registers". That is, it can refer to registers on the current row or on a row relative to the current row (e.g. the next row, or the previous row, etc).

type Id 

type Id = trace.ColumnId

Id captures the notion of a register index. That is, for each module, every register is allocated a given index starting from 0. The purpose of the wrapper is to avoid confusion between uint values and things which are expected to identify Columns.

func NewId 

func NewId(index uint) Id

NewId constructs a new register ID from a given raw index.

func UnusedId 

func UnusedId() Id

UnusedId constructs something akin to a null reference. This is used in some situations where we may (or may not) want to refer to a specific register.

type Limb 

type Limb = Register

Limb is just an alias for Register, but it helps to clarify when we are referring to a register after subdivision.

func LimbsOf 

func LimbsOf(mapping LimbsMap, lids []LimbId) []Limb

LimbsOf returns those limbs corresponding to a given set of identifiers.

type LimbId 

type LimbId = Id

LimbId is just an alias for register.RegisterId, but it helps to clarify when we are referring to a register after subdivision.

func ApplyLimbsMap 

func ApplyLimbsMap(mapping LimbsMap, rids ...Id) []LimbId

ApplyLimbsMap applies a given mapping to a set of registers producing a corresponding set of limbs. In essence, each register is convert to its limbs in turn, and these are all appended together in order of ococurence.

type LimbsMap 

type LimbsMap interface {
	Map
	// Field returns the underlying field configuration used for this mapping.
	// This includes the field bandwidth (i.e. number of bits available in
	// underlying field) and the maximum register width (i.e. width at which
	// registers are capped).
	Field() field.Config
	// Limbs identifies the limbs into which a given register is divided.
	// Observe that limbs are ordered by their position in the original
	// register.  In particular, the first limb (i.e. at index 0) is always
	// least significant limb, and the last always most significant.
	LimbIds(Id) []LimbId
	// Limbs returns information about a given limb (i.e. a register which
	// exists after the split).
	Limb(LimbId) Limb
	// Limbs returns all limbs in the mapping.
	Limbs() []Limb
	// LimbsMap returns a register map for the limbs themselves.  This is useful
	// where we need a register map over the limbs, rather than the original
	// registers.
	LimbsMap() Map
}

LimbsMap provides a high-level mapping of all registers before and after subdivision occurs within a given module. That is, it maps a given register to those limbs into which it was subdivided.

type Map 

type Map interface {
	fmt.Stringer
	// Name returns the name given to the enclosing entity (i.e. module or
	// function), along with its multiplier.
	Name() trace.ModuleName
	// HasRegister checks whether a register with the given name exists and, if
	// so, returns its register identifier.  Otherwise, it returns false.
	HasRegister(name string) (Id, bool)
	// Access a given register in this module.
	Register(Id) Register
	// Registers providers access to the underlying registers of this map.
	Registers() []Register
}

Map provides a generic interface for entities which hold information about registers.

func ArrayMap 

func ArrayMap(name trace.ModuleName, regs ...Register) Map

ArrayMap constructs a register map from an array of registers.

type Polynomial 

type Polynomial[T util.Comparable[T]] = *poly.ArrayPoly[T]

Polynomial defines the type of polynomials over which packets (and register splitting in general) operate.

type Ref 

type Ref = trace.ColumnRef

Ref abstracts a complete (i.e. global) register identifier.

func AsRefArray 

func AsRefArray(p Refs) []Ref

AsRefArray converts a register refs array into an array of register ref.

func NewRef 

func NewRef(mid trace.ModuleId, id Id) Ref

NewRef constructs a new register reference from the given module and register identifiers.

type Refs 

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

Refs is a "registers reference" which abstracts a set of registers in a given module.

func NewRefs 

func NewRefs(mid trace.ModuleId, ids ...Id) Refs

NewRefs constructs a new registers reference for a given module and identifier set.

func (*Refs) Apply 

func (p *Refs) Apply(mapping LimbsMap) Refs

Apply a given mapping to this set of registers.

func (*Refs) GobDecode 

func (p *Refs) GobDecode(data []byte) error

GobDecode a previously encoded option

func (Refs) GobEncode 

func (p Refs) GobEncode() (data []byte, err error)

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

func (*Refs) Module 

func (p *Refs) Module() trace.ModuleId

Module returns the module identifier of this registers reference.

func (*Refs) Registers 

func (p *Refs) Registers() []Id

Registers returns the register identifiers for the referenced registers.

type Register 

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

Register represents a specific register in the schema that, eventually, will be mapped to one (or more) columns in the trace. Observe that multiple registers can end up being mapped to the same column via "register allocation". Likewise, a single register can end up being mapped across multiple columns as a result of subdivision to ensure field agnosticity. Hence, why they are referred to as registers rather than columns --- they are similar, but not identical, concepts.

func New 

func New(kind Type, name string, bitwidth uint, padding big.Int) Register

New constructs a new register of a given kind (i.e. input, output or computed) with the given name and bitwidth.

func NewComputed 

func NewComputed(name string, bitwidth uint, padding big.Int) Register

NewComputed constructs a new computed register with the given name and bitwidth.

func NewConst 

func NewConst(value uint8) Register

NewConst constructs a new "constant register". That is a register which always holds a constant value. Currently, only constants 0 or 1 are supported.

func NewInput 

func NewInput(name string, bitwidth uint, padding big.Int) Register

NewInput constructs a new input register with the given name and bitwidth.

func NewNative 

func NewNative(kind Type, name string, padding big.Int) Register

NewNative constructs a new "native" register. That is, a register backed by a field element rather than a fixed-width unsigned integer. Such registers have no fixed bitwidth and can hold any value representable in the underlying field.

func NewOutput 

func NewOutput(name string, bitwidth uint, padding big.Int) Register

NewOutput constructs a new output register with the given name and bitwidth.

func SplitIntoLimbs 

func SplitIntoLimbs(maxWidth uint, r Register) []Register

SplitIntoLimbs splits a register into a number of limbs with the given maximum bitwidth. For the resulting array, the least significant register is first. Since registers are always split to the maximum width as much as possible, it is only the most significant register which may (in some cases) have fewer bits than the maximum allowed.

func (*Register) Bound 

func (p *Register) Bound() *big.Int

Bound returns the first value which cannot be represented by the given bitwidth. For example, the bound of an 8bit register is 256.

func (*Register) ConstValue 

func (p *Register) ConstValue() uint8

ConstValue determines the constant value for a given constant register.

func (*Register) IsComputed 

func (p *Register) IsComputed() bool

IsComputed determines whether or not this is a computed register. Observer that "zero" registers are included in this, since they are neither input nor output registers.

func (*Register) IsInput 

func (p *Register) IsInput() bool

IsInput determines whether or not this is an input register

func (*Register) IsInputOutput 

func (p *Register) IsInputOutput() bool

IsInputOutput determines whether or not this is an input or output register

func (*Register) IsNative 

func (p *Register) IsNative() bool

IsNative determines whether or not this is a "native" register. That is, a register backed by a field element rather than a fixed-width unsigned integer.

func (*Register) IsOutput 

func (p *Register) IsOutput() bool

IsOutput determines whether or not this is an output register

func (*Register) IsU1Const added in v1.2.21 

func (p *Register) IsU1Const() bool

IsU1Const determines whether or not this is a constant "zero" or "one" register

func (Register) Kind 

func (p Register) Kind() Type

Kind returns the type of this register

func (*Register) MarshalBinary 

func (p *Register) MarshalBinary() (data []byte, err error)

MarshalBinary converts a register into binary data

func (*Register) MaxValue 

func (p *Register) MaxValue() *big.Int

MaxValue returns the largest value expressible in this register (i.e. Bound() - 1). For example, the max value of an 8bit register is 255.

func (Register) Name 

func (p Register) Name() string

Name returns the (unqualified) name of this register

func (*Register) Padding 

func (p *Register) Padding() *big.Int

Padding determines what value will be used to padd this register.

func (Register) QualifiedName 

func (p Register) QualifiedName(mod Map) string

QualifiedName returns the fully qualified name of this register

func (*Register) SetPadding 

func (p *Register) SetPadding(padding *big.Int)

SetPadding updates the padding value to use for this register.

func (Register) String 

func (p Register) String() string

func (*Register) UnmarshalBinary 

func (p *Register) UnmarshalBinary(data []byte) error

UnmarshalBinary unmarshals a register

func (Register) Width 

func (p Register) Width() uint

Width determines the bitwidth of this register. This panics if called on a native register, since such registers have no fixed bitwidth. Callers should guard with IsNative() if the register may be native.

func (Register) WidthOrNative added in v1.2.21 

func (p Register) WidthOrNative() uint

WidthOrNative returns the bitwidth of this register, or math.MaxUint if it is a native register.

type Type 

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

Type captures the type of a given register, such as whether it represents an input column, and output column or a computed register, etc.

func (Type) Cmp 

func (p Type) Cmp(o Type) int

Cmp implementation for register types, where inputs come first, followed by outputs then computed registers.

func (*Type) GobDecode 

func (p *Type) GobDecode(data []byte) error

GobDecode a previously encoded option

func (Type) GobEncode 

func (p Type) GobEncode() (data []byte, err error)

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

type Vector 

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

Vector represents a sequence of one or more registers which are imagined to be concatenated together, with the least significant having the least index in the vector. For example, we might have a vector hi::lo where lo has index 0, and hi has index 1.

func NewVector 

func NewVector(regs ...Id) Vector

NewVector constructs a new vector from a given sequence of registers, where the least significant register has the lowest index.

func (Vector) AsRegister 

func (p Vector) AsRegister() Id

AsRegister returns this vector as a single register. Observe that this will panic if the vector contains more than one register.

func (Vector) BitWidth 

func (p Vector) BitWidth(fn Map) uint

BitWidth returns the bitwidth of this vector in a given context.

func (Vector) Clone 

func (p Vector) Clone() Vector

Clone this vector producing an identical but physically disjoint vector.

func (Vector) Last 

func (p Vector) Last() Id

Last returns the last (i.e. most significant) register in this vector

func (Vector) Len 

func (p Vector) Len() uint

Len returns the length of this vector

func (*Vector) MarshalBinary 

func (p *Vector) MarshalBinary() (data []byte, err error)

MarshalBinary converts a vector into binary data.

func (Vector) Registers 

func (p Vector) Registers() []Id

Registers provides raw access to the underlying register array wrapped in this vector.

func (Vector) Split 

func (p Vector) Split(mapping LimbsMap) Vector

Split this vector according to a given limbs mapping.

func (Vector) String 

func (p Vector) String(fn Map) string

func (*Vector) UnmarshalBinary 

func (p *Vector) UnmarshalBinary(data []byte) error

UnmarshalBinary unmarshals a vector.

Source Files

View all Source files

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.