Skip to content

Commit aa62f11

Browse files
StebalienStebalien
authored
doc: improve syscall documentation (#498)
1 parent ada077c commit aa62f11

File tree

10 files changed

+357
-115
lines changed

10 files changed

+357
-115
lines changed

‎sdk/src/sys/actor.rs

Lines changed: 24 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,32 +3,43 @@
33
#[doc(inline)]
44
pub use fvm_shared::sys::out::actor::*;
55

6+
// for documentation links
7+
#[cfg(doc)]
8+
use crate::sys::ErrorNumber::*;
9+
610
super::fvm_syscalls! {
711
module = "actor";
812

913
/// Resolves the ID address of an actor.
1014
///
15+
/// # Arguments
16+
///
17+
/// `addr_off` and `addr_len` specify the location and length of an address to be resolved.
18+
///
1119
/// # Errors
1220
///
13-
/// | Error | Reason |
14-
/// |-------------------|-----------------------------------------------------------|
15-
/// | `NotFound` | target actor doesn't exist |
16-
/// | `IllegalArgument` | if the passed address buffer isn't valid, in memory, etc. |
21+
/// | Error | Reason |
22+
/// |---------------------|-----------------------------------------------------------|
23+
/// | [`IllegalArgument`] | if the passed address buffer isn't valid, in memory, etc. |
1724
pub fn resolve_address(
1825
addr_off: *const u8,
1926
addr_len: u32,
2027
) -> Result<ResolveAddress>;
2128

2229
/// Gets the CodeCID of an actor by address.
2330
///
24-
/// Returns the
31+
/// # Arguments
32+
///
33+
/// - `addr_off` and `addr_len` specify the location and length of an address of the target
34+
/// actor.
35+
/// - `obuf_off` and `obuf_len` specify the location and length of a byte buffer into which the
36+
/// FVM will write the actor's code CID, if the actor is found. If the
2537
///
2638
/// # Errors
2739
///
28-
/// | Error | Reason |
29-
/// |-------------------|-----------------------------------------------------------|
30-
/// | `NotFound` | target actor doesn't exist |
31-
/// | `IllegalArgument` | if the passed address buffer isn't valid, in memory, etc. |
40+
/// | Error | Reason |
41+
/// |---------------------|-----------------------------------------------------------|
42+
/// | [`IllegalArgument`] | if the passed address buffer isn't valid, in memory, etc. |
3243
pub fn get_actor_code_cid(
3344
addr_off: *const u8,
3445
addr_len: u32,
@@ -41,10 +52,10 @@ super::fvm_syscalls! {
4152
/// internal errors.
4253
pub fn resolve_builtin_actor_type(cid_off: *const u8) -> Result<i32>;
4354

44-
/// Returns the CodeCID for the given built-in actor type. Aborts with exit
45-
/// code IllegalArgument if the supplied type is invalid. Returns the
46-
/// length of the written CID written to the output buffer. Can only
47-
/// return a failure due to internal errors.
55+
/// Returns the CodeCID for the given built-in actor type. Aborts with exit
56+
/// code IllegalArgument if the supplied type is invalid. Returns the
57+
/// length of the written CID written to the output buffer. Can only
58+
/// return a failure due to internal errors.
4859
pub fn get_code_cid_for_type(typ: i32, obuf_off: *mut u8, obuf_len: u32) -> Result<i32>;
4960

5061
/// Generates a new actor address for an actor deployed

‎sdk/src/sys/crypto.rs

Lines changed: 91 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,28 @@
33
#[doc(inline)]
44
pub use fvm_shared::sys::out::crypto::*;
55

6+
// for documentation links
7+
#[cfg(doc)]
8+
use crate::sys::ErrorNumber::*;
9+
610
super::fvm_syscalls! {
711
module = "crypto";
812

913
/// Verifies that a signature is valid for an address and plaintext.
1014
///
1115
/// Returns 0 on success, or -1 if the signature fails to validate.
1216
///
17+
/// # Arguments
18+
///
19+
/// - `sig_off` and `sig_len` specify location and length of the signature.
20+
/// - `addr_off` and `addr_len` specify location and length of expected signer's address.
21+
/// - `plaintext_off` and `plaintext_len` specify location and length of the signed data.
22+
///
1323
/// # Errors
1424
///
15-
/// | Error | Reason |
16-
/// |-------------------|------------------------------------------------------|
17-
/// | `IllegalArgument` | signature, address, or plaintext buffers are invalid |
25+
/// | Error | Reason |
26+
/// |---------------------|------------------------------------------------------|
27+
/// | [`IllegalArgument`] | signature, address, or plaintext buffers are invalid |
1828
pub fn verify_signature(
1929
sig_off: *const u8,
2030
sig_len: u32,
@@ -26,13 +36,17 @@ super::fvm_syscalls! {
2636

2737
/// Hashes input data using blake2b with 256 bit output.
2838
///
29-
/// The output buffer must be sized to a minimum of 32 bytes.
39+
/// Returns a 32-byte hash digest.
40+
///
41+
/// # Arguments
42+
///
43+
/// - `data_off` and `data_len` specify location and length of the data to be hashed.
3044
///
3145
/// # Errors
3246
///
33-
/// | Error | Reason |
34-
/// |-------------------|-------------------------------------------------|
35-
/// | `IllegalArgument` | the input buffer does not point to valid memory |
47+
/// | Error | Reason |
48+
/// |---------------------|-------------------------------------------------|
49+
/// | [`IllegalArgument`] | the input buffer does not point to valid memory |
3650
pub fn hash_blake2b(
3751
data_off: *const u8,
3852
data_len: u32,
@@ -44,11 +58,19 @@ super::fvm_syscalls! {
4458
/// Writes the CID in the provided output buffer, and returns the length of
4559
/// the written CID.
4660
///
61+
/// # Arguments
62+
///
63+
/// - `proof_type` is the type of seal proof.
64+
/// - `pieces_off` and `pieces_len` specify the location and length of a cbor-encoded list of
65+
/// [`PieceInfo`][fvm_shared::piece::PieceInfo] in tuple representation.
66+
/// - `cid_off` is the offset at which the computed CID will be written.
67+
/// - `cid_len` is the size of the buffer at `cid_off`. 100 bytes is guaranteed to be enough.
68+
///
4769
/// # Errors
4870
///
49-
/// | Error | Reason |
50-
/// |-------------------|--------------------------|
51-
/// | `IllegalArgument` | an argument is malformed |
71+
/// | Error | Reason |
72+
/// |---------------------|--------------------------|
73+
/// | [`IllegalArgument`] | an argument is malformed |
5274
pub fn compute_unsealed_sector_cid(
5375
proof_type: i64,
5476
pieces_off: *const u8,
@@ -61,22 +83,32 @@ super::fvm_syscalls! {
6183
///
6284
/// Returns 0 to indicate that the proof was valid, -1 otherwise.
6385
///
86+
/// # Arguments
87+
///
88+
/// `info_off` and `info_len` specify the location and length of a cbor-encoded
89+
/// [`SealVerifyInfo`][fvm_shared::sector::SealVerifyInfo] in tuple representation.
90+
///
6491
/// # Errors
6592
///
66-
/// | Error | Reason |
67-
/// |-------------------|--------------------------|
68-
/// | `IllegalArgument` | an argument is malformed |
93+
/// | Error | Reason |
94+
/// |---------------------|--------------------------|
95+
/// | [`IllegalArgument`] | an argument is malformed |
6996
pub fn verify_seal(info_off: *const u8, info_len: u32) -> Result<i32>;
7097

7198
/// Verifies a window proof of spacetime.
7299
///
73100
/// Returns 0 to indicate that the proof was valid, -1 otherwise.
74101
///
102+
/// # Arguments
103+
///
104+
/// `info_off` and `info_len` specify the location and length of a cbor-encoded
105+
/// [`WindowPoStVerifyInfo`][fvm_shared::sector::WindowPoStVerifyInfo] in tuple representation.
106+
///
75107
/// # Errors
76108
///
77-
/// | Error | Reason |
78-
/// |-------------------|--------------------------|
79-
/// | `IllegalArgument` | an argument is malformed |
109+
/// | Error | Reason |
110+
/// |---------------------|--------------------------|
111+
/// | [`IllegalArgument`] | an argument is malformed |
80112
pub fn verify_post(info_off: *const u8, info_len: u32) -> Result<i32>;
81113

82114
/// Verifies that two block headers provide proof of a consensus fault.
@@ -85,12 +117,19 @@ super::fvm_syscalls! {
85117
/// BlockId containing the fault details. Otherwise, a -1 status is returned,
86118
/// and the second result parameter must be ignored.
87119
///
120+
/// # Arguments
121+
///
122+
/// - `h1_off`/`h1_len` and `h2_off`/`h2_len` specify the location and length of the block
123+
/// headers that allegedly represent a consensus fault.
124+
/// - `extra_off` and `extra_len` specifies the "extra data" passed in the
125+
/// `ReportConsensusFault` message.
126+
///
88127
/// # Errors
89128
///
90-
/// | Error | Reason |
91-
/// |-------------------|---------------------------------------|
92-
/// | `LimitExceeded` | exceeded lookback limit finding block |
93-
/// | `IllegalArgument` | an argument is malformed |
129+
/// | Error | Reason |
130+
/// |---------------------|---------------------------------------|
131+
/// | [`LimitExceeded`] | exceeded lookback limit finding block |
132+
/// | [`IllegalArgument`] | an argument is malformed |
94133
pub fn verify_consensus_fault(
95134
h1_off: *const u8,
96135
h1_len: u32,
@@ -104,32 +143,52 @@ super::fvm_syscalls! {
104143
///
105144
/// Returns 0 to indicate that the proof was valid, -1 otherwise.
106145
///
146+
/// # Arguments
147+
///
148+
/// `agg_off` and `agg_len` specify the location and length of a cbor-encoded
149+
/// [`AggregateSealVerifyProofAndInfos`][fvm_shared::sector::AggregateSealVerifyProofAndInfos]
150+
/// in tuple representation.
151+
///
107152
/// # Errors
108153
///
109-
/// | Error | Reason |
110-
/// |-------------------|--------------------------------|
111-
/// | `LimitExceeded` | exceeds seal aggregation limit |
112-
/// | `IllegalArgument` | an argument is malformed |
154+
/// | Error | Reason |
155+
/// |---------------------|--------------------------------|
156+
/// | [`LimitExceeded`] | exceeds seal aggregation limit |
157+
/// | [`IllegalArgument`] | an argument is malformed |
113158
pub fn verify_aggregate_seals(agg_off: *const u8, agg_len: u32) -> Result<i32>;
114159

115160
/// Verifies a replica update proof.
116161
///
117162
/// Returns 0 to indicate that the proof was valid, -1 otherwise.
118163
///
164+
/// # Arguments
165+
///
166+
/// `rep_off` and `rep_len` specify the location and length of a cbor-encoded
167+
/// [`ReplicaUpdateInfo`][fvm_shared::sector::ReplicaUpdateInfo] in tuple representation.
168+
///
119169
/// # Errors
120170
///
121-
/// | Error | Reason |
122-
/// |-------------------|-------------------------------|
123-
/// | `LimitExceeded` | exceeds replica update limit |
124-
/// | `IllegalArgument` | an argument is malformed |
171+
/// | Error | Reason |
172+
/// |---------------------|-------------------------------|
173+
/// | [`LimitExceeded`] | exceeds replica update limit |
174+
/// | [`IllegalArgument`] | an argument is malformed |
125175
pub fn verify_replica_update(rep_off: *const u8, rep_len: u32) -> Result<i32>;
126176

127-
/// Verifies an aggregated batch of sector seal proofs.
177+
/// Verifies a batch of sector seal proofs.
178+
///
179+
/// # Arguments
180+
///
181+
/// - `batch_off` and `batch_len` specify the location and length of a cbor-encoded list of
182+
/// [`SealVerifyInfo`][fvm_shared::sector::SealVerifyInfo] in tuple representation.
183+
/// - `results_off` specifies the location of a length `L` byte buffer where the results of the
184+
/// verification will be written, where `L` is the number of proofs in the batch. For each
185+
/// proof in the input list (in input order), a 1 or 0 byte will be written on success or
186+
/// failure, respectively.
128187
///
129188
/// # Errors
130189
///
131-
/// | Error | Reason |
132-
/// |-------------------|--------------------------|
133-
/// | `IllegalArgument` | an argument is malformed |
190+
/// | Error | Reason |
191+
/// |---------------------|--------------------------|
192+
/// | [`IllegalArgument`] | an argument is malformed |
134193
pub fn batch_verify_seals(batch_off: *const u8, batch_len: u32, result_off: *const u8) -> Result<()>;
135194
}

‎sdk/src/sys/gas.rs

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
//! Syscalls for working with gas.
22
3+
// for documentation links
4+
#[cfg(doc)]
5+
use crate::sys::ErrorNumber::*;
6+
37
super::fvm_syscalls! {
48
module = "gas";
59

@@ -8,11 +12,17 @@ super::fvm_syscalls! {
812

913
/// Charge gas.
1014
///
15+
/// # Arguments
16+
///
17+
/// - `name_off` and `name_len` specify the location and length of the "name" of the gas charge,
18+
/// for debugging.
19+
/// - `amount` is the amount of gas to charge.
20+
///
1121
/// # Errors
1222
///
13-
/// | Error | Reason |
14-
/// |-------------------|----------------------|
15-
/// | `IllegalArgument` | invalid name buffer. |
23+
/// | Error | Reason |
24+
/// |---------------------|----------------------|
25+
/// | [`IllegalArgument`] | invalid name buffer. |
1626
pub fn charge(name_off: *const u8, name_len: u32, amount: u64) -> Result<()>;
1727

1828
// Returns the amount of gas remaining.

0 commit comments

Comments
 (0)