Nuttx操作系统用户手册(阅读记录)（翻译）

1.0 介绍

这个手册从固件开发者的角度提供了一般的Nuttx RTOS操作系统的相关使用信息。

1.1 文件总览

该用户手册分为三个部分和一个索引：
部分一，介绍：本节提供Ｎuttx用户手册的概述
部分二，操作系统接口：本节详细介绍了Ｎuttx提供的程序接口。这一节分成几个段落来描述不同的操作系统接口组:
段2.1 任务控制接口
段2.2 任务调度接口
段2.3 任务控制接口（我也不知道为什么和第一个一样）
段2.4 命名消息队列接口
段2.5 信号量计数接口
段2.6 时钟和定时器
段2.7 信号接口
段2.8 线程接口
段2.9 环境变量
段3.0 文件系统接口
段3.1 网络接口
段3.2 共享内存接口
部分３　操作系统数据结构：这部分的文档介绍了接口使用的数据的结构

1.2 预期读者和范围

（略）

2.0 系统接口

这个部分介绍了nuttx操作系统的每个C-callable（这个是什么）接口，用下面所示的格式描述。
　　　函数原型：提供接口函数的C原型。
　　　说明：　　介绍了由接口函数执行的操作。
　　　输入参数：列出所有输入参数，并简要描述每个输入参数。
　　　返回值：　列出了接口函数返回的所有可能值。作为副作用返回的值（通过指针输入参数或通过全局变量）将在接口函数的描述中得到处理。
　　　假定/限制：指出接口函数或对接口函数使用的任何不明显的限制所产生的任何不寻常的假设。(待定，没太看懂)
　　　POSIX 兼容性：注明Nuttx接口和POSIX接口之间的任何显著差异。
　　　注：为了实现接口函数的独立名称空间，函数名和类型的差异是当然的，不会作区分。（好迷啊）

2.1　任务控制接口

任务
Nuttx是一个平面地址操作系统，因此它不能像LINUX一样支持进程的操作，它只支持在同一地址空间运行的简单进程，然而编程模型使任务和线程之间有所区别：
　　　　　
　　　　　任务是具有一定独立性的线程。
　　　　　线程共享一些资源。

文件描述符和流
这尤其适用于打开的文件描述符（确实是文件描述符）和流。当使用本节的接口启动任务时，最多可以创建三个打开的文件。
如果 CONFIG_DEV_CONSOLE被定义了，对于新任务，前三个文件描述符（对应 stdin, stdout, stderr）会被复制。因为这些文件描述符是重复的，子任务可以自由地关闭他们或以任何方式操作他们，而不影响父任务。任务中的与文件相关的操作（打开，关闭等）对其他任务没有影响。由于复制了三个文件描述符，所以也可以执行某种级别的重定向。
另一方面进程会和父线程共享文件描述符。在这种情况下，文件操作会影响从同一个父线程开始的所有的线程。

在文件系统中执行程序
nuttx提供了　用于执行驻留在文件系统中的单独构建的程序的　内部接口。然而这些内部接口是非标准的，用二进制加载器和 NXFLAT记录。

任务控制接口　Nuttx提供了以下任务控制接口：

非标准的来自于 VxWorks 接口：
2.1.1　task_creat
2.1.2 task_init
2.1.3 task_activate
2.1.4 task_delete
2.1.5 task_restart

Non-standard extensions to VxWorks-like interfaces to support POSIX Cancellation Points.：
2.1.6 task_setcancelstate
2.1.7 task_setcanceltype
2.1.8 task_testcancel

标准接口：
2.1.9 　exit
2.1.10 getpid

标准vfork和exec [v|l ]接口：
2.1.11 vfork
2.1.12 execv
2.1.13 execl

标准posix_spawn接口：
2.1.14　 posix_spawn and 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.1.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

来自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

函数原型：

＃include 
int task_creat(char *name, int priority, int stack_size, main_t entry, char * const argv[]);

描述：

   此函数以指定的优先级创建和激活一个任务返回系统分配的ID。
   入口地址entry是任务的主函数的地址。一旦C环境设置完成这个函数就会被调用。指定的函数（ The specified function）将用四个参数调用。如果指定的程序返回，将自动调用exit()。
   注意，任意数量的参数可以传递给生成的函数。（the spawned functions）。
   实参会被复制，使得传递的字符串的有效期不依赖于task_create()的调用者的有效期。（The arguments are copied (via strdup) so that the life of the passed strings is not dependent on the life of the caller to task_create(). ）
   新创建的任务不从父任务继承调度器特性:新任务从默认的系统优先级开始，并使用SCHED_FIFO调度策略。这些特征可以在新任务启动后进行修改。
   新创建的任务确实继承了前三个文件描述符(对应于stdin、stdout和stderr)，并支持标准I / O的重定向。

输入参数：

name:新任务的名字
priority:新任务的优先级
stack_size:所需栈的大小，单位为字节
entry:新任务的入口点
argv:一个指向输入参数数组的指针，取决与提CONFIG_MAX_TASK_ARG参数，如果传递参数数目少于CONFIG_MAX_TASK_ARG，则该列表（lists）应该用NULL argv[]值(NULL argv value)终止。如果不需要参数argv应为NULL

返回值

返回新任务的非０任务ＩＤ,如果内存不足无法创建任务（errno　未设置）时会返回ERROR

假定和限制

POSIX兼容性:这是一个非POSIX接口。VxWorks提供如下类似接口:

int taskSpawn(char *name, int priority, int options, int stackSize, FUNCPTR entryPt,arg1, int arg2, int arg3, int arg4, int arg5,int arg6, int arg7, int arg8, int arg9, int arg10);

NuttX的 task_create() 和 VxWorks的 taskSpawn()在以下几个方面不同：

          接口名称
          类型和参数　　
          没有options参数
          可以将可变数量的参数传递给任务（(VxWorks支持10个参数）

2.1.2 task_init

函数原型

#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 * const argv[]);

描述

   此函数初始化任务控制块(TCB)，以准备启动新的线程。它执行task_create()的功能子集(参见上面)。
  与task_create()不同，task_init()不激活任务。这必须通过调用task_activate()来完成。

输入参数

tcb. 新任务的TCB地址
name.新任务的名字(未被使用过)
priority.新任务的优先次序
stack,预分配的堆栈的起始
stack_size, 预分配栈的大小
argv,一个指向输入参数数组的指针，取决与提CONFIG_MAX_TASK_ARG参数，如果传递参数数目少于CONFIG_MAX_TASK_ARG，则该列表（lists）应该用NULL argv[]值(NULL argv value)终止。如果不需要参数argv应为NULL

返回值

任务无法初始化(失败),返回ERROR,成功返回OK,
这个函数只会在不能为TCB分配一个新的唯一的任务ID的时候失败.

假定和限制

    task_init()提供支持内部OS功能。正常情况下不建议使用该功能。task_create()是初始化和启动新任务的首选机制。

POSIX兼容性:这是一个非POSIX接口。VxWorks提供如下类似接口:

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的 task_init() 和 VxWorks的 taskInit()在以下几个方面不同：

          接口名称
          类型和参数　　
          没有options参数
          可以将可变数量的参数传递给任务（(VxWorks支持10个参数）

2.1.3 task_activate

函数原型：

   #include <sched.h>
   int task_activate(struct tcb_s *tcb);

　　　　　　　　　
描述:

由task_init()创建的任务.没有task_activate()激活,任务不会被调度器执行.

输入参数

任务的TCB(原文是The TCB for the task for the task,笑哭)(和与task_init参数相同).

返回值

任务激活返回OK,未被激活返回ERROR(errno未被设置).

假定和限制

task_activate()提供支持内部操作系统功能。正常情况下不建议使用。task_create()是初始化和启动新任务的首选机制。

POSIX兼容性:这是一个非POSIX接口。VxWorks提供如下类似接口:

STATUS taskActivate(int tid);

NuttX task_activate()在以下几个方面与VxWorks的taskActivate()不同:

函数名
使用VxWork的taskActivate,pid参数应该是一个指向WIND_TCB的整数型的指针。

2.1.4 task_delete

函数原型

#include <sched.h>
int task_delete(pid_t pid);

描述:

   该函数删除指定的任务。任务的堆栈和TCB将被释放。这个函数通常和task_create()成对使用。这是向用户提供的函数的版本;它只是对task_terminate()函数作了进一步的封装。
   此函数中的逻辑功能只能删除非运行任务,如果PID参数指的是当前运行中的任务,则进程会重定向到exit().这种情况只会发生在任务调用task_delete()删除自己的时候.
   这函数遵循了线程取消的语义(确实是线程取消的语义):如果任务的删除取消或支持延迟删除(启用了取消点),则延迟执行任务删除.(This function obeys the semantics of pthread cancellation: task deletion is deferred if cancellation is disabled or if deferred cancellation is supported (with Cancellation Points enabled).)

输入参数

pid.要删除的任务的ID.ID为0表示调用任务( the calling task),任何调用任务的尝试都将重定向到exit().

返回值

如果任务不能删除,返回ERROR,删除成功返回OK,errno被设置为表示失败.例如,如果提供的pid不符合当前执行的任务,则该函数会失败.

假设/限制

task_delete()必须谨慎使用:如果任务持有资源(例如，其他任务所需的内存或信号)，那么task_delete()就可以将这些资源进行处理。

POSIX兼容性:这是一个非POSIX接口。VxWorks提供如下类似接口:

STATUS taskDelete(int tid);

它们之间的不同:

   不支持调用任务删除routines (因为不支持VxWorks taskDeleteHookAdd())。但是，如果启用了atexit()或on_exit支持，则在任务删除时会调用这些支持。
   支持删除自身，但这仅仅是因为task_delete()将重定向至 exit()。

2.1.5 task_restart

函数原型

#include <sched.h>
int task_restart(pid_t pid);

描述:

这个函数“重新启动”一个任务。任务首先被终止，然后以相同的ID、优先级、原始入口点、堆栈大小和它刚开始时的参数重新初始化。

注

   1.不会执行正常任务退出时的清理工作,文件描述符不被关闭,在重启前打开的文件,重启后保留打开的状态.
   2.在重启前分配的内存不会被释放,所以设计需要重启的任务时必须要防止内存的泄漏.

输入参数

pid.要重启任务的ID(这里原文是The task ID of the task to delete.)。ID为0将表示要重启的任务是调用task_restart的任务本身(However, support for a task to restart itself has not been implemented然而，并不支持对本身的重启（(lll￢ω￢)）)。

返回值

成功返回OK,如果任务ID是无效的或者没能任务重启,会返回ERROR.且当(1)pid为0,或者pid是调用task_restart的任务本身的pid(也就是上面所说的不支持的功能),(2)所给pid没有与之对应的任务,任务的重启就会失败.

假设/限制

POSIX兼容性这是一个非posix接口。VxWorks提供如下类似接口:

  STATUS taskRestart (int tid);

它们之间区别如下:

NuttX不支持重新启动当前运行的任务。
VxWorks版描述，在任务终止时，ID、优先级等具有它们所具有过的值。