Skip to content

Commit 664ab0b

Browse files
StebalienStebalien
authored
Merge pull request #484 from filecoin-project/doc/syscalls
doc: document syscalls & errors
2 parents 348efd8 + 8c7bfac commit 664ab0b

File tree

13 files changed

+292
-48
lines changed

13 files changed

+292
-48
lines changed

‎sdk/src/sys/actor.rs

Lines changed: 39 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,41 @@
1+
//! Syscalls for creating and resolving actors.
2+
3+
#[doc(inline)]
4+
pub use fvm_shared::sys::out::actor::*;
5+
16
super::fvm_syscalls! {
27
module = "actor";
38

49
/// Resolves the ID address of an actor.
5-
pub fn resolve_address(addr_off: *const u8, addr_len: u32) -> Result<fvm_shared::sys::out::actor::ResolveAddress>;
10+
///
11+
/// # Errors
12+
///
13+
/// | Error | Reason |
14+
/// |-------------------|-----------------------------------------------------------|
15+
/// | `NotFound` | target actor doesn't exist |
16+
/// | `IllegalArgument` | if the passed address buffer isn't valid, in memory, etc. |
17+
pub fn resolve_address(
18+
addr_off: *const u8,
19+
addr_len: u32,
20+
) -> Result<ResolveAddress>;
621

722
/// Gets the CodeCID of an actor by address.
23+
///
24+
/// Returns the
25+
///
26+
/// # Errors
27+
///
28+
/// | Error | Reason |
29+
/// |-------------------|-----------------------------------------------------------|
30+
/// | `NotFound` | target actor doesn't exist |
31+
/// | `IllegalArgument` | if the passed address buffer isn't valid, in memory, etc. |
832
pub fn get_actor_code_cid(
933
addr_off: *const u8,
1034
addr_len: u32,
1135
obuf_off: *mut u8,
1236
obuf_len: u32,
1337
) -> Result<i32>;
1438

15-
/// Generates a new actor address for an actor deployed
16-
/// by the calling actor.
17-
pub fn new_actor_address(obuf_off: *mut u8, obuf_len: u32) -> Result<u32>;
18-
19-
/// Creates a new actor of the specified type in the state tree, under
20-
/// the provided address.
21-
/// TODO this syscall will change to calculate the address internally.
22-
pub fn create_actor(actor_id: u64, typ_off: *const u8) -> Result<()>;
23-
2439
/// Determines whether the specified CodeCID belongs to that of a builtin
2540
/// actor and which. Returns 0 if unrecognized. Can only fail due to
2641
/// internal errors.
@@ -31,4 +46,18 @@ super::fvm_syscalls! {
3146
/// length of the written CID written to the output buffer. Can only
3247
/// return a failure due to internal errors.
3348
pub fn get_code_cid_for_type(typ: i32, obuf_off: *mut u8, obuf_len: u32) -> Result<i32>;
49+
50+
/// Generates a new actor address for an actor deployed
51+
/// by the calling actor.
52+
///
53+
/// **Privledged:** May only be called by the init actor.
54+
#[doc(hidden)]
55+
pub fn new_actor_address(obuf_off: *mut u8, obuf_len: u32) -> Result<u32>;
56+
57+
/// Creates a new actor of the specified type in the state tree, under
58+
/// the provided address.
59+
///
60+
/// **Privledged:** May only be called by the init actor.
61+
#[doc(hidden)]
62+
pub fn create_actor(actor_id: u64, typ_off: *const u8) -> Result<()>;
3463
}

‎sdk/src/sys/crypto.rs

Lines changed: 73 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,20 @@
1+
//! Syscalls for cryptographic operations.
2+
3+
#[doc(inline)]
4+
pub use fvm_shared::sys::out::crypto::*;
5+
16
super::fvm_syscalls! {
27
module = "crypto";
38

49
/// Verifies that a signature is valid for an address and plaintext.
10+
///
11+
/// Returns 0 on success, or -1 if the signature fails to validate.
12+
///
13+
/// # Errors
14+
///
15+
/// | Error | Reason |
16+
/// |-------------------|------------------------------------------------------|
17+
/// | `IllegalArgument` | signature, address, or plaintext buffers are invalid |
518
pub fn verify_signature(
619
sig_off: *const u8,
720
sig_len: u32,
@@ -14,6 +27,12 @@ super::fvm_syscalls! {
1427
/// Hashes input data using blake2b with 256 bit output.
1528
///
1629
/// The output buffer must be sized to a minimum of 32 bytes.
30+
///
31+
/// # Errors
32+
///
33+
/// | Error | Reason |
34+
/// |-------------------|-------------------------------------------------|
35+
/// | `IllegalArgument` | the input buffer does not point to valid memory |
1736
pub fn hash_blake2b(
1837
data_off: *const u8,
1938
data_len: u32,
@@ -24,6 +43,12 @@ super::fvm_syscalls! {
2443
///
2544
/// Writes the CID in the provided output buffer, and returns the length of
2645
/// the written CID.
46+
///
47+
/// # Errors
48+
///
49+
/// | Error | Reason |
50+
/// |-------------------|--------------------------|
51+
/// | `IllegalArgument` | an argument is malformed |
2752
pub fn compute_unsealed_sector_cid(
2853
proof_type: i64,
2954
pieces_off: *const u8,
@@ -33,31 +58,78 @@ super::fvm_syscalls! {
3358
) -> Result<u32>;
3459

3560
/// Verifies a sector seal proof.
61+
///
62+
/// Returns 0 to indicate that the proof was valid, -1 otherwise.
63+
///
64+
/// # Errors
65+
///
66+
/// | Error | Reason |
67+
/// |-------------------|--------------------------|
68+
/// | `IllegalArgument` | an argument is malformed |
3669
pub fn verify_seal(info_off: *const u8, info_len: u32) -> Result<i32>;
3770

3871
/// Verifies a window proof of spacetime.
72+
///
73+
/// Returns 0 to indicate that the proof was valid, -1 otherwise.
74+
///
75+
/// # Errors
76+
///
77+
/// | Error | Reason |
78+
/// |-------------------|--------------------------|
79+
/// | `IllegalArgument` | an argument is malformed |
3980
pub fn verify_post(info_off: *const u8, info_len: u32) -> Result<i32>;
4081

4182
/// Verifies that two block headers provide proof of a consensus fault.
4283
///
4384
/// Returns a 0 status if a consensus fault was recognized, along with the
4485
/// BlockId containing the fault details. Otherwise, a -1 status is returned,
4586
/// and the second result parameter must be ignored.
87+
///
88+
/// # Errors
89+
///
90+
/// | Error | Reason |
91+
/// |-------------------|---------------------------------------|
92+
/// | `LimitExceeded` | exceeded lookback limit finding block |
93+
/// | `IllegalArgument` | an argument is malformed |
4694
pub fn verify_consensus_fault(
4795
h1_off: *const u8,
4896
h1_len: u32,
4997
h2_off: *const u8,
5098
h2_len: u32,
5199
extra_off: *const u8,
52100
extra_len: u32,
53-
) -> Result<fvm_shared::sys::out::crypto::VerifyConsensusFault>;
101+
) -> Result<VerifyConsensusFault>;
54102

55103
/// Verifies an aggregated batch of sector seal proofs.
104+
///
105+
/// Returns 0 to indicate that the proof was valid, -1 otherwise.
106+
///
107+
/// # Errors
108+
///
109+
/// | Error | Reason |
110+
/// |-------------------|--------------------------------|
111+
/// | `LimitExceeded` | exceeds seal aggregation limit |
112+
/// | `IllegalArgument` | an argument is malformed |
56113
pub fn verify_aggregate_seals(agg_off: *const u8, agg_len: u32) -> Result<i32>;
57114

58115
/// Verifies a replica update proof.
116+
///
117+
/// Returns 0 to indicate that the proof was valid, -1 otherwise.
118+
///
119+
/// # Errors
120+
///
121+
/// | Error | Reason |
122+
/// |-------------------|-------------------------------|
123+
/// | `LimitExceeded` | exceeds replica update limit |
124+
/// | `IllegalArgument` | an argument is malformed |
59125
pub fn verify_replica_update(rep_off: *const u8, rep_len: u32) -> Result<i32>;
60126

61127
/// Verifies an aggregated batch of sector seal proofs.
128+
///
129+
/// # Errors
130+
///
131+
/// | Error | Reason |
132+
/// |-------------------|--------------------------|
133+
/// | `IllegalArgument` | an argument is malformed |
62134
pub fn batch_verify_seals(batch_off: *const u8, batch_len: u32, result_off: *const u8) -> Result<()>;
63135
}

‎sdk/src/sys/debug.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
//! Syscalls for debugging.
2+
13
super::fvm_syscalls! {
24
module = "debug";
35

‎sdk/src/sys/gas.rs

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,18 @@
1+
//! Syscalls for working with gas.
2+
13
super::fvm_syscalls! {
24
module = "gas";
35

46
// TODO: name for debugging & tracing?
57
// We could also _not_ feed that through to the outside?
68

79
/// Charge gas.
10+
///
11+
/// # Errors
12+
///
13+
/// | Error | Reason |
14+
/// |-------------------|----------------------|
15+
/// | `IllegalArgument` | invalid name buffer. |
816
pub fn charge(name_off: *const u8, name_len: u32, amount: u64) -> Result<()>;
917

1018
// Returns the amount of gas remaining.

‎sdk/src/sys/ipld.rs

Lines changed: 48 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,11 @@
1-
// Q: Charge the first time? Or every time? We have several idempotent operations here.
2-
// A: TODO
1+
//! Syscalls for manipulating IPLD state.
32
4-
// Q: How to allocate?
5-
// A: Let the user do it, and reference blocks with "handles".
6-
7-
// Q: Ids or CIDs in set/get root?
8-
// A: CIDs.
9-
// - Forces the user to explicitly call "load" if they actually want the data.
10-
// - Gives the user access to the CID without forcing them to recompute it.
11-
// - Makes the user explicitly compute the CID.
12-
13-
// Q: We have open, do we have close?
14-
// A: We'd need reference counting at runtime. Not terrible, but somewhat complicated. Do we need
15-
// it? We probably want it in the future, but maybe not yet.
16-
// Idea: Use WASM "reftypes". Maybe someday.
17-
18-
// Q: Do we really need `stat`?
19-
// A: No, we don't. We can punt on that if we want to.
20-
21-
// TODO: Implement this!
223
/// The ID of the "unit" block (or void for C programmers).
234
pub const UNIT: u32 = 0;
245

6+
#[doc(inline)]
7+
pub use fvm_shared::sys::out::ipld::*;
8+
259
super::fvm_syscalls! {
2610
module = "ipld";
2711

@@ -31,26 +15,65 @@ super::fvm_syscalls! {
3115
/// - The reachable set is initialized to the root.
3216
/// - The reachable set is extended to include the direct children of loaded blocks until the
3317
/// end of the invocation.
34-
pub fn open(cid: *const u8) -> Result<fvm_shared::sys::out::ipld::IpldOpen>;
18+
///
19+
/// # Errors
20+
///
21+
/// | Error | Reason |
22+
/// |-------------------|---------------------------------------------|
23+
/// | `NotFound` | the target block isn't in the reachable set |
24+
/// | `IllegalArgument` | there's something wrong with the CID |
25+
pub fn open(cid: *const u8) -> Result<IpldOpen>;
3526

3627
/// Creates a new block, returning the block's ID. The block's children must be in the reachable
3728
/// set. The new block isn't added to the reachable set until the CID is computed.
29+
///
30+
/// | Error | Reason |
31+
/// |-------------------|---------------------------------------------------------|
32+
/// | `LimitExceeded` | the block is too big |
33+
/// | `NotFound` | one of the blocks's children isn't in the reachable set |
34+
/// | `IllegalCodec` | the passed codec isn't supported |
35+
/// | `Serialization` | the passed block doesn't match the passed codec |
36+
/// | `IllegalArgument` | the block isn't in memory, etc. |
3837
pub fn create(codec: u64, data: *const u8, len: u32) -> Result<u32>;
3938

40-
/// Reads the identified block into obuf, starting at offset, reading _at most_ len bytes.
39+
/// Reads the block identified by `id` into `obuf`, starting at `offset`, reading _at most_
40+
/// `max_len` bytes.
41+
///
4142
/// Returns the number of bytes read.
43+
///
44+
/// # Errors
45+
///
46+
/// | Error | Reason |
47+
/// |-------------------|---------------------------------------------------|
48+
/// | `InvalidHandle` | if the handle isn't known. |
49+
/// | `IllegalArgument` | if the passed buffer isn't valid, in memory, etc. |
4250
pub fn read(id: u32, offset: u32, obuf: *mut u8, max_len: u32) -> Result<u32>;
4351

4452
/// Returns the codec and size of the specified block.
45-
pub fn stat(id: u32) -> Result<fvm_shared::sys::out::ipld::IpldStat>;
53+
///
54+
/// # Errors
55+
///
56+
/// | Error | Reason |
57+
/// |-----------------|----------------------------|
58+
/// | `InvalidHandle` | if the handle isn't known. |
59+
pub fn stat(id: u32) -> Result<IpldStat>;
4660

4761
// TODO: CID versions?
4862

49-
/// Computes the given block's CID, returning the actual size of the CID.
63+
/// Computes the given block's CID, writing the resulting CID into `cid`, returning the actual
64+
/// size of the CID.
5065
///
51-
/// If the CID is longer than cid_max_len, no data is written and the actual size is returned.
66+
/// If the CID is longer than `cid_max_len`, no data is written and the actual size is returned.
5267
///
5368
/// The returned CID is added to the reachable set.
69+
///
70+
/// # Errors
71+
///
72+
/// | Error | Reason |
73+
/// |-------------------|---------------------------------------------------|
74+
/// | `InvalidHandle` | if the handle isn't known. |
75+
/// | `IllegalCid` | hash code and/or hash length aren't supported. |
76+
/// | `IllegalArgument` | if the passed buffer isn't valid, in memory, etc. |
5477
pub fn cid(
5578
id: u32,
5679
hash_fun: u64,

‎sdk/src/sys/message.rs

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,33 @@
1+
//! Syscalls for reading message metadata.
2+
13
super::fvm_syscalls! {
24
module = "message";
35

46
/// Returns the caller's actor ID.
7+
///
8+
/// # Errors
9+
///
10+
/// None
511
pub fn caller() -> Result<u64>;
612

713
/// Returns the receiver's actor ID (i.e. ourselves).
14+
///
15+
/// # Errors
16+
///
17+
/// None
818
pub fn receiver() -> Result<u64>;
919

1020
/// Returns the method number from the message.
21+
///
22+
/// # Errors
23+
///
24+
/// None
1125
pub fn method_number() -> Result<u64>;
1226

13-
/// Returns the value that was received, as little-Endian
14-
/// tuple of u64 values to be concatenated in a u128.
15-
pub fn value_received() -> Result<fvm_shared::sys::TokenAmount>;
27+
/// Returns the value that was received.
28+
///
29+
/// # Errors
30+
///
31+
/// None
32+
pub fn value_received() -> Result<super::TokenAmount>;
1633
}

‎sdk/src/sys/mod.rs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
//! This module defines the low-level syscall FFI "shims".
2+
#[doc(inline)]
3+
pub use fvm_shared::sys::TokenAmount;
4+
15
pub mod actor;
26
pub mod crypto;
37
//#[cfg(feature = "debug")]

0 commit comments

Comments
 (0)