libc: add support for C23 stdbit.h with bit manipulation macros

- Introduced Kconfig options for stdbit.h, allowing architecture-specific and generic implementations.
- Added new documentation for stdbit.h, detailing its usage and configuration.
- Updated CMake and Makefile to handle the inclusion of stdbit.h based on configuration settings.

This enhances the NuttX library with optional C23 bit manipulation utilities, improving functionality for architectures that support it.

Signed-off-by: Arjav Patel <arjav1528@gmail.com>

Documentation/components/libs/libc/index.rst

@@ -51,6 +51,7 @@ functions.  So we have::
   sched     - sched.h
   search    - search.h
   semaphore - semaphore.h
+  stdbit    - stdbit.h (optional C23)
   stdio     - stdio.h
   stdlib    - stdlib.h
   string    - string.h (and legacy strings.h and non-standard nuttx/b2c.h)
@@ -155,5 +156,6 @@ Implementation Details
    :caption: Contents:
    
    search.rst
+   stdbit.rst
    stream.rst
    zoneinfo.rst

Documentation/components/libs/libc/stdbit.rst

@@ -0,0 +1,30 @@
+========
+stdbit.h
+========
+
+The optional C23 ``stdbit.h`` header provides bit manipulation macros
+(endianness, leading/trailing zeros and ones, count, single-bit test,
+bit width, bit floor, bit ceil). NuttX provides this header only when
+explicitly enabled via Kconfig.
+
+Configuration
+=============
+
+- **CONFIG_ARCH_HAVE_STDBIT_H** (bool, selected by arch)
+  Architecture indicates it provides ``arch/<arch>/include/stdbit.h``.
+
+- **CONFIG_ARCH_STDBIT_H** (bool "stdbit.h", depends on ARCH_HAVE_STDBIT_H)
+  Use the redirecting header. The build copies
+  ``include/nuttx/lib/stdbit.h`` to ``include/stdbit.h``; that header
+  then includes ``<arch/stdbit.h>`` when this option is set.
+
+- **CONFIG_LIBC_STDBIT_GENERIC** (bool "stdbit.h (generic C23)")
+  Use the generic C23 implementation. The same redirecting file
+  ``include/nuttx/lib/stdbit.h`` is copied to ``include/stdbit.h``,
+  and the generic implementation is used (no arch header). Requires
+  compiler builtins (e.g. ``__builtin_clz``, ``__builtin_ctz``,
+  ``__builtin_popcount``); see ``CONFIG_HAVE_BUILTIN_*`` in
+  ``nuttx/compiler.h``.
+
+Either **CONFIG_ARCH_STDBIT_H** or **CONFIG_LIBC_STDBIT_GENERIC** may be
+enabled so that ``#include <stdbit.h>`` is available.

Kconfig

@@ -625,6 +625,31 @@ config ARCH_STDARG_H
 		ARCH_STDARG_H=y and providing. If ARCH_STDARG_H, is not defined, then
 		the stdarg.h header file will stay out-of-the-way in include/nuttx/.
 
+config ARCH_HAVE_STDBIT_H
+	bool
+	default n
+	---help---
+		Selected by architecture specific logic if the architecture
+		provides a stdbit.h header file.
+
+config ARCH_STDBIT_H
+	bool "stdbit.h"
+	depends on ARCH_HAVE_STDBIT_H
+	default n
+	---help---
+		Redirecting stdbit.h lives at include/nuttx/lib/stdbit.h. When
+		this is set, the build copies it to include/stdbit.h and it
+		includes arch/stdbit.h if the architecture provides one.
+
+config LIBC_STDBIT_GENERIC
+	bool "stdbit.h (generic C23)"
+	default n
+	---help---
+		Use generic C23 stdbit implementation. When set, copy
+		include/nuttx/lib/stdbit.h to include/stdbit.h. No arch
+		header is used; builtins (e.g. __builtin_clz) must be
+		available (see CONFIG_HAVE_BUILTIN_* in compiler.h).
+
 config ARCH_HAVE_SETJMP
 	bool
 	default n

cmake/nuttx_generate_headers.cmake

@@ -137,6 +137,17 @@ else()
   file(REMOVE ${CMAKE_BINARY_DIR}/include/setjmp.h)
 endif()
 
+# Target used to copy include/nuttx/lib/stdbit.h.  If CONFIG_ARCH_STDBIT_H or
+# CONFIG_LIBC_STDBIT_GENERIC is set, copy stdbit.h to include/ for C23 bit
+# utilities.
+
+if(CONFIG_ARCH_STDBIT_H OR CONFIG_LIBC_STDBIT_GENERIC)
+  nuttx_create_symlink(${NUTTX_DIR}/include/nuttx/lib/stdbit.h
+                       ${CMAKE_BINARY_DIR}/include/stdbit.h)
+else()
+  file(REMOVE ${CMAKE_BINARY_DIR}/include/stdbit.h)
+endif()
+
 # Add final context target that ties together all of the above The context
 # target is invoked on each target build to assure that NuttX is properly
 # configured.  The basic configuration steps include creation of the the
@@ -151,7 +162,10 @@ add_custom_target(
     $<$<BOOL:${CONFIG_ARCH_STDARG_H}>:${CMAKE_BINARY_DIR}/include/stdarg.h>
     $<$<BOOL:${NEED_MATH_H}>:${CMAKE_BINARY_DIR}/include/math.h>
     $<$<BOOL:${CONFIG_ARCH_FLOAT_H}>:${CMAKE_BINARY_DIR}/include/float.h>
-    $<$<BOOL:${CONFIG_ARCH_SETJMP_H}>:${CMAKE_BINARY_DIR}/include/setjmp.h>)
+    $<$<BOOL:${CONFIG_ARCH_SETJMP_H}>:${CMAKE_BINARY_DIR}/include/setjmp.h>
+    $<$<BOOL:${CONFIG_ARCH_STDBIT_H}>:${CMAKE_BINARY_DIR}/include/stdbit.h>
+    $<$<BOOL:${CONFIG_LIBC_STDBIT_GENERIC}>:${CMAKE_BINARY_DIR}/include/stdbit.h>
+)
 
 # apps_context is a PHONY target used as an intermediate process to control the
 # time order of context preparation actions of app building

tools/Unix.mk

@@ -212,6 +212,15 @@ include/stdarg.h: include/nuttx/lib/stdarg.h
 	$(Q) cp -f include/nuttx/lib/stdarg.h include/stdarg.h
 endif
 
+# Target used to copy include/nuttx/lib/stdbit.h.  If CONFIG_ARCH_STDBIT_H or
+# CONFIG_LIBC_STDBIT_GENERIC is set, copy stdbit.h to include/ for C23 bit
+# utilities.
+
+ifeq ($(firstword $(filter y, $(CONFIG_ARCH_STDBIT_H) $(CONFIG_LIBC_STDBIT_GENERIC))),y)
+include/stdbit.h: include/nuttx/lib/stdbit.h
+	$(Q) cp -f include/nuttx/lib/stdbit.h include/stdbit.h
+endif
+
 # Target used to copy include/nuttx/lib/setjmp.h.  If CONFIG_ARCH_SETJMP_H is
 # defined, then there is an architecture specific setjmp.h header file
 # that will be included indirectly from include/lib/setjmp.h.  But first, we
@@ -470,6 +479,10 @@ ifeq ($(CONFIG_ARCH_STDARG_H),y)
 context: include/stdarg.h
 endif
 
+ifeq ($(firstword $(filter y, $(CONFIG_ARCH_STDBIT_H) $(CONFIG_LIBC_STDBIT_GENERIC))),y)
+context: include/stdbit.h
+endif
+
 ifeq ($(CONFIG_ARCH_SETJMP_H),y)
 context: include/setjmp.h
 endif

tools/Win.mk

@@ -194,6 +194,17 @@ else
 include\stdarg.h:
 endif
 
+# Target used to copy include\nuttx\lib\stdbit.h.  If CONFIG_ARCH_STDBIT_H or
+# CONFIG_LIBC_STDBIT_GENERIC is set, copy stdbit.h to include\ for C23 bit
+# utilities.
+
+ifeq ($(firstword $(filter y, $(CONFIG_ARCH_STDBIT_H) $(CONFIG_LIBC_STDBIT_GENERIC))),y)
+include\stdbit.h: include\nuttx\lib\stdbit.h
+	$(Q) cp -f include\nuttx\lib\stdbit.h include\stdbit.h
+else
+include\stdbit.h:
+endif
+
 # Target used to copy include\nuttx\setjmp.h.  If CONFIG_ARCH_SETJMP_H is
 # defined, then there is an architecture specific setjmp.h header file
 # that will be included indirectly from include\setjmp.h.  But first, we
@@ -441,6 +452,10 @@ ifeq ($(CONFIG_ARCH_STDARG_H),y)
 context: include\stdarg.h
 endif
 
+ifeq ($(firstword $(filter y, $(CONFIG_ARCH_STDBIT_H) $(CONFIG_LIBC_STDBIT_GENERIC))),y)
+context: include\stdbit.h
+endif
+
 ifeq ($(CONFIG_ARCH_SETJMP_H),y)
 context: include\setjmp.h
 endif