gear_sandbox_interface/
lib.rs

1// This file is part of Gear.
2
3// Copyright (C) Gear Technologies Inc.
4// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
5
6// This program is free software: you can redistribute it and/or modify
7// it under the terms of the GNU General Public License as published by
8// the Free Software Foundation, either version 3 of the License, or
9// (at your option) any later version.
10
11// This program is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15
16// You should have received a copy of the GNU General Public License
17// along with this program. If not, see <https://www.gnu.org/licenses/>.
18
19//! Runtime interface for gear node
20
21#![cfg_attr(not(feature = "std"), no_std)]
22
23#[cfg(feature = "std")]
24pub use gear_sandbox_host::sandbox::{SandboxBackend, env::Instantiate};
25use sp_runtime_interface::{Pointer, runtime_interface};
26use sp_wasm_interface::HostPointer;
27
28#[cfg(feature = "std")]
29pub mod detail;
30
31#[cfg(feature = "std")]
32pub use detail::init;
33
34/// Wasm-only interface that provides functions for interacting with the sandbox.
35#[runtime_interface(wasm_only)]
36pub trait Sandbox {
37    /// Instantiate a new sandbox instance with the given `wasm_code`.
38    fn instantiate(
39        &mut self,
40        dispatch_thunk_id: u32,
41        wasm_code: &[u8],
42        raw_env_def: &[u8],
43        state_ptr: Pointer<u8>,
44    ) -> u32 {
45        detail::instantiate(
46            *self,
47            dispatch_thunk_id,
48            wasm_code,
49            raw_env_def,
50            state_ptr,
51            Instantiate::Version1,
52        )
53    }
54
55    /// Instantiate a new sandbox instance with the given `wasm_code`.
56    #[version(2)]
57    fn instantiate(
58        &mut self,
59        dispatch_thunk_id: u32,
60        wasm_code: &[u8],
61        raw_env_def: &[u8],
62        state_ptr: Pointer<u8>,
63    ) -> u32 {
64        detail::instantiate(
65            *self,
66            dispatch_thunk_id,
67            wasm_code,
68            raw_env_def,
69            state_ptr,
70            Instantiate::Version2,
71        )
72    }
73
74    /// Invoke `function` in the sandbox with `sandbox_idx`.
75    fn invoke(
76        &mut self,
77        instance_idx: u32,
78        function: &str,
79        args: &[u8],
80        return_val_ptr: Pointer<u8>,
81        return_val_len: u32,
82        state_ptr: Pointer<u8>,
83    ) -> u32 {
84        detail::invoke(
85            *self,
86            instance_idx,
87            function,
88            args,
89            return_val_ptr,
90            return_val_len,
91            state_ptr,
92        )
93    }
94
95    /// Create a new memory instance with the given `initial` and `maximum` size.
96    fn memory_new(&mut self, initial: u32, maximum: u32) -> u32 {
97        detail::memory_new(*self, initial, maximum)
98    }
99
100    /// Get the memory starting at `offset` from the instance with `memory_idx` into the buffer.
101    fn memory_get(
102        &mut self,
103        memory_idx: u32,
104        offset: u32,
105        buf_ptr: Pointer<u8>,
106        buf_len: u32,
107    ) -> u32 {
108        detail::memory_get(*self, memory_idx, offset, buf_ptr, buf_len)
109    }
110
111    /// Set the memory in the given `memory_idx` to the given value at `offset`.
112    fn memory_set(
113        &mut self,
114        memory_idx: u32,
115        offset: u32,
116        val_ptr: Pointer<u8>,
117        val_len: u32,
118    ) -> u32 {
119        detail::memory_set(*self, memory_idx, offset, val_ptr, val_len)
120    }
121
122    /// Teardown the memory instance with the given `memory_idx`.
123    fn memory_teardown(&mut self, memory_idx: u32) {
124        detail::memory_teardown(*self, memory_idx)
125    }
126
127    /// Teardown the sandbox instance with the given `instance_idx`.
128    fn instance_teardown(&mut self, instance_idx: u32) {
129        detail::instance_teardown(*self, instance_idx)
130    }
131
132    /// Get the value from a global with the given `name`. The sandbox is determined by the given
133    /// `instance_idx`.
134    ///
135    /// Returns `Some(_)` when the requested global variable could be found.
136    fn get_global_val(
137        &mut self,
138        instance_idx: u32,
139        name: &str,
140    ) -> Option<sp_wasm_interface::Value> {
141        detail::get_global_val(*self, instance_idx, name)
142    }
143
144    /// Set the value of a global with the given `name`. The sandbox is determined by the given
145    /// `instance_idx`.
146    fn set_global_val(
147        &mut self,
148        instance_idx: u32,
149        name: &str,
150        value: sp_wasm_interface::Value,
151    ) -> u32 {
152        detail::set_global_val(*self, instance_idx, name, value)
153    }
154
155    fn memory_grow(&mut self, memory_idx: u32, size: u32) -> u32 {
156        detail::memory_grow(*self, memory_idx, size)
157    }
158
159    fn memory_size(&mut self, memory_idx: u32) -> u32 {
160        detail::memory_size(*self, memory_idx)
161    }
162
163    fn get_buff(&mut self, memory_idx: u32) -> HostPointer {
164        detail::get_buff(*self, memory_idx)
165    }
166
167    fn get_instance_ptr(&mut self, instance_id: u32) -> HostPointer {
168        detail::get_instance_ptr(*self, instance_id)
169    }
170}
gear_sandbox_interface/lib.rs

gear_sandbox_interface/
lib.rs
