Skip to content

Commit

Permalink
feat(book): Custom backend, kona-executor extensions, and FPVM back…
Browse files Browse the repository at this point in the history
…end (#552)

* feat(book): Custom backend, `kona-executor` extensions, and FPVM backend

* updates

* README

rm telegram ref
  • Loading branch information
clabby authored Sep 23, 2024
1 parent 56935c7 commit 7f744d1
Show file tree
Hide file tree
Showing 14 changed files with 895 additions and 91 deletions.
11 changes: 11 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,16 @@ the block execution logic.
Built on top of these libraries, this repository also features a [fault proof program][fpp-specs] designed to deterministically execute the
rollup state transition in order to verify an [L2 output root][g-output-root] from the L1 inputs it was [derived from][g-derivation-pipeline].

### Alternative Backends

Kona's libraries were built with alternative backend support and extensibility in mind - it is not just a fault proof
program! Kona is also used by:

- [`op-succinct`][op-succinct]

To build your own backend for kona, or build a new application on top of its libraries,
see the [SDK section of the book](https://anton-rs.github.io/kona/sdk/intro.html).

### Development Status

`kona` is currently in active development, and is not yet ready for use in production.
Expand Down Expand Up @@ -70,6 +80,7 @@ The [book][book] contains a more in-depth overview of the project, contributor g
[asterisc]: https://github.com/etheruem-optimism/asterisc
[fpp-specs]: https://specs.optimism.io/experimental/fault-proof/index.html
[book]: https://anton-rs.github.io/kona/
[op-succinct]: https://github.com/succinctlabs/op-succinct
[op-labs]: https://github.com/ethereum-optimism
[bad-boi-labs]: https://github.com/BadBoiLabs
[g-output-root]: https://specs.optimism.io/glossary.html#l2-output-root
Expand Down
5 changes: 5 additions & 0 deletions book/book.toml
Original file line number Diff line number Diff line change
Expand Up @@ -11,4 +11,9 @@ command = "mdbook-mermaid"
[preprocessor.template]

[output.html]
default-theme = "ferra"
preferred-dark-theme = "ferra"
git-repository-url = "https://github.com/anton-rs/kona"
edit-url-template = "https://github.com/anton-rs/kona/edit/main/book/{path}"
additional-css = ["custom.css"]
additional-js = ["mermaid.min.js", "mermaid-init.js"]
141 changes: 141 additions & 0 deletions book/custom.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
table {
width: 100%;
}

table thead th {
padding: .75rem;
text-align: left;
font-weight: 500;
line-height: 1.5;
width: auto;
}

table td {
padding: .75rem;
border: none;
}

table thead tr {
border: none;
border-bottom: 2px var(--table-border-color) solid;
}

table tbody tr {
border-bottom: 1px var(--table-border-line) solid;
}

table tbody tr:nth-child(2n) {
background: unset;
}

.content h1,
.content h2,
.content h3,
.content h4 {
font-weight: 600;
margin-top: 1.275em;
margin-bottom: .875em;
}

.ferra {
--bg: #2b292d;
--fg: #fecdb2;
--heading-fg: #fff;

--sidebar-bg: #383539;
--sidebar-fg: #fecdb2;
--sidebar-non-existant: #feceb454;
--sidebar-active: #ffa07a;
--scrollbar: var(--sidebar-fg);

--icons: #f6b6c9ba;
--icons-hover: #b7b9cc;

--links: #ffa07a;

--inline-code-color: #f6b6c9ba;

--theme-popup-bg: #383539;
--theme-popup-border: #5f5a60;
--theme-hover: rgba(0, 0, 0, .2);

--quote-bg: #222124;
--quote-border: #2b292d;

--table-border-color: #383539;
--table-header-bg: hsla(226, 23%, 31%, 0);
--table-alternate-bg: hsl(226, 23%, 14%);
--table-border-line: #383539;

--searchbar-border-color: #222124;
--searchbar-bg: #222124;
--searchbar-fg: #fecdb2;
--searchbar-shadow-color: #aaa;
--searchresults-header-fg: #fce2d4;
--searchresults-border-color: #feceb454;
--search-mark-bg: #f6b6c9ba;

}

.ferra .content .header {
color: #fce2d4;
}

/* highlight.js theme, :where() is used to avoid increasing specificity */

:where(.ferra) .hljs {
background: #222124;
color: #feceb4e1;
}

:where(.ferra) .hljs-comment,
:where(.ferra) .hljs-quote {
color: #6F5D63;
}

:where(.ferra) .hljs-link,
:where(.ferra) .hljs-meta,
:where(.ferra) .hljs-name,
:where(.ferra) .hljs-regexp,
:where(.ferra) .hljs-selector-class,
:where(.ferra) .hljs-selector-id,
:where(.ferra) .hljs-tag,
:where(.ferra) .hljs-template-variable,
:where(.ferra) .hljs-variable {
color: #fecdb2;
}

:where(.ferra) .hljs-built_in,
:where(.ferra) .hljs-deletion,
:where(.ferra) .hljs-literal,
:where(.ferra) .hljs-number,
:where(.ferra) .hljs-params,
:where(.ferra) .hljs-type {
color: #f6b6c9;
}

:where(.ferra) .hljs-attribute,
:where(.ferra) .hljs-section,
:where(.ferra) .hljs-title {
color: #ffa07a;
}

:where(.ferra) .hljs-addition,
:where(.ferra) .hljs-bullet,
:where(.ferra) .hljs-string,
:where(.ferra) .hljs-symbol {
color: #b1b695;
}

:where(.ferra) .hljs-keyword,
:where(.ferra) .hljs-selector-tag {
color: #d1d1e0;
}

:where(.ferra) .hljs-emphasis {
font-style: italic;
}

:where(.ferra) .hljs-strong {
font-weight: 700;
}
2 changes: 1 addition & 1 deletion book/src/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Contributing

Thank you for wanting to contribute! Before contributing to this repository, please read through this document and
discuss the change you wish to make via issue or in the development telegram.
discuss the change you wish to make via issue.

## Dependencies

Expand Down
4 changes: 4 additions & 0 deletions book/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,9 @@
- [Prologue](./fpp-dev/prologue.md)
- [Execution](./fpp-dev/execution.md)
- [Epilogue](./fpp-dev/epilogue.md)
- [Kona SDK](./sdk/intro.md)
- [FPVM Backend](./sdk/fpvm-backend.md)
- [Custom Backend](./sdk/custom-backend.md)
- [`kona-executor` Extensions](./sdk/exec-ext.md)
- [Glossary](./glossary.md)
- [Contributing](./CONTRIBUTING.md)
2 changes: 1 addition & 1 deletion book/src/fpp-dev/env.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,9 @@ when the `host` is the native implementation of the FPVM.
```mermaid
sequenceDiagram
Client->>+Host: Hint preimage (no-op on-chain / read-only mode)
Host-->>Host: Prepare Preimage
Host-->>-Client: Hint acknowledgement
Client-->>+Host: Preimage Request
Host-->>Host: Prepare Preimage
Host-->>-Client: Preimage Data
```

Expand Down
103 changes: 15 additions & 88 deletions book/src/fpp-dev/targets.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,95 +3,13 @@
Kona seeks to support all FPVM targets that LLVM and `rustc` can offer introductory support for. Below is a matrix of features that Kona offers
for each FPVM target:

| Target | Build Pipeline | IO | malloc | Program Stages |
| ---------------------- | -------------- | --- | ------ | -------------- |
| `cannon` & `cannon-rs` |||||
| `asterisc` |||||
| Target | Build Pipeline | IO | malloc |
| ---------------------- | -------------- | --- | ------ |
| `cannon` & `cannon-rs` ||||
| `asterisc` ||||

If there is a feature that you would like to see supported, please [open an issue][new-issue] or [consider contributing][contributing]!

## Cannon (MIPS32r2)

Cannon is based off of the `mips32r2` target architecture, supporting 55 instructions:

| Category | Instruction | Description |
| -------------------- | ----------- | ----------------------------------------- |
| `Arithmetic` | `addi` | Add immediate (with sign-extension). |
| `Arithmetic` | `addiu` | Add immediate unsigned (no overflow). |
| `Arithmetic` | `addu` | Add unsigned (no overflow). |
| `Logical` | `and` | Bitwise AND. |
| `Logical` | `andi` | Bitwise AND immediate. |
| `Branch` | `b` | Unconditional branch. |
| `Conditional Branch` | `beq` | Branch on equal. |
| `Conditional Branch` | `beqz` | Branch if equal to zero. |
| `Conditional Branch` | `bgez` | Branch on greater than or equal to zero. |
| `Conditional Branch` | `bgtz` | Branch on greater than zero. |
| `Conditional Branch` | `blez` | Branch on less than or equal to zero. |
| `Conditional Branch` | `bltz` | Branch on less than zero. |
| `Conditional Branch` | `bne` | Branch on not equal. |
| `Conditional Branch` | `bnez` | Branch if not equal to zero. |
| `Logical` | `clz` | Count leading zeros. |
| `Arithmetic` | `divu` | Divide unsigned. |
| `Unconditional Jump` | `j` | Jump. |
| `Unconditional Jump` | `jal` | Jump and link. |
| `Unconditional Jump` | `jalr` | Jump and link register. |
| `Unconditional Jump` | `jr` | Jump register. |
| `Data Transfer` | `lb` | Load byte. |
| `Data Transfer` | `lbu` | Load byte unsigned. |
| `Data Transfer` | `lui` | Load upper immediate. |
| `Data Transfer` | `lw` | Load word. |
| `Data Transfer` | `lwr` | Load word right. |
| `Data Transfer` | `mfhi` | Move from HI register. |
| `Data Transfer` | `mflo` | Move from LO register. |
| `Data Transfer` | `move` | Move between registers. |
| `Data Transfer` | `movn` | Move conditional on not zero. |
| `Data Transfer` | `movz` | Move conditional on zero. |
| `Data Transfer` | `mtlo` | Move to LO register. |
| `Arithmetic` | `mul` | Multiply (to produce a word result). |
| `Arithmetic` | `multu` | Multiply unsigned. |
| `Arithmetic` | `negu` | Negate unsigned. |
| `No Op` | `nop` | No operation. |
| `Logical` | `not` | Bitwise NOT (pseudo-instruction in MIPS). |
| `Logical` | `or` | Bitwise OR. |
| `Logical` | `ori` | Bitwise OR immediate. |
| `Data Transfer` | `sb` | Store byte. |
| `Logical` | `sll` | Shift left logical. |
| `Logical` | `sllv` | Shift left logical variable. |
| `Comparison` | `slt` | Set on less than (signed). |
| `Comparison` | `slti` | Set on less than immediate. |
| `Comparison` | `sltiu` | Set on less than immediate unsigned. |
| `Comparison` | `sltu` | Set on less than unsigned. |
| `Logical` | `sra` | Shift right arithmetic. |
| `Logical` | `srl` | Shift right logical. |
| `Logical` | `srlv` | Shift right logical variable. |
| `Arithmetic` | `subu` | Subtract unsigned. |
| `Data Transfer` | `sw` | Store word. |
| `Data Transfer` | `swr` | Store word right. |
| `Serialization` | `sync` | Synchronize shared memory. |
| `System Calls` | `syscall` | System call. |
| `Logical` | `xor` | Bitwise XOR. |
| `Logical` | `xori` | Bitwise XOR immediate. |

### Syscalls

| \$v0 | system call | \$a0 | \$a1 | \$a2 | Effect |
| ---- | ----------- | --------------- | ---------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
| 4090 | mmap | uint32 addr | uint32 len | 🚫 | Allocates a page from the heap. See [heap](#heap) for details. |
| 4045 | brk | 🚫 | 🚫 | 🚫 | Returns a fixed address for the program break at `0x40000000` |
| 4120 | clone | 🚫 | 🚫 | 🚫 | Returns 1 |
| 4246 | exit_group | uint8 exit_code | 🚫 | 🚫 | Sets the Exited and ExitCode states to `true` and `$a0` respectively. |
| 4003 | read | uint32 fd | char \*buf | uint32 count | Similar behavior as Linux/MIPS with support for unaligned reads. See [I/O](#io) for more details. |
| 4004 | write | uint32 fd | char \*buf | uint32 count | Similar behavior as Linux/MIPS with support for unaligned writes. See [I/O](#io) for more details. |
| 4055 | fcntl | uint32 fd | int32 cmd | 🚫 | Similar behavior as Linux/MIPS. Only the `F_GETFL` (3) cmd is supported. Sets errno to `0x16` for all other commands |

For all of the above syscalls, an error is indicated by setting the return
register (`$v0`) to `0xFFFFFFFF` (-1) and `errno` (`$a3`) is set accordingly.
The VM must not modify any register other than `$v0` and `$a3` during syscall handling.
For unsupported syscalls, the VM must do nothing except to zero out the syscall return (`$v0`)
and errno (`$a3`) registers.

Note that the above syscalls have identical syscall numbers and ABIs as Linux/MIPS.

## Asterisc (RISC-V)

Asterisc is based off of the `rv64gc` target architecture, which defines the following extensions:
Expand All @@ -100,7 +18,6 @@ Asterisc is based off of the `rv64gc` target architecture, which defines the fol
- `FENCE`, `ECALL`, `EBREAK` are hardwired to implement a minimal subset of systemcalls of the linux kernel
- Work in progress. All syscalls used by the Golang `risc64` runtime.
- `RV64I` support
- `RV64C`: Compressed instructions
- `RV32M`+`RV64M`: Multiplication support
- `RV32A`+`RV64A`: Atomics support
- `RV{32,64}{D,F,Q}`: no-op: No floating points support (since no IEEE754 determinism with rounding modes etc., nor worth the complexity)
Expand All @@ -116,6 +33,16 @@ programs to directly invoke a select few syscalls:
1. `WRITE` - Write the passed buffer to the passed file descriptor.
1. `READ` - Read the specified number of bytes from the passed file descriptor.

[asterisc-syscalls]: https://github.com/ethereum-optimism/asterisc
[asterisc-syscalls]: https://github.com/ethereum-optimism/asterisc/blob/master/docs/golang.md#linux-syscalls-used-by-go

## Cannon (MIPS32r2)

Cannon is based off of the `mips32r2` target architecture, specified in [_MIPS32™ Architecture For Programmers Volume III: The MIPS32™ Privileged Resource Architecture_](https://www.cs.cornell.edu/courses/cs3410/2013sp/MIPS_Vol3.pdf)

### Syscalls

Syscalls supported by `cannon` can be found within the `cannon` specification [here][cannon-syscalls].

[cannon-syscalls]: https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html#syscalls

{{#include ../links.md}}
2 changes: 1 addition & 1 deletion book/src/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

_Documentation for the Kona project._

<a href="https://github.com/kona-rs/kona"><img src="https://img.shields.io/badge/GitHub%20Repo-kona-green?logo=github"></a>
<a href="https://github.com/anton-rs/kona"><img src="https://img.shields.io/badge/GitHub%20Repo-kona-green?logo=github"></a>

> 📖 `kona` is in active development, and is not yet ready for use in production. During development, this book will evolve quickly and may contain inaccuracies.
>
Expand Down
2 changes: 2 additions & 0 deletions book/src/links.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@
[preimage-specs]: https://specs.optimism.io/experimental/fault-proof/index.html#pre-image-oracle
[cannon-specs]: https://specs.optimism.io/experimental/fault-proof/cannon-fault-proof-vm.html#cannon-fault-proof-virtual-machine
[l2-output-root]: https://specs.optimism.io/protocol/proposals.html#l2-output-commitment-construction
[op-succinct]: https://github.com/succinctlabs/op-succinct
[revm]: https://github.com/bluealloy/revm

<!-- Kona links -->

Expand Down
Loading

0 comments on commit 7f744d1

Please sign in to comment.