util: move utf8 utils to a separate header

This moves the declaration of the utf8 utils defined in lib/utils/utf8.c
in their own header. Main reason to do this is that the current setup
requried adding an include for sys/types.h in util.h, which can result
in a build falure due to a circular header depdenecy when using:

CONFIG_POSIX_API=y
CONFIG_NEWLIB_LIBC=y
_GNU_SOURCE

the loop and error are:

- include/sys/types.h:50: <- this is a NEWLIB one
- include/zephyr/posix/sys/select.h:9:
- include/zephyr/posix/posix_types.h:30:
- include/zephyr/kernel.h:17:
- include/zephyr/kernel_includes.h:25:
- include/zephyr/sys/atomic.h:18:

include/zephyr/sys/util.h:705:1:
error: unknown type name 'ssize_t'

Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>

Author: fabiobaltieri

doc/releases/migration-guide-4.3.rst

@@ -26,6 +26,13 @@ Build System
 Kernel
 ******
 
+Base Libraries
+**************
+
+* UTF-8 utils declarations (:c:func:`utf8_trunc`, :c:func:`utf8_lcpy`) have
+  been moved from ``util.h`` to a separate
+  :zephyr_file:`include/zephyr/sys/util_utf8.h` file.
+
 Boards
 ******
 

include/zephyr/sys/util.h

@@ -29,8 +29,6 @@
 #include <stddef.h>
 #include <stdint.h>
 #include <string.h>
-#include <sys/types.h>
-
 
 /** @brief Number of bits that make up a type */
 #define NUM_BITS(t) (sizeof(t) * BITS_PER_BYTE)
@@ -647,63 +645,6 @@ static inline int64_t sign_extend_64(uint64_t value, uint8_t index)
 	return (int64_t)(value << shift) >> shift;
 }
 
-/**
- * @brief Properly truncate a NULL-terminated UTF-8 string
- *
- * Take a NULL-terminated UTF-8 string and ensure that if the string has been
- * truncated (by setting the NULL terminator) earlier by other means, that
- * the string ends with a properly formatted UTF-8 character (1-4 bytes).
- *
- * Example:
- *
- * @code{.c}
- *      char test_str[] = "€€€";
- *      char trunc_utf8[8];
- *
- *      printf("Original : %s\n", test_str); // €€€
- *      strncpy(trunc_utf8, test_str, sizeof(trunc_utf8));
- *      trunc_utf8[sizeof(trunc_utf8) - 1] = '\0';
- *      printf("Bad      : %s\n", trunc_utf8); // €€�
- *      utf8_trunc(trunc_utf8);
- *      printf("Truncated: %s\n", trunc_utf8); // €€
- * @endcode
- *
- * @param utf8_str NULL-terminated string
- *
- * @return Pointer to the @p utf8_str
- */
-char *utf8_trunc(char *utf8_str);
-
-/**
- * @brief Copies a UTF-8 encoded string from @p src to @p dst
- *
- * The resulting @p dst will always be NULL terminated if @p n is larger than 0,
- * and the @p dst string will always be properly UTF-8 truncated.
- *
- * @param dst The destination of the UTF-8 string.
- * @param src The source string
- * @param n   The size of the @p dst buffer. Maximum number of characters copied
- *            is @p n - 1. If 0 nothing will be done, and the @p dst will not be
- *            NULL terminated.
- *
- * @return Pointer to the @p dst
- */
-char *utf8_lcpy(char *dst, const char *src, size_t n);
-
-/**
- * @brief Counts the characters in a UTF-8 encoded string @p s
- *
- * Counts the number of UTF-8 characters (code points) in a null-terminated string.
- * This function steps through each UTF-8 sequence by checking leading byte patterns.
- * It does not fully validate UTF-8 correctness, only counts characters.
- *
- * @param s The input string
- *
- * @return Number of UTF-8 characters in @p s on success or (negative) error code
- *  otherwise.
- */
-ssize_t utf8_count_chars(const char *s);
-
 #define __z_log2d(x) (32 - __builtin_clz(x) - 1)
 #define __z_log2q(x) (64 - __builtin_clzll(x) - 1)
 #define __z_log2(x) (sizeof(__typeof__(x)) > 4 ? __z_log2q(x) : __z_log2d(x))

include/zephyr/sys/util_utf8.h

@@ -0,0 +1,94 @@
+/*
+ * Copyright The Zephyr Project Contributors
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @file
+ * @brief UTF-8 utilities
+ *
+ * Misc UTF-8 utilities.
+ */
+
+#ifndef ZEPHYR_INCLUDE_SYS_UTIL_UFT8_H_
+#define ZEPHYR_INCLUDE_SYS_UTIL_UFT8_H_
+
+#include <stddef.h>
+#include <sys/types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @addtogroup sys-util
+ * @{
+ */
+
+/**
+ * @brief Properly truncate a NULL-terminated UTF-8 string
+ *
+ * Take a NULL-terminated UTF-8 string and ensure that if the string has been
+ * truncated (by setting the NULL terminator) earlier by other means, that
+ * the string ends with a properly formatted UTF-8 character (1-4 bytes).
+ *
+ * Example:
+ *
+ * @code{.c}
+ *      char test_str[] = "€€€";
+ *      char trunc_utf8[8];
+ *
+ *      printf("Original : %s\n", test_str); // €€€
+ *      strncpy(trunc_utf8, test_str, sizeof(trunc_utf8));
+ *      trunc_utf8[sizeof(trunc_utf8) - 1] = '\0';
+ *      printf("Bad      : %s\n", trunc_utf8); // €€�
+ *      utf8_trunc(trunc_utf8);
+ *      printf("Truncated: %s\n", trunc_utf8); // €€
+ * @endcode
+ *
+ * @param utf8_str NULL-terminated string
+ *
+ * @return Pointer to the @p utf8_str
+ */
+char *utf8_trunc(char *utf8_str);
+
+/**
+ * @brief Copies a UTF-8 encoded string from @p src to @p dst
+ *
+ * The resulting @p dst will always be NULL terminated if @p n is larger than 0,
+ * and the @p dst string will always be properly UTF-8 truncated.
+ *
+ * @param dst The destination of the UTF-8 string.
+ * @param src The source string
+ * @param n   The size of the @p dst buffer. Maximum number of characters copied
+ *            is @p n - 1. If 0 nothing will be done, and the @p dst will not be
+ *            NULL terminated.
+ *
+ * @return Pointer to the @p dst
+ */
+char *utf8_lcpy(char *dst, const char *src, size_t n);
+
+/**
+ * @brief Counts the characters in a UTF-8 encoded string @p s
+ *
+ * Counts the number of UTF-8 characters (code points) in a null-terminated string.
+ * This function steps through each UTF-8 sequence by checking leading byte patterns.
+ * It does not fully validate UTF-8 correctness, only counts characters.
+ *
+ * @param s The input string
+ *
+ * @return Number of UTF-8 characters in @p s on success or (negative) error code
+ *  otherwise.
+ */
+ssize_t utf8_count_chars(const char *s);
+
+#ifdef __cplusplus
+}
+#endif
+
+/**
+ * @}
+ */
+
+#endif /* ZEPHYR_INCLUDE_SYS_UTIL_UFT8_H_ */

lib/utils/utf8.c

@@ -9,6 +9,7 @@
 #include <zephyr/sys/__assert.h>
 #include <errno.h>
 #include <sys/types.h>
+#include <zephyr/sys/util_utf8.h>
 
 #define ASCII_CHAR 0x7F
 #define SEQUENCE_FIRST_MASK 0xC0

subsys/bluetooth/audio/aics.c

@@ -27,6 +27,7 @@
 #include <zephyr/sys/check.h>
 #include <zephyr/sys/util.h>
 #include <zephyr/sys/util_macro.h>
+#include <zephyr/sys/util_utf8.h>
 #include <zephyr/sys_clock.h>
 
 #include "aics_internal.h"

subsys/bluetooth/audio/has.c

@@ -31,6 +31,7 @@
 #include <zephyr/sys/slist.h>
 #include <zephyr/sys/util.h>
 #include <zephyr/sys/util_macro.h>
+#include <zephyr/sys/util_utf8.h>
 #include <zephyr/sys_clock.h>
 #include <zephyr/toolchain.h>
 

subsys/bluetooth/audio/has_client.c

@@ -23,6 +23,7 @@
 #include <zephyr/sys/check.h>
 #include <zephyr/sys/util.h>
 #include <zephyr/sys/util_macro.h>
+#include <zephyr/sys/util_utf8.h>
 
 #include "has_internal.h"
 

subsys/bluetooth/audio/shell/bap_broadcast_assistant.c

@@ -30,6 +30,7 @@
 #include <zephyr/sys/byteorder.h>
 #include <zephyr/sys/util.h>
 #include <zephyr/sys/util_macro.h>
+#include <zephyr/sys/util_utf8.h>
 #include <zephyr/types.h>
 
 #include "common/bt_shell_private.h"

subsys/bluetooth/audio/tbs.c

@@ -33,6 +33,7 @@
 #include <zephyr/sys/check.h>
 #include <zephyr/sys/util.h>
 #include <zephyr/sys/util_macro.h>
+#include <zephyr/sys/util_utf8.h>
 #include <zephyr/types.h>
 
 #include "audio_internal.h"

subsys/bluetooth/audio/tbs_client.c

@@ -28,6 +28,7 @@
 #include <zephyr/sys/slist.h>
 #include <zephyr/sys/util.h>
 #include <zephyr/sys/util_macro.h>
+#include <zephyr/sys/util_utf8.h>
 #include <zephyr/toolchain.h>
 #include <zephyr/types.h>
 #include <zephyr/sys/check.h>