@riseandshaheen/libcma 0.1.0-alpha.0

package/deps/machine-guest-tools/sys-utils/libcmt/include/libcmt/buf.h

@@ -0,0 +1,82 @@
+/* Copyright Cartesi and individual authors (see AUTHORS)
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** @file
+ * @defgroup libcmt_buf buf
+ * slice of contiguous memory
+ *
+ * @ingroup libcmt
+ * @{ */
+#ifndef CMT_BUF_H
+#define CMT_BUF_H
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+/** A slice of contiguous memory from @b begin to @b end, as an open range.
+ * Size can be taken with: `end - begin`.
+ *
+ * `begin == end` indicate an empty buffer */
+typedef struct {
+    uint8_t *begin; /**< begin of memory region */
+    uint8_t *end;   /**< end of memory region */
+} cmt_buf_t;
+
+/** Initialize @p me buffer backed by @p data, @p length bytes in size
+ *
+ * @param [out] me     a uninitialized instance
+ * @param [in]  length size in bytes of @b data
+ * @param [in]  data   the backing memory to be used.
+ *
+ * @note @p data memory must outlive @p me.
+ * user must copy the contents otherwise */
+void cmt_buf_init(cmt_buf_t *me, size_t length, void *data);
+
+/** Split a buffer in two, @b lhs with @b lhs_length bytes and @b rhs with the rest
+ *
+ * @param [in,out] me         initialized buffer
+ * @param [in]     lhs_length bytes in @b lhs
+ * @param [out]    lhs        left hand side
+ * @param [out]    rhs        right hand side
+ *
+ * @return
+ * - 0 success
+ * - negative value on error. -ENOBUFS when length(me) < lhs_length. */
+int cmt_buf_split(const cmt_buf_t *me, size_t lhs_length, cmt_buf_t *lhs, cmt_buf_t *rhs);
+
+/** Length in bytes of @p me
+ *
+ * @param [in] me     initialized buffer
+ *
+ * @return
+ * - size in bytes */
+size_t cmt_buf_length(const cmt_buf_t *me);
+
+/** Print the contents of @b me buffer to stdout
+ *
+ * @param [in] begin          start of memory region
+ * @param [in] end            end of memory region
+ * @param [in] bytes_per_line bytes per line (must be a power of 2). */
+void cmt_buf_xxd(void *begin, void *end, int bytes_per_line);
+
+/** Take the substring @p x from @p xs start to the first @p , (comma).
+ * @param [out]    x           substring
+ * @param [in,out] xs          string (iterator)
+ *
+ * @note @p x points inside @p xs, make a copy if it outlives @p xs. */
+bool cmt_buf_split_by_comma(cmt_buf_t *x, cmt_buf_t *xs);
+
+#endif /* CMT_BUF_H */
+/** @} */

package/deps/machine-guest-tools/sys-utils/libcmt/include/libcmt/io.h

@@ -0,0 +1,168 @@
+/* Copyright Cartesi and individual authors (see AUTHORS)
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** @file
+ * @defgroup libcmt_io_driver Cartesi Machine Input/Output Driver
+ * Low level abstraction of the Cartesi Machine kernel driver.
+ *
+ * Interaction is as follows:
+ * - Open the kernel device and mmap the shared memory ranges (tx and rx) with:
+ *   @ref cmt_io_init.
+ * - Retrieve the memory regions from the library with: @ref cmt_io_get_tx and
+ *   @ref cmt_io_get_rx.
+ * - Do requests (next input, emit output ...) by yielding the control back to
+ *   the emulator with: @ref cmt_io_yield.
+ *
+ * Lets look at some code:
+ *
+ * @include examples/io.c
+ *
+ * There are two implementations provided: `ioctl` that interacts with the
+ * cartesi-machine linux driver and `mock` that reads and writes the host
+ * filesystem, used for testing.
+ *
+ * @section Environment variables
+ *
+ * this module exposes two environment variables: @p CMT_DEBUG and @p CMT_INPUTS.
+ *
+ * @p CMT_DEBUG prints runtime information during application execution.
+ *
+ * ```
+ * CMT_DEBUG=yes ./application
+ * ```
+ *
+ * @p CMT_INPUTS feeds inputs to the mock (ignored for ioctl).
+ *
+ * ```
+ * CMT_INPUTS=0:advance.bin,1:inspect.bin ./application
+ * ```
+ *
+ * @ingroup libcmt
+ * @{ */
+#ifndef CMT_IO_H
+#define CMT_IO_H
+#include "buf.h"
+#include <stdint.h>
+
+/** Device */
+enum {
+    HTIF_DEVICE_YIELD = 2, /**< Yield device */
+};
+
+/** Commands */
+enum {
+    HTIF_YIELD_CMD_AUTOMATIC = 0, /**< Automatic yield */
+    HTIF_YIELD_CMD_MANUAL = 1,    /**< Manual yield */
+};
+
+/** Automatic reasons */
+enum {
+    HTIF_YIELD_AUTOMATIC_REASON_PROGRESS = 1,  /**< Progress */
+    HTIF_YIELD_AUTOMATIC_REASON_TX_OUTPUT = 2, /**< emit an output */
+    HTIF_YIELD_AUTOMATIC_REASON_TX_REPORT = 4, /**< emit a report */
+};
+
+/** Manual reasons */
+enum {
+    HTIF_YIELD_MANUAL_REASON_RX_ACCEPTED = 1,  /**< Accept and load next input */
+    HTIF_YIELD_MANUAL_REASON_RX_REJECTED = 2,  /**< Reject and revert */
+    HTIF_YIELD_MANUAL_REASON_TX_EXCEPTION = 4, /**< emit a exception and halt execution */
+};
+
+/** Reply reason when requesting @ref HTIF_YIELD_REASON_RX_ACCEPTED or HTIF_YIELD_REASON_RX_REJECTED */
+enum {
+    HTIF_YIELD_REASON_ADVANCE = 0, /**< Input is advance */
+    HTIF_YIELD_REASON_INSPECT = 1, /**< Input is inspect */
+};
+
+typedef struct {
+    cmt_buf_t tx[1];
+    cmt_buf_t rx[1];
+    int fd;
+} cmt_io_driver_ioctl_t;
+
+typedef struct {
+    cmt_buf_t tx[1];
+    cmt_buf_t rx[1];
+    cmt_buf_t inputs_left;
+
+    int input_type;
+    char input_filename[128];
+    char input_fileext[16];
+
+    int input_seq;
+    int output_seq;
+    int report_seq;
+    int exception_seq;
+    int gio_seq;
+} cmt_io_driver_mock_t;
+
+/** Implementation specific cmio state. */
+typedef union cmt_io_driver {
+    cmt_io_driver_ioctl_t ioctl;
+    cmt_io_driver_mock_t mock;
+} cmt_io_driver_t;
+
+/** yield struct cmt_io_yield */
+typedef struct cmt_io_yield {
+    uint8_t dev;
+    uint8_t cmd;
+    uint16_t reason;
+    uint32_t data;
+} cmt_io_yield_t;
+
+/** Open the io device and initialize the driver. Release its resources with @ref cmt_io_fini.
+ *
+ * @param [in] me A uninitialized @ref cmt_io_driver state
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_io_init(cmt_io_driver_t *me);
+
+/** Release the driver resources and close the io device.
+ *
+ * @param [in] me A successfully initialized state by @ref cmt_io_init
+ * @note usage of @p me after this call is a BUG and will cause undefined behaviour */
+void cmt_io_fini(cmt_io_driver_t *me);
+
+/** Retrieve the transmit buffer @p tx
+ *
+ * @param [in] me A successfully initialized state by @ref cmt_io_init
+ * @return
+ * - writable memory region as defined in the setup structure (check @ref cmt_buf_t)
+ * @note memory is valid until @ref cmt_io_fini is called. */
+cmt_buf_t cmt_io_get_tx(cmt_io_driver_t *me);
+
+/** Retrieve the receive buffer @p rx
+ *
+ * @param [in] me A successfully initialized state by @ref cmt_io_init
+ * @return
+ * - readable memory region as defined in the setup structure (check @ref cmt_buf_t)
+ * @note memory is valid until @ref cmt_io_fini is called. */
+cmt_buf_t cmt_io_get_rx(cmt_io_driver_t *me);
+
+/** Perform the yield encoded in @p rr.
+ *
+ * @param [in] me A successfully initialized state by @ref cmt_io_init
+ * @param [in,out] rr Request and Reply
+ * @return
+ * - 0 on success
+ * - negative errno code on error */
+int cmt_io_yield(cmt_io_driver_t *me, cmt_io_yield_t *rr);
+
+#endif /* CMT_IO_H */

package/deps/machine-guest-tools/sys-utils/libcmt/include/libcmt/keccak.h

@@ -0,0 +1,131 @@
+/* Copyright Cartesi and individual authors (see AUTHORS)
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** @file
+ * @defgroup libcmt_keccak keccak
+ * Keccak 256 digest
+ *
+ * Data can be inserted in pieces:
+ * @code
+ * ...
+ * uint8_t h[CMT_KECCAK_LENGTH];
+ * cmt_keccak_t st[1];
+ *
+ * cmt_keccak_init(st);
+ * cmt_keccak_update(st, 1, "h");
+ * cmt_keccak_update(st, 1, "e");
+ * cmt_keccak_update(st, 1, "l");
+ * cmt_keccak_update(st, 1, "l");
+ * cmt_keccak_update(st, 1, "o");
+ * cmt_keccak_final(st, h);
+ * ...
+ * @endcode
+ *
+ * all at once:
+ * @code
+ * ...
+ * const char data[] = "hello";
+ * uint8_t h[CMT_KECCAK_LENGTH];
+ * cmt_keccak_data(h, sizeof(data)-1, data);
+ * ...
+ * @endcode
+ *
+ * or with a specialized call to generate @ref funsel data:
+ * @code
+ * ...
+ * uint32_t funsel = cmt_keccak_funsel("FunctionCall(address,bytes)");
+ * ...
+ * @endcode
+ *
+ * Code based on https://github.com/mjosaarinen/tiny_sha3 with the sha3 to
+ * keccak change as indicated by this comment:
+ * https://github.com/mjosaarinen/tiny_sha3#updated-07-aug-15
+ *
+ * @ingroup libcmtcmt
+ * @{ */
+#ifndef CMT_KECCAK_H
+#define CMT_KECCAK_H
+#include <stddef.h>
+#include <stdint.h>
+
+enum {
+    CMT_KECCAK_LENGTH = 32, /**< Bytes in the hash digest */
+};
+
+/** Opaque internal keccak state */
+typedef union cmt_keccak_state {
+    uint8_t b[200];
+    uint64_t q[25];
+} cmt_keccak_state_t;
+
+/** Opaque Keccak state, used to do hash computations, initialize with:
+ * - @ref cmt_keccak_init
+ * - @ref CMT_KECCAK_INIT
+ * - @ref CMT_KECCAK_DECL */
+typedef struct cmt_keccak {
+    cmt_keccak_state_t st;
+    int pt, rsiz;
+} cmt_keccak_t;
+
+/** Initialize a @ref cmt_keccak_t hasher state.
+ *
+ * @param [out] state uninitialized @ref cmt_keccak_t */
+void cmt_keccak_init(cmt_keccak_t *state);
+
+/** Hash @b n bytes of @b data
+ *
+ * @param [in,out] state  initialize the hasher state
+ * @param [in]     length bytes in @b data to process
+ * @param [in]     data   data to hash */
+void cmt_keccak_update(cmt_keccak_t *state, size_t n, const void *data);
+
+/** Finalize the hash calculation from @b state and store it in @b md
+ *
+ * @param [in]  state initialize the hasher state (with all data already added to it)
+ * @param [out] md    32bytes to store the computed hash */
+void cmt_keccak_final(cmt_keccak_t *state, void *md);
+
+/** Hash all @b n bytes of @b data at once
+ *
+ * @param [in]  length bytes in @b data to process
+ * @param [in]  data   data to hash
+ * @param [out] md     32bytes to store the computed hash
+ * @return pointer to @b md
+ *
+ * Equivalent to:
+ * @code
+ * cmt_keccak_t st = CMT_KECCAK_INIT(&st);
+ * cmt_keccak_update(&st, n, data);
+ * cmt_keccak_final(&st, md);
+ * return md;
+ * @endcode */
+uint8_t *cmt_keccak_data(size_t length, const void *data, uint8_t md[CMT_KECCAK_LENGTH]);
+
+/** Compute the function selector from the solidity declaration @p decl
+ *
+ * @param [in]  decl   solidity call declaration, without variable names
+ * @param [out] funsel function selector as described by @ref funsel
+ * @return A @p funsel value as if defined by @ref CMT_ABI_FUNSEL
+ *
+ * Example usage:
+ * @code
+ * ...
+ * uint32_t funsel = cmt_keccak_funsel("FunctionCall(address,bytes)");
+ * ...
+ * @endcode
+ */
+uint32_t cmt_keccak_funsel(const char *decl);
+#endif /* CMT_KECCAK_H */
+/** $@} */

package/deps/machine-guest-tools/sys-utils/libcmt/include/libcmt/merkle.h

@@ -0,0 +1,118 @@
+/* Copyright Cartesi and individual authors (see AUTHORS)
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** @file
+ * @defgroup libcmt_merkle merkle
+ * merkle tree of keccak256 hashes
+ *
+ * @ingroup libcmt
+ * @{ */
+#ifndef CMT_MERKLE_H
+#define CMT_MERKLE_H
+#include "keccak.h"
+
+enum {
+    CMT_MERKLE_TREE_HEIGHT = 63, /**< merkle tree height */
+};
+
+/** Opaque Merkle tree state.
+ * initialize with: @ref cmt_merkle_init */
+typedef struct {
+    uint64_t leaf_count;                                      /**< number of leaves in tree */
+    uint8_t state[CMT_MERKLE_TREE_HEIGHT][CMT_KECCAK_LENGTH]; /**< hashes of complete subtrees */
+} cmt_merkle_t;
+
+/** Initialize a @ref cmt_merkle_t tree state.
+ *
+ * @param [in] me    uninitialized state */
+void cmt_merkle_init(cmt_merkle_t *me);
+
+/** Resets a @ref cmt_merkle_t to pristine conditions.
+ *
+ * @param [in] me    initialized state */
+void cmt_merkle_reset(cmt_merkle_t *me);
+
+/** Finalize a @ref cmt_merkle_t tree state.
+ *
+ * @param [in] me    initialized state
+ *
+ * @note use of @p me after this call is undefined behavior. */
+void cmt_merkle_fini(cmt_merkle_t *me);
+
+/** Load the a @ref cmt_merkle_t tree from a @p file handle.
+ *
+ * @param [in] me       either a initialized or uninitialized state
+ * @param [in] filepath which file to save the merkle state
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_merkle_load(cmt_merkle_t *me, const char *filepath);
+
+/** Save the a @ref cmt_merkle_t tree to a @p file handle.
+ *
+ * @param [in] me       either a initialized or uninitialized state
+ * @param [in] filepath which file to save the merkle state
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_merkle_save(cmt_merkle_t *me, const char *filepath);
+
+/** Return number of leaves already in tree
+ *
+ * @param [in,out] me initialized state
+ * @return
+ * - leaf count */
+uint64_t cmt_merkle_get_leaf_count(cmt_merkle_t *me);
+
+/** Append a leaf node
+ *
+ * @param [in,out] me initialized state
+ * @param [in] hash   value of the new leaf
+ *
+ * @return
+ * |          |                                 |
+ * |---------:|---------------------------------|
+ * |         0| success                         |
+ * | -ENOBUFS | indicates that the tree is full |
+ * |       < 0| failure with a -errno value     | */
+int cmt_merkle_push_back(cmt_merkle_t *me, const uint8_t hash[CMT_KECCAK_LENGTH]);
+
+/** Compute the keccak-256 hash of @p data and append it as a leaf node
+ *
+ * @param [in,out] me     initialized state
+ * @param [in]     length size of @p data in bytes
+ * @param [in]     data   array of bytes
+ *
+ * @return
+ * |          |                                 |
+ * |---------:|---------------------------------|
+ * |         0| success                         |
+ * | -ENOBUFS | indicates that the tree is full |
+ * |       < 0| failure with a -errno value     | */
+int cmt_merkle_push_back_data(cmt_merkle_t *me, size_t length, const void *data);
+
+/** Compute the root hash of the merkle tree
+ *
+ * @param [in]  me   initialized state
+ * @param [out] root root hash of the merkle tree */
+void cmt_merkle_get_root_hash(cmt_merkle_t *me, uint8_t root[CMT_KECCAK_LENGTH]);
+
+#endif /* CMT_MERKLE_H */