♻️ Cleanup

README.md

@@ -22,7 +22,6 @@
   <a href="#whats-kona">What's Kona?</a> •
   <a href="#overview">Overview</a> •
   <a href="https://static.optimism.io/kona/CONTRIBUTING.html">Contributing</a> •
-  <a href="#book">Book</a> •
   <a href="#credits">Credits</a>
 </p>
 
@@ -46,11 +45,16 @@ verify an [L2 output root][g-output-root] from the L1 inputs it was [derived fro
 **`client` / `host` SDK**
 
 - [`common`](./crates/common): A suite of utilities for developing `client` programs to be ran on top of Fault Proof VMs.
+- [`preimage`](./crates/preimage): High level interfaces to the [`PreimageOracle`][fpp-specs] ABI
 
 ## Book
 
 The [book][book] contains a more in-depth overview of the project, contributor guidelines, tutorials for getting started with building your own programs, and a reference for the libraries and tools provided by Kona.
 
+## Development Status
+
+`kona` is currently in active development, and is not yet ready for use in production.
+
 ## Credits
 
 `kona` is inspired by the work of several teams, namely [OP Labs][op-labs] and other contributors' work on the [`op-program`][op-program] and [BadBoiLabs][bad-boi-labs]'s work on [Cannon-rs][badboi-cannon-rs].
@@ -60,12 +64,12 @@ The [book][book] contains a more in-depth overview of the project, contributor g
 [cannon]: https://github.com/ethereum-optimism/optimism/tree/develop/cannon
 [cannon-rs]: https://github.com/anton-rs/cannon-rs
 [badboi-cannon-rs]: https://github.com/BadBoiLabs/cannon-rs
-[asterisc]: https://github.com/protolambda/asterisc
-[fpp-specs]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/fault-proof.md#fault-proof-program
+[asterisc]: https://github.com/etheruem-optimism/asterisc
+[fpp-specs]: https://specs.optimism.io/experimental/fault-proof/index.html
 [book]: https://ethereum-optimism.github.io/kona/
 [op-labs]: https://github.com/ethereum-optimism
 [bad-boi-labs]: https://github.com/BadBoiLabs
-[g-output-root]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/glossary.md#l2-output-root
-[g-derivation-pipeline]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/derivation.md#l2-chain-derivation-pipeline
-[g-fault-proof-vm]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/fault-proof.md#fault-proof-vm
-[g-preimage-oracle]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/fault-proof.md#pre-image-oracle
+[g-output-root]: https://specs.optimism.io/glossary.html#l2-output-root
+[g-derivation-pipeline]: https://specs.optimism.io/protocol/derivation.html#l2-chain-derivation-pipeline
+[g-fault-proof-vm]: https://specs.optimism.io/experimental/fault-proof/index.html#fault-proof-vm
+[g-preimage-oracle]: https://specs.optimism.io/experimental/fault-proof/index.html#pre-image-oracle

book/src/fpp-dev/env.md

@@ -12,11 +12,11 @@ communication with the `host` (the FPVM), and other implementation-specific feat
 While the program is running on top of the FPVM, it is considered to be in the `client` role, while the VM is in the `host` role. The only way for the `client` and `host`
 to communicate with one another is synchronously through the {{#template ../../templates/glossary-link.md root=../ text=Preimage ABI ref=preimage-abi}} ([specification][preimage-specs]).
 
-In order for the `client` to read from the `host`, special syscalls are modified within the FPVM to allow the `client` to request preparation of and read foreign data.
+In order for the `client` to read from the `host`, the `read` and `write` syscalls are modified within the FPVM to allow the `client` to request preparation of and read foreign data.
 
 ### Reading
 
-When the `client` wants to read data from the `host`, it must first send a "hint" to the `host` through the hint file descriptor, which is a request for the `host` to prepare the data for reading. The `host` will then
+When the `client` wants to read data from the `host`, it must first send a "hint" to the `host` through the hint file descriptor, which signals a request for the `host` to prepare the data for reading. The `host` will then
 prepare the data, and send a hint acknowledgement back to the `client`. The `client` can then read the data from the host through the designated file descriptor.
 
 The preparation step ("hinting") is an optimization that allows the `host` to know ahead of time the intents of the `client` and the data it requires for execution. This can allow

book/src/fpp-dev/epilogue.md

@@ -1 +1,3 @@
 # Epilogue
+
+_TODO_

book/src/fpp-dev/execution.md

@@ -1 +1,3 @@
 # Execution
+
+_TODO_

book/src/fpp-dev/prologue.md

@@ -1 +1,3 @@
 # Prologue
+
+_TODO_

book/src/fpp-dev/targets.md

@@ -72,6 +72,26 @@ Cannon is based off of the `mips32r2` target architecture, supporting 55 instruc
 | `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:
@@ -96,6 +116,6 @@ 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/protolambda/asterisc
+[asterisc-syscalls]: https://github.com/ethereum-optimism/asterisc
 
 {{#include ../links.md}}