zcbor: Copy source and header files

from zcbor 0.8.0

Signed-off-by: Øyvind Rønningstad <[email protected]>

Author: oyvindronningstad

boot/zcbor/include/zcbor_common.h

@@ -1,8 +1,3 @@
-/*
- * This file has been copied from the zcbor library.
- * Commit zcbor 0.7.0
- */
-
 /*
  * Copyright (c) 2020 Nordic Semiconductor ASA
  *
@@ -21,137 +16,80 @@
 extern "C" {
 #endif
 
+
 /** The zcbor_encode library provides functions for encoding CBOR data elements.
  *
  * See The README for an introduction to CBOR, including the meaning of pint,
  * nint, bstr etc.
  */
 
 
-/** The following param and retval docs apply to all single value encoding functions
- *
- * @param[inout] state  The current state of the encoding.
- * @param[in]    input  The value to encode.
- *
- * @retval true   Everything is ok.
- * @retval false  If the payload is exhausted. Or an unexpected error happened.
- */
-
-/** Encode a pint/nint. */
-bool zcbor_int32_put(zcbor_state_t *state, int32_t input);
-bool zcbor_int64_put(zcbor_state_t *state, int64_t input);
-bool zcbor_uint32_put(zcbor_state_t *state, uint32_t input);
-bool zcbor_uint64_put(zcbor_state_t *state, uint64_t input);
-bool zcbor_size_put(zcbor_state_t *state, size_t input);
-
-/** Encode a pint/nint from a pointer.
- *
- *  Can be used for bulk encoding with @ref zcbor_multi_encode.
- */
-bool zcbor_int_encode(zcbor_state_t *state, const void *input_int, size_t int_size);
-bool zcbor_int32_encode(zcbor_state_t *state, const int32_t *input);
-bool zcbor_int64_encode(zcbor_state_t *state, const int64_t *input);
-bool zcbor_uint32_encode(zcbor_state_t *state, const uint32_t *input);
-bool zcbor_uint64_encode(zcbor_state_t *state, const uint64_t *input);
-bool zcbor_size_encode(zcbor_state_t *state, const size_t *input);
-
-/** Encode a bstr. */
-bool zcbor_bstr_encode(zcbor_state_t *state, const struct zcbor_string *input);
-/** Encode a tstr. */
-bool zcbor_tstr_encode(zcbor_state_t *state, const struct zcbor_string *input);
-
-/** Encode a pointer to a string as a bstr/tstr.
- *
- * @param[inout] state   The current state of the encoding.
- * @param[in]    string  The value to encode. A pointer to the string
- * @param[in]    len     The length of the string pointed to by @p string.
- */
-static inline bool zcbor_bstr_encode_ptr(zcbor_state_t *state, const char *ptr, size_t len)
-{
-	const struct zcbor_string zs = { .value = (const uint8_t *)ptr, .len = len };
-
-	return zcbor_bstr_encode(state, &zs);
-}
-static inline bool zcbor_tstr_encode_ptr(zcbor_state_t *state, const char *ptr, size_t len)
-{
-	const struct zcbor_string zs = { .value = (const uint8_t *)ptr, .len = len };
-
-	return zcbor_tstr_encode(state, &zs);
-}
-
-/** Encode a string literal as a bstr/tstr.
- *
- * @param[inout] state   The current state of the encoding.
- * @param[in]    string  The value to encode. A string literal, e.g. "Foo", so
- *                       that sizeof(string) - 1 is the length of the string.
- */
-#define zcbor_bstr_put_lit(state, string) \
-	zcbor_bstr_encode_ptr(state, string, sizeof(string) - 1)
-#define zcbor_tstr_put_lit(state, string) \
-	zcbor_tstr_encode_ptr(state, string, sizeof(string) - 1)
+/** See @ref zcbor_new_state() */
+void zcbor_new_encode_state(zcbor_state_t *state_array, size_t n_states,
+		uint8_t *payload, size_t payload_len, size_t elem_count);
 
-/** Encode null-terminated string as a bstr/tstr.
+/** Convenience macro for declaring and initializing an encoding state with backups.
  *
- * @param[inout] state   The current state of the encoding.
- * @param[in]    string  The value to encode. Must be a null-terminated string,
- *                       so that strlen can be used.
- */
-#define zcbor_bstr_put_term(state, string) \
-	zcbor_bstr_encode_ptr(state, string, strlen(string))
-#define zcbor_tstr_put_term(state, string) \
-	zcbor_tstr_encode_ptr(state, string, strlen(string))
-
-/** Encode a char array literal as a bstr/tstr.
+ *  This gives you a state variable named @p name. The variable functions like
+ *  a pointer.
  *
- * @param[inout] state   The current state of the encoding.
- * @param[in]    string  The value to encode. An array literal, e.g. {'F', 'o', 'o'},
- *                       so that sizeof(string) is the length of the string.
+ *  @param[in]  name          The name of the new state variable.
+ *  @param[in]  num_backups   The number of backup slots to keep in the state.
+ *  @param[in]  payload       The payload to work on.
+ *  @param[in]  payload_size  The size (in bytes) of @p payload.
+ *  @param[in]  elem_count    The starting elem_count (typically 1).
  */
-#define zcbor_bstr_put_arr(state, string) \
-	zcbor_bstr_encode_ptr(state, string, sizeof(string))
-#define zcbor_tstr_put_arr(state, string) \
-	zcbor_tstr_encode_ptr(state, string, sizeof(string))
-
-/** Encode a tag. Must be called before encoding the value being tagged. */
-bool zcbor_tag_encode(zcbor_state_t *state, uint32_t input);
-
-/** Encode a boolean primitive value. */
-bool zcbor_bool_put(zcbor_state_t *state, bool input);
-bool zcbor_bool_encode(zcbor_state_t *state, const bool *input);
+#define ZCBOR_STATE_E(name, num_backups, payload, payload_size, elem_count) \
+zcbor_state_t name[((num_backups) + 2)]; \
+do { \
+	zcbor_new_encode_state(name, ZCBOR_ARRAY_SIZE(name), payload, payload_size, elem_count); \
+} while(0)
 
-/** Encode a float */
-bool zcbor_float32_put(zcbor_state_t *state, float input);
-bool zcbor_float32_encode(zcbor_state_t *state, const float *input);
-bool zcbor_float64_put(zcbor_state_t *state, double input);
-bool zcbor_float64_encode(zcbor_state_t *state, const double *input);
 
-/** Encode a "nil"/"undefined" primitive value. @p unused should be NULL.
+/** The following applies to all _put and _encode functions listed directly below.
  *
- * @param[inout] state   The current state of the encoding.
- * @param[in]    unused  Unused parameter to maintain signature parity with
- *                       @ref zcbor_encoder_t.
- */
-bool zcbor_nil_put(zcbor_state_t *state, const void *unused);
-bool zcbor_undefined_put(zcbor_state_t *state, const void *unused);
-
-/** Encode a bstr header.
+ * The difference between _put and _encode is only in the argument type,
+ * but when a @ref zcbor_encoder_t is needed, such as for  @ref zcbor_multi_encode,
+ * the _encode variant must be used.
  *
- * The rest of the string can be encoded as CBOR.
- * A state backup is created to keep track of the element count.
- * Call @ref zcbor_bstr_end_encode when done encoding the contents of the bstr.
- *
- * @param[inout] state   The current state of the encoding.
- *
- * @retval true   Header encoded correctly
- * @retval false  Header encoded incorrectly, or backup failed.
- */
-bool zcbor_bstr_start_encode(zcbor_state_t *state);
-
-/** Finalize encoding a CBOR-encoded bstr.
+ * @param[inout] state  The current state of the encoding.
+ * @param[in]    input  The value to encode.
  *
- * Restore element count from backup.
- */
-bool zcbor_bstr_end_encode(zcbor_state_t *state, struct zcbor_string *result);
+ * @retval true   Everything is ok.
+ * @retval false  If the payload is exhausted. Or an unexpected error happened.
+ *                Use zcbor_peek_error() to see the error code.
+ */
+bool zcbor_int32_put(zcbor_state_t *state, int32_t input); /* pint/nint */
+bool zcbor_int64_put(zcbor_state_t *state, int64_t input); /* pint/nint */
+bool zcbor_uint32_put(zcbor_state_t *state, uint32_t input); /* pint */
+bool zcbor_uint64_put(zcbor_state_t *state, uint64_t input); /* pint */
+bool zcbor_size_put(zcbor_state_t *state, size_t input); /* pint */
+bool zcbor_tag_put(zcbor_state_t *state, uint32_t tag); /* CBOR tag */
+bool zcbor_simple_put(zcbor_state_t *state, uint8_t input); /* CBOR simple value */
+bool zcbor_bool_put(zcbor_state_t *state, bool input); /* boolean CBOR simple value */
+bool zcbor_nil_put(zcbor_state_t *state, const void *unused); /* 'nil' CBOR simple value */
+bool zcbor_undefined_put(zcbor_state_t *state, const void *unused); /* 'undefined' CBOR simple value */
+bool zcbor_float16_put(zcbor_state_t *state, float input); /* IEEE754 float16 */
+bool zcbor_float16_bytes_put(zcbor_state_t *state, uint16_t input); /* IEEE754 float16 raw bytes */
+bool zcbor_float32_put(zcbor_state_t *state, float input); /* IEEE754 float32 */
+bool zcbor_float64_put(zcbor_state_t *state, double input); /* IEEE754 float64 */
+
+bool zcbor_int32_encode(zcbor_state_t *state, const int32_t *input); /* pint/nint */
+bool zcbor_int64_encode(zcbor_state_t *state, const int64_t *input); /* pint/nint */
+bool zcbor_uint32_encode(zcbor_state_t *state, const uint32_t *input); /* pint */
+bool zcbor_uint64_encode(zcbor_state_t *state, const uint64_t *input); /* pint */
+bool zcbor_size_encode(zcbor_state_t *state, const size_t *input); /* pint */
+bool zcbor_int_encode(zcbor_state_t *state, const void *input_int, size_t int_size);
+bool zcbor_uint_encode(zcbor_state_t *state, const void *input_uint, size_t uint_size);
+bool zcbor_bstr_encode(zcbor_state_t *state, const struct zcbor_string *input); /* bstr */
+bool zcbor_tstr_encode(zcbor_state_t *state, const struct zcbor_string *input); /* tstr */
+bool zcbor_tag_encode(zcbor_state_t *state, uint32_t *tag); /* CBOR tag. Note that zcbor_tag_encode()'s argument was changed to be a pointer. See also zcbor_tag_put(). */
+bool zcbor_simple_encode(zcbor_state_t *state, uint8_t *input); /* CBOR simple value */
+bool zcbor_bool_encode(zcbor_state_t *state, const bool *input); /* boolean CBOR simple value */
+bool zcbor_float16_encode(zcbor_state_t *state, const float *input); /* IEEE754 float16 */
+bool zcbor_float16_bytes_encode(zcbor_state_t *state, const uint16_t *input); /* IEEE754 float16 raw bytes */
+bool zcbor_float32_encode(zcbor_state_t *state, const float *input); /* IEEE754 float32 */
+bool zcbor_float64_encode(zcbor_state_t *state, const double *input); /* IEEE754 float64 */
 
 /** Encode a list/map header.
  *
@@ -169,8 +107,8 @@ bool zcbor_bstr_end_encode(zcbor_state_t *state, struct zcbor_string *result);
  *                        call.
  *                        Only used when ZCBOR_CANONICAL is defined.
  */
-bool zcbor_list_start_encode(zcbor_state_t *state, uint_fast32_t max_num);
-bool zcbor_map_start_encode(zcbor_state_t *state, uint_fast32_t max_num);
+bool zcbor_list_start_encode(zcbor_state_t *state, size_t max_num);
+bool zcbor_map_start_encode(zcbor_state_t *state, size_t max_num);
 
 /** Encode the end of a list/map. Do some checks and deallocate backup.
  *
@@ -189,8 +127,8 @@ bool zcbor_map_start_encode(zcbor_state_t *state, uint_fast32_t max_num);
  *                        @ref zcbor_list_start_encode call.
  *                        Only used when ZCBOR_CANONICAL is defined.
  */
-bool zcbor_list_end_encode(zcbor_state_t *state, uint_fast32_t max_num);
-bool zcbor_map_end_encode(zcbor_state_t *state, uint_fast32_t max_num);
+bool zcbor_list_end_encode(zcbor_state_t *state, size_t max_num);
+bool zcbor_map_end_encode(zcbor_state_t *state, size_t max_num);
 bool zcbor_list_map_end_force_encode(zcbor_state_t *state);
 
 /** Encode 0 or more elements with the same type and constraints.
@@ -241,49 +179,59 @@ bool zcbor_list_map_end_force_encode(zcbor_state_t *state);
  * @retval false  If @p encoder failed before having encoded @p min_encode
  *                values.
  */
-bool zcbor_multi_encode(uint_fast32_t num_encode,
-		zcbor_encoder_t encoder,
-		zcbor_state_t *state,
-		const void *input,
-		uint_fast32_t result_len);
+bool zcbor_multi_encode(size_t num_encode, zcbor_encoder_t encoder,
+		zcbor_state_t *state, const void *input, size_t result_len);
 
 /** Works like @ref zcbor_multi_encode
  *
  * But first checks that @p num_encode is between @p min_encode and @p max_encode.
  */
-bool zcbor_multi_encode_minmax(uint_fast32_t min_encode, uint_fast32_t max_encode, const uint_fast32_t *num_encode,
-		zcbor_encoder_t encoder, zcbor_state_t *state, const void *input,
-		uint_fast32_t input_len);
+bool zcbor_multi_encode_minmax(size_t min_encode, size_t max_encode,
+		const size_t *num_encode, zcbor_encoder_t encoder,
+		zcbor_state_t *state, const void *input, size_t input_len);
 
-/** Runs @p encoder on @p state and @p input if @p present is true.
- *
- * Calls @ref zcbor_multi_encode under the hood.
- */
-bool zcbor_present_encode(const uint_fast32_t *present,
-		zcbor_encoder_t encoder,
-		zcbor_state_t *state,
-		const void *input);
 
-/** See @ref zcbor_new_state() */
-void zcbor_new_encode_state(zcbor_state_t *state_array, uint_fast32_t n_states,
-		uint8_t *payload, size_t payload_len, uint_fast32_t elem_count);
+/* Supplementary string (bstr/tstr) encoding functions: */
 
-/** Convenience macro for declaring and initializing a state with backups.
+/** Encode a char/uint8_t pointer as a bstr/tstr.
  *
- *  This gives you a state variable named @p name. The variable functions like
- *  a pointer.
+ * @param[inout] state   The current state of the encoding.
+ * @param[in]    str     The value to encode. A pointer to the string/array.
+ *                       _term() uses strnlen(), so @p str must be null-terminated.
+ *                       _lit() uses sizeof()-1, so @p str must be a (null-terminated) string literal.
+ *                       _arr() uses sizeof(), so @p str must be a uint8_t array (not null-terminated).
+ * @param[in]    len     (if present) The length of the string pointed to by @p str
+ * @param[in]    maxlen  (if present) The maximum length of the string pointed to by @p str.
+ *                       This value is passed to strnlen.
+ */
+bool zcbor_bstr_encode_ptr(zcbor_state_t *state, const char *str, size_t len);
+bool zcbor_tstr_encode_ptr(zcbor_state_t *state, const char *str, size_t len);
+bool zcbor_bstr_put_term(zcbor_state_t *state, char const *str, size_t maxlen);
+bool zcbor_tstr_put_term(zcbor_state_t *state, char const *str, size_t maxlen);
+#define zcbor_bstr_put_lit(state, str) zcbor_bstr_encode_ptr(state, str, sizeof(str) - 1)
+#define zcbor_tstr_put_lit(state, str) zcbor_tstr_encode_ptr(state, str, sizeof(str) - 1)
+#define zcbor_bstr_put_arr(state, str) zcbor_bstr_encode_ptr(state, str, sizeof(str))
+#define zcbor_tstr_put_arr(state, str) zcbor_tstr_encode_ptr(state, str, sizeof(str))
+
+/** Encode a bstr header.
  *
- *  @param[in]  name          The name of the new state variable.
- *  @param[in]  num_backups   The number of backup slots to keep in the state.
- *  @param[in]  payload       The payload to work on.
- *  @param[in]  payload_size  The size (in bytes) of @p payload.
- *  @param[in]  elem_count    The starting elem_count (typically 1).
+ * The rest of the string can be encoded as CBOR.
+ * A state backup is created to keep track of the element count.
+ * Call @ref zcbor_bstr_end_encode when done encoding the contents of the bstr.
+ *
+ * @param[inout] state   The current state of the encoding.
+ *
+ * @retval true   Header encoded correctly
+ * @retval false  Header encoded incorrectly, or backup failed.
  */
-#define ZCBOR_STATE_E(name, num_backups, payload, payload_size, elem_count) \
-zcbor_state_t name[((num_backups) + 2)]; \
-do { \
-	zcbor_new_encode_state(name, ZCBOR_ARRAY_SIZE(name), payload, payload_size, elem_count); \
-} while(0)
+bool zcbor_bstr_start_encode(zcbor_state_t *state);
+
+/** Finalize encoding a CBOR-encoded bstr.
+ *
+ * This writes the final size of the bstr to the header.
+ * Restore element count from backup.
+ */
+bool zcbor_bstr_end_encode(zcbor_state_t *state, struct zcbor_string *result);
 
 #ifdef __cplusplus
 }