generate a machine-readable syscall descriptor file

[raulk]

Two SDK teams (@ainhoa-a and @dtynn) have independently come up with the idea of creating a machine-readable JSON (or like) descriptor of FVM syscalls out of the FFI definitions (source of truth).

Assuming JSON, this would likely be some form of a top-level array, containing one entry per syscall. Every entry would contain:

• name of the module
• name of the function
• whether it's privileged or not (see Privilege system for syscalls #468)
• input parameters (array)
• return value, if any (we don't support multi-value returns)
• error numbers

An open question is whether to include documentation or not.

[raulk]

@ainhoa-a and @dtynn could you confirm if this would be useful to you?

[raulk]

What types would you expect to see on this descriptor? If we generate them from the FFI definitions, you'd see low level types and would lose high-level types like Cids, structs, etc.

[dtynn]

@ainhoa-a and @dtynn could you confirm if this would be useful to you?

Yes.
With the descriptor, we can check if the syscalls are compatible between different sdks automatically.
That would be useful in ci checks and upgardings, etc.

What types would you expect to see on this descriptor? If we generate them from the FFI definitions, you'd see low level types and would lose high-level types like Cids, structs, etc.

go down all the way util the primitive types is definitely not a good way.
Based on my experience in using reflect in golang, we could setup a collection of don't go lower' types, like Cid`, and let the traversor stop at these types.
However, I don't know for sure how to elegantly achieve the way above in rust. This could be discussed in the future.

[hunjixin]

as dtynn mention. for tinygo sdk, one is we can use tool to check if syscall change or new syscall add when upgrade, and another usage is we can use generate syscall code through this difinition file directly.
and in my rough idea, in this description file, there are two sections, one section describes the type information, one section describes the module/methods information, and the type association id is used in the input and output for the method. In addition, I hope to add a comment field to the method/type to describe the usage and precautions of the type/method. but this maybe unable to implement through a simple macro.

[emmanuelm41]

@ainhoa-a and @dtynn could you confirm if this would be useful to you?

Sorry for the lateness in the response! I think it would definitely help us to link our syscall definition to filecoin one. I think we should have high-level definitions on arguments and return types, and some section were we can check how those types are defined.