Struct FastProcessor

pub struct FastProcessor { /* private fields */ }

A fast processor which doesn’t generate any trace.

This processor is designed to be as fast as possible. Hence, it only keeps track of the current state of the processor (i.e. the stack, current clock cycle, current memory context, and free memory pointer).

Stack Management

A few key points about how the stack was designed for maximum performance:

• The stack has a fixed buffer size defined by STACK_BUFFER_SIZE.
  • This was observed to increase performance by at least 2x compared to using a Vec with push() & pop().
  • We track the stack top and bottom using indices stack_top_idx and stack_bot_idx, respectively.
• Since we are using a fixed-size buffer, we need to ensure that stack buffer accesses are not out of bounds. Naively, we could check for this on every access. However, every operation alters the stack depth by a predetermined amount, allowing us to precisely determine the minimum number of operations required to reach a stack buffer boundary, whether at the top or bottom.
  • For example, if the stack top is 10 elements away from the top boundary, and the stack bottom is 15 elements away from the bottom boundary, then we can safely execute 10 operations that modify the stack depth with no bounds check.
• When switching contexts (e.g., during a call or syscall), all elements past the first 16 are stored in an ExecutionContextInfo struct, and the stack is truncated to 16 elements. This will be restored when returning from the call or syscall.

Clock Cycle Management

• The clock cycle (clk) is managed in the same way as in Process. That is, it is incremented by 1 for every row that Process adds to the main trace.
  • It is important to do so because the clock cycle is used to determine the context ID for new execution contexts when using call or dyncall.
• When executing a basic block, the clock cycle is not incremented for every individual operation for performance reasons.
  • Rather, we use clk + operation_index to determine the clock cycle when needed.
  • However this performance improvement is slightly offset by the need to parse operation batches exactly the same as Process. We will be able to recover the performance loss by redesigning the BasicBlockNode.

Implementations

impl FastProcessor

pub fn arithmetic_circuit_eval( &mut self, op_idx: usize, ) -> Result<(), ExecutionError>

Checks that the evaluation of an arithmetic circuit is equal to zero.

The inputs are composed of:

1. a pointer to the memory region containing the arithmetic circuit description, which itself is arranged as:

   a. Read section:

   1. Inputs to the circuit which are elements in the quadratic extension field,
   2. Constants of the circuit which are elements in the quadratic extension field,

   b. Eval section, which contains the encodings of the evaluation gates of the circuit. Each gate is encoded as a single base field element.

2. the number of rows in the READ section,

3. the number of rows in the EVAL section,

Stack transition: [ptr, num_read_rows, num_eval_rows, …] -> [ptr, num_read_rows, num_eval_rows, …]

impl FastProcessor

pub fn op_hperm(&mut self)

Applies a permutation of the Rpo256 hash function to the top 12 elements of the stack.

Analogous to Process::op_hperm.

pub fn op_mpverify( &mut self, err_code: Felt, host: &mut impl Host, program: &MastForest, ) -> Result<(), ExecutionError>

Analogous to Process::op_mpverify.

pub fn op_mrupdate( &mut self, host: &mut impl Host, ) -> Result<(), ExecutionError>

Analogous to Process::op_mrupdate.

impl FastProcessor

pub fn op_add(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_add.

pub fn op_neg(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_neg.

pub fn op_mul(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_mul.

pub fn op_inv(&mut self, op_idx: usize) -> Result<(), ExecutionError>

Analogous to Process::op_inv.

pub fn op_incr(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_inc.

pub fn op_and(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_and.

pub fn op_or(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_or.

pub fn op_not(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_not.

pub fn op_eq(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_eq.

pub fn op_eqz(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_eqz.

pub fn op_expacc(&mut self)

Analogous to Process::op_expacc.

pub fn op_ext2mul(&mut self)

Analogous to Process::op_ext2mul.

Gets the top four values from the stack [b1, b0, a1, a0], where a = (a1, a0) and b = (b1, b0) are elements of the extension field, and outputs the product c = (c1, c0) where c0 = b0 * a0 - 2 * b1 * a1 and c1 = (b0 + b1) * (a1 + a0) - b0 * a0. It pushes 0 to the first and second positions on the stack, c1 and c2 to the third and fourth positions, and leaves the rest of the stack unchanged.

impl FastProcessor

pub fn op_fri_ext2fold4(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_fri_ext2fold4.

impl FastProcessor

pub fn op_horner_eval_base( &mut self, op_idx: usize, ) -> Result<(), ExecutionError>

Analogous to Process::op_horner_eval_base.

pub fn op_horner_eval_ext( &mut self, op_idx: usize, ) -> Result<(), ExecutionError>

Analogous to Process::op_horner_eval_ext.

impl FastProcessor

pub fn op_push(&mut self, element: Felt)

Analogous to Process::op_push.

pub fn op_advpop( &mut self, op_idx: usize, host: &mut impl Host, ) -> Result<(), ExecutionError>

Analogous to Process::op_advpop.

pub fn op_advpopw( &mut self, op_idx: usize, host: &mut impl Host, ) -> Result<(), ExecutionError>

Analogous to Process::op_advpopw.

pub fn op_mloadw(&mut self, op_idx: usize) -> Result<(), ExecutionError>

Analogous to Process::op_mloadw.

pub fn op_mstorew(&mut self, op_idx: usize) -> Result<(), ExecutionError>

Analogous to Process::op_mstorew.

pub fn op_mload(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_mload.

pub fn op_mstore(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_mstore.

pub fn op_mstream(&mut self, op_idx: usize) -> Result<(), ExecutionError>

Analogous to Process::op_mstream.

pub fn op_pipe( &mut self, op_idx: usize, host: &mut impl Host, ) -> Result<(), ExecutionError>

Analogous to Process::op_pipe.

impl FastProcessor

pub fn op_pad(&mut self)

Analogous to Process::op_pad.

pub fn op_swap(&mut self)

Analogous to Process::op_swap.

pub fn op_swap_double_word(&mut self)

Analogous to Process::op_swapdw.

pub fn rotate_left(&mut self, n: usize)

Rotates the top n elements of the stack to the left by 1.

For example, if the stack is [a, b, c, d], with d at the top, then rotate_left(3) will result in the top 3 elements being rotated left: [a, c, d, b].

This operation is useful for implementing the movup instructions.

The stack size doesn’t change.

Note: This method doesn’t use the stack_get() and stack_write() methods because it is more efficient to directly manipulate the stack array (~10% performance difference).

pub fn rotate_right(&mut self, n: usize)

Rotates the top n elements of the stack to the right by 1.

Analogous to rotate_left, but in the opposite direction.

Note: This method doesn’t use the stack_get() and stack_write() methods because it is more efficient to directly manipulate the stack array (~10% performance difference).

pub fn dup_nth(&mut self, n: usize)

Duplicates the n’th element from the top of the stack to the top of the stack.

The size of the stack is incremented by 1.

pub fn swapw_nth(&mut self, n: usize)

Swaps the nth word from the top of the stack with the top word of the stack.

Valid values of n are 1, 2, and 3.

pub fn op_cswap(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_cswap.

pub fn op_cswapw(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_cswapw.

impl FastProcessor

pub fn op_assert( &mut self, err_code: Felt, op_idx: usize, host: &mut impl Host, program: &MastForest, ) -> Result<(), ExecutionError>

Analogous to Process::op_assert.

pub fn op_fmpadd(&mut self)

Analogous to Process::op_fmpadd.

pub fn op_fmpupdate(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_fmpupdate.

pub fn op_sdepth(&mut self)

Analogous to Process::op_sdepth.

pub fn op_caller(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_caller.

pub fn op_clk(&mut self, op_idx: usize) -> Result<(), ExecutionError>

Analogous to Process::op_clk.

pub fn op_emit( &mut self, event_id: u32, op_idx: usize, host: &mut impl Host, ) -> Result<(), ExecutionError>

Analogous to Process::op_emit.

impl FastProcessor

pub fn op_u32split(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_u32split.

pub fn op_u32add(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_u32add.

pub fn op_u32add3(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_u32add3.

Pops three elements off the stack, adds them, splits the result into low and high 32-bit values, and pushes these values back onto the stack.

The size of the stack is decremented by 1.

pub fn op_u32sub(&mut self, op_idx: usize) -> Result<(), ExecutionError>

Analogous to Process::op_u32sub.

pub fn op_u32mul(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_u32mul.

pub fn op_u32madd(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_u32madd.

Pops three elements off the stack, multiplies the first two and adds the third element to the result, splits the result into low and high 32-bit values, and pushes these values back onto the stack.

pub fn op_u32div(&mut self, op_idx: usize) -> Result<(), ExecutionError>

Analogous to Process::op_u32div.

pub fn op_u32and(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_u32and.

pub fn op_u32xor(&mut self) -> Result<(), ExecutionError>

Analogous to Process::op_u32xor.

pub fn op_u32assert2(&mut self, err_code: Felt) -> Result<(), ExecutionError>

Analogous to Process::op_u32assert2.

impl FastProcessor

pub fn new(stack_inputs: &[Felt]) -> Self

Creates a new FastProcessor instance with the given stack inputs.

The stack inputs are expected to be stored in reverse order. For example, if stack_inputs = [1,2,3], then the stack will be initialized as [3,2,1,0,0,...], with 3 being on top.

Panics

• Panics if the length of stack_inputs is greater than MIN_STACK_DEPTH.

pub fn new_debug(stack_inputs: &[Felt]) -> Self

Creates a new FastProcessor instance with the given stack inputs, set to debug mode.

The stack inputs are expected to be stored in reverse order. For example, if stack_inputs = [1,2,3], then the stack will be initialized as [3,2,1,0,0,...], with 3 being on top.

Panics

• Panics if the length of stack_inputs is greater than MIN_STACK_DEPTH.

pub fn stack(&self) -> &[Felt]

Returns the stack, such that the top of the stack is at the last index of the returned slice.

pub fn stack_get(&self, idx: usize) -> Felt

Returns the element on the stack at index idx.

pub fn stack_get_mut(&mut self, idx: usize) -> &mut Felt

Mutable variant of stack_get().

pub fn stack_get_word(&self, start_idx: usize) -> Word

Returns the word on the stack starting at index start_idx in “stack order”.

That is, for start_idx=0 the top element of the stack will be at the last position in the word.

For example, if the stack looks like this:

top bottom v v a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p

Then

• stack_get_word(0) returns [d, c, b, a],
• stack_get_word(1) returns [e, d, c ,b],
• etc.

pub fn stack_depth(&self) -> u32

Returns the number of elements on the stack in the current context.

pub fn stack_write(&mut self, idx: usize, element: Felt)

Writes an element to the stack at the given index.

pub fn stack_write_word(&mut self, start_idx: usize, word: &Word)

Writes a word to the stack starting at the given index.

The index is the index of the first element of the word, and the word is written in reverse order.

pub fn stack_swap(&mut self, idx1: usize, idx2: usize)

Swaps the elements at the given indices on the stack.

pub fn execute( self, program: &Program, host: &mut impl Host, ) -> Result<StackOutputs, ExecutionError>

Executes the given program and returns the stack outputs.

Trait Implementations

impl Debug for FastProcessor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.