feat: add libdriver

Dockerfile

@@ -66,6 +66,7 @@ RUN make -C ${BUILD_BASE}tools/linux/xhalt/ CROSS_COMPILE="" xhalt.toolchain
 RUN make -C ${BUILD_BASE}tools/linux/htif/ CROSS_COMPILE="" yield.toolchain
 RUN make -C ${BUILD_BASE}tools/linux/rollup/ioctl-echo-loop/ CROSS_COMPILE="" ioctl-echo-loop.toolchain
 RUN make -C ${BUILD_BASE}tools/linux/rollup/rollup/ CROSS_COMPILE="" rollup.toolchain
+RUN make -C ${BUILD_BASE}tools/linux/rollup/libdriver/ CROSS_COMPILE="" rollup.toolchain
 
 # build rust tools
 # ------------------------------------------------------------------------------

linux/libdriver/Makefile

@@ -0,0 +1,10 @@
+doc: doc/theme
+	doxygen doc/Doxyfile
+doc/theme:
+	git clone --depth=1 --branch=v2.2.1 \
+		[email protected]:jothepro/doxygen-awesome-css.git $@
+clean:
+	rm -rf doc/html
+distclean:
+	rm -rf doc/theme
+.PHONY: doc

linux/libdriver/README.md

@@ -0,0 +1,8 @@
+Userspace library to interact with cartesi kernel drivers
+
+- @ref rollup
+- @ref yield
+
+# Getting Started
+
+Download the static library from [cartesi tools](https://github.com/cartesi/machine-emulator-tools/).

linux/libdriver/base/rollup-api.h

@@ -0,0 +1,103 @@
+/** @file
+ * @defgroup rollup rollup
+ * Abstraction of the Cartesi rollup driver API
+ *
+ * Lets look at some code:
+ *
+ * @include examples/rollup.c
+ *
+ * @ingroup driver
+ * @{ */
+#ifndef ROLLUP_API_H
+#define ROLLUP_API_H
+#include<stdbool.h>
+#include<stddef.h>
+#include<stdint.h>
+
+enum {
+	ROLLUP_DRIVER_INVALID_STATE = -1, /**< @ref rollup_driver_loop invalid state */
+	ROLLUP_DRIVER_ADVANCE_STATE =  0, /**< @ref rollup_driver_loop advance state */
+	ROLLUP_DRIVER_INSPECT_STATE =  1, /**< @ref rollup_driver_loop inspect state */
+};
+
+/** contents of @ref rollup_driver_t are implementation specific.
+ * Define it in @p <rollup.h> */
+typedef struct rollup_driver rollup_driver_t;
+
+/** Open the rollup device and initialize the driver
+ *
+ * @param [in] me A uninitialized @ref rollup_driver_t state
+ * @returns
+ * - 0 on success
+ * - -1 on failure */
+int rollup_driver_init(struct rollup_driver *me);
+
+/** Release the driver resources and close the rollup device
+ *
+ * @param [in] me A sucessfuly initialized state by @ref rollup_driver_init
+ * @note usage of @p me after this call is a BUG and will cause undefined behaviour */
+void rollup_driver_fini(struct rollup_driver *me);
+
+/** Create a output, verifiable or not, with the first @p n bytes of @ref
+ * rollup_driver_t.tx
+ *
+ * @param [in] me A sucessfuly initialized state by @ref rollup_driver_init
+ * @param [in] verifiable @p true if this output should be verifiable
+ * @param [in] n size in bytes of the output, contents from @p tx buffer.
+ * @return
+ * - 0 on success
+ * - ENOBUFS in case the requested size is too large. User must split the
+ *   message in smaller chunks. */
+int rollup_driver_write_output(struct rollup_driver *me, bool verifiable, uint64_t n);
+
+/** Create a exception, with the first @p n bytes of @ref rollup_driver_t.tx
+ *
+ * @param [in] me A sucessfuly initialized state by @ref rollup_driver_init
+ * @param [in] verifiable @p true if this output should be verifiable
+ * @param [in] n size in bytes of the message, contents from @p tx buffer.
+ * @return
+ * - 0 on success
+ * - ENOBUFS in case the requested size is too large. User must split the
+ *   message in smaller chunks.
+ *
+ * @note There is no catch mechanism. Execution will be aborted! */
+int rollup_driver_write_exception(struct rollup_driver *me, uint64_t n);
+
+/** Accept this input, wait for the next one.
+ *
+ * @param [in] me A sucessfuly initialized state by @ref rollup_driver_init
+ * @param [in] accept @p true if this input was processed successfuly
+ * @param [out] n size in bytes of the current input.
+ * @return
+ * - ROLLUP_ADVANCE_STATE On advancing state
+ * - ROLLUP_INSPECT_STATE On inspecting state
+ * - Any other value indicates an error condition */
+int rollup_driver_loop(struct rollup_driver *me, uint8_t hash[32], uint64_t *n);
+
+/** Reject this input, revert state back to the previous @ref rollup_driver_loop call.
+ *
+ * @param [in] me A sucessfuly initialized state by @ref rollup_driver_init
+ * @return
+ * 0 on success */
+int rollup_driver_reject_input(struct rollup_driver *me);
+
+/** Retrieve the writable memory region @p tx
+ * @param [in] me A sucessfuly initialized state by @ref rollup_driver_init
+ * @param [out] max size in bytes.
+ *
+ * @return
+ * - pointer to the buffer.
+ * @note memory is live until @ref rollup_driver_fini is called. */
+void *rollup_driver_get_tx(struct rollup_driver *me, size_t *max);
+
+/** Retrieve the writable memory region @p rx
+ * @param [in] me A sucessfuly initialized state by @ref rollup_driver_init
+ * @param [out] max size in bytes.
+ *
+ * @return
+ * - pointer to the buffer.
+ * @note memory is live until @ref rollup_driver_fini is called. */
+const void *rollup_driver_get_rx(struct rollup_driver *me, size_t *max);
+
+#endif /* ROLLUP_API_H */
+/** @} */

linux/libdriver/base/yield-api.h

@@ -0,0 +1,33 @@
+/** @file
+ * @defgroup yield yield
+ * Abstraction of the Cartesi yield driver IOCTL API
+ *
+ * Lets look at some code:
+ *
+ * @include yield.c
+ *
+ * @ingroup driver
+ * @{ */
+#ifndef YIELD_API_H
+#define YIELD_API_H
+
+/** contents of @ref rollup_driver_t are implementation specific.
+ * Define it in @p <yield.h> */
+typedef struct yield_driver yield_driver_t;
+
+/** Open the rollup device and initialize the driver
+ *
+ * @param [in] me A uninitialized @ref rollup_driver_t state
+ * @returns
+ * - 0 on success
+ * - EPERM Operation not permitted */
+int yield_driver_init(struct yield_driver *me);
+
+/** Report the application progress to the emulator.
+ *
+ * @param [in] me A sucessfuly initialized state by @ref yield_driver_init
+ *
+ * @note usage of @p me after this call is a BUG and will cause undefined behaviour */
+int yield_driver_progress(struct yield_driver *me, float progress);
+
+#endif /* YIELD_API_H */

linux/libdriver/build.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+
+${CROSS_COMPILE}gcc -I ioctl -O2 -Wall -pedantic -o ioctl/rollup.o -c ioctl/rollup.c
+${CROSS_COMPILE}gcc -I ioctl -O2 -Wall -pedantic -o ioctl/yield.o -c ioctl/yield.c
+${CROSS_COMPILE}ar rcs libdriver.a ioctl/yield.o ioctl/rollup.o 
+
+${CROSS_COMPILE}gcc -I ioctl -O2 -Wall -pedantic -o examples/rollup examples/rollup.c libdriver.a
+${CROSS_COMPILE}gcc -I ioctl -O2 -Wall -pedantic -o examples/yield examples/yield.c libdriver.a