vm: more docs

src/flamenco/vm/fd_vm_context.h

@@ -240,6 +240,25 @@ fd_vm_consume_compute_meter( fd_vm_exec_context_t * ctx, ulong cost );
 FD_FN_PURE ulong
 fd_vm_context_validate( fd_vm_exec_context_t const * ctx );
 
+/* fd_vm_translate_vm_to_host{_const} translates a virtual memory area
+   into the local address space.  ctx is the current execution context.
+   vm_addr points to the region's first byte in VM address space.  sz is
+   the number of bytes in the requested access.  align is the required
+   alignment for vm_addr (2^n where n in [1,63) and may not be zero).
+   Returns pointer to same memory region in local address space on
+   success.  On failure, returns NULL.  Reasons for failure include
+   access violation (out-of-bounds access, write requested on read-only
+   region).
+
+   fd_vm_translate_vm_to_host checks whether the target area is writable
+   and returns a pointer to a mutable data region.
+
+   fd_vm_translate_vm_to_host_const is the read-only equivalent and
+   checks for a read-only or writable data region.
+
+   Security note: Watch out for pointer aliasing when translating
+                  multiple user-specified data types. */
+
 ulong
 fd_vm_translate_vm_to_host_private( fd_vm_exec_context_t * ctx,
                                     ulong                  vm_addr,

src/flamenco/vm/fd_vm_syscalls.h

@@ -1,7 +1,6 @@
 #ifndef HEADER_fd_src_flamenco_vm_fd_vm_syscalls_h
 #define HEADER_fd_src_flamenco_vm_fd_vm_syscalls_h
 
-#include "../fd_flamenco_base.h"
 #include "fd_vm_context.h"
 
 #define FD_VM_SYSCALL_SUCCESS           (0UL)
@@ -16,42 +15,94 @@
 
 #define MAX_RETURN_DATA                 (1024UL)
 
-#define FD_VM_SYSCALL_DECL(name) ulong fd_vm_syscall_##name ( \
-    void * _ctx, \
-    ulong arg0, ulong arg1, ulong arg2, ulong arg3, ulong arg4, \
+#define FD_VM_SYSCALL_DECL(name) \
+  ulong fd_vm_syscall_##name ( \
+    void *  _ctx, \
+    ulong   r1,  \
+    ulong   r2, \
+    ulong   r3, \
+    ulong   r4, \
+    ulong   r5, \
     ulong * ret_val )
 
-struct fd_vm_syscall_bytes_slice {
-  ulong addr;
-  ulong len;
-};
-typedef struct fd_vm_syscall_bytes_slice fd_vm_syscall_bytes_slice_t;
-
 FD_PROTOTYPES_BEGIN
 
 /* Registers a syscall by name to an execution context. */
-void fd_vm_register_syscall( fd_sbpf_syscalls_t * syscalls, char const * name, fd_sbpf_syscall_fn_ptr_t fn_ptr );
 
-/* Registers all standard syscalls with the VM */
-void fd_vm_syscall_register_all( fd_sbpf_syscalls_t * syscalls );
+void
+fd_vm_register_syscall( fd_sbpf_syscalls_t *     syscalls,
+                        char const *             name,
+                        fd_sbpf_syscall_fn_ptr_t fn_ptr );
+
+/* fd_vm_syscall_register all reigsters all syscalls implemented.
+   May change between Firedancer versions without warning. */
+
+void
+fd_vm_syscall_register_all( fd_sbpf_syscalls_t * syscalls );
+
+/* fd_vm_syscall_register_ctx registers all syscalls appropriate for
+   slot context. */
 
-/* Syscall function declarations */
+void
+fd_vm_syscall_register_ctx( fd_sbpf_syscalls_t *       syscalls,
+                            fd_exec_slot_ctx_t const * slot_ctx );
+
+/* Syscall function declarations **************************************/
+
+/*** Exceptional syscalls ***/
+
+/* syscall(b6fc1a11) "abort"
+   Abort program execution and fail transaction. */
 
-/* Exceptional syscalls */
 FD_VM_SYSCALL_DECL(abort);
+
+/* syscall(686093bb) "sol_panic_"
+   Log panic message, abort program execution, and fail transaction. */
+
 FD_VM_SYSCALL_DECL(sol_panic);
 
-/* Logging syscalls */
-FD_VM_SYSCALL_DECL(sol_log);
-FD_VM_SYSCALL_DECL(sol_log_64);
-FD_VM_SYSCALL_DECL(sol_log_compute_units);
-FD_VM_SYSCALL_DECL(sol_log_pubkey);
-FD_VM_SYSCALL_DECL(sol_log_data);
+/*** Logging syscalls ***/
 
-/* Program syscalls */
-FD_VM_SYSCALL_DECL(sol_create_program_address);
-FD_VM_SYSCALL_DECL(sol_try_find_program_address);
-FD_VM_SYSCALL_DECL(sol_get_processed_sibling_instruction);
+/* syscall(207559bd) "sol_log_"
+   Write message to log. */
+
+FD_VM_SYSCALL_DECL( sol_log );
+
+/* syscall(5c2a3178) "sol_log_64_"
+   Write register file (r1, r2, r3, r4, r5) to log. */
+
+FD_VM_SYSCALL_DECL( sol_log_64 );
+
+/* syscall(52ba5096) "sol_log_compute_units_"
+   Write remaining compute unit count to log. */
+
+FD_VM_SYSCALL_DECL( sol_log_compute_units );
+
+/* syscall(7ef088ca) "sol_log_pubkey"
+   Write Base58 encoding of 32 byte array to log. */
+
+FD_VM_SYSCALL_DECL( sol_log_pubkey );
+
+/* syscall(???) "sol_log_data"
+   Write Base64 encoded bytes to log. */
+
+FD_VM_SYSCALL_DECL( sol_log_data );
+
+/*** PDA (program derived address) syscalls ***/
+
+/* syscall(9377323c) "sol_create_program_address"
+   Compute SHA-256 hash of `<program ID> .. &[&[u8]] .. <PDA Marker>`,
+   and check whether result is an Ed25519 curve point. */
+
+FD_VM_SYSCALL_DECL( sol_create_program_address );
+
+/* syscall(48504a38) "sol_try_find_program_address"
+   Repeatedly derive program address while incrementing nonce in seed
+   list  until a point is found that is not a valid Ed25519 curve point. */
+
+FD_VM_SYSCALL_DECL( sol_try_find_program_address );
+
+/*** Program syscalls ***/
 
 /* Crypto syscalls */
 FD_VM_SYSCALL_DECL(sol_sha256);
@@ -70,13 +121,23 @@ FD_VM_SYSCALL_DECL(sol_memcmp);
 FD_VM_SYSCALL_DECL(sol_memset);
 FD_VM_SYSCALL_DECL(sol_memmove);
 
-/* CPI syscalls */
-FD_VM_SYSCALL_DECL(sol_invoke_signed_c);
-FD_VM_SYSCALL_DECL(sol_invoke_signed_rust);
+/*** CPI syscalls ***/
+
+/* syscall(a22b9c85) "sol_invoke_signed_c"
+   Dispatch a cross program invocation.  Inputs are in C ABI. */
+
+FD_VM_SYSCALL_DECL(cpi_c);
+
+/* syscall(d7449092) "sol_invoke_signed_rust"
+   Dispatch a cross program invocation.  Inputs are in Rust ABI. */
+
+FD_VM_SYSCALL_DECL(cpi_rust);
+
 FD_VM_SYSCALL_DECL(sol_alloc_free);
 FD_VM_SYSCALL_DECL(sol_set_return_data);
 FD_VM_SYSCALL_DECL(sol_get_return_data);
 FD_VM_SYSCALL_DECL(sol_get_stack_height);
+FD_VM_SYSCALL_DECL(sol_get_processed_sibling_instruction);
 
 /* Sysvar syscalls */
 FD_VM_SYSCALL_DECL(sol_get_clock_sysvar);