gear_sandbox_env/
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//! Definition of a sandbox environment.
20
21#![cfg_attr(not(feature = "std"), no_std)]
22
23extern crate alloc;
24
25use alloc::string::String;
26use parity_scale_codec::{Decode, Encode};
27use sp_debug_derive::RuntimeDebug;
28use sp_std::vec::Vec;
29use sp_wasm_interface_common::ReturnValue;
30
31#[derive(Clone, Copy, Debug)]
32pub enum Instantiate {
33    /// The first version of instantiate method and syscalls.
34    Version1,
35    /// The second version of syscalls changes their signatures to
36    /// accept global gas value as its first argument and return the remaining
37    /// gas value as its first result tuple element. The approach eliminates
38    /// redundant host calls to get/set WASM-global value.
39    Version2,
40}
41
42/// Error error that can be returned from host function.
43#[derive(Encode, Decode, RuntimeDebug)]
44pub struct HostError;
45
46/// Describes an entity to define or import into the environment.
47#[derive(Clone, PartialEq, Eq, Encode, Decode, RuntimeDebug)]
48pub enum ExternEntity {
49    /// Function that is specified by an index in a default table of
50    /// a module that creates the sandbox.
51    #[codec(index = 1)]
52    Function(u32),
53
54    /// Linear memory that is specified by some identifier returned by sandbox
55    /// module upon creation new sandboxed memory.
56    #[codec(index = 2)]
57    Memory(u32),
58}
59
60/// An entry in a environment definition table.
61///
62/// Each entry has a two-level name and description of an entity
63/// being defined.
64#[derive(Clone, PartialEq, Eq, Encode, Decode, RuntimeDebug)]
65pub struct Entry {
66    /// Module name of which corresponding entity being defined.
67    pub module_name: String,
68    /// Field name in which corresponding entity being defined.
69    pub field_name: String,
70    /// External entity being defined.
71    pub entity: ExternEntity,
72}
73
74/// Definition of runtime that could be used by sandboxed code.
75#[derive(Clone, PartialEq, Eq, Encode, Decode, RuntimeDebug)]
76pub struct EnvironmentDefinition {
77    /// Vector of all entries in the environment definition.
78    pub entries: Vec<Entry>,
79}
80
81/// Constant for specifying no limit when creating a sandboxed
82/// memory instance. For FFI purposes.
83pub const MEM_UNLIMITED: u32 = -1i32 as u32;
84
85/// No error happened.
86///
87/// For FFI purposes.
88pub const ERR_OK: u32 = 0;
89
90/// Validation or instantiation error occurred when creating new
91/// sandboxed module instance.
92///
93/// For FFI purposes.
94pub const ERR_MODULE: u32 = -1i32 as u32;
95
96/// Out-of-bounds access attempted with memory or table.
97///
98/// For FFI purposes.
99pub const ERR_OUT_OF_BOUNDS: u32 = -2i32 as u32;
100
101/// Execution error occurred (typically trap).
102///
103/// For FFI purposes.
104pub const ERR_EXECUTION: u32 = -3i32 as u32;
105
106/// A global variable has been successfully changed.
107///
108/// For FFI purposes.
109pub const ERROR_GLOBALS_OK: u32 = 0;
110
111/// A global variable is not found.
112///
113/// For FFI purposes.
114pub const ERROR_GLOBALS_NOT_FOUND: u32 = u32::MAX;
115
116/// A global variable is immutable or has a different type.
117///
118/// For FFI purposes.
119pub const ERROR_GLOBALS_OTHER: u32 = u32::MAX - 1;
120
121/// Typed value that can be returned from a wasm function
122/// through the dispatch thunk.
123/// Additionally contains globals values.
124#[derive(Clone, Copy, PartialEq, Encode, Decode, Debug)]
125pub struct WasmReturnValue {
126    pub gas: i64,
127    pub inner: ReturnValue,
128}
129
130impl WasmReturnValue {
131    pub const ENCODED_MAX_SIZE: usize = 8 + ReturnValue::ENCODED_MAX_SIZE;
132}
133
134// TODO #3057
135pub const GLOBAL_NAME_GAS: &str = "gear_gas";
136
137#[cfg(test)]
138mod tests {
139    use super::*;
140    use parity_scale_codec::Codec;
141    use std::fmt;
142
143    fn roundtrip<S: Codec + PartialEq + fmt::Debug>(s: S) {
144        let encoded = s.encode();
145        assert_eq!(S::decode(&mut &encoded[..]).unwrap(), s);
146    }
147
148    #[test]
149    fn env_def_roundtrip() {
150        roundtrip(EnvironmentDefinition { entries: vec![] });
151
152        roundtrip(EnvironmentDefinition {
153            entries: vec![Entry {
154                module_name: "kernel".to_string(),
155                field_name: "memory".to_string(),
156                entity: ExternEntity::Memory(1337),
157            }],
158        });
159
160        roundtrip(EnvironmentDefinition {
161            entries: vec![Entry {
162                module_name: "env".to_string(),
163                field_name: "abort".to_string(),
164                entity: ExternEntity::Function(228),
165            }],
166        });
167    }
168}
gear_sandbox_env/lib.rs

gear_sandbox_env/
lib.rs
