From 5947e4115707d513820721171439d8d6e6466943 Mon Sep 17 00:00:00 2001 From: Dr K Murphy Date: Tue, 10 Sep 2024 15:42:58 +0200 Subject: [PATCH] style update, broken link, run script and dependencies --- .gitignore | 12 +++++++++ docs/appendix/calling_conventions.md | 21 ++++++++-------- docs/appendix/canonabi-adhocabi-mismatch.md | 8 +++--- docs/appendix/known-limitations.md | 25 +++++++++---------- docs/design/frontends.md | 2 +- docs/design/overview.md | 2 +- docs/guides/develop_miden_in_rust.md | 6 ++--- ...ollup_accounts_and_note_scripts_in_rust.md | 4 +-- docs/guides/rust_to_wasm.md | 2 +- docs/guides/wasm_to_masm.md | 2 +- docs/index.md | 6 ++--- docs/usage/cargo-miden.md | 2 +- docs/usage/debugger.md | 14 +++++------ docs/usage/midenc.md | 4 +-- mkdocs.yml | 14 +++++------ requirements.txt | 3 +++ run.sh | 7 ++++++ 17 files changed, 77 insertions(+), 57 deletions(-) create mode 100644 requirements.txt create mode 100755 run.sh diff --git a/.gitignore b/.gitignore index 4beda79c0..bfe20b171 100644 --- a/.gitignore +++ b/.gitignore @@ -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 \ No newline at end of file diff --git a/docs/appendix/calling_conventions.md b/docs/appendix/calling_conventions.md index 6acc64806..04baaa175 100644 --- a/docs/appendix/calling_conventions.md +++ b/docs/appendix/calling_conventions.md @@ -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. @@ -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 -|-|-|-|-|- @@ -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: @@ -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 @@ -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 @@ -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 @@ -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 diff --git a/docs/appendix/canonabi-adhocabi-mismatch.md b/docs/appendix/canonabi-adhocabi-mismatch.md index efd207e9f..17413987a 100644 --- a/docs/appendix/canonabi-adhocabi-mismatch.md +++ b/docs/appendix/canonabi-adhocabi-mismatch.md @@ -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 @@ -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. @@ -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. @@ -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` diff --git a/docs/appendix/known-limitations.md b/docs/appendix/known-limitations.md index a9e18104e..4cd203a45 100644 --- a/docs/appendix/known-limitations.md +++ b/docs/appendix/known-limitations.md @@ -1,4 +1,4 @@ -# Known Limitations +# Known limitations !!! tip @@ -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 @@ -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) @@ -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 { @@ -64,7 +63,7 @@ pub fn is_zeroed(bytes: &[u8; 32]) -> bool { } ``` -#### Monomorphization + Inlining +#### Monomorphization + inlining ```rust pub fn call(fun: F) -> T @@ -84,7 +83,7 @@ fn main() { } ``` -#### Inlined Trait Impl +#### Inlined trait impl ```rust pub trait Foo { @@ -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) @@ -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) @@ -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) @@ -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) diff --git a/docs/design/frontends.md b/docs/design/frontends.md index 30d624bbd..e48dfbf47 100644 --- a/docs/design/frontends.md +++ b/docs/design/frontends.md @@ -1,4 +1,4 @@ -# Supported Frontends +# Supported front ends ## WebAssembly (Wasm) diff --git a/docs/design/overview.md b/docs/design/overview.md index 95fb3cbbf..fc09cffc9 100644 --- a/docs/design/overview.md +++ b/docs/design/overview.md @@ -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 diff --git a/docs/guides/develop_miden_in_rust.md b/docs/guides/develop_miden_in_rust.md index 2c2524453..118653a41 100644 --- a/docs/guides/develop_miden_in_rust.md +++ b/docs/guides/develop_miden_in_rust.md @@ -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: diff --git a/docs/guides/develop_miden_rollup_accounts_and_note_scripts_in_rust.md b/docs/guides/develop_miden_rollup_accounts_and_note_scripts_in_rust.md index e1326e890..5e2145773 100644 --- a/docs/guides/develop_miden_rollup_accounts_and_note_scripts_in_rust.md +++ b/docs/guides/develop_miden_rollup_accounts_and_note_scripts_in_rust.md @@ -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. \ No newline at end of file +This chapter walks you through how to develop Miden rollup accounts and note scripts in Rust using the Miden SDK crate. \ No newline at end of file diff --git a/docs/guides/rust_to_wasm.md b/docs/guides/rust_to_wasm.md index bafa054dc..19ce9fdb5 100644 --- a/docs/guides/rust_to_wasm.md +++ b/docs/guides/rust_to_wasm.md @@ -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`! diff --git a/docs/guides/wasm_to_masm.md b/docs/guides/wasm_to_masm.md index a7c3e998c..b9c993e57 100644 --- a/docs/guides/wasm_to_masm.md +++ b/docs/guides/wasm_to_masm.md @@ -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 diff --git a/docs/index.md b/docs/index.md index 37b52ddce..aa212383a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 @@ -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). diff --git a/docs/usage/cargo-miden.md b/docs/usage/cargo-miden.md index 18db2361e..7c5ee64f7 100644 --- a/docs/usage/cargo-miden.md +++ b/docs/usage/cargo-miden.md @@ -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 diff --git a/docs/usage/debugger.md b/docs/usage/debugger.md index 14ebf0810..f79c60d93 100644 --- a/docs/usage/debugger.md +++ b/docs/usage/debugger.md @@ -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. @@ -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 @@ -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: @@ -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: @@ -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 @@ -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: @@ -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 diff --git a/docs/usage/midenc.md b/docs/usage/midenc.md index a3530e43f..7664a39e3 100644 --- a/docs/usage/midenc.md +++ b/docs/usage/midenc.md @@ -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. @@ -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: diff --git a/mkdocs.yml b/mkdocs.yml index e6dc1b227..3509afc2a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -21,24 +21,24 @@ theme: - content.action.edit nav: - - Getting Started: index.md + - Getting started: index.md - Usage: - midenc: usage/midenc.md - cargo miden: usage/cargo-miden.md - Guides: - Rust To WebAssembly: guides/rust_to_wasm.md - WebAssembly To Miden Assembly: guides/wasm_to_masm.md - - Developing Miden Programs In Rust: guides/develop_miden_in_rust.md - - Developing Miden Rollup Accounts And Note Scripts In Rust: guides/develop_miden_rollup_accounts_and_note_scripts_in_rust.md - - Debugging Programs: usage/debugger.md - - Compiler Architecture: + - Developing Miden programs In Rust: guides/develop_miden_in_rust.md + - Developing Miden rollup accounts and note scripts In Rust: guides/develop_miden_rollup_accounts_and_note_scripts_in_rust.md + - Debugging programs: usage/debugger.md + - Compiler architecture: - Overview: design/overview.md - - Supported Frontends: design/frontends.md + - Supported front ends: design/frontends.md #- HIR: #- Code Generation: #- Testing: - Appendices: - - Calling Conventions: appendix/calling_conventions.md + - Calling conventions: appendix/calling_conventions.md - Canonical ABI vs Miden ABI: appendix/canonabi-adhocabi-mismatch.md markdown_extensions: diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 000000000..23079102b --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +mkdocs-material==9.5.33 +markdown-include==0.8.1 +mkdocs-open-in-new-tab==1.0.3 diff --git a/run.sh b/run.sh new file mode 100755 index 000000000..7ec676851 --- /dev/null +++ b/run.sh @@ -0,0 +1,7 @@ +#!/usr/bin/env bash +set -euo pipefail + +virtualenv venv +source venv/bin/activate +pip3 install -r requirements.txt +mkdocs serve --strict \ No newline at end of file