mirror of
https://github.com/apache/nuttx.git
synced 2026-03-23 13:14:50 +08:00
e2f3950d45
Some checks failed
Build Documentation / build-html (push) Has been cancelled
- 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>
162 lines
6.1 KiB
ReStructuredText
162 lines
6.1 KiB
ReStructuredText
====
|
|
libc
|
|
====
|
|
|
|
This directory contains numerous, small functions typically associated with
|
|
what you would expect to find in a standard C library. The sub-directories
|
|
in this directory contain standard interface that can be executed by user-
|
|
mode programs.
|
|
|
|
Normally, NuttX is built with no protection and all threads running in kernel-
|
|
mode. In that mode, there is no real architectural distinction between
|
|
what is a kernel-mode program and what is a user-mode program; the system is
|
|
more like an multi-threaded program that all runs in kernel-mode.
|
|
|
|
But if the ``CONFIG_BUILD_PROTECTED`` option is selected, NuttX will be built
|
|
into distinct user-mode and kernel-mode sections. In that case, most of the
|
|
code in the ``nuttx/`` directory will run in kernel-mode with exceptions
|
|
of (1) the user-mode "proxies" found in syscall/proxies, and (2) the
|
|
standard C library functions found in this directory. In this build mode,
|
|
it is critical to separate the user-mode OS interfaces in this way.
|
|
|
|
If ``CONFIG_BUILD_KERNEL`` is selected, then only a NuttX kernel will be built
|
|
with no applications.
|
|
|
|
Sub-Directories
|
|
===============
|
|
|
|
The files in the ``libs/libc/`` directory are organized (mostly) according
|
|
which file in the ``include/`` directory provides the prototype for library
|
|
functions. So we have::
|
|
|
|
audio - This part of the audio system: nuttx/audio/audio.h
|
|
builtin - Support for builtin applications. Used by nuttx/binfmt and NSH.
|
|
dlfcn - dlfcn.h
|
|
endian - endian.h
|
|
errno - errno.h
|
|
hex2bin - hex2bin.h
|
|
libgen - libgen.h
|
|
locale - locale.h
|
|
lzf - lzf.h
|
|
fixedmath - fixedmath.h
|
|
grp - grp.h
|
|
inttypes - inttypes.h
|
|
machine - Various architecture-specific implementations.
|
|
math - math.h
|
|
elf - Part of module and shared library logic: nuttx/lib/elf.h
|
|
net - Various network-related header files: netinet/ether.h, arpa/inet.h
|
|
pthread - pthread.h
|
|
pwd - pwd.h
|
|
queue - queue.h
|
|
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)
|
|
time - time.h
|
|
uio - sys/uio.h
|
|
unistd - unistd.h
|
|
wchar - wchar.h
|
|
wctype - wctype.h
|
|
|
|
Most of these are "standard" header files; some are not: ``hex2bin.h`` and
|
|
``fixemath.h`` are non-standard.
|
|
|
|
There is also a ``misc/`` subdirectory that contains various internal functions
|
|
and interfaces from header files that are too few to warrant their own sub-
|
|
directory::
|
|
|
|
misc - Nonstandard "glue" logic, debug.h, crc32.h, dirent.h
|
|
|
|
Library Database
|
|
================
|
|
|
|
Information about functions available in the NuttX C library information is
|
|
maintained in a database. That "database" is implemented as a simple comma-
|
|
separated-value file, libc.csv. Most spreadsheets programs will accept this
|
|
format and can be used to maintain the library database.
|
|
|
|
This library database will (eventually) be used to generate symbol library
|
|
symbol table information that can be exported to external applications.
|
|
|
|
The format of the CSV file for each line is::
|
|
|
|
Field 1: Function name
|
|
Field 2: The header file that contains the function prototype
|
|
Field 3: Condition for compilation
|
|
Field 4: The type of function return value.
|
|
Field 5 - N+5: The type of each of the N formal parameters of the function
|
|
|
|
Each type field has a format as follows::
|
|
|
|
type name:
|
|
For all simpler types
|
|
formal type | actual type:
|
|
For array types where the form of the formal (eg. int param[2])
|
|
differs from the type of actual passed parameter (eg. int*). This
|
|
is necessary because you cannot do simple casts to array types.
|
|
formal type | union member actual type | union member fieldname:
|
|
A similar situation exists for unions. For example, the formal
|
|
parameter type union sigval -- You cannot cast a uintptr_t to
|
|
a union sigval, but you can cast to the type of one of the union
|
|
member types when passing the actual parameter. Similarly, we
|
|
cannot cast a union sigval to a uinptr_t either. Rather, we need
|
|
to cast a specific union member fieldname to uintptr_t.
|
|
|
|
NOTE: The tool mksymtab can be used to generate a symbol table from this CSV
|
|
file. See ``Documentation/components/tools`` for further details about the use of mksymtab.
|
|
|
|
symtab
|
|
======
|
|
|
|
Symbol Tables and Build Modes
|
|
-----------------------------
|
|
|
|
This directory provide support for a symbol table which provides all/most of
|
|
system and C library services/functions to the application and NSH.
|
|
|
|
Symbol tables have differing usefulness in different NuttX build modes:
|
|
|
|
#. In the FLAT build (``CONFIG_BUILD_FLAT``), symbol tables are used to bind
|
|
addresses in loaded ELF or NxFLAT modules to base code that usually
|
|
resides in FLASH memory. Both OS interfaces and user/application
|
|
libraries are made available to the loaded module via symbol tables.
|
|
|
|
#. Symbol tables may be of value in a protected build
|
|
(``CONFIG_BUILD_PROTECTED``) where the newly started user task must
|
|
share resources with other user code (but should use system calls to
|
|
interact with the OS).
|
|
|
|
#. But in the kernel build mode (``CONFIG_MODULES``), only fully linked
|
|
executables loadable via ``execl()``, ``execv()``, or ``posix_spawan()``
|
|
can be used.
|
|
There is no use for a symbol table with the kernel build since all
|
|
memory resources are separate; nothing is share-able with the newly
|
|
started process.
|
|
|
|
Code/Text Size Implications
|
|
---------------------------
|
|
|
|
The option can have substantial effect on system image size, mainly
|
|
code/text. That is because the instructions to generate symtab.inc
|
|
above will cause EVERY interface in the NuttX RTOS and the C library to be
|
|
included into build. Add to that the size of a huge symbol table.
|
|
|
|
In order to reduce the code/text size, you may want to manually prune the
|
|
auto-generated symtab.inc file to remove all interfaces that you do
|
|
not wish to include into the base FLASH image.
|
|
|
|
Implementation Details
|
|
======================
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
:caption: Contents:
|
|
|
|
search.rst
|
|
stdbit.rst
|
|
stream.rst
|
|
zoneinfo.rst
|