assembly

Miden Assembly

This crate contains Miden assembler.

The purpose of the assembler is to compile/assemble Miden Assembly (MASM) source code into a Miden VM program (represented by Program struct). The program can then be executed on Miden VM processor.

Compiling Miden Assembly

To assemble a program for the Miden VM from some Miden Assembly source code, you first need to instantiate the assembler, and then call one of its provided assembly methods, e.g. assemble.

The assemble method takes the source code of an executable module as a string, or file path, and either compiles it to a Program, or returns an error if the program is invalid in some way. The error type returned can be pretty-printed to show rich diagnostics about the source code from which an error is derived, when applicable, much like the Rust compiler.

Example

use std::path::Path;
use miden_assembly::Assembler;

// Instantiate a default, empty assembler
let assembler = Assembler::default();

// Emit a program which pushes values 3 and 5 onto the stack and adds them
let program = assembler.assemble_program("begin push.3 push.5 add end").unwrap();

// Emit a program from some source code on disk (requires the `std` feature)
let program = assembler.assemble_program(&Path::new("./example.masm")).unwrap();

Note

The default assembler provides no kernel or standard libraries, you must explicitly add those using the various builder methods of Assembler, as described in the next section.

Assembler Options

As noted above, the default assembler is instantiated with nothing in it but the source code you provide. If you want to support more complex programs, you will want to factor code into libraries and modules, and then link all of them together at once. This can be acheived using a set of builder methods of the Assembler struct, e.g. with_kernel_from_module, with_library, etc.

We'll look at a few of these in more detail below. See the module documentation for the full set of APIs and how to use them.

Libraries

The first use case that you are likely to encounter is the desire to factor out some shared code into a library. A library is a set of modules which belong to a common namespace, and which are packaged together. The standard library is an example of this.

To call code in this library from your program entrypoint, you must add the library to the instance of the assembler you will compile the program with, using the with_library or with_libraries methods.

To be a bit more precise, a library can be anything that implements the Library trait, allowing for some flexibility in how they are managed. The standard library referenced above implements this trait, so if we wanted to make use of the Miden standard library in our own program, we would add it like so:

use miden_assembly::Assembler;

let assembler = Assembler::default()
    .with_library(&miden_stdlib::StdLibrary::default())
    .unwrap();

The resulting assembler can now compile code that invokes any of the standard library procedures by importing them from the namespace of the library, as shown next:

use.std::math::u64

begin
    push.1.0
    push.2.0
    exec.u64::wrapping_add
end

A generic container format for libraries, which implements Library and can be used for any set of Miden assembly modules belonging to the same namespace, is provided by the MaslLibrary struct.

A MaslLibrary serializes/deserializes to the .masl file format, which is a binary format containing the parsed, but uncompiled, Miden Assembly code in the form of its abstract syntax tree. You can construct and load .masl files using the MaslLibrary interface.

Program Kernels

A program kernel defines a set of procedures which can be invoked via syscall instructions. Miden programs are always compiled against some kernel, and by default this kernel is empty, and so no syscall instructions are allowed.

You can provide a kernel in one of two ways: a precompiled Kernel struct, or by compiling a kernel module from source, as shown below:

use miden_assembly::Assembler;

let assembler = Assembler::default()
    .with_kernel_from_module("export.foo add end")
    .unwrap();

Programs compiled by this assembler will be able to make calls to the foo procedure by executing the syscall instruction, like so:

assembler.assemble_program("
begin
    syscall.foo
end
").unwrap();

Note

An unqualified syscall target is assumed to be defined in the kernel module. This is unlike the exec and call instructions, which require that callees resolve to a local procedure; a procedure defined in an explicitly imported module; or the hash of a MAST root corresponding to the compiled procedure.

These options are also available to syscall, with the caveat that whatever method is used, it must resolve to a procedure in the kernel specified to the assembler, or compilation will fail with an error.

Debug Mode

The assembler can be instantiated in debug mode. Compiling a program with such an assembler retains source mappings between assembly instructions and VM operations. Thus, when such a program is executed using the execute_iter() function of the processor, it is possible to correlate each instruction with the source code that it is derived from. You can do this as shown below:

use miden_assembly::Assembler;

// Instantiate the assembler in debug mode
let assembler = Assembler::default().with_debug_mode(true);

Putting it all together

To help illustrate how all of the topics we discussed above can be combined together, let's look at one last example:

use miden_assembly::Assembler;
use miden_stdlib::StdLibrary;

// Source code of the kernel module
let kernel = "export.foo add end";

// Instantiate the assembler with multiple options at once
let assembler = Assembler::default()
    .with_debug_mode(true)
    .with_library(&StdLibrary::default())
    .and_then(|a| a.with_kernel_from_module(kernel))
    .unwrap();

// Assemble our program
assembler.assemble_program("
begin
    push.1.2
    syscall.foo
end
");

License

This project is MIT licensed.