Simplify the C API

[edubart]

Context

Our C API is currently being used to create machine bindings in Lua, Rust, Go and TypeScript languages. Since this, we noticed there are some pain points when creating C bindings in those languages, we could make a refactor to improve it, make it smaller and simpler.

Subtasks

• Use a JSON string instead of C data structures for loading machines, then deprecate the C config structures. This will make it much easier to bind to other languages, and more proof to mistakes when managing C configs.
• Combine all write/read CSRs methods into a single method using CSR enumerations, this will make the C API much smaller, simplifying the binding work in case someone is not using a binding generator. We can be even more drastic and combine all read/write methods that fits an uint64 into a single write/read method shared for all registers and CSRs, and use a new enumeration.
• Stop passing double pointers for error messages in all methods, instead all methods should return an error code, and set an error message that can be optionally inspected with cm_get_last_error_message(machine).
• Try to minimize the need of some cm_delete_* methods, for example cm_delete_semantic_version could be removed by making it always static allocated.
• Some dynamic arrays that have bounded limits could also be replaced with fixed arrays, for example doing this with cm_merkle_tree_proof we could remove cm_delete_merkle_tree_proof . Similar we could maybe remove cm_delete_memory_range_config and cm_delete_memory_range_descr_array .

[tuler]

Those changes would help as well with the Node.js binding I'm working on. I have ~400 lines (probably badly written) only to handle config.

[tuler]

Side node: cm_reset_uarch should be called cm_reset_uarch_halt_flag, for consistency with other reset methods.

[diegonehab]

That’s not what it does. It really resets the entirety of uarch. Including RAM and all other registers.

[tuler]

That’s not what it does. It really resets the entirety of uarch. Including RAM and all other registers.

So documentation should be fixed.

machine-emulator/src/machine-c-api.h

Line 1845 in 77fb173

/// \brief Resets the value of the microarchitecture halt flag.

[diegonehab]

@mpernambuco can you take a look?

[mpernambuco]

@mpernambuco can you take a look?

#211

[GCdePaula]

I wanted to relate our experience on creating Rust binding.

• The bindings for Rust in general haven’t been particularly hard to create. Like, the low-level bindings are automatic. Our wrapper to make it idiomatic does require some manual work, but it wasn't particularly hard.
• It was easy building the machine as part of Rust build pipeline, and linking statically.
• The read/write register methods were a bit laborious though.
• Rust deals ok with the double pointer for error messages. In any case, the proposed simplification would help.
• The runtime config was not a problem to use. Is there a default runtime config? I think I copied "rollups defaults" from cartesi-machine.lua. I also copied some of the asserts.
• The C machine config structures is a bit unwieldy.

I was initially confused me about the machine config. I think it's because there are instances of it created and managed by us (like in the create function), and there are instances of it created and managed by the emulator. It was easy to deal with the one created and managed by the emulator. I had no problem accessing the fields. No problem freeing memory either, we just need to wrap it in another Rust object and implement Drop correctly.

On using json for machine config. For creating a machine, I think that may help a lot. For querying the machine about the initial config, I think it would not be super ergonomic, but it would be easy, and it may be the best solution

I have a feeling most users will be after the same few fields in the machine config (like the address and length of the tx/rx buffer). Maybe dedicated methods to read commonly needed fields could help?

Or maybe specific functions for common operations, like clearing rx/tx buffer. Or writing an input (setting all the correct registers and buffers). Or reading an input (parsing all the correct registers). I was copying these operations from cartesi-machine.lua. Having them on the API would be more ergonomic, but I don't know if it makes sense. It could give you more freedom to change things though.