docs: Add a bit on system-level interactions (#1078)

* docs: Add a bit on system-level interactions * fix --------- Co-authored-by: Jonathan Wang <[email protected]>
openvm-org · Dec 16, 2024 · 7a0f790 · 7a0f790
1 parent 1456ac1
commit 7a0f790
Showing 1 changed file with 15 additions and 3 deletions.
diff --git a/docs/crates/vm.md b/docs/crates/vm.md
@@ -37,6 +37,18 @@ Together, these provide the following functionalities:
   execution records and then `Chip::<SC>::generate_air_proof_input()` which generates the trace using the corresponding
   records.
 
+### VM AIR Integration
+
+At the AIR-level, for an AIR to integrate with the OpenVM architecture (constrain memory, read the instruction from the program, etc.), the AIR
+communicates over different (virtual) buses. There are three main system buses: the memory bus, program bus, and the
+execution bus. The memory bus is used to access memory, the program bus is used to read instructions from the program,
+and the execution bus is used to constrain the execution flow. These buses are derivable from the `SystemPort` struct,
+which is provided by the `VmInventoryBuilder`.
+
+The buses have very low-level APIs and are not intended to be used directly. "Bridges" are provided to provide a cleaner interface for
+sending interactions over the buses and enforcing additional constraints for soundness. The two system bridges are
+`MemoryBridge` and `ExecutionBridge`, which should respectively be used to constrain memory accesses and execution flow.
+
 ### Phantom Sub-Instructions
 
 You can specify phantom sub-instruction executors by implementing the trait:
@@ -186,13 +198,13 @@ pub trait VmAdapterChip<F: Field> {
 
     fn preprocess(
         &mut self,
-        memory: &mut MemoryChip<F>,
+        memory: &mut MemoryController<F>,
         instruction: &Instruction<F>,
     ) -> Result<(<Self::Interface as VmAdapterInterface<F>>::Reads, Self::ReadRecord)>;
 
     fn postprocess(
         &mut self,
-        memory: &mut MemoryChip<F>,
+        memory: &mut MemoryController<F>,
         instruction: &Instruction<F>,
         from_state: ExecutionState<u32>,
         ctx: AdapterRuntimeContext<F, Self::Interface<F>>,
@@ -295,7 +307,7 @@ pub struct VmChipWrapper<F, A: VmAdapterChip<F>, C: VmCoreChip<F, A>> {
     pub core: C,
     pub records: Vec<(A::ReadRecord, A::WriteRecord, C::Record)>,
     // For accessing memory
-    memory: MemoryChipRef<F>,
+    memory: MemoryControllerRef<F>,
 }
 
 pub struct VmAirWrapper<A, C> {