Why is import/export macros necessary?

[nazar-pc]

This might be one of those stupid questions because I do not really know what I'm talking about here.

However, I was reading https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-cc.adoc a few days ago and now wondering why it doesn't seem to be used instead of what seems to be a custom calling convention that constraints inputs to [i|u][32|64|size]?

For example it would be possible to use small structs or other integer types (like u8) as long as caller can set up registers correctly. Also since PVM is effectively a library, maybe it would be possible to compile it as an actual library instead of binary. That way library before linking with polkatool might be usable as a regular C library.

Calls to the host are a bit different of course due to ecalli usage, but similar logic generally applies I think. BTW I was trying to understand what why is ecalli used instead of ecall, but didn't really find an explanation, I also failed to find anything relevant in chapters 19 of both unprivileged and privileged specs mentioned here (actual link to the spec and version would be nice.

I might be completely off here, in which case I'd appreciate links where I can learn more about this stuff.

[koute]

seems to be a custom calling convention that constraints inputs to [i|u][32|64|size]?

It's not a custom calling convention; it uses the standard calling convention, but the types are constrained to only the primitive types because anything more than that essentially requires using the stack**, which means reading/writing memory, which is why it needs to be done manually and not automagically hidden behind macro machinery.

(** - except the small types like u8 etc., which under the hood would still be passed as usize, and which are not supported by the macro because it's somewhat ambiguous who/if should clear the upper bits; this reminds me, I might have to remove support for passing u32s on 64-bit)

Also since PVM is effectively a library, maybe it would be possible to compile it as an actual library instead of binary. That way library before linking with polkatool might be usable as a regular C library.

I'm not entirely sure what you're trying to say here, but yes, you can use standard tooling to produce libraries/link multiple libraries/whatever, and only at the very end build a single ELF file and pass that into polkatool.

I was trying to understand what why is ecalli used instead of ecall

To be able to statically figure out which exact host calls are used by a given binary; with ecall this is not possible since it must implicitly take the host call number from a register.

Note that ecalli is not a RISC-V instruction; it's PVM-specific.

Why is import/export macros necessary?

To explicitly have a list of imports/exports, instead of relying on the janky system that native binaries use where undefined symbols are imports (and we can't tell whether an undefined symbol is meant to be an import, or it's a programmer error) and visible symbols are exports (there's usually a lot of garbage symbols that are unintentionally emitted as visible, especially when people write C). Having the macros and using custom sections for imports/exports sidesteps these issues.

[nazar-pc]

It's not a custom calling convention; it uses the standard calling convention, but the types are constrained to only the primitive types because anything more than that essentially requires using the stack**, which means reading/writing memory, which is why it needs to be done manually and not automagically hidden behind macro machinery.

That makes sense to me from typed API point of view. What would you say about having a macro option that exports "raw" function "as is", assuming users can set up registers and memory correctly for it to succeed? I would expect this to require very little actual metadata, maybe just a pointer to the function itself.

Specifically I'm experimenting with a system that has predictable inputs (always a single pointer argument, which fits current API) and single return type (u8, which doesn't fit current API without expanding it to the register size explicitly). So I'd rather set registers and call untyped function directly and had as little PolkaVM-specific code as possible, ideally none.

I'm not entirely sure what you're trying to say here, but yes, you can use standard tooling to produce libraries/link multiple libraries/whatever, and only at the very end build a single ELF file and pass that into polkatool.

This is an area where I do not have sufficient depth of knowledge right now (I read some stuff about ELF format and such, but ultimately I know quite little). What I meant is that right now, at least according to build-examples.sh, polkatool expects an executable binary (cargo build --bin/crate-type = bin), which results in also requiring #[no_main], despite the fact that there isn't really a single entrypoint, it is a library with many entrypoints. What I would like/expect is something like crate-type = cdylib or crate-type = staticlib instead.

And if I could just tell polkatool which functions to export explicitly that'd be just awesome (assuming raw API mentioned above is used, so it doesn't need to know much beyond function location, at least according to my limited understanding).

To be able to statically figure out which exact host calls are used by a given binary; with ecall this is not possible since it must implicitly take the host call number from a register.

I'm not sure why this is necessary, what I saw in the code is that you need an "index" of a host function, which is represented by a metadata pointer that follows ecalli instruction in the assembly, the index or metadata pointer could just as well be passed via register ecall expects.

Note that ecalli is not a RISC-V instruction; it's PVM-specific.

Yes, I did notice that. I also noticed that ecall seem to be explicitly forbidden at runtime. While I'd prefer to not have any custom instructions inserted or supported during runtime and instead use ecall with domain-specific call types (only two really: call into a different contract that only require a single pointer as input and sbrk or even simply brk instruction that allocates memory, nothing else).

To explicitly have a list of imports/exports, instead of relying on the janky system that native binaries use where undefined symbols are imports (and we can't tell whether an undefined symbol is meant to be an import, or it's a programmer error) and visible symbols are exports (there's usually a lot of garbage symbols that are unintentionally emitted as visible, especially when people write C). Having the macros and using custom sections for imports/exports sidesteps these issues.

Thanks for elaborating, this makes a lot of sense.

What if it was possible to specify list of exports explicitly (for example via CLI options) and imports are not a concern (implemented as custom host calls using ecall that PolkaVM doesn't need to know anything about and handled as InterruptKind::Ecall explicitly by PolkaVM user), would that mean that those macros can be skipped completely?

[koute]

What would you say about having a macro option that exports "raw" function "as is", assuming users can set up registers and memory correctly for it to succeed?

By "raw" do you mean go YOLO and depend on the user being able to exactly match the compiler's implicit ABI in cases like e.g. the function taking structs as params?

I think that's too error-prone, as you really need to know what you're doing and if the compiler's ABI ever changes (and it is currently unstable) then you're screwed, so I have no plans to add something like that. If you really want to do it you could just jerry rig your own macro that just emits the metadata and nothing else.

polkatool expects an executable binary (cargo build --bin/crate-type = bin), which results in also requiring #[no_main]

We maybe could get rid of this now and have it work as cdylib. It's not a fundamental limitation; it's just an artifact of how the bare metal targets work in rustc, because cdylib means "shared library" and you don't have shared libraries on bare metal.

the index or metadata pointer could just as well be passed via register ecall expects.

No, it couldn't, again, because then it'd make it impossible to statically figure out which host calls the program can trigger. Imagine this piece of code:

hostcall_num = foobar()
ecall

Which host calls can this trigger? You don't know. It depends on how foobar is implemented; it might use a pseudorandom number generator, it might depend on a global variable, or it might just always return the number 4. You'd have to solve the halting problem to figure this out.

While I'd prefer to not have any custom instructions inserted or supported during runtime

I'm really confused by this statement; every PVM instruction is technically a custom instruction because the VM doesn't use RISC-V machine code (RISC-V code only exists before you call polkatool/polkavm-linker, then it's translated to PVM machine code), and we don't support self-modifying code anyway (so you can't have your program generate machine code and have it execute it, nor can it even inspect it as the program's machine code is not loaded into its address space).

What if it was possible to specify list of exports explicitly (for example via CLI options) and imports are not a concern (implemented as custom host calls using ecall that PolkaVM doesn't need to know anything about and handled as InterruptKind::Ecall explicitly by PolkaVM user), would that mean that those macros can be skipped completely?

Are you asking whether it's theoretically possible? Yes, in theory you could make it not require any macros at all.

[nazar-pc]

By "raw" do you mean go YOLO and depend on the user being able to exactly match the compiler's implicit ABI in cases like e.g. the function taking structs as params?

I think that's too error-prone, as you really need to know what you're doing and if the compiler's ABI ever changes (and it is currently unstable) then you're screwed, so I have no plans to add something like that. If you really want to do it you could just jerry rig your own macro that just emits the metadata and nothing else.

My understanding was that by simply following https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-cc.adoc#integer-calling-convention (with correction that ILP32E/LP64E have only 6 argument registers instead of 8) it is non-ambiguous as to what compiler will generate and how to call it. Are you saying that isn't actually the case?

No, it couldn't, again, because then it'd make it impossible to statically figure out which host calls the program can trigger.

The missing piece for me is: why it is necessary to know statically and just reading it from registers at runtime is not enough?

every PVM instruction is technically a custom instruction because the VM doesn't use RISC-V machine code (RISC-V code only exists before you call polkatool/polkavm-linker, then it's translated to PVM machine code)

This is an extremely helpful piece information for my understanding. I assumed the output of the linker was a RISC-V code. It obviously can't run directly and would have to be compiled to the target machine code (I guess unless running in a hardware-accelerated VM on RISC-V hardware). It did look like a RISC-V though on the surface from various API names and such.

Are you asking whether it's theoretically possible? Yes, in theory you could make it not require any macros at all.

This is a sufficient answer for now, just wanted to make sure I understand this part.

[koute]

My understanding was that by simply following https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-cc.adoc#integer-calling-convention (with correction that ILP32E/LP64E have only 6 argument registers instead of 8) it is non-ambiguous as to what compiler will generate and how to call it. Are you saying that isn't actually the case?

I didn't say it was ambiguous. I said it's unstable (so it can change from one compiler version to another), and that it's prone to misuse unless you know what you're doing, e.g. that struct you've defined on your host might be padded differently than the one defined in your guest program; if you get such mismatch then it's instant undefined behavior - your program is broken, and you get no error message that it is, and you spend the next two weeks debugging and trying to figure out why it's broken. Forcing people to explicitly marshal more complex types is a useful footgun reducing feature.

The missing piece for me is: why it is necessary to know statically and just reading it from registers at runtime is not enough?

Because it's a useful property. We want to be able to tell which host calls a program can call (e.g. imagine we want to remove or deprecate a host call - we can then fetch all programs which exist and check how many will be affected), we want to be able to produce a nice error message if the program you're trying to load/run needs a host call that your host doesn't support.

[nazar-pc]

I said it's unstable (so it can change from one compiler version to another)

The spec itself is unstable, that is true, but beyond that I don't think any breaking changes are expected.

and that it's prone to misuse unless you know what you're doing, e.g. that struct you've defined on your host might be padded differently than the one defined in your guest program; if you get such mismatch then it's instant undefined behavior - your program is broken, and you get no error message that it is, and you spend the next two weeks debugging and trying to figure out why it's broken.

That is something I just assumed to be the case, there is no way around it.

Forcing people to explicitly marshal more complex types is a useful footgun reducing feature.

I'd argue it is already the case and unavoidable in non-trivial cases. I can specify a pointer as usize argument, where the pointer leads and what layout/alignment that type has is something user has to know before calling, so I don't believe there is a fundamental change in allowing to specify something like this directly:

#[repr(C)]
pub struct S {
    a: u32,
    b: u32,
}

We want to be able to tell which host calls a program can call (e.g. imagine we want to remove or deprecate a host call - we can then fetch all programs which exist and check how many will be affected)

This feels a bit orthogonal to the code being executed, more like extra metadata to be stored alongside the code itself, though I understand the appeal of it, thanks for explaining.

we want to be able to produce a nice error message if the program you're trying to load/run needs a host call that your host doesn't support

True, but the same error will inevitably happen at runtime and user will be able to see it too, just at a later time.