NUTTX Operating System User manual (Nuttx Operating system users ' s Manual)

1. Introduction

This manual provides general usage of the NUTTX real-time operating system from the perspective of the firmware developer.

1.1 Literature Review

This user manual is divided into three sections:
* Part 1th, Introduction: This section provides an overview of the NUTTX user manual.
* Part 2nd, operating System Interface: This section describes the details of the program interface provided by NUTTX. This section is divided into several paragraphs to describe different sets of operating system interfaces:
* Paragraph 2.1: Task control Interface
* Paragraph 2.2: task scheduling interface
* Paragraph 2.3: Task control Interface
* Paragraph 2.4: Naming Message Queuing interfaces
* Paragraph 2.5: Count semaphore interface
* Paragraph 2.6: Clocks and timers
* Paragraph 2.7: signal interface
* Paragraph 2.8: thread interface
* Paragraph 2.9: Environment variables
* Paragraph 2.10: File system interface
* Paragraph 2.11: network interface
* Paragraph 2.12: Shared memory interface
* Part 3rd, OS data structure: This section describes the data structures used in the Nuttx interface.
* Paragraph 3.1: scalar type
* Paragraph 3.2: Hidden interface mobile phone open structure
* Paragraph 3.3: Access errno variables
* Paragraph 3.4: User interface data structure 1.2 expected audience

The target audience for this document is the firmware developer who wants to implement the application on NUTTX, specifically, the document is limited to describing the real-time operating system APIs available to NUTTX application developers. Therefore, this document does not focus on any technical details about the NUTTX organization or implementation. Those technical details will be available in the NUTTX porting guide documentation.
application developers also need to know how to configure and build NUTTX information. This information can also be found in the NUTTX Migration Guide documentation.

2.0 Operating System interface

This section describes each interface that can be called by C in the NUTTX operating system. Each interface will be described in the following format:
function prototype : The C-form function prototype of the interface function.
Description : Discusses the related functions of interface functions.
input Parameters : All input parameters will be listed and each parameter will be described briefly.
return value : All return values that may be returned by the interface will be listed. The return value that occurs with the accompanying effect (either through the input parameter or a pointer to a variable or through a global variable) is indicated in the interface function description paragraph.
Assumptions/Limitations : Any unusual assumptions or any non-obvious limitations that arise when using this interface will be described here.
POSIX compatibility : There is no obvious difference between the Nuttx interface and its corresponding POSIX interface that will be indicated here.

Note: In order to realize the independence of the namespace of the Nuttx interface function, the difference between the function name and the type is desirable and is not considered to be different in these paragraphs. 2.1 Task Control Interface

Task: NUTTX is an operating system with a flat address. Therefore, it does not support processes such as Linux (address space). XUTTX is a simple thread that only supports running in the same address space. However, the programming model makes some difference between tasks and threads:
* The task is a thread group with a certain degree of independence.
* Some resources can be shared between threads.

file descriptors and streams: this is especially true for open file descriptors and streams. When you start a task using the interfaces in this section, you will create up to three open files.
if Config_dev_console is defined, the first three file descriptors (corresponding to Stdin,stdout and stderr) will be copied to the new task. Because these file descriptors are duplicated, child tasks can be free to close them or manipulate them in any way without affecting the parent task. File-related actions in a task (open, close, and so on) will not have an impact on other tasks. Because these three file descriptors are duplicated, you can also achieve some degree of redirection.
threads, on the other hand, typically share file descriptors with the parent thread. In this case, the file operation will affect all child threads from the same parent thread.
executing programs in the file system: NUTTX also provides a separate interface for executing programs that reside in a file system that is compiled independently. These internal interfaces are however not standard and they will be described in "NUTTX binary loader" and "Nxflat" two documents.

Task control interface. The following is a task control interface provided by NUTTX:

Non-standard task control interfaces introduced by the VxWorks interface:
2.1.1 Task_create
2.1.2 Task_init
2.1.3 Task_activate
2.1.4 Task_delete
2.1.5 Task_restart

A non-standard extension interface similar to VxWorks to support POSIX thread cancellation point features.
2.1.6 Task_setcancelstate
2.1.7 Task_setcanceltype
2.1.8 Task_testcancel

Standard interface
2.1.9 exit
2.1.10 Getpid

Standard vfork and exec [v|l] interfaces:
2.1.11 vfork
2.1.12 EXECV
2.1.13 execl

Standard Posix_spawn Interface:
2.1.14 POSIX_SPAWN_ABD_POSIX_SPAWNP
2.1.15 Posix_spawn_file_actions_init
2.1.16 Posix_spawn_file_actions_destroy
2.1.17 Posix_spawn_file_actions_addclose
2.6.18 posix_spawn_file_actions_adddup2
2.1.19 Posix_spawn_file_actions_addopen
2.1.20 Posix_spawnattr_init
2.1.21 Posix_spawnattr_getflags
2.1.22 Posix_spawnattr_getschedparam
2.1.23 Posix_spawnattr_getschedpolicy
2.1.24 Posix_spawnattr_getsigmask
2.1.25 Posix_spawnattr_setflags
2.1.26 Posix_spawnattr_setschedparam
2.1.27 Posix_spawnattr_setschedpolicy
2.1.28 Posix_spawnattr_setsigmask

Inspired by non-standard task control interfaces with Posix_spawn:
2.1.29 Task_spawn
2.1.30 task_spawnattr_getstacksize
2.1.31 task_spawnattr_setstacksize
2.1.32 Posix_spawn_file_actions_init

2.1.1 Task_create
function Prototypes：
#include <sched.h>
int Task_create (char *name, int priority, int stack_size, main_t entry, char * const argv[]);
Description: This function creates and activates a new task based on the specified priority and returns the system-assigned ID.
The entry address is the address of the "primary" function of the task. Once the C environment is set, this function will be called. When the function is called, four parameters are passed in. When the process is returned (that is, when the main function returns), exit () is automatically called.
Note that any number of arguments can be passed to the related function.
Incoming parameters are copied (via StrDup) so that the lifetime of the passed-in parameter does not depend on the parent function that calls Task_create ().
The newly created task does not inherit the scheduler's characteristics from the parent task: When a new task starts, it starts at the system default priority and SCHED_FIFO scheduling policy. These features can be modified after the new task is started.
The newly created task inherits support for the first three file descriptors (corresponding to Stdin,stdout and stderr,) and standard I/O redirection.
Input Parameters：
Name. The name of the new task
Priority. Priorities for new tasks
Stack_size. The size of the stack space (in bytes) required for the new task
Entry. Entry point for new tasks
Argv. A pointer to the input parameter array can provide a maximum of config_max_task_arg, and if fewer than config_max_task_arg parameters are passed in, then the parameter list will need to end with a null value, and if no arguments are required, then argv will be null.
return value: Returns the task ID of the new task nonzero or returns error if the memory is low or the task cannot be created (errno is not set).
Assumptions/Limitations：
POSIX compatibility: This is a non-POSIX interface, Vxwroks provides an interface similar to the following:
int Taskspawn (char *name, int priority, int options, int stackSize, funcptr entrypt,int arg1, int arg2, int arg3, int arg4 , int arg5,int arg6, int arg7, int arg8, int arg9, int arg10);
Nuttx's Task_create () and VxWorks's Taskspawn () have the following differences: interface names different types of parameters have no optional parameters (NUTTX) variable number of parameters can be passed to a task (corresponding VxWorks up to 10 support)

2.1.2 Task_init
function Prototypes：
#include <sched.h>
int task_init (struct tcb_s *tcb, char *name, int priority, uint32_t *stack, uint32_t stack_size,maint_t entry, char * cons T argv[]);
Description: This function initializes a Process control block (TCB) to start a new thread. It acts as a subset of the Task_create () function. But unlike task_create (), Task_init () does not activate the thread, and the created thread must be activated by calling Task_activate ().
Input Parameters：
Tcb. The address of the process control block for the new task
Name. Name of new task (not used)
Priority. Priorities for new tasks
Stack. Start address of pre-allocated stack
Stack_size. The size of the pre-allocated stack (in bytes)
Entry. Entry point for new tasks
Argv. A pointer to the input parameter array can provide a maximum of config_max_task_arg, and if fewer than config_max_task_arg parameters are passed in, then the parameter list will need to end with a null value, and if no arguments are required, then argv will be null.
return value: Returns OK, and returns error if the task is not initialized.
The new task will fail only if a new unique task ID cannot be set to the task control block (errno is not set).
Assumptions/Limitations: Taks_init () provides internal support to the operating system. Used as a general use is not recommended. Task_create () is the preferred interface for initializing and starting a task.
POSIX compatibility: This is a non-POSIX interface, Vxwroks provides an interface similar to the following:
STATUS Taskinit (WIND_TCB *PTCB, char *name, int priority, int options, uint32_t *pstackbase, int stacksize,funcptr entrypt , int arg1, int arg2, int arg3, int arg4, int arg5,int arg6, int arg7, int arg8, int arg9, int arg10);
Nuttx's Task_init () and VxWorks's Taskinit () have the following differences: interface names different types of parameters have no optional parameters (NUTTX) variable number of parameters can be passed to a task (corresponding VxWorks up to 10 support)

2.1.3 Task_activate
function prototype
#include <sched.h>
int task_activate (struct tcb_s *TCB) ;
describes : This function activates the task created by Task_init (). Tasks that are not activated are not eligible to be executed by the scheduler.
input parameter :
TCB. The address of the process control block for the new task.
return value : Returns OK and returns error if the task cannot be activated (errno is not set). The
hypothesis/restriction : Taks_activate () is provided to the operating system for internal support. Used as a general use is not recommended. Task_create () is the preferred interface for initializing and starting a task.
POSIX compatibility : This is a non-POSIX interface, Vxwroks provides an interface similar to the following:
STATUS taskactivate (int tid); The
Nuttx task_activate () differs from VxWorks's taskactivate () in the following ways: The interface name is in VxWorks taskactivate function, the PID parameter is Wind_ The TCB pointer is converted into an integer value (that is, the TID is actually the TCB's address map.) Because the memory address is unique, the TID is also guaranteed to be unique within the system)

2.1.4 Task_delete
function prototype
#include <sched.h>
int task_delete (pid_t pid);
Description : This function cancels the operation of the specified task. Its stack and process control blocks will be freed. The function corresponds to Task_create (). This is the version that is exposed to the user; It starts with an encapsulation of the intrinsic function task_terminate ().
input parameter :
PID. The task control block ID that will be deleted. An ID of 0 indicates the task that called the function. Any attempt to invoke the function's task will be automatically redirected to exit ().
return value : Returns OK and returns error if the task cannot be deleted. Errno will be set to indicate the wrong behavior. The function can fail, for example, the provided PID does not correspond to a task that is being performed.
Assume/Limit : Taks_delete () must be used with caution. If a task holds resources (such as allocated memory or semaphores required by other tasks), task_delete () can cause confusion for these resources.
POSIX compatibility : This is a non-POSIX interface, Vxwroks provides an interface similar to the following:
STATUS taskdelete (int tid); The
Nuttx task_activate () differs from VxWorks's taskactivate () in the following way: The task removal routine is not supported (because the Vxwroks () function of Taskdeletehookadd is not supported by the system). However, if atexit () or on_exit () support is enabled, they will be called when the task is deleted. Deleting itself is supported, but in this case, the delete Call of Task_delete () to its own process will be redirected to the exit () function.

2.1.3 Task_activate
function prototype
#include <sched.h>
int task_activate (struct tcb_s *TCB) ;
describes : This function activates the task created by Task_init (). Tasks that are not activated are not eligible to be executed by the scheduler.
input parameter :
TCB. The address of the process control block for the new task.
return value : Returns OK and returns error if the task cannot be activated (errno is not set). The
hypothesis/restriction : Taks_activate () is provided to the operating system for internal support. Used as a general use is not recommended. Task_create () is the preferred interface for initializing and starting a task.
POSIX compatibility : This is a non-POSIX interface, Vxwroks provides an interface similar to the following:
STATUS taskactivate (int tid); The
Nuttx task_activate () differs from VxWorks's taskactivate () in the following ways: The interface name is in VxWorks taskactivate function, the PID parameter is Wind_ The TCB pointer is converted into an integer value (that is, the TID is actually the TCB's address map.) Because the memory address is unique, the TID is also guaranteed to be unique within the system)

2.1.4 Task_delete
function prototype
#include <sched.h>
int task_delete (pid_t pid);
Description : This function cancels the operation of the specified task. Its stack and process control blocks will be freed. The function corresponds to Task_create (). This is the version that is exposed to the user; It starts with an encapsulation of the intrinsic function task_terminate ().
input parameter :
PID. The task control block ID that will be deleted. An ID of 0 indicates the task that called the function. Any attempt to invoke the function's task will be automatically redirected to exit ().
return value : Returns OK and returns error if the task cannot be deleted. Errno will be set to indicate the wrong behavior. The function can fail, for example, the provided PID does not correspond to a task that is being performed.
Assume/Limit : Taks_delete () must be used with caution. If a task holds resources (such as allocated memory or semaphores required by other tasks), task_delete () can cause confusion for these resources.
POSIX compatibility : This is a non-POSIX interface, Vxwroks provides an interface similar to the following:
STATUS taskdelete (int tid); The
Nuttx task_activate () differs from VxWorks's taskactivate () in the following way: The task removal routine is not supported (because the Vxwroks () function of Taskdeletehookadd is not supported by the system). However, if atexit () or on_exit () support is enabled, they will be called when the task is deleted. Deleting itself is supported, but in this case, the delete Call of Task_delete () to its own process will be redirected to the exit () function.

2.1.5 Task_restart
function prototype
#include <sched.h>
int task_restart (pid_t pid);
describes the : this function "restarts" a task. The task is first stopped and then reinitialized with the same priority as its first start, the same ID, the original entry point, the stack size, the parameters, and so on.
Note : A general task exits when the related cleanup operation is not performed. For example, the file descriptor is not closed, and any previously opened file will remain open after the task is reinitialized. Memory requested before the task restarts will not be released after the task is restarted. So a task that enforces the need for restartable must be designed in such a way as to avoid memory leaks. Initialization data is not reset. A global or static variable remains in the state before the task is stopped. This feature can be used by the restart process to detect if it has been restarted.
input parameter :
PID. The id,id of the task that you want to restart is 0 indicates the task that is currently calling the function (although support for the task restart itself has not yet been implemented).
return value : Returns OK and returns error if the task cannot be restarted. The function may fail under the following conditions:
0 or the PID of the primary call function is passed to the Task_restart () (function not implemented) PID is not associated with any task in the current system (no task corresponds to this PID).
Assumptions/Limitations :
POSIX compatibility : This is a non-POSIX interface, Vxwroks provides an interface similar to the following:
STATUS Taskrestart ( int tid); The
Nuttx Task_restart () differs from VxWorks's Taskrestart () in the following way: Restarting the currently executing task is not supported on NUTTX (however VxWorks is supported) The VxWorks description says the system takes over the ID, priority, and so on when the task terminates.

2.1.6 task_setcancelstate
function prototype
#include <sched.h>
int task_setcancelstate (int State, int *oldstate);
Description : This function automatically sets the revocable state of the current call task (the state) and returns the Revocable state (oldstate) of the task before the valid value states are task_cancel_enable and task_ Cancel_disable.
Any suspended thread may be revoked when the thread's revocable state is set to task_cancel_enable.
The type of cancellation state for any newly created task, which may be task_cancel_enable or task_cancel_disable.
input parameter :
State. The new revocable status. Task_cancel_enable or task_cancel_disable both.
Oldstate. Locate the old revocable state.
return value : Returns OK or 0 successfully, and returns error if it fails. The errno will be properly set to indicate the wrong behavior.
Assumptions/Limitations :
POSIX compatibility : This is a nonstandard interface that extends the version of the Pthread_setcancelstate () feature for the task, and supports the use of Task_delete ().

2.1.7 Task_setcanceltype
function prototype
#include <sched.h>
int task_setcanceltype (int Type, far int *oldtype);
Description : This function automatically sets the revocable type (type) of the currently invoked task and returns the valid value state of the revocable type (oldtype) before the task is task_cancel_deferred and task_ Cancel_asynchronous.
Any newly created task can undo the status and type, respectively, Task_cancel_enable and task_cancel_deferred.
input parameter :
type. The new revocable type. Task_cancel_deferred or task_cancel_asynchronous both.
Oldtype. Locate the old revocable type ...
return value : Returns OK or 0 successfully, and returns error if it fails. The errno will be properly set to indicate the wrong behavior.
Assumptions/Limitations :
POSIX compatibility : This is a nonstandard interface that extends the version of the Pthread_setcanceltype () feature for the task, and supports the use of Task_delete ().

2.1.8 Task_testcancel
function Prototypes
#include <sched.h>
int task_testcancel (void);
Description : This function creates a process cancellation point in the calling task. If the undo state of the task is forbidden, then the function has no effect.
Input Parameters :
return value :
Assumptions/Limitations :
POSIX compatibility : This is a non-standard interface that extends the Pthread_testcancel () feature for the task version and supports the use of Task_delete ().

2.1.9 exit
function Prototypes
' #include