@deroll/cmio 0.1.0

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

@@ -0,0 +1,589 @@
+/* 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_abi abi
+ *
+ * This is a C library to encode and decode Ethereum Virtual Machine (EVM)
+ * calldata. This format is used to interacts with contracts in the Ethereum
+ * ecosystem.
+ *
+ * We will cover the basic concepts required to use the API we provide, but for
+ * a complete reference consult the solidity specification, it can be found
+ * here: https://docs.soliditylang.org/en/latest/abi-spec.html
+ *
+ * ## Function Selector {#funsel}
+ *
+ * 4 bytes that identify the function name and parameter types. This is used to
+ * distinguish between different formats. To compute it, take the four first
+ * bytes of the `keccak` digest of the solidity function declaration. It should
+ * respect a canonical format and such as having no the variable names, check
+ * docs for details. For reference, for a hypotetical "FunctionName" function,
+ * it should look something like this:
+ * `keccak("FunctionName(type1,type2,...,typeN)");`
+ *
+ * ## Data Sections {#sections}
+ *
+ * After the function selector, we can start encoding the function parameters.
+ * One by one, left to right in two sections. `Static` for fixed sized values.
+ * Think ints, bools, addresses, offsets, etc. Then `Dynamic` for variable
+ * sized data such as the contents of @b bytes. Values that need a dynamic
+ * section will also have an entry in the static section.
+ *
+ * ### Static Section {#static-section}
+ *
+ * [uint](@ref cmt_abi_put_uint), [bool](@ref cmt_abi_put_bool) and
+ * [address](@ref cmt_abi_put_address) values are encoded directly in the
+ * static section. In addition to those, @b bytes gets an entry in both
+ * sections. The static part is done with [this](@ref cmt_abi_put_bytes_s) call.
+ *
+ * ### Dynamic Section {#dynamic-section}
+ *
+ * The Dynamic section encodes the contents of variable sized types. Every entry
+ * in this section requires a corresponding entry in the static section as well.
+ *
+ * So types with variable size are encoded in both sections.
+ *
+ * - `static` section gets some kind of reference / offset to the dynamic section.
+ * - `dynamic` section gets the actual contents
+ *
+ * In more concrete terms, the @b bytes type is encoded first with a call to @ref
+ * cmt_abi_put_bytes_s for its `static` section part and then with a call to
+ * @ref cmt_abi_put_bytes_d for its `dynamic` section part.
+ *
+ * ## Encoder
+ *
+ * Lets look at some code starting with a simple case. A function that encodes
+ * the function selector and a single @b address value into the buffer:
+ *
+ * @includelineno "examples/abi_encode_000.c"
+ *
+ * For @b bytes, we need both sections. static and dynamic.
+ *
+ * @includelineno "examples/abi_encode_001.c"
+ *
+ * For multiple values in the dynamic section, do them in order.
+ *
+ * @includelineno "examples/abi_encode_002.c"
+ *
+ * ## Decoder
+ *
+ * Lets look at code that decodes the examples above. We'll _check_ instead of
+ * _put_ for funsel. And _get_ instead _put_ for most of everything else.
+ *
+ * @includelineno "examples/abi_decode_000.c"
+ *
+ * Retrieving @b bytes is a bit different since the API doesn't do dynamic
+ * memory allocation. @b data points inside the @p rd buffer itself, into its
+ * dynamic section. This makes the API very lightweight and fast but requires
+ * care in its usage. If @p rd gets free'd or reused while there is still a
+ * reference to @p data, we'll get memory corruption. If in doublt create a
+ * copy of @p data and use it instead.
+ *
+ * @includelineno "examples/abi_decode_001.c"
+ *
+ * ## Complete
+ *
+ * Lets look at some code on how to tie everything together. We'll build a @b
+ * echo of sorts that decodes the contents of @p rd and re-encodes it into @p
+ * wr. We'll use previous examples as a starting point to implement encode_echo
+ * and decode_echo. With the entrypoint being @p f. We'll use @ref
+ * cmt_abi_peek_funsel to switch on the message function selector, only one
+ * valid case in this example. Decode and if we succeed, encode it back. If the
+ * caller needs the encoded size, we can compute it by storing @p wr at the
+ * start and compute the difference.
+ *
+ * @includelineno "examples/abi_multi.c"
+ *
+ * @ingroup libcmt
+ * @{ */
+#ifndef CMT_ABI_H
+#define CMT_ABI_H
+#include "buf.h"
+#include <stdbool.h>
+
+enum {
+    CMT_ABI_U256_LENGTH = 32,    /**< length of a evm word in bytes */
+    CMT_ABI_ADDRESS_LENGTH = 20, /**< length of a evm address in bytes */
+};
+
+/** Compile time equivalent to @ref cmt_abi_funsel
+ * @note don't port. use @ref cmt_abi_funsel instead */
+#if __BYTE_ORDER__ != __ORDER_LITTLE_ENDIAN__
+#define CMT_ABI_FUNSEL(A, B, C, D)                                                                                     \
+    (((uint32_t) (D) << 000) | ((uint32_t) (C) << 010) | ((uint32_t) (B) << 020) | ((uint32_t) (A) << 030))
+#else
+#define CMT_ABI_FUNSEL(A, B, C, D)                                                                                     \
+    (((uint32_t) (A) << 000) | ((uint32_t) (B) << 010) | ((uint32_t) (C) << 020) | ((uint32_t) (D) << 030))
+#endif
+
+/** EVM address */
+typedef struct cmt_abi_address {
+    uint8_t data[CMT_ABI_ADDRESS_LENGTH];
+} cmt_abi_address_t;
+
+/** EVM u256 in big endian format */
+typedef struct cmt_abi_u256 {
+    uint8_t data[CMT_ABI_U256_LENGTH];
+} cmt_abi_u256_t;
+
+typedef struct cmt_abi_bytes {
+    size_t length;
+    void *data;
+} cmt_abi_bytes_t;
+
+/** Create a function selector from an array of bytes
+ * @param [in] funsel function selector bytes
+ * @return
+ * - function selector converted to big endian (as expected by EVM) */
+uint32_t cmt_abi_funsel(uint8_t a, uint8_t b, uint8_t c, uint8_t d);
+
+/** Create a frame for the dynamic section. Read the EVM ABI for the details
+ * @param [in] me     reader or writer buffer
+ * @param [out] frame start of the parameters frame
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value |
+ */
+int cmt_abi_mark_frame(const cmt_buf_t *me, cmt_buf_t *frame);
+
+// put section ---------------------------------------------------------------
+
+/** Encode a function selector into the buffer @p me
+ *
+ * @param [in,out] me     a initialized buffer working as iterator
+ * @param [in]     funsel function selector
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value |
+ *
+ * @note A function selector can be compute it with: @ref cmt_keccak_funsel.
+ * It is always represented in big endian. */
+int cmt_abi_put_funsel(cmt_buf_t *me, uint32_t funsel);
+
+/** Encode a native endianness unsigned integer of up to 32bytes of data into
+ * the buffer
+ *
+ * @param [in,out] me   a initialized buffer working as iterator
+ * @param [in]     n    size of @p data in bytes
+ * @param [in]     data pointer to a integer
+ *
+ * @return
+ * |        |                                          |
+ * |-------:|------------------------------------------|
+ * |       0| success                                  |
+ * |-ENOBUFS| no space left in @p me                   |
+ * |   -EDOM| integer not representable in @p 32 bytes |
+ *
+ *
+ * @code
+ * ...
+ * cmt_buf_t it = ...;
+ * uint64_t x = UINT64_C(0xdeadbeef);
+ * cmt_abi_put_uint(&it, sizeof x, &x);
+ * ...
+ * @endcode */
+int cmt_abi_put_uint(cmt_buf_t *me, size_t data_length, const void *data);
+
+/** Encode a big endian unsigned integer of up to 32bytes of data into the
+ * buffer
+ *
+ * @param [in,out] me     a initialized buffer working as iterator
+ * @param [in]     length size of @p data in bytes
+ * @param [in]     data   pointer to a integer
+ *
+ * @return
+ * |        |                                                   |
+ * |-------:|---------------------------------------------------|
+ * |       0| success                                           |
+ * |-ENOBUFS| no space left in @p me                            |
+ * |   -EDOM| integer not representable in @p data_length bytes |
+ *
+ * @code
+ * ...
+ * cmt_buf_t it = ...;
+ * uint8_t small[] = {
+ *     0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ *     0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ *     0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ *     0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
+ * };
+ * cmt_abi_put_uint(&it, sizeof small, &small);
+ * ...
+ * uint8_t big[] = {
+ *     0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ *     0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ *     0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ *     0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ * };
+ * cmt_abi_put_uint(&it, sizeof big, &big);
+ * @endcode
+ * @note This function takes care of endianness conversions */
+int cmt_abi_put_uint_be(cmt_buf_t *me, size_t data_length, const void *data);
+
+/** Encode a @ref cmt_abi_u256_t into the buffer
+ *
+ * @param [in,out] me     a initialized buffer working as iterator
+ * @param [in]     data   pointer to a @ref cmt_abi_u256_t
+ *
+ * @return
+ * |        |                                                   |
+ * |-------:|---------------------------------------------------|
+ * |       0| success                                           |
+ * |-ENOBUFS| no space left in @p me                            | */
+int cmt_abi_put_uint256(cmt_buf_t *me, const cmt_abi_u256_t *value);
+
+/** Encode a bool into the buffer
+ *
+ * @param [in,out] me    a initialized buffer working as iterator
+ * @param [in]     value boolean value
+ *
+ * @return
+ * |        |                        |
+ * |-------:|------------------------|
+ * |       0| success                |
+ * |-ENOBUFS| no space left in @p me |
+ *
+ * @code
+ * ...
+ * cmt_buf_t it = ...;
+ * cmt_abi_put_bool(&it, true);
+ * ...
+ * @endcode
+ * @note This function takes care of endianness conversions */
+int cmt_abi_put_bool(cmt_buf_t *me, bool value);
+
+/** Encode @p address (exactly @ref CMT_ABI_ADDRESS_LENGTH bytes) into the buffer
+ *
+ * @param [in,out] me      initialized buffer
+ * @param [in]     address a value of type @ref cmt_abi_address_t
+ *
+ * @return
+ * |        |                        |
+ * |-------:|------------------------|
+ * |       0| success                |
+ * |-ENOBUFS| no space left in @p me | */
+int cmt_abi_put_address(cmt_buf_t *me, const cmt_abi_address_t *address);
+
+/** Encode the static part of @b bytes into the message,
+ * used in conjunction with @ref cmt_abi_put_bytes_d
+ *
+ * @param [in,out] me     initialized buffer
+ * @param [out]    offset initialize for @ref cmt_abi_put_bytes_d
+ *
+ * @return
+ * |        |                        |
+ * |-------:|------------------------|
+ * |       0| success                |
+ * |-ENOBUFS| no space left in @p me | */
+int cmt_abi_put_bytes_s(cmt_buf_t *me, cmt_buf_t *offset);
+
+/** Encode the dynamic part of @b bytes into the message,
+ * used in conjunction with @ref cmt_abi_put_bytes_d
+ *
+ * @param [in,out] me     initialized buffer
+ * @param [in]     offset initialized from @ref cmt_abi_put_bytes_h
+ * @param [in]     n      size of @b data
+ * @param [in]     data   array of bytes
+ * @param [in]     start  starting point for offset calculation (first byte after funsel)
+ *
+ * @return
+ * |        |                        |
+ * |-------:|------------------------|
+ * |       0| success                |
+ * |-ENOBUFS| no space left in @p me | */
+//int cmt_abi_put_bytes_d(cmt_buf_t *me, cmt_buf_t *offset, size_t n, const void *data, const void *start);
+int cmt_abi_put_bytes_d(cmt_buf_t *me, cmt_buf_t *offset, const cmt_buf_t *frame, const cmt_abi_bytes_t *payload);
+
+/** Reserve @b n bytes of data from the buffer into @b res to be filled by the
+ * caller
+ *
+ * @param [in,out] me     initialized buffer
+ * @param [in]     n      amount of bytes to reserve
+ * @param [out]    res    slice of bytes extracted from @p me
+ * @param [in]     start  starting point for offset calculation (first byte after funsel)
+ *
+ * @return
+ * |        |                        |
+ * |-------:|------------------------|
+ * |       0| success                |
+ * |-ENOBUFS| no space left in @p me |
+ *
+ * @note @p me must outlive @p res.
+ * Create a duplicate otherwise */
+int cmt_abi_reserve_bytes_d(cmt_buf_t *me, cmt_buf_t *of, size_t n, cmt_buf_t *out, const void *start);
+
+// get section ---------------------------------------------------------------
+
+/** Read the funsel without consuming it from the buffer @p me, 0 is returned
+ * if there are less than 4 bytes in the buffer.
+ *
+ * @return
+ * |        |                         |
+ * |-------:|-------------------------|
+ * |    != 0| function selector value |
+ * |       0| failure                 |
+ *
+ * @code
+ * ...
+ * if (cmt_buf_length(it) < 4)
+ * 	return EXIT_FAILURE;
+ * switch (cmt_abi_peek_funsel(it) {
+ * case CMT_ABI_FUNSEL(...): // known type, try to parse it
+ * case CMT_ABI_FUNSEL(...): // known type, try to parse it
+ * default:
+ * 	return EXIT_FAILURE;
+ * }
+ * @endcode */
+uint32_t cmt_abi_peek_funsel(cmt_buf_t *me);
+
+/** Consume funsel from the buffer @p me and ensure it matches @p expected_funsel
+ *
+ * @param [in,out] me       initialized buffer
+ * @param [in]     expected expected function selector
+ *
+ * @return
+ * |        |                        |
+ * |-------:|------------------------|
+ * |       0| success                |
+ * |-ENOBUFS| no space left in @p me |
+ * |-EBADMSG| funsel mismatch       | */
+int cmt_abi_check_funsel(cmt_buf_t *me, uint32_t expected);
+
+/** Decode a @ref cmt_abi_u256_t from the buffer
+ *
+ * @param [in,out] me     initialized buffer
+ * @param [out]    data   value of type @ref cmt_abi_u256_t
+ *
+ * @return
+ * |        |                                                   |
+ * |-------:|---------------------------------------------------|
+ * |       0| success                                           |
+ * |-ENOBUFS| no space left in @p me                            | */
+int cmt_abi_get_uint256(cmt_buf_t *me, cmt_abi_u256_t *value);
+
+/** Decode a unsigned integer of up to 32bytes, in native endianness, from the buffer
+ *
+ * @param [in,out] me     initialized buffer
+ * @param [in]     n      size of @p data in bytes
+ * @param [out]    data   pointer to a integer
+ *
+ * @return
+ * |        |                                                   |
+ * |-------:|---------------------------------------------------|
+ * |       0| success                                           |
+ * |-ENOBUFS| no space left in @p me                            |
+ * |   -EDOM| integer not representable in @p data_length bytes | */
+int cmt_abi_get_uint(cmt_buf_t *me, size_t n, void *data);
+
+/** Decode @p length big-endian bytes, up to 32, from the buffer into @p data
+ *
+ * @param [in,out] me     initialized buffer
+ * @param [in]     length size of @p data in bytes
+ * @param [out]    data   pointer to a integer
+ *
+ * @return
+ * |        |                                                   |
+ * |-------:|---------------------------------------------------|
+ * |       0| success                                           |
+ * |-ENOBUFS| no space left in @p me                            |
+ * |   -EDOM| integer not representable in @p data_length bytes | */
+int cmt_abi_get_uint_be(cmt_buf_t *me, size_t n, void *data);
+
+/** Consume and decode a bool from the buffer
+ *
+ * @param [in,out] me    a initialized buffer working as iterator
+ * @param [out]    value boolean value
+ *
+ * @return
+ * |        |                        |
+ * |-------:|------------------------|
+ * |       0| success                |
+ * |-ENOBUFS| no space left in @p me |
+ *
+ * @code
+ * ...
+ * cmt_buf_t it = ...;
+ * bool value;
+ * int rc = cmt_abi_put_bool(&it, &value);
+ * assert(rc == 0);
+ * ...
+ * @endcode
+ * @note This function takes care of endianness conversions */
+int cmt_abi_get_bool(cmt_buf_t *me, bool *value);
+
+/** Consume and decode @b address from the buffer
+ *
+ * @param [in,out] me      initialized buffer
+ * @param [out]    address value of type @ref cmt_abi_address_t
+ *
+ * @return
+ * |        |                        |
+ * |-------:|------------------------|
+ * |       0| success                |
+ * |-ENOBUFS| no space left in @p me | */
+int cmt_abi_get_address(cmt_buf_t *me, cmt_abi_address_t *value);
+
+/** Create a frame of reference for the dynamic section
+ *
+ * @param [in,out] me    initialized buffer
+ * @param [out]    frame used when encoding dynamic values
+ * @return
+ * |        |                        |
+ * |-------:|------------------------|
+ * |       0| success                |
+ * |-ENOBUFS| no space left in @p me | */
+int cmt_abi_start_frame(cmt_buf_t *me, void *frame);
+
+/** Consume and decode the offset @p of
+ *
+ * @param [in,out] me initialized buffer
+ * @param [out]    of offset to @p bytes data, for use in conjunction with @ref cmt_abi_get_bytes_d
+ *
+ * @return
+ * |        |                        |
+ * |-------:|------------------------|
+ * |       0| success                |
+ * |-ENOBUFS| no space left in @p me | */
+int cmt_abi_get_bytes_s(cmt_buf_t *me, cmt_buf_t of[1]);
+
+/** Decode @b bytes from the buffer by taking a pointer to its contents.
+ *
+ * @param [in]  start initialized buffer (from the start after funsel)
+ * @param [out]    of    offset to @p bytes data
+ * @param [out]    n     amount of data available in @b bytes
+ * @param [out]    data memory range with contents
+ *
+ * @return
+ * |        |                        |
+ * |-------:|------------------------|
+ * |       0| success                |
+ * |-ENOBUFS| no space left in @p me |
+ *
+ * @note @p of can be initialized by calling @ref cmt_abi_get_bytes_s */
+int cmt_abi_get_bytes_d(const cmt_buf_t *start, cmt_buf_t of[1], size_t *n, void **data);
+
+/** Decode @b bytes from the buffer by taking a pointer to its contents.
+ *
+ * @param [in]  start initialized buffer (from the start after funsel)
+ * @param [out] of    offset to @p bytes data
+ * @param [out] n     amount of data available in @b bytes
+ * @param [out] bytes memory range with contents
+ *
+ * @return
+ * |        |                        |
+ * |-------:|------------------------|
+ * |       0| success                |
+ * |-ENOBUFS| no space left in @p me |
+ *
+ * @note @p of can be initialized by calling @ref cmt_abi_get_bytes_s */
+int cmt_abi_peek_bytes_d(const cmt_buf_t *start, cmt_buf_t of[1], cmt_buf_t *bytes);
+
+// raw codec section --------------------------------------------------------
+
+/** Encode @p n bytes of @p data into @p out (up to 32).
+ *
+ * @param [in]  n    size of @p data in bytes
+ * @param [in]  data integer value to encode into @p out
+ * @param [out] out  encoded result
+ *
+ * @return
+ * |        |                                                   |
+ * |-------:|---------------------------------------------------|
+ * |       0| success                                           |
+ * |   -EDOM| integer not representable in @p data_length bytes | */
+int cmt_abi_encode_uint(size_t n, const void *data, uint8_t out[CMT_ABI_U256_LENGTH]);
+
+/** Encode @p n bytes of @p data into @p out (up to 32) in reverse order.
+ *
+ * @param [in]  n    size of @p data in bytes
+ * @param [in]  data integer value to encode into @p out
+ * @param [out] out  encoded result
+ *
+ * @return
+ * |        |                                                   |
+ * |-------:|---------------------------------------------------|
+ * |       0| success                                           |
+ * |   -EDOM| integer not representable in @p data_length bytes |
+ *
+ * @note use @ref cmt_abi_encode_uint instead */
+int cmt_abi_encode_uint_nr(size_t n, const uint8_t *data, uint8_t out[CMT_ABI_U256_LENGTH]);
+
+/** Encode @p n bytes of @p data into @p out (up to 32) in normal order.
+ *
+ * @param [in]  n    size of @p data in bytes
+ * @param [in]  data integer value to encode into @p out
+ * @param [out] out  encoded result
+ *
+ * @return
+ * |        |                                                   |
+ * |-------:|---------------------------------------------------|
+ * |       0| success                                           |
+ * |   -EDOM| integer not representable in @p data_length bytes |
+ *
+ * @note use @ref cmt_abi_encode_uint instead */
+int cmt_abi_encode_uint_nn(size_t n, const uint8_t *data, uint8_t out[CMT_ABI_U256_LENGTH]);
+
+/** Decode @p n bytes of @p data into @p out (up to 32).
+ *
+ * @param [in]  data integer value to decode into @p out
+ * @param [in]  n    size of @p data in bytes
+ * @param [out] out  decoded output
+ *
+ * @return
+ * |        |                                                   |
+ * |-------:|---------------------------------------------------|
+ * |       0| success                                           |
+ * |   -EDOM| integer not representable in @p data_length bytes | */
+int cmt_abi_decode_uint(const uint8_t data[CMT_ABI_U256_LENGTH], size_t n, uint8_t *out);
+
+/** Decode @p n bytes of @p data into @p out (up to 32) in reverse order.
+ *
+ * @param [in]  data integer value to decode into @p out
+ * @param [in]  n    size of @p data in bytes
+ * @param [out] out  decoded output
+ *
+ * @return
+ * |        |                                                   |
+ * |-------:|---------------------------------------------------|
+ * |       0| success                                           |
+ * |   -EDOM| integer not representable in @p data_length bytes |
+ *
+ * @note if in doubt, use @ref cmt_abi_decode_uint */
+int cmt_abi_decode_uint_nr(const uint8_t data[CMT_ABI_U256_LENGTH], size_t n, uint8_t *out);
+
+/** Decode @p n bytes of @p data into @p out (up to 32) in normal order.
+ *
+ * @param [in]  data integer value to decode into @p out
+ * @param [in]  n    size of @p data in bytes
+ * @param [out] out  decoded output
+ *
+ * @return
+ * |        |                                                   |
+ * |-------:|---------------------------------------------------|
+ * |       0| success                                           |
+ * |   -EDOM| integer not representable in @p data_length bytes |
+ *
+ * @note if in doubt, use @ref cmt_abi_decode_uint */
+int cmt_abi_decode_uint_nn(const uint8_t data[CMT_ABI_U256_LENGTH], size_t n, uint8_t *out);
+
+#endif /* CMT_ABI_H */
+/** @} */

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 */
+/** @} */