update doc of bei

docs/appendix/bei.md

@@ -1 +1,128 @@
-# BCOS Wasm环境接口规范
+# BCOS环境接口规范
+
+BCOS环境接口（BCOS Environment Interface，BEI）规范提供了合约字节码在执行时能够使用的FISCO BCOS核心API，这些API在FISCO BCOS中使用C++语言实现。BEI中所有接口的参数或返回值都被限制为32位或64位的整数，不允许使用浮点数。
+
+## 数据类型
+
+在BEI规范中，使用了以下数据类型：
+
+- `i32`：与WebAssembly中的`i32`相同
+- `i32ptr`：与WebAssembly中的`i32`相同，但是被当作一个指向虚拟机内存中某个位置的指针
+- `i64`：与WebAssembly中的`i64`相同
+
+## API
+
+### setStorage
+
+将虚拟机内存中的键值对存储至区块链永久存储中。
+
+#### 参数
+
+- `keyOffset`，**i32ptr**，键在虚拟机内存中的存储位置的起始地址
+- `keyLength`，**i32**，键的长度
+- `valueOffset`，**i32ptr**，值在虚拟机内存中的存储位置的起始地址
+- `valueLength`，**i32**，值的长度
+
+```eval_rst
+.. admonition:: 注意
+
+   调用`setStorage`时，若提供的`valueLength`为0，则表示从区块链存储中删除键所对应的键值对。
+```
+
+#### 返回值
+
+无
+
+### getStorage
+
+将区块链永久存储中的键值对载入至虚拟机内存中。
+
+#### 参数
+
+- `keyOffset`，**i32ptr**，键在虚拟机内存中的存储位置的起始地址
+- `keyLength`，**i32**，键的长度
+- `valueOffset`，**i32ptr**，用于存放值的虚拟机内存起始地址
+
+#### 返回值
+
+- `valueLength`，**i32**，值的长度
+
+### getCallData
+
+将当前交易的输入数据拷贝至虚拟机内存中。
+
+#### 参数
+
+- `resultOffset`，**i32ptr**，用于存放交易输入的虚拟机内存起始地址
+
+#### 返回值
+
+无
+
+### getCallDataSize
+
+获取当前交易的输入数据的长度。
+
+#### 参数
+
+无
+
+#### 返回值
+
+- `callDataSize`，**i32**，当前交易的输入数据的长度
+
+### getCaller
+
+获取调用合约的调用者地址。
+
+#### 参数
+
+- `resultOffset`，**i32ptr**，用于存放调用者地址的虚拟机内存起始地址
+
+#### 返回值
+
+无
+
+### finish
+
+将合约方法的返回值返回至宿主环境，宿主环境会将该结果作为交易回执的一部分返回至调用者。调用此接口后，合约的执行将会被强行终止。
+
+#### 参数
+
+- `dataOffset`，**i32ptr**，用于存放返回值的虚拟机内存起始地址
+- `dataLength`，**i32**，返回值的长度
+
+#### 返回值
+
+无
+
+### revert
+
+将执行合约期间的抛出的异常信息返回至宿主环境，宿主环境会将该结果作为交易回执的一部分返回至调用者。调用此接口后，合约的执行将会被强行终止，合约的执行状态将会被标记为“已回滚”。
+
+#### 参数
+
+- `dataOffset`，**i32ptr**，用于存放异常信息的虚拟机内存起始地址
+- `dataLength`，**i32**，异常信息的长度
+
+#### 返回值
+
+无
+
+### log
+
+创建一条交易日志。
+
+#### 参数
+
+- `dataOffset`，**i32ptr**，用于存放异常信息的虚拟机内存起始地址
+- `dataLength`，**i32**，异常信息的长度
+- `numberOfTopics`，**i32**，日志索引的数量（0到4）
+- `topic1`，**i32ptr**，用于存放第一个日志索引的虚拟机内存起始地址
+- `topic2`，**i32ptr**，用于存放第二个日志索引的虚拟机内存起始地址
+- `topic3`，**i32ptr**，用于存放第三个日志索引的虚拟机内存起始地址
+- `topic4`，**i32ptr**，用于存放第四个日志索引的虚拟机内存起始地址
+
+#### 返回值
+
+无

docs/appendix/bwci.md

@@ -1,6 +1,6 @@
 # BCOS Wasm合约接口规范
 
-BCOS Wasm合约接口规范（BCOS Wasm Contract Interface，BWCI）用于规范合约中的内容及结构。
+BCOS Wasm合约接口（BCOS Wasm Contract Interface，BWCI）规范用于规范合约中的内容及结构。
 
 ## 传输格式
 
@@ -41,4 +41,4 @@ BCOS Wasm合约接口规范（BCOS Wasm Contract Interface，BWCI）用于规范
 
 ## Traps
 
-如果合约的执行过程中触发了Wasm的`trap`（如执行了`unreachable`等指令），则合约的执行会立即终止。
+如果合约的执行过程中触发了Wasm的`trap`（如执行了`unreachable`指令、共享内存访问越界等），则合约的执行会立即终止。