feat: implement asm debug output (#940)

* assembly debug output operational

* support compiling mixed schemas

This now puts in support for linking assembly schemas against corset
modules being compiled.

Author: DavePearce

pkg/asm/assembler/validation.go

@@ -69,7 +69,7 @@ func validateInstructions[T io.Instruction[T]](fieldWidth uint, fn io.Function[T
 	var errors []source.SyntaxError
 
 	for _, insn := range fn.Code() {
-		err := insn.Validate(fieldWidth, fn)
+		err := insn.Validate(fieldWidth, &fn)
 		//
 		if err != nil {
 			if !srcmaps.Has(insn) {

pkg/asm/io/constraint.go

@@ -0,0 +1,66 @@
+// 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
+package io
+
+import (
+	"github.com/consensys/gnark-crypto/ecc/bls12-377/fr"
+	sc "github.com/consensys/go-corset/pkg/schema"
+	"github.com/consensys/go-corset/pkg/trace"
+	"github.com/consensys/go-corset/pkg/util"
+	"github.com/consensys/go-corset/pkg/util/collection/bit"
+	"github.com/consensys/go-corset/pkg/util/source/sexp"
+)
+
+// Constraint represents a wrapper around an instruction in order for it to
+// conform to the constraint interface.
+type Constraint[T Instruction[T]] Function[T]
+
+// Accepts implementation for schema.Constraint interface.
+func (p Constraint[T]) Accepts(trace.Trace) (bit.Set, sc.Failure) {
+	panic("todo")
+}
+
+// Bounds implementation for schema.Constraint interface.
+func (p Constraint[T]) Bounds(module uint) util.Bounds {
+	panic("todo")
+}
+
+// Consistent implementation for schema.Constraint interface.
+func (p Constraint[T]) Consistent(sc.AnySchema) []error {
+	panic("todo")
+}
+
+// Contexts implementation for schema.Constraint interface.
+func (p Constraint[T]) Contexts() []sc.ModuleId {
+	panic("todo")
+}
+
+// Name implementation for schema.Constraint interface.
+func (p Constraint[T]) Name() string {
+	panic("todo")
+}
+
+// Lisp implementation for schema.Constraint interface.
+func (p Constraint[T]) Lisp(schema sc.AnySchema) sexp.SExp {
+	//
+	return sexp.NewList([]sexp.SExp{
+		sexp.NewSymbol("function"),
+		sexp.NewSymbol(p.name),
+	})
+}
+
+// Substitute implementation for schema.Constraint interface.
+func (p Constraint[T]) Substitute(map[string]fr.Element) {
+	// Do nothing since assembly instructions do not (at the time of writing)
+	// employ labelled constants.
+}

pkg/asm/io/function.go

@@ -16,6 +16,7 @@ import (
 	"bytes"
 	"encoding/gob"
 	"math"
+	"math/big"
 
 	"github.com/consensys/go-corset/pkg/schema"
 	"github.com/consensys/go-corset/pkg/util/collection/iter"
@@ -33,14 +34,22 @@ const (
 	UNUSED_REGISTER = math.MaxUint
 )
 
-// Sanity check
-var _ schema.Module = &Function[uint]{}
+// FunctionInstance represents a specific instance of a function.  That is, a
+// mapping from input values to expected output values.
+type FunctionInstance struct {
+	// Identifies corresponding function.
+	Function uint
+	// Inputs identifies the input arguments
+	Inputs map[string]big.Int
+	// Outputs identifies the outputs
+	Outputs map[string]big.Int
+}
 
 // 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.
-type Function[T any] struct {
+type Function[T Instruction[T]] struct {
 	// Unique name of this function.
 	name string
 	// Registers describes zero or more registers of a given width.  Each
@@ -51,7 +60,7 @@ type Function[T any] struct {
 }
 
 // NewFunction constructs a new function with the given components.
-func NewFunction[T any](name string, registers []Register, code []T) Function[T] {
+func NewFunction[T Instruction[T]](name string, registers []Register, code []T) Function[T] {
 	return Function[T]{name, registers, code}
 }
 
@@ -75,7 +84,9 @@ func (p *Function[T]) Code() []T {
 // Constraints provides access to those constraints associated with this
 // function.
 func (p *Function[T]) Constraints() iter.Iterator[schema.Constraint] {
-	return iter.NewArrayIterator[schema.Constraint](nil)
+	var constraint Constraint[T] = Constraint[T]{p.name, p.registers, p.code}
+	//
+	return iter.NewUnitIterator[schema.Constraint](constraint)
 }
 
 // Consistent applies a number of internal consistency checks.  Whilst not

pkg/asm/io/instruction.go

@@ -15,6 +15,8 @@ package io
 import (
 	"math"
 	"math/big"
+
+	"github.com/consensys/go-corset/pkg/schema"
 )
 
 // UNKNOWN_BUS signals a bus which is unknown.
@@ -58,10 +60,10 @@ type Instruction[T any] interface {
 	// 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 Function[T]) error
+	Validate(fieldWidth uint, fn schema.Module) error
 	// Produce a suitable string representation of this instruction.  This is
 	// primarily used for debugging.
-	String(fn Function[T]) string
+	String(fn schema.Module) string
 }
 
 // InOutInstruction is simply a kind of instruction which performs some kind of I/O

pkg/asm/io/macro/IfGoto.go

@@ -18,6 +18,7 @@ import (
 
 	"github.com/consensys/go-corset/pkg/asm/io"
 	"github.com/consensys/go-corset/pkg/asm/io/micro"
+	"github.com/consensys/go-corset/pkg/schema"
 )
 
 const (
@@ -135,7 +136,7 @@ func (p *IfGoto) RegistersWritten() []io.RegisterId {
 	return nil
 }
 
-func (p *IfGoto) String(fn io.Function[Instruction]) string {
+func (p *IfGoto) String(fn schema.Module) string {
 	var (
 		l  = fn.Register(p.Left).Name
 		r  string
@@ -169,7 +170,7 @@ func (p *IfGoto) String(fn io.Function[Instruction]) string {
 }
 
 // Validate checks whether or not this instruction is correctly balanced.
-func (p *IfGoto) Validate(fieldWidth uint, fn io.Function[Instruction]) error {
+func (p *IfGoto) Validate(fieldWidth uint, fn schema.Module) error {
 	if p.Left == p.Right {
 		switch p.Cond {
 		case EQ, LTEQ, GTEQ:

pkg/asm/io/macro/add.go

@@ -18,6 +18,7 @@ import (
 
 	"github.com/consensys/go-corset/pkg/asm/io"
 	"github.com/consensys/go-corset/pkg/asm/io/micro"
+	"github.com/consensys/go-corset/pkg/schema"
 )
 
 // Add represents a generic operation of the following form:
@@ -84,12 +85,12 @@ func (p *Add) RegistersWritten() []io.RegisterId {
 	return p.Targets
 }
 
-func (p *Add) String(fn io.Function[Instruction]) string {
+func (p *Add) String(fn schema.Module) string {
 	return assignmentToString(p.Targets, p.Sources, p.Constant, fn, zero, " + ")
 }
 
 // Validate checks whether or not this instruction is correctly balanced.
-func (p *Add) Validate(fieldWidth uint, fn io.Function[Instruction]) error {
+func (p *Add) Validate(fieldWidth uint, fn schema.Module) error {
 	var (
 		regs     = fn.Registers()
 		lhs_bits = sumTargetBits(p.Targets, regs)

pkg/asm/io/macro/call.go

@@ -18,6 +18,7 @@ import (
 
 	"github.com/consensys/go-corset/pkg/asm/io"
 	"github.com/consensys/go-corset/pkg/asm/io/micro"
+	"github.com/consensys/go-corset/pkg/schema"
 )
 
 // Call represents a function call providing one or more arguments and accepting
@@ -110,7 +111,7 @@ func (p *Call) RegistersWritten() []io.RegisterId {
 	return p.Targets
 }
 
-func (p *Call) String(fn io.Function[Instruction]) string {
+func (p *Call) String(fn schema.Module) string {
 	var (
 		builder strings.Builder
 		regs    = fn.Registers()
@@ -125,7 +126,7 @@ func (p *Call) String(fn io.Function[Instruction]) string {
 }
 
 // Validate checks whether or not this instruction well-formed.
-func (p *Call) Validate(fieldWidth uint, fn io.Function[Instruction]) error {
+func (p *Call) Validate(fieldWidth uint, fn schema.Module) error {
 	// Check bus is assigned
 	if p.bus.IsUnlinked() {
 		return fmt.Errorf("unknown function")

pkg/asm/io/macro/goto.go

@@ -17,6 +17,7 @@ import (
 
 	"github.com/consensys/go-corset/pkg/asm/io"
 	"github.com/consensys/go-corset/pkg/asm/io/micro"
+	"github.com/consensys/go-corset/pkg/schema"
 )
 
 // Goto provides an unconditional branching instruction to a given instructon.
@@ -53,11 +54,11 @@ func (p *Goto) RegistersWritten() []io.RegisterId {
 	return nil
 }
 
-func (p *Goto) String(fn io.Function[Instruction]) string {
+func (p *Goto) String(fn schema.Module) string {
 	return fmt.Sprintf("goto %d", p.Target)
 }
 
 // Validate checks whether or not this instruction is correctly balanced.
-func (p *Goto) Validate(fieldWidth uint, fn io.Function[Instruction]) error {
+func (p *Goto) Validate(fieldWidth uint, fn schema.Module) error {
 	return nil
 }

pkg/asm/io/macro/insn.go

@@ -19,6 +19,7 @@ import (
 
 	"github.com/consensys/go-corset/pkg/asm/io"
 	"github.com/consensys/go-corset/pkg/asm/io/micro"
+	"github.com/consensys/go-corset/pkg/schema"
 )
 
 // Alias for big integer representation of 0.
@@ -56,7 +57,7 @@ type IoInstruction interface {
 	Link(bus io.Bus)
 }
 
-func assignmentToString(dsts []io.RegisterId, srcs []io.RegisterId, constant big.Int, fn io.Function[Instruction],
+func assignmentToString(dsts []io.RegisterId, srcs []io.RegisterId, constant big.Int, fn schema.Module,
 	c big.Int, op string) string {
 	//
 	var (

pkg/asm/io/macro/mul.go

@@ -18,6 +18,7 @@ import (
 
 	"github.com/consensys/go-corset/pkg/asm/io"
 	"github.com/consensys/go-corset/pkg/asm/io/micro"
+	"github.com/consensys/go-corset/pkg/schema"
 )
 
 // Mul represents a generic operation of the following form:
@@ -86,12 +87,12 @@ func (p *Mul) RegistersWritten() []io.RegisterId {
 	return p.Targets
 }
 
-func (p *Mul) String(fn io.Function[Instruction]) string {
+func (p *Mul) String(fn schema.Module) string {
 	return assignmentToString(p.Targets, p.Sources, p.Constant, fn, one, " * ")
 }
 
 // Validate checks whether or not this instruction is correctly balanced.
-func (p *Mul) Validate(fieldWidth uint, fn io.Function[Instruction]) error {
+func (p *Mul) Validate(fieldWidth uint, fn schema.Module) error {
 	var (
 		regs     = fn.Registers()
 		lhs_bits = sumTargetBits(p.Targets, regs)