Documentation: remove all migrated READMEs

2026-05-26 10:46:28 +08:00 · 2023-10-25 20:29:00 +02:00
parent 54a16e8f74
commit 5b87fdfb9d
44 changed files with 0 additions and 6598 deletions
@@ -1,177 +0,0 @@
-syscall/README.txt
-==================
-
-This directory supports a syscall layer from communication between a
-monolithic, kernel-mode NuttX kernel and a separately built, user-mode
-application set.
-
-With most MCUs, NuttX is built as a flat, single executable image
-containing the NuttX RTOS along with all application code.  The RTOS code
-and the application run in the same address space and at the same kernel-
-mode privileges.  In order to exploit security features of certain
-processors, an alternative build model is also supported:  NuttX can
-be built separately as a monolithic, kernel-mode module and the applications
-can be added as a separately built, user-mode module.
-
-The syscall layer provided in this directory serves as the communication
-layer from the user-mode application into the kernel-mode RTOS.  The
-switch from user-mode to kernel-mode is accomplished using software
-interrupts (SWIs).  SWIs are implemented differently and named differently
-by different manufacturers but all work essentially the same:  A special
-instruction is executed in user-mode that causes a software generated
-interrupt.  The software generated interrupt is caught within the kernel
-and handle in kernel-mode.
-
-Header Files
-============
-
-include/syscall.h
-
-  This header file supports general access to SWI facilities.  It is simply
-  a wrapper file that includes include/sys/syscall.h and
-  include/arch/syscall.h.
-
-include/sys/syscall.h
-
-  The SWIs received by the kernel are distinguish by a code that identifies
-  how to process the SWI.  This header file defines all such codes understood
-  by the NuttX kernel.
-
-include/arch/syscall.h (or arch/<cpu>/include/syscall.h)
-
-  This header file is provided by the platform-specific logic and declares
-  (or defines) the mechanism for providing software interrupts on this
-  platform.  The following functions must be declared (or defined) in this
-  header file:
-
-  - SWI with SYS_ call number and one parameter
-
-    uintptr_t sys_call0(unsigned int nbr);
-
-  - SWI with SYS_ call number and one parameter
-
-    uintptr_t sys_call1(unsigned int nbr, uintptr_t parm1);
-
-  - SWI with SYS_ call number and two parameters
-
-    uintptr_t sys_call2(unsigned int nbr, uintptr_t parm1, uintptr_t parm2);
-
-  - SWI with SYS_ call number and three parameters
-
-    uintptr_t sys_call3(unsigned int nbr, uintptr_t parm1,
-                        uintptr_t parm2, uintptr_t parm3);
-
-  - SWI with SYS_ call number and four parameters
-
-    uintptr_t sys_call4(unsigned int nbr, uintptr_t parm1, uintptr_t parm2,
-                        uintptr_t parm3, uintptr_t parm4);
-
-  - SWI with SYS_ call number and five parameters
-
-    uintptr_t sys_call5(unsigned int nbr, uintptr_t parm1, uintptr_t parm2,
-                        uintptr_t parm3, uintptr_t parm4, uintptr_t parm5);
-
-  - SWI with SYS_ call number and six parameters
-
-    uintptr_t sys_call6(unsigned int nbr, uintptr_t parm1, uintptr_t parm2,
-                        uintptr_t parm3, uintptr_t parm4, uintptr_t parm5,
-                        uintptr_t parm6);
-Syscall Database
-================
-
-Sycall information is maintained in a database.  That "database" is
-implemented as a simple comma-separated-value file, syscall.csv.  Most
-spreadsheets programs will accept this format and can be used to maintain
-the syscall database.
-
-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
-  Fields N+5 - : If the last parameter is "...", then the following fields
-           provide the type and number of of possible optional parameters.
-           See note below about variadic functions
-
-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.
-
-Variadic Functions:
-
-   General variadic functions which may have an arbitrary number of argument
-   or arbitrary types cannot be represented as system calls.  syslog() is a
-   good example.   Normally you would work around this by using the non-
-   variadic form of the OS interface that accepts a va_list as an argument,
-   vsyslog() in this case.
-
-   There there are many functions that have a variadic form but take only
-   one or two arguments optional arguments.  There can be handled as system
-   calls, but only by treating them as though they had a fixed number of
-   arguments.
-
-   These are are handled in syscall.csv by appending the number and type of
-   optional arguments.  For example, consider the open() OS interface.  Its
-   prototype is:
-
-      int open(const char *path, int oflag, ...);
-
-   In reality, open may take only a single optional argument of type mode_t
-   and is represented in syscall.cvs like this:
-
-      "open","fcntl.h","","int","const char*","int","...","mode_t"
-
-   The existence of the "mode_t" tells tools/mksyscall that there is at most
-   one optional parameter and, if present, it is of type mode_t.
-
-NOTE: This CSV file is used both to support the generate of trap information,
-but also for the generation of symbol tables.  See nuttx/tools/README.txt
-and nuttx/lib/README.txt for further information.
-
-Auto-Generated Files
-====================
-
-Stubs and proxies for the sycalls are automatically generated from this CSV
-database.  Here the following definition is used:
-
-  Proxy - A tiny bit of code that executes in the user space. A proxy
-          has exactly the same function prototype as does the "real" function
-          for which it proxies.  However, it only serves to map the function
-          call into a syscall, marshaling all of the system call parameters
-          as necessary.
-
-  Stub  - Another tiny bit of code that executes within the NuttX kernel
-          that is used to map a software interrupt received by the kernel to
-          a kernel function call. The stubs receive the marshaled system
-          call data, and perform the actually kernel function call (in
-          kernel-mode) on behalf of the proxy function.
-
-Sub-Directories
-===============
-
-  stubs - Autogenerated stub files are placed in this directory.
-  proxies - Autogenerated proxy files are placed in this directory.
-
-mksyscall
-=========
-
-  mksyscall is C program that is used used during the initial NuttX build
-  by the logic in the top-level syscall/ directory. Information about the
-  stubs and proxies is maintained in a comma separated value (CSV) file
-  in the syscall/ directory.  The mksyscall program will accept this CVS
-  file as input and generate all of the required proxy or stub files as
-  output.  See tools/README.txt for additional information.