Skip to content

Commit

Permalink
style update, broken link, run script and dependencies
Browse files Browse the repository at this point in the history
  • Loading branch information
kmurphypolygon committed Sep 10, 2024
1 parent a48d095 commit 5947e41
Show file tree
Hide file tree
Showing 17 changed files with 77 additions and 57 deletions.
12 changes: 12 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,15 @@ bin/midenc
bin/litcheck
.crates.toml
.crates2.json

# Docs platform ignores
.vscode
.code
.idea
site/
venv/
env/
*.out
node_modules/
*DS_Store
*.iml
21 changes: 10 additions & 11 deletions docs/appendix/calling_conventions.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Calling Conventions
# Calling conventions

This document describes the various calling conventions recognized/handled by the compiler,
including a specification for the interaction with the IR type system.
Expand All @@ -25,17 +25,16 @@ There are four calling conventions represented in the compiler:
convention is allowed to have types in its signature that are/contain pointers, with certain caveats around
those pointers.


All four conventions above are based on the System V C ABI, tailored to the Miden VM. The only exception is
`Fast`, which may modify the ABI arbitrarily as it sees fit, and makes no guarantees about what modifications,
if any, it will make.

# Data Representation
## Data representation

The following is a description of how the IR type system is represented in the `C` calling convention. Later,
a description of how the other conventions extend/restrict/modify this representation will be provided.

## Scalars
### Scalars

General type | C Type | IR Type | `sizeof` | Alignment (bytes) | Miden Type
-|-|-|-|-|-
Expand Down Expand Up @@ -101,14 +100,14 @@ two's complement rules.
The Miden VM only has native support for field elements, words, and `u32`; all other types are implemented in software
using intrinsics.

## Aggregates and Unions
### Aggregates and unions

Structures and unions assume the alignment of their most strictly aligned component. Each member is assigned to the
lowest available offset with the appropriate alignment. The size of any object is always a multiple of the object's alignment.
An array uses the same alignment as its elements. Structure and union objects can require padding to meet size and alignment
constraints. The contents of any padding is undefined.

## Memory Model
### Memory model

Interacting with memory in Miden is quite similar to WebAssembly in some ways:

Expand Down Expand Up @@ -176,12 +175,12 @@ word-aligned or element-aligned, so an unaligned load or store would require eit
bytes starting at some arbitrary address. In practice, most loads/stores are likely to be element-aligned, so most overhead from
emulation will come from values which cross an element or word boundary.

# Function Calls
## Function calls

This section describes the conventions followed when executing a function call via `exec`, including how arguments are passed on the
operand stack, stack frames, etc. Later, we'll cover the differences when executing calls via `call` or `syscall`.

## Locals and the stack frame
### Locals and the stack frame

Miden does not have registers in the style of hardware architectures. Instead it has an operand stack, on which an arbitrary number of
operands may be stored, and local variables. In both cases - an operand on the operand stack, or a single local variable - the value
Expand All @@ -201,7 +200,7 @@ Because there are no registers, the notion of callee-saved or caller-saved regis
in its place, a somewhat equivalent set of rules defines the contract between caller and callee in terms of the state of the operand stack,
those are described below in the section covering the operand stack.

### The shadow stack
#### The shadow stack

Miden is a [Harvard](https://en.wikipedia.org/wiki/Harvard_architecture) architecture; as such, code and data are not in the same memory
space. More precisely, in Miden, code is only addressable via the hash of the MAST root of that code, which must correspond to code that
Expand All @@ -222,7 +221,7 @@ constraints of the callee's calling convention).
Languages with more elaborate requirements with regard to the stack will need to implement their own shadow stack, and emit code in function
prologues/epilogues to manage it.

### The operand stack
#### The operand stack

The Miden virtual machine is a stack machine, not a register machine. Rather than having a fixed set of registers that are used to
store and manipulate scalar values, the Miden VM has the operand stack, which can hold an arbitrary number of operands (where each
Expand All @@ -246,7 +245,7 @@ then one of the following must happen:
which refers to the remaining arguments on the advice provider stack. The callee must arrange to fetch the spilled arguments from the advice
provider using that hash.

### Function signatures
#### Function signatures

Miden Abstract Syntax Trees (MASTs) do not have any notion of functions, and as such are not aware of parameters, return values, etc. For
this document, that's not a useful level of abstraction to examine. Even a step higher, Miden Assembly (MASM) has functions (procedures
Expand Down
8 changes: 4 additions & 4 deletions docs/appendix/canonabi-adhocabi-mismatch.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Canonical ABI vs Miden ABI Incompatibility
# Canonical ABI vs Miden ABI incompatibility

This document describes an issue that arises when trying to map the ad-hoc calling convention/ABI
used by various Miden Assembly procedures, such as those comprising the transaction kernel, and
Expand Down Expand Up @@ -140,7 +140,7 @@ library is a part of the Miden compiler. It is not anticipated that we will have
these; however in the near term we are going to manually map procedures to their adapter strategies,
as we have not yet automated the pattern recognition step.

### Return-via-pointer Adapter
### Return-via-pointer adapter

The return value is expected to be returned by storing its flattened representation in a pointer
passed as an argument.
Expand Down Expand Up @@ -174,7 +174,7 @@ func wasm_core_add_asset(v0: f64, v1: f64, v2: f64, v3: f64, ptr: i32) {
}
```

### No-op Adapter
### No-op adapter

No adapter is needed. The Wasm core function type is the same as the tx kernel ad-hoc signature.

Expand All @@ -183,7 +183,7 @@ This Miden ABI pattern is selected if no other Miden ABI pattern is applicable a
For example, the `get_id` function falls under this Miden ABI pattern and its calls will be translated to the tx kernel function calls without any modifications.


## Transaction kernel functions that require manual adapter functions:
## Transaction kernel functions that require manual adapter functions

### `get_assets`

Expand Down
25 changes: 12 additions & 13 deletions docs/appendix/known-limitations.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Known Limitations
# Known limitations

!!! tip

Expand All @@ -13,9 +13,9 @@ important to be aware of this when using the compiler.
The features discussed below are broken up into sections, to make them easier to navigate and
reference.

## Rust Language Support
## Rust language support

### Floating Point Types
### Floating point types

- Status: **Unsupported**
- Tracking Issue: N/A
Expand All @@ -34,8 +34,7 @@ first place.
At this point in time, we have no plans to support floats, but this may change if we are able to
find a better/more natural representation for `Felt` in WebAssembly.


### Function Call Indirection
### Function call indirection

- Status: **Unimplemented**
- Tracking Issue: [#32](https://github.com/0xPolygonMiden/compiler/issues/32)
Expand All @@ -55,7 +54,7 @@ will raise an error when it encounters any use of `call_indirect`.
the amount of inlining that can occur. Even then, it may not be possible to remove some forms of
indirection, in which case you will need to find another workaround.

#### Iterator Lowered to Loop
#### Iterator lowered to loop

```rust
pub fn is_zeroed(bytes: &[u8; 32]) -> bool {
Expand All @@ -64,7 +63,7 @@ pub fn is_zeroed(bytes: &[u8; 32]) -> bool {
}
```

#### Monomorphization + Inlining
#### Monomorphization + inlining

```rust
pub fn call<F, T>(fun: F) -> T
Expand All @@ -84,7 +83,7 @@ fn main() {
}
```

#### Inlined Trait Impl
#### Inlined trait impl

```rust
pub trait Foo {
Expand Down Expand Up @@ -124,7 +123,7 @@ will be expanding the SDK rapidly over the next few weeks and months, but for th
you encounter a missing API that you need, let us know, so we can ensure it is prioritized above
APIs which are lesser used.

### Rust/Miden FFI (Foreign Function Interface) and Interop
### Rust/Miden FFI (foreign function interface) and interop

- Status: **Internal Use Only**
- Tracking Issue: [#304](https://github.com/0xPolygonMiden/compiler/issues/304)
Expand All @@ -148,9 +147,9 @@ procedures at a minimum, and in some cases we may require details of the calling
This metadata does not currently exist, but is on the roadmap for inclusion into Miden Assembly
and Miden packaging. Once present, we can open up the FFI for general use.

## Core Miden Functionality
## Core Miden functionality

### Dynamic Procedure Invocation
### Dynamic procedure invocation

- Status: **Unimplemented**
- Tracking Issue: [#32](https://github.com/0xPolygonMiden/compiler/issues/32)
Expand All @@ -175,7 +174,7 @@ the body of which drop the callee hash, fix up the operand stack as necessary, a
simple `exec` or `call` to invoke the "real" callee. We will emit a single stub for every function
which has its "address" taken, and use the hash of the stub in place of the actual callee hash.

### Cross-Context Procedure Invocation
### Cross-context procedure invocation

- Status: **Unimplemented**
- Tracking Issue: [#303](https://github.com/0xPolygonMiden/compiler/issues/303)
Expand Down Expand Up @@ -213,7 +212,7 @@ subfeatures being implemented first.

## Packaging

### Package Format
### Package format

- Status: **Experimental**
- Tracking Issue: [#121](https://github.com/0xPolygonMiden/compiler/issues/121)
Expand Down
2 changes: 1 addition & 1 deletion docs/design/frontends.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Supported Frontends
# Supported front ends

## WebAssembly (Wasm)

Expand Down
2 changes: 1 addition & 1 deletion docs/design/overview.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Compiler Architecture
# Compiler architecture

This is an index of various design documents for the compiler and its components. Some of these
are planned topics, and some have documentation that hasn't been polished up yet. We'll slowly
Expand Down
6 changes: 3 additions & 3 deletions docs/guides/develop_miden_in_rust.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Developing Miden Programs In Rust
# Developing Miden programs in Rust

This chapter will walk through how to develop Miden programs in Rust using the standard library
provided by the `miden-stdlib-sys` crate (see the
[README](https://github.com/0xPolygonMiden/compiler/sdk/stdlib-sys/README.md)).
[README](https://github.com/0xPolygonMiden/compiler/blob/main/sdk/stdlib-sys/README.md).

## Getting Started
## Getting started

Import the standard library from the `miden-stdlib-sys` crate:

Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
# Developing Miden Rollup Accounts And Note Scripts In Rust
# Developing Miden rollup accounts and note scripts in Rust

This chapter will walk through how to develop Miden rollup accounts and note scripts in Rust using the Miden SDK crate.
This chapter walks you through how to develop Miden rollup accounts and note scripts in Rust using the Miden SDK crate.
2 changes: 1 addition & 1 deletion docs/guides/rust_to_wasm.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@ Which dumps the following output (may differ slightly on your machine, depending

Success!

## Next Steps
## Next steps

In [Compiling WebAssembly to Miden Assembly](wasm_to_masm.md), we walk through how to take the
WebAssembly module we just compiled, and lower it to Miden Assembly using `midenc`!
2 changes: 1 addition & 1 deletion docs/guides/wasm_to_masm.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ We can test our compiled program like so:

Success! We got the expected result of `55`.

## Next Steps
## Next steps

This guide is not comprehensive, as we have not yet examined in detail the differences between
compiling libraries vs programs, linking together multiple libraries, packages, or discussed some of
Expand Down
6 changes: 3 additions & 3 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Getting Started
# Getting started

Welcome to the documentation for the Miden compiler toolchain!
Welcome to the documentation for the Miden compiler toolchain.

!!! warning

Expand Down Expand Up @@ -78,7 +78,7 @@ We do not currently perform any optimizations on the IR, since we are primarily
output of compiler backends which have already applied optimizations, at this time. This may change
in the future, but for now it is expected that you implement your own optimization passes as needed.

## Known Bugs and Limitations
## Known bugs and limitations

For the latest information on known bugs, see the [issue tracker](https://github.com/0xpolygonmiden/compiler/issues).

Expand Down
2 changes: 1 addition & 1 deletion docs/usage/cargo-miden.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Getting Started with Cargo
# Getting started with Cargo

As part of the Miden compiler toolchain, we provide a Cargo extension, `cargo-miden`, which provides
a template to spin up a new Miden project in Rust, and takes care of orchestrating `rustc` and
Expand Down
14 changes: 7 additions & 7 deletions docs/usage/debugger.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Debugging Programs
# Debugging programs

A very useful tool in the Miden compiler suite, is its TUI-based interactive debugger, accessible
via the `midenc debug` command.
Expand All @@ -8,7 +8,7 @@ via the `midenc debug` command.
The debugger is still quite new, and while very useful already, still has a fair number of
UX annoyances. Please report any bugs you encounter, and we'll try to get them patched ASAP!

## Getting Started
## Getting started

The debugger is launched by executing `midenc debug`, and giving it a path to a program compiled
by `midenc compile`. See [Program Inputs](#program-inputs) for information on how to provide inputs
Expand All @@ -26,7 +26,7 @@ midenc compile foo.wasm -o foo.masl
midenc debug foo.masl
```

## Program Inputs
## Program inputs

To pass arguments to the program on the operand stack, or via the advice provider, you have two
options, depending on the needs of the program:
Expand All @@ -35,7 +35,7 @@ options, depending on the needs of the program:
is, the first argument you specify will be on top of the stack, and so on.
2. Specify a configuration file from which to load inputs for the program, via the `--inputs` option.

### Via Command Line
### Via command line

To specify the contents of the operand stack, you can do so following the raw arguments separator `--`.
Each operand must be a valid field element value, in either decimal or hexadecimal format. For example:
Expand All @@ -48,7 +48,7 @@ If you pass arguments via the command line in conjunction with `--inputs`, then
will be used instead of the contents of the `inputs.stack` option (if set). This lets you specify a baseline
set of inputs, and then try out different arguments using the command line.

### Via Inputs Config
### Via inputs config

While simply passing operands to the `midenc debug` command is useful, it only allows you to specify
inputs to be passed via operand stack. To provide inputs via the advice provider, you will need to use
Expand Down Expand Up @@ -103,7 +103,7 @@ one you get dropped into when the debugger starts. The home page contains the fo
* Breakpoints - displays the set of current breakpoints, along with how many were hit
at the current instruction, when relevant

### Keyboard Shortcuts
### Keyboard shortcuts

On the home page, the following keyboard shortcuts are available:

Expand Down Expand Up @@ -177,7 +177,7 @@ After a breakpoint is hit, it expires if it is one of the following types:

When a breakpoint expires, it is removed from the breakpoint list on the next cycle.

## Reading Memory
## Reading memory

Another useful diagnostic task is examining the contents of linear memory, to verify that expected
data has been written. You can do this via the command prompt, using `r` (or `read`), followed by
Expand Down
4 changes: 2 additions & 2 deletions docs/usage/midenc.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Getting Started with `midenc`
# Getting started with `midenc`

The `midenc` executable is the command-line interface for the compiler driver, as well as other
helpful tools, such as the interactive debugger.
Expand Down Expand Up @@ -110,7 +110,7 @@ than the default path that would have been used (`target/miden/foo.masp`).

See [Debugging Programs](debugger.md) for details on using `midenc debug` to debug Miden programs.

## Next Steps
## Next steps

We have put together two useful guides to walk through more detail on compiling Rust to WebAssembly:

Expand Down
Loading

0 comments on commit 5947e41

Please sign in to comment.