nuttx/libs/libc
Tiago Medicci Serrano d3ffeb40a7 libc/machine/xtensa: make longjmp safe against context switch
In order to turn longjmp context-switch safe, it's necessary
to disable interrupts before modifying windowbase and windowstart.
Otherwise, after a context switch, windowstart and windowbase
would be different, leading to a wrongly set windowstart bit due to
longjmp writing it based on the windowbase before the context switch.
This corrupts the registers at the next window overflow reaching
that wrongly set bit.

*Background:*
This PR is related to an issue first observed on ESP-IDF
https://github.com/espressif/esp-idf/issues/5229 and it was, then,
checked on NuttX using a test application.

*The test application:*
To check if the problem affects ESP32, ESP32-S2 and ESP32-S3 on
NuttX, it was created an application based on:
https://en.cppreference.com/w/c/program/longjmp

The application creates 16 tasks (`#define NUMBER_OF_TASKS  16`)
that implements the following daemon:

```
static int setjmp_longjmp_daemon(int argc, char *argv[])
{
  for (int i = 0; i < NUMBER_OF_TASKS * 2; i++)
    {
      jmp_buf env;

      volatile int count = 0;
      if (setjmp(env) != UINT16_MAX)
        {
          foo(&env, ++count);
        }
    }

  sem_post(&g_sem);

  return EXIT_SUCCESS;
}
```

The main function also initializes a semaphore to avoid application
exiting before tasks return successfully:

```
  sem_init(&g_sem, 0, -NUMBER_OF_TASKS);
```

Finally, the round-robin interval was lowered to 1ms to raise the
chances of the longjmp being interrupted by a context switch
(`CONFIG_RR_INTERVAL=1).

This setup was able to reproduce the problem prior to this patch
being applied.
2022-11-22 19:34:44 +01:00
..
aio include: fix double include pre-processor guards 2022-01-16 11:11:14 -03:00
assert libc: Move stack check stuff from libc/stdlib/ to libc/assert/ 2021-02-20 10:10:15 -08:00
audio tools: replace INCDIR to Makefile variable 2022-11-03 19:59:55 +08:00
bin libs: Author Gregory Nutt: update licenses to Apache 2021-03-03 18:52:53 -08:00
builtin binfmt: Decouple builtin from binfs file system 2022-02-14 09:35:35 -03:00
ctype ctype/iscntrl: correct the control character function 2021-01-05 01:34:36 -06:00
dirent Implement fdopendir 2022-10-19 21:20:35 +08:00
dlfcn Fix typos in comments and Kconfig files 2021-12-21 03:26:16 -06:00
errno Fix various typos 2022-07-08 02:15:54 +08:00
eventfd eventfd: Remove the unused and private eventfd_get_minor 2021-12-19 01:41:11 -06:00
fixedmath libc/fixedmatch: Avoid "divide by zero" error 2022-04-23 20:15:31 +03:00
grp Fix compiler warnings (-Wunused-parameter) in various functions 2022-07-12 11:42:34 +08:00
hex2bin libc/hex2bin: Handle the line ending(\r, \n and \r\n) dynamically 2021-11-26 11:55:00 -03:00
inttypes sourcefiles: Fix relative path in file header 2021-03-09 23:18:28 +08:00
kbin libs: Author Gregory Nutt: update licenses to Apache 2021-03-03 18:52:53 -08:00
libgen Fix various typos 2022-07-08 02:15:54 +08:00
locale Replace nxsem API when used as a lock with nxmutex API 2022-10-17 15:59:46 +09:00
lzf include: fix double include pre-processor guards 2022-01-16 11:11:14 -03:00
machine libc/machine/xtensa: make longjmp safe against context switch 2022-11-22 19:34:44 +01:00
math * Squash round() commits 2022-09-08 20:57:27 +08:00
misc sched/task/task_getpid: getpid should return process id not thread id 2022-11-17 17:58:08 +08:00
modlib Fix various typos 2022-07-08 02:15:54 +08:00
net Replace all strncpy with strlcpy for safety 2022-08-25 13:38:36 +08:00
netdb dns: Reduce the dns_lock granularity 2022-11-11 20:07:05 +08:00
obstack libs/libc: add obstack 2022-10-26 09:11:52 +08:00
pthread phtread: Change stacksize type from long to size_t 2022-11-22 08:23:37 +09:00
pwd libs: nxstyle fixes 2021-03-03 18:52:53 -08:00
queue libc: Move queue.h from include to include/nuttx 2022-09-26 08:04:58 +02:00
sched sched/getprioritymax: handle invaild policy as posix style 2022-11-01 03:33:58 +08:00
semaphore semaphore: move param check to sem_xx level 2022-11-10 22:36:21 +08:00
signal libc/psignal: Output the message to STDERR_FILENO instead STDOUT_FILENO 2021-11-22 19:37:12 +01:00
spawn libc/spawn: Always build lib_psa_[get|set]stacksize.c 2022-11-01 21:03:52 +01:00
stdio libc/stdio: Remove the one line mutex wrapper 2022-11-09 21:38:10 +01:00
stdlib lib/atexit: correct return value of exitfunc lock 2022-11-07 18:14:30 +08:00
stream Fix compiler warnings (-Wunused-parameter) in various functions 2022-07-12 11:42:34 +08:00
string Update errno to match asm-generic 2022-10-28 02:19:26 +08:00
symtab libc: Fix wrong report from UBSan 2022-08-30 19:35:24 +08:00
syslog include: fix double include pre-processor guards 2022-01-16 11:11:14 -03:00
termios libc: Implement terminal api regardless of CONFIG_SERIAL_TERMIOS setting 2021-12-29 08:11:08 -03:00
time libs/libc/time: fix regression in clock_calendar2utc 2022-10-28 10:21:05 +08:00
tls sched/tls: Wrap up_info_size into tls_info_size 2022-06-08 19:07:33 +09:00
uio libc: Remove the redundant seek in writev 2022-05-01 10:07:36 +03:00
unistd sched/task/task_getpid: getpid should return process id not thread id 2022-11-17 17:58:08 +08:00
userfs Replace nxsem API when used as a lock with nxmutex API 2022-10-17 15:59:46 +09:00
uuid libc/uuid: Call getrandom instaed arc4random_buf 2022-03-25 13:48:33 +02:00
wchar libc: Remove the unnecessary include from wchar and wctype 2022-07-27 10:55:37 +03:00
wctype libc: Remove the unnecessary include from wchar and wctype 2022-07-27 10:55:37 +03:00
wqueue Initialize global mutext/sem by NXMUTEX_INITIALIZER and SEM_INITIALIZER 2022-11-14 09:34:04 +09:00
zoneinfo Rename LIB_ to LIBC_ for all libc Kconfig 2021-08-05 19:45:24 +02:00
.gitignore build: Remve the unnecessary .gitignore 2020-05-23 18:00:40 +01:00
Kconfig libc/wchar: remove unnecessary config 2022-07-27 00:36:49 +08:00
libc.csv fs: Remove the unused nx_pipe to prefer file_pipe for kernel 2022-10-27 23:14:25 +02:00
libc.h libc/stdio: Remove the one line mutex wrapper 2022-11-09 21:38:10 +01:00
Makefile tools: replace INCDIR to Makefile variable 2022-11-03 19:59:55 +08:00
math.csv syscall: Fix typo error in cvs and header file 2020-05-07 10:31:05 -06:00
README.txt Completes the Implementation of the TLS-based errno 2020-05-07 23:11:34 +01:00

lib
===

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 kerne-
mode.  In that model, 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 on 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 model,
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
  modlib    - Part of module and shared library logic: nuttx/lib/modlib.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
  semaphore - semaphore.h
  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 parm[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 nuttx/tools/README.txt 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:

  1. 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.

  2. 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).

  3. But in the kernel build mode (CONFIG_BUILD_LOADABLE), only fully linked
     executables loadable via execl(), execv(), or posix_spawan() can 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.