refactor!: design new simplified C API

[edubart]

This PR is very WIP, it will be a long road before this is finished and polished. I created the PR before the time so I can document here a changelog of what is being changed while I change them. Also to request for comments on the changes.

You can look around the C API files to see how the new simplified API feels. I have also update each function documentation along the way.

Changes

Added:

• Added CM_MCYCLE_MAX macro and set to UINT64_MAX
• Added CM_ACCESS_LOG_TYPE enum with bitwise flags for access log type
• Added cm_get_last_error_message/cm_jsonrpc_get_last_error_message, returning the error message for the most recent failed call.
• Added cm_get_default_runtime_config/cm_jsonrpc_get_default_runtime_config, for now it will return just {}, but we might in the future return a value based on current environment variables, like the Cartesi Node does. People also asked for this function.
• Added views CSRs for HTIF fromhost/tohost for dev/data/cmd (eg. CM_CSR_HTIF_TOHOST_DEV), the idea is to write on fields of these CSRs through cm_write_csr/cm_read_csr.
• Added views CSRs for IFLAGS PRV/X/Y/H (eg. CM_CSR_IFLAGS_H), the idea is to write on fields of these CSRs through cm_write_csr/cm_read_csr.

Removed:

• Remove all structs, complex structs are passed as JSON strings now (configs, access logs and proofs).
• Remove all cm_read_*/cm_write_* of CSRs, except for mcycle/uarch_cycle/uarch_halt_flag.
• Remove all cm_delete_* functions, now any function that returns a string guarantees to maintain the validity of the string pointer until next API call or machine destruction.
• Removed cm_new_default_machine_config
• Removed cm_reset_iflags_*/cm_set_iflags_*/cm_packed_iflags, iflags can be read/written using CSR views CM_CSR_IFLAGS_PRV, CM_CSR_IFLAGS_X, CM_CSR_IFLAGS_Y, CM_CSR_IFLAGS_H.
• Removed the machine-c-defines.h header, its contents was moved to machine-c-api.h.

Renames:

• Renamed *_uarch_reset* -> *_reset_uarch*
• Renamed *_uarch_step* -> *_step_uarch*
• Renamed cm_machine_run -> cm_run
• Renamed cm_create_machine -> cm_create
• Renamed cm_load_machine -> cm_load,
• Renamed cm_machine_run_uarch -> cm_run_uarch
• Renamed CM_PROC_CSR -> CM_CSR
• Renamed cm_create_jsonrpc_machine -> cm_jsonrpc_create_machine
• Renamed cm_load_jsonrpc_machine -> cm_jsonrpc_load_machine
• Renamed cm_get_jsonrpc_machine -> cm_jsonrpc_get_machine
• Renamed cm_create_jsonrpc_mgr -> cm_jsonrpc_create_mgr
• Renamed cm_delete_jsonrpc_mgr -> cm_jsonrpc_destroy_mgr

Changed:

• All all machine runtime config arguments were removed from verify functions, because seems like they were not being used.
• All err_msg arguments were removed, the latest error message can be retrieved from cm_get_last_error_message().
• Changed cm_replace_memory_range, now it takes multiple arguments instead of a struct argument.
• Reorganized the C API intro different categories in the header, making easy for the reader to navigate through the API.
• Replaced all definitions with enums, because they are more friendly for binding generators.
• Polished the API documentation.

Changes rationale

First have in mind the goal of the changes was to simplify usage of the C API in other languages, to minimize the binding work and make easier to create binding generators.

• Overall the C API decreased from 152 functions to 59 functions.
• The rationale of removing _machine from some methods is that most API are related to the machine yet they don't contain the machine word, so here we make this the standard.
• All methods related to jsonrpc were forced to always begin with cm_jsonrpc_, this makes it easier for binding generators to categorize and filter jsonrpc related methods.
• All structs were removed, because binding structs in some languages can be quite a work, also because we will now use JSON strings for complex objects (configs, access logs and proofs).
• All methods that return a C string (for JSON example) will guarantee validity of the string until the same method is called again, saving the need of any deallocating string functions. Most bindings will parse the JSON immediately and duplicate its contents into a special JSON format the language cares about anyway, it's not like people will retain the string pointer stored somewhere, even so the documentation explicitly states its lifetime. This also removes the burden of developers to do C memory management.
• The only methods required to call to free memory are cm_destroy and cm_jsonrpc_destroy_mgr.

[edubart]

Addressed some comments:

• Avoid splitting IFLAGS, introduce CSR views of its fields instead, to avoid creating unpack/pack methods.
• Removed addition of cm_write_word.
• Improved documentation of cm_replace_memory_range
• Renamed *_uarch_step* -> *_step_uarch*
• Removed read/write for CSRs pc and uarch_pc.

[diegonehab]

Addressed some comments:

* Avoid splitting IFLAGS, introduce CSR views of its fields instead, to avoid creating unpack/pack methods.

* Removed addition of `cm_write_word`.

* Improved documentation of `cm_replace_memory_range`

* Renamed `*_uarch_step*` -> `*_step_uarch*`

* Removed read/write for CSRs `pc` and `uarch_pc`.

I think we should keep reset_iflags_Y at least. And we might want to keep read_iflags_X, read_iflags_Y, and read_iflags_H just because everybody uses them.

[diegonehab]

One thing to consider. Are we doing to offer a “raw” version of these JSON functions in the binds, ones that return/receive JSON and other that receive/return parsed objects (like lua tables) or not?

[edubart]

One thing to consider. Are we doing to offer a “raw” version of these JSON functions in the binds, ones that return/receive JSON and other that receive/return parsed objects (like lua tables) or not?

I think I could try making a generic function to translate JSON <-> Lua table, so we don't use raw JSON strings on Lua side. In the worst case if that turns out to be a bit of work or having flaws (such as JSON special values like its NULL), we could have a raw JSON string and on Lua side and use lua-dkjson. For now my concerns is the C API, later I will think more about Lua goodies.

[edubart]

I updated the PR adding back some iflags methods and trying to clarify more how string lifetime for JSON will work (thread local storage per function).